1 /* 2 * Copyright (c) 2023 Raspberry Pi (Trading) Ltd. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef _PICO_FLASH_H 8 #define _PICO_FLASH_H 9 10 #include "pico.h" 11 12 /** \file pico/flash.h 13 * \defgroup pico_flash pico_flash 14 * 15 * \brief High level flash API 16 * 17 * Flash cannot be erased or written to when in XIP mode. However the system cannot directly access memory in the flash 18 * address space when not in XIP mode. 19 * 20 * It is therefore critical that no code or data is being read from flash while flash is been written or erased. 21 * 22 * If only one core is being used, then the problem is simple - just disable interrupts; however if code is running on 23 * the other core, then it has to be asked, nicely, to avoid flash for a bit. This is hard to do if you don't have 24 * complete control of the code running on that core at all times. 25 * 26 * This library provides a \ref flash_safe_execute method which calls a function back having successfully gotten 27 * into a state where interrupts are disabled, and the other core is not executing or reading from flash. 28 * 29 * How it does this is dependent on the supported environment (Free RTOS SMP or pico_multicore). Additionally 30 * the user can provide their own mechanism by providing a strong definition of \ref get_flash_safety_helper(). 31 * 32 * Using the default settings, flash_safe_execute will only call the callback function if the state is safe 33 * otherwise returning an error (or an assert depending on \ref PICO_FLASH_ASSERT_ON_UNSAFE). 34 * 35 * There are conditions where safety would not be guaranteed: 36 * 37 * 1. FreeRTOS smp with `configNUM_CORES=1` - FreeRTOS still uses pico_multicore in this case, so \ref flash_safe_execute 38 * cannot know what the other core is doing, and there is no way to force code execution between a FreeRTOS core 39 * and a non FreeRTOS core. 40 * 2. FreeRTOS non SMP with pico_multicore - Again, there is no way to force code execution between a FreeRTOS core and 41 * a non FreeRTOS core. 42 * 3. pico_multicore without \ref flash_safe_execute_core_init() having been called on the other core - The 43 * \ref flash_safe_execute method does not know if code is executing on the other core, so it has to assume it is. Either 44 * way, it is not able to intervene if \ref flash_safe_execute_core_init() has not been called on the other core. 45 * 46 * Fortunately, all is not lost in this situation, you may: 47 * 48 * * Set \ref PICO_FLASH_ASSUME_CORE0_SAFE=1 to explicitly say that core 0 is never using flash. 49 * * Set \ref PICO_FLASH_ASSUME_CORE1_SAFE=1 to explicitly say that core 1 is never using flash. 50 */ 51 52 #ifdef __cplusplus 53 extern "C" { 54 #endif 55 56 /** 57 * \brief Initialize a core such that the other core can lock it out during \ref flash_safe_execute. 58 * \ingroup pico_flash 59 * 60 * \note This is not necessary for FreeRTOS SMP, but should be used when launching via \ref multicore_launch_core1 61 * \return true on success; there is no need to call \ref flash_safe_execute_core_deinit() on failure. 62 */ 63 bool flash_safe_execute_core_init(void); 64 65 /** 66 * \brief De-initialize work done by \ref flash_safe_execute_core_init 67 * \ingroup pico_flash 68 * \return true on success 69 */ 70 bool flash_safe_execute_core_deinit(void); 71 72 /** 73 * \brief Execute a function with IRQs disabled and with the other core also not executing/reading flash 74 * \ingroup pico_flash 75 * 76 * \param func the function to call 77 * \param param the parameter to pass to the function 78 * \param enter_exit_timeout_ms the timeout for each of the enter/exit phases when coordinating with the other core 79 * 80 * \return PICO_OK on success (the function will have been called). 81 * PICO_ERROR_TIMEOUT on timeout (the function may have been called). 82 * PICO_ERROR_NOT_PERMITTED if safe execution is not possible (the function will not have been called). 83 * PICO_ERROR_INSUFFICIENT_RESOURCES if the method fails due to dynamic resource exhaustion (the function will not have been called) 84 * \note if \ref PICO_FLASH_ASSERT_ON_UNSAFE is 1, this function will assert in debug mode vs returning 85 * PICO_ERROR_NOT_PERMITTED 86 */ 87 int flash_safe_execute(void (*func)(void *), void *param, uint32_t enter_exit_timeout_ms); 88 89 // PICO_CONFIG: PICO_FLASH_ASSERT_ON_UNSAFE, Assert in debug mode rather than returning an error if flash_safe_execute cannot guarantee safety to catch bugs early, type=bool, default=1, group=pico_flash 90 #ifndef PICO_FLASH_ASSERT_ON_UNSAFE 91 #define PICO_FLASH_ASSERT_ON_UNSAFE 1 92 #endif 93 94 // PICO_CONFIG: PICO_FLASH_ASSUME_CORE0_SAFE, Assume that core 0 will never be accessing flash and so doesn't need to be considered during flash_safe_execute, type=bool, default=0, group=pico_flash 95 #ifndef PICO_FLASH_ASSUME_CORE0_SAFE 96 #define PICO_FLASH_ASSUME_CORE0_SAFE 0 97 #endif 98 99 // PICO_CONFIG: PICO_FLASH_ASSUME_CORE1_SAFE, Assume that core 1 will never be accessing flash and so doesn't need to be considered during flash_safe_execute, type=bool, default=0, group=pico_flash 100 #ifndef PICO_FLASH_ASSUME_CORE1_SAFE 101 #define PICO_FLASH_ASSUME_CORE1_SAFE 0 102 #endif 103 104 // PICO_CONFIG: PICO_FLASH_SAFE_EXECUTE_SUPPORT_FREERTOS_SMP, Support using FreeRTOS SMP to make the other core safe during flash_safe_execute, type=bool, default=1 when using FreeRTOS SMP, group=pico_flash 105 #ifndef PICO_FLASH_SAFE_EXECUTE_SUPPORT_FREERTOS_SMP 106 #if LIB_FREERTOS_KERNEL && FREE_RTOS_KERNEL_SMP // set by RP2040 SMP port 107 #define PICO_FLASH_SAFE_EXECUTE_SUPPORT_FREERTOS_SMP 1 108 #endif 109 #endif 110 111 // PICO_CONFIG: PICO_FLASH_SAFE_EXECUTE_PICO_SUPPORT_MULTICORE_LOCKOUT, Support using multicore_lockout functions to make the other core safe during flash_safe_execute, type=bool, default=1 when using pico_multicore, group=pico_flash 112 #ifndef PICO_FLASH_SAFE_EXECUTE_PICO_SUPPORT_MULTICORE_LOCKOUT 113 #if LIB_PICO_MULTICORE 114 #define PICO_FLASH_SAFE_EXECUTE_PICO_SUPPORT_MULTICORE_LOCKOUT 1 115 #endif 116 #endif 117 118 typedef struct { 119 bool (*core_init_deinit)(bool init); 120 int (*enter_safe_zone_timeout_ms)(uint32_t timeout_ms); 121 int (*exit_safe_zone_timeout_ms)(uint32_t timeout_ms); 122 } flash_safety_helper_t; 123 124 /** 125 * \brief Internal method to return the flash safety helper implementation. 126 * \ingroup pico_flash 127 * 128 * Advanced users can provide their own implementation of this function to perform 129 * different inter-core coordination before disabling XIP mode. 130 * 131 * @return the \ref flash_safety_helper_t 132 */ 133 flash_safety_helper_t *get_flash_safety_helper(void); 134 135 #ifdef __cplusplus 136 } 137 #endif 138 139 #endif 140
