1 /* 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 * Description: FLASH task shared definitions between the SCPU and A/PCPU. 15 */ 16 17 #ifndef FLASH_TASK_ETYPES_H 18 #define FLASH_TASK_ETYPES_H 19 20 #include "stdbool.h" 21 #include "errcode.h" 22 23 #ifdef __cplusplus 24 #if __cplusplus 25 extern "C" { 26 #endif /* __cplusplus */ 27 #endif /* __cplusplus */ 28 29 /** Identifier to check that a section of memory is indeed a flash_task_node */ 30 #define FLASH_TASK_NODE_IDENTIFIER 0xd3a71f85 31 32 /* Normal values of the flash_task_node.result field; anything else is an error being reported - must remain in sync 33 * with the SCPU soc_errno. The A/PCPU can use these defines in case they have a different set of error codes */ 34 #define FLASH_TASK_DISCARD 0x80002040 35 #define FLASH_TASK_DISCARDED 0x80002041 36 #define FLASH_TASK_READY 0x80002042 37 #define FLASH_TASK_BEING_PROCESSED 0x80002043 38 #define FLASH_TASK_COMPLETED 0x80003130 39 40 #define FLASH_TASK_ERASE_ALL_MAGIC_VALUE_LEN 10 41 42 typedef enum { 43 /* Create KV storage in flash memory */ 44 FLASH_TASK_KV_PAGE_INIT = 0, 45 /* A new or modification to an existing key-value */ 46 FLASH_TASK_KV_DATA, 47 /* Modify the attribute on an existing key-value */ 48 FLASH_TASK_KV_ATTRIBUTE, 49 /* Erase a key-value */ 50 FLASH_TASK_KV_ERASE, 51 /* Write / overwrite some FOTA patch data in FLASH */ 52 FLASH_TASK_FOTA_DATA, 53 /* Erase some FOTA patch data in FLASH and re-write the FOTA header */ 54 FLASH_TASK_FOTA_ERASE, 55 /* Write some data to ACPU storage in FLASH */ 56 FLASH_TASK_ACPU_DATA, 57 /* Erase some ACPU storage in FLASH */ 58 FLASH_TASK_ACPU_ERASE, 59 /* Number of task types */ 60 FLASH_TASK_NUM_TYPES, 61 } flash_task_type_t; 62 63 64 /** @brief Key type */ 65 typedef uint16_t kv_storage_key; 66 67 typedef struct { 68 uint32_t kv_addr; 69 uint32_t kv_size; 70 } flash_task_kv_init_t; 71 72 typedef struct { 73 const uint8_t *kvalue; 74 kv_storage_key key; 75 uint16_t kvalue_length; 76 uint8_t attribute; 77 bool force_write; 78 } flash_task_kv_data_t; 79 80 typedef struct { 81 kv_storage_key key; 82 uint8_t attribute; 83 } flash_task_kv_attribute_t; 84 85 typedef struct { 86 kv_storage_key key; 87 } flash_task_kv_erase_t; 88 89 typedef struct { 90 kv_storage_key key; 91 } flash_task_kv_backup_t; 92 93 typedef struct { 94 /* Used to ensure erase all is not called by mistake. */ 95 uint8_t magic_value[FLASH_TASK_ERASE_ALL_MAGIC_VALUE_LEN]; 96 } kv_erase_all_t; 97 98 typedef struct { 99 uint8_t *src; /* Mapped address in calling core memory map, can in RAM or FLASH. */ 100 uint8_t *dst; /* Mapped address in calling core memory map FOTA FLASH region 101 * - must not include the FOTA header. */ 102 uint16_t length; 103 } flash_task_flash_data_t; 104 105 typedef struct { 106 uint32_t start_address; /* Core mapped address in FOTA FLASH region; must be at the start of a flash page. */ 107 uint32_t length; /* Must be a multiple of the page size. */ 108 } flash_task_flash_erase_t; 109 110 typedef union { 111 flash_task_kv_init_t kv_region; 112 flash_task_kv_data_t kv; 113 flash_task_kv_attribute_t kv_attribute; 114 flash_task_kv_erase_t kv_erase; 115 flash_task_flash_data_t flash; 116 flash_task_flash_erase_t flash_erase; 117 } task_node_data_t; 118 119 typedef struct owner_callback_data_t owner_callback; 120 121 /** 122 * @brief Flash task local callback from the flash_task_process_completed_task(...) function. 123 * 124 * @param result is the result of the flash task execution on the SCPU. 125 * @param callback is the callback struct containing any information that was prepared for use during the callback. 126 * @return soc_errno value SOC_ERR_SUCCESS or another error code indicating that the callback has failed; this 127 * will be returned by the flash_task_process_completed_task(...) function. */ 128 typedef errcode_t (*flash_task_completed_callback)(errcode_t result, owner_callback *callback); 129 130 struct owner_callback_data_t { 131 /** Callback function to call if not EXT_NULL. */ 132 flash_task_completed_callback func; 133 /* Include any owner data to be available to the callback function upon execution. */ 134 }; 135 136 typedef struct flash_task_description_t flash_task_node; 137 struct flash_task_description_t { 138 /** A flash_task identifier to maximise the chance that a bug is detected quickly. */ 139 uint32_t identifier; 140 /** Next task in the queue or EXT_NULL if nothing. */ 141 volatile flash_task_node *next; 142 /** FOR THE TASK PRODUCER: This is private to the core that owns the cache and will not be examined by the SCPU task 143 * handlers. It will nominally be used by the owning core as the call-back it should call when it discovers that 144 * this task has been completed combined with a pointer to a struct with any state information. 145 * 146 * NB: IN THE SCPU FLASH TASK HANDLER DURING EXECUTION ONLY: this will be nulled out in the copy initially provided 147 * to the SCPU task handler and can be used to store task state while the task is in progress, even if the task 148 * must be temporarily suspended due to an A/PCPU wake-up. */ 149 owner_callback *owner_callback; 150 /** The state_code is a soc_errno and is used as a lock so is volatile so that it can be read/written from each core 151 * properly. 152 * FLASH_TASK_DISCARD - Set by the owning core so that the SCPU will stop checking this memory 153 * (and will acknowledge this by setting this to DISCARDED). 154 * FLASH_TASK_DISCARDED - Set by the SCPU to acknowledge that this task has not been processed and 155 * was discarded by request of the owning core. 156 * (the SCPU is no longer examining this memory which can be modified/freed). 157 * FLASH_TASK_READY - Set by the owning core so that the SCPU will process this task 158 * (and will update it when finished) so the owning core cannot change 159 * anything other than the owner_callback once this has been set. 160 * FLASH_TASK_BEING_PROCESSED - Set by the SCPU to indicate that this task is being processed; 161 * this may take some time if the SCPU has to wait for other cores to sleep. 162 * The owning core must not change anything other than the owner_callback. 163 * FLASH_TASK_COMPLETED - Set by the SCPU to indicate that this task completed successfully 164 * (the SCPU is no longer examining this memory which can be modified/freed). 165 * any other value - Provides an error code; contact customer support to obtain it's meaning 166 * (the SCPU is no longer examining this memory which can be modified/freed). 167 */ 168 volatile uint32_t state_code; 169 /** The flash task to be performed. */ 170 flash_task_type_t task; 171 /** The unique per task data contents. */ 172 task_node_data_t data; 173 /** A checksum formed by xoring the flash write task information (task and data) and is used to spot errors. */ 174 uint32_t checksum; 175 }; 176 177 #ifdef __cplusplus 178 #if __cplusplus 179 } 180 #endif /* __cplusplus */ 181 #endif /* __cplusplus */ 182 183 #endif /* _EXTERNAL_ETYPES_5GNBRBIV100_SHARED_FLASH_TASK_ETYPES_H */ 184 185