Wirepas SDK
bl_interface.h
Go to the documentation of this file.
1 /* Copyright 2018 Wirepas Ltd. All Rights Reserved.
2  *
3  * See file LICENSE.txt for full license details.
4  *
5  */
6 
13 #ifndef BL_INTERFACE_H_
14 #define BL_INTERFACE_H_
15 
16 #include <stdbool.h>
17 #include <stdint.h>
18 #include <stddef.h>
19 
20 #if defined(EFR32_PLATFORM)
21 #include "em_cmu.h"
22 #endif
23 
25 typedef enum
26 {
27  BL_RES_OK = 0,
36 
38 #define BL_MEMORY_AREA_UNDEFINED 0xFFFFFFFF
39 
41 typedef uint32_t bl_memory_area_id_t;
42 
44 typedef enum
45 {
54 
56 typedef struct
57 {
59  size_t flash_size;
74  uint32_t byte_write_time;
76  uint32_t page_write_time;
88 
90 typedef struct
91 {
95  size_t area_size;
107 
112 typedef struct
113 {
115  uint32_t length;
117  uint16_t crc;
119  uint8_t seq;
121  uint8_t major;
123  uint8_t minor;
125  uint8_t maint;
127  uint8_t devel;
129 
131 typedef enum
132 {
140 
142 typedef enum
143 {
163 
165 typedef enum
166 {
182 
184 typedef struct
185 {
187  uint32_t area_length;
189  uint32_t erase_time;
191  uint32_t length;
193  uint16_t crc;
197  uint8_t seq;
201  uint8_t flags;
203  uint32_t type;
205  uint32_t status;
207  bool dedicated;
210  uint32_t modem_fw_data;
213  uint32_t modem_fw_length;
215 
216 #if defined(NRF91_PLATFORM)
217 typedef struct
218 {
224  const char * at_commands;
225 } bl_platform_nrf91_t;
226 #elif defined(EFR32_PLATFORM)
227 
228 typedef struct
229 {
233  const CMU_HFXOInit_TypeDef * hfxoInit;
237  const CMU_LFXOInit_TypeDef * lfxoInit;
238 } bl_platform_efr32_t;
239 #endif
240 
242 typedef union
243 {
244 #if defined(NRF52_PLATFORM)
245 
248  const void * nrf52;
249 #elif defined(NRF91_PLATFORM)
250 
253  const bl_platform_nrf91_t * nrf91;
254 #elif defined(EFR32_PLATFORM)
255 
258  const bl_platform_efr32_t * efr32;
259 #endif
260 } bl_platform_t;
261 
263 typedef struct
264 {
272  bool dcdc;
278 
292 typedef bl_interface_res_e
294  void * to,
295  uint32_t from,
296  size_t amount);
297 
312 typedef bl_interface_res_e
314  uint32_t to,
315  const void * from,
316  size_t amount);
317 
332 typedef bl_interface_res_e
334  uint32_t * sector_base,
335  size_t * number_of_sector);
336 
343 typedef bool
345 
355 typedef bl_interface_res_e
357  bl_memory_area_info_t * info);
358 
367 typedef void
369  uint8_t * num_areas);
370 
382 typedef bl_interface_res_e
385 
397 typedef bl_interface_res_e
399  bl_memory_area_header_t * header);
400 
408 typedef uint8_t
410 
420 typedef bl_interface_res_e
422 
435 typedef bl_interface_res_e
436  (*bl_scrat_read_f)(void * to, uint32_t from, size_t amount);
437 
443 typedef bl_interface_res_e (*bl_scrat_clear_f)(void (*clear_wdt)(void));
444 
455 typedef bl_interface_res_e
457  uint8_t seq,
458  void (*clear_wdt)(void));
459 
474 typedef bl_interface_res_e
475  (*bl_scrat_write_f)(uint32_t to,
476  const void * from,
477  size_t amount,
478  bl_scrat_write_status_e * status);
479 
488 typedef bl_interface_res_e
490 
497 typedef bl_interface_res_e
499 
500 typedef bl_interface_res_e (*bl_scrat_setStatus_f)(uint32_t status);
501 
507 typedef const bl_hardware_capabilities_t *
508  (*bl_hardware_getCapabilities_f)(void);
509 
513 typedef void (*bl_debug_flow_f)(dflow_tag_e tag);
514 
515 
516 typedef struct
517 {
528 
529 typedef struct
530 {
540 
541 typedef struct
542 {
545 
546 typedef struct
547 {
550 
554 typedef struct
555 {
556  uint32_t version;
562 
563 #endif /* BL_INTERFACE_H_ */
BL_SCRAT_IS_INVALID
@ BL_SCRAT_IS_INVALID
Definition: bl_interface.h:178
bl_flash_info_t::page_write_call_time
uint32_t page_write_call_time
Definition: bl_interface.h:82
bl_memory_area_info_t::area_id
bl_memory_area_id_t area_id
Definition: bl_interface.h:93
bl_debug_flow_f
void(* bl_debug_flow_f)(dflow_tag_e tag)
Add flow debugging point.
Definition: bl_interface.h:513
BL_SCRAT_WRITE_STATUS_INVALID_HEADER
@ BL_SCRAT_WRITE_STATUS_INVALID_HEADER
Definition: bl_interface.h:157
bl_memory_area_header_t::seq
uint8_t seq
Definition: bl_interface.h:119
bl_scrat_info_t::area_length
uint32_t area_length
Definition: bl_interface.h:187
bl_memory_area_getIdfromType_f
bl_interface_res_e(* bl_memory_area_getIdfromType_f)(bl_memory_area_id_t *id, bl_memory_area_type_e type)
Return the memory area id of the FIRST area with provided type.
Definition: bl_interface.h:383
scratchpad_services_t::setBootable
bl_scrat_setBootable_f setBootable
Definition: bl_interface.h:537
bl_interface_t::hardware_services_p
const hardware_services_t * hardware_services_p
Definition: bl_interface.h:559
bl_flash_info_t::sector_erase_time
uint32_t sector_erase_time
Definition: bl_interface.h:78
BL_SCRAT_IS_NOTAG
@ BL_SCRAT_IS_NOTAG
Definition: bl_interface.h:172
BL_SCRAT_WRITE_STATUS_INVALID_START
@ BL_SCRAT_WRITE_STATUS_INVALID_START
Definition: bl_interface.h:153
BL_RES_ERROR
@ BL_RES_ERROR
Definition: bl_interface.h:28
bl_memory_area_info_t::area_physical_address
uint32_t area_physical_address
Definition: bl_interface.h:97
bl_memory_area_info_t::external_flash
bool external_flash
Definition: bl_interface.h:101
bl_memory_area_header_t
Informations contained in the header that the bootloader can store in the beginning of an area (only ...
Definition: bl_interface.h:112
BL_SCRAT_WRITE_STATUS_FLASH_ERROR
@ BL_SCRAT_WRITE_STATUS_FLASH_ERROR
Definition: bl_interface.h:161
bl_memory_area_startRead_f
bl_interface_res_e(* bl_memory_area_startRead_f)(bl_memory_area_id_t id, void *to, uint32_t from, size_t amount)
Read bytes from a memory area.
Definition: bl_interface.h:293
BL_SCRAT_WRITE_STATUS_COMPLETED_ERROR
@ BL_SCRAT_WRITE_STATUS_COMPLETED_ERROR
Definition: bl_interface.h:149
bl_flash_info_t::flash_size
size_t flash_size
Definition: bl_interface.h:59
bl_scrat_info_t::erase_time
uint32_t erase_time
Definition: bl_interface.h:189
bl_platform_t
Platform specific descriptions.
Definition: bl_interface.h:242
bl_interface_t::version
uint32_t version
Definition: bl_interface.h:556
BL_MEM_AREA_TYPE_MODEMFW
@ BL_MEM_AREA_TYPE_MODEMFW
Definition: bl_interface.h:52
bl_memory_area_info_t::has_header
bool has_header
Definition: bl_interface.h:103
memory_area_services_t::startErase
bl_memory_area_startErase_f startErase
Definition: bl_interface.h:520
bl_scrat_write_status_e
bl_scrat_write_status_e
Scratchpad write status.
Definition: bl_interface.h:142
bl_hardware_capabilities_t::dcdc
bool dcdc
Definition: bl_interface.h:272
BL_MEM_AREA_TYPE_APPLICATION
@ BL_MEM_AREA_TYPE_APPLICATION
Definition: bl_interface.h:48
BL_MEM_AREA_TYPE_PERSISTENT
@ BL_MEM_AREA_TYPE_PERSISTENT
Definition: bl_interface.h:49
memory_area_services_t::isBusy
bl_memory_area_isBusy_f isBusy
Definition: bl_interface.h:521
bl_flash_info_t::is_busy_call_time
uint32_t is_busy_call_time
Definition: bl_interface.h:86
bl_scrat_info_t::status
uint32_t status
Definition: bl_interface.h:205
bl_memory_area_getMaxNumAreas_f
uint8_t(* bl_memory_area_getMaxNumAreas_f)(void)
Return the total number of areas supported by the bootloader.
Definition: bl_interface.h:409
memory_area_services_t::startWrite
bl_memory_area_startWrite_f startWrite
Definition: bl_interface.h:519
memory_area_services_t::getMaxNumAreas
bl_memory_area_getMaxNumAreas_f getMaxNumAreas
Definition: bl_interface.h:526
BL_SCRAT_WRITE_STATUS_COMPLETED_OK
@ BL_SCRAT_WRITE_STATUS_COMPLETED_OK
Definition: bl_interface.h:147
BL_SCRAT_TYPE_BLANK
@ BL_SCRAT_TYPE_BLANK
Definition: bl_interface.h:134
bl_memory_area_header_t::crc
uint16_t crc
Definition: bl_interface.h:117
bl_flash_info_t::write_alignment
size_t write_alignment
Definition: bl_interface.h:68
bl_scrat_setBootable_f
bl_interface_res_e(* bl_scrat_setBootable_f)(void)
Set scratchpad as bootable.
Definition: bl_interface.h:498
scratchpad_services_t::read
bl_scrat_read_f read
Definition: bl_interface.h:532
bl_interface_t
Global interface entry point with a version id.
Definition: bl_interface.h:554
BL_RES_TIMEOUT
@ BL_RES_TIMEOUT
Definition: bl_interface.h:33
bl_hardware_getCapabilities_f
const typedef bl_hardware_capabilities_t *(* bl_hardware_getCapabilities_f)(void)
Returns board hardware capabilities.
Definition: bl_interface.h:508
bl_flash_info_t::byte_write_call_time
uint32_t byte_write_call_time
Definition: bl_interface.h:80
bl_memory_area_info_t::type
bl_memory_area_type_e type
Definition: bl_interface.h:105
scratchpad_services_t::setStatus
bl_scrat_setStatus_f setStatus
Definition: bl_interface.h:538
scratchpad_services_t::clear
bl_scrat_clear_f clear
Definition: bl_interface.h:533
bl_scrat_info_t::modem_fw_length
uint32_t modem_fw_length
Definition: bl_interface.h:213
scratchpad_services_t::getInfo
bl_scrat_getInfo_f getInfo
Definition: bl_interface.h:536
bl_memory_area_getAreaHeader_f
bl_interface_res_e(* bl_memory_area_getAreaHeader_f)(bl_memory_area_id_t id, bl_memory_area_header_t *header)
Return a structure containing the information stored in the header at the beginning of the area.
Definition: bl_interface.h:398
bl_memory_area_header_t::length
uint32_t length
Definition: bl_interface.h:115
bl_scrat_write_f
bl_interface_res_e(* bl_scrat_write_f)(uint32_t to, const void *from, size_t amount, bl_scrat_write_status_e *status)
Write bytes to scratchpad area.
Definition: bl_interface.h:475
bl_flash_info_t::erase_sector_size
size_t erase_sector_size
Definition: bl_interface.h:63
bl_flash_info_t::byte_write_time
uint32_t byte_write_time
Definition: bl_interface.h:74
bl_interface_t::scratchpad_services_p
const scratchpad_services_t * scratchpad_services_p
Definition: bl_interface.h:558
BL_SCRAT_IS_CLEAR
@ BL_SCRAT_IS_CLEAR
Definition: bl_interface.h:170
bl_interface_res_e
bl_interface_res_e
Bootloader interface operations result.
Definition: bl_interface.h:25
scratchpad_services_t
Definition: bl_interface.h:529
BL_SCRAT_WRITE_STATUS_NOT_ONGOING
@ BL_SCRAT_WRITE_STATUS_NOT_ONGOING
Definition: bl_interface.h:151
BL_SCRAT_TYPE_PRESENT
@ BL_SCRAT_TYPE_PRESENT
Definition: bl_interface.h:136
BL_SCRAT_IS_UNKNOWN
@ BL_SCRAT_IS_UNKNOWN
Definition: bl_interface.h:168
BL_MEM_AREA_TYPE_SCRATCHPAD
@ BL_MEM_AREA_TYPE_SCRATCHPAD
Definition: bl_interface.h:50
hardware_services_t::getCapabilities
bl_hardware_getCapabilities_f getCapabilities
Definition: bl_interface.h:543
bl_flash_info_t::page_write_time
uint32_t page_write_time
Definition: bl_interface.h:76
BL_MEM_AREA_TYPE_STACK
@ BL_MEM_AREA_TYPE_STACK
Definition: bl_interface.h:47
BL_RES_OK
@ BL_RES_OK
Definition: bl_interface.h:27
dflow_services_t::debug_flow
bl_debug_flow_f debug_flow
Definition: bl_interface.h:548
BL_SCRAT_IS_INVALID_HEADER
@ BL_SCRAT_IS_INVALID_HEADER
Definition: bl_interface.h:174
bl_scrat_info_t::flags
uint8_t flags
Definition: bl_interface.h:201
bl_scrat_info_t
Scratchpad info definition.
Definition: bl_interface.h:184
BL_RES_BUSY
@ BL_RES_BUSY
Definition: bl_interface.h:29
bl_memory_area_info_t::area_size
size_t area_size
Definition: bl_interface.h:95
scratchpad_services_t::begin
bl_scrat_begin_f begin
Definition: bl_interface.h:534
bl_memory_area_startErase_f
bl_interface_res_e(* bl_memory_area_startErase_f)(bl_memory_area_id_t id, uint32_t *sector_base, size_t *number_of_sector)
Erase a sector of a memory area.
Definition: bl_interface.h:333
bl_scrat_valid_e
bl_scrat_valid_e
Scratchpad validity.
Definition: bl_interface.h:165
bl_memory_area_getAreaList_f
void(* bl_memory_area_getAreaList_f)(bl_memory_area_id_t *list, uint8_t *num_areas)
Return the list of areas defined in the bootloader.
Definition: bl_interface.h:368
hardware_services_t
Definition: bl_interface.h:541
bl_memory_area_startWrite_f
bl_interface_res_e(* bl_memory_area_startWrite_f)(bl_memory_area_id_t id, uint32_t to, const void *from, size_t amount)
Write bytes to a memory area.
Definition: bl_interface.h:313
bl_hardware_capabilities_t
Hardware features that can be installed on a board.
Definition: bl_interface.h:263
bl_scrat_read_f
bl_interface_res_e(* bl_scrat_read_f)(void *to, uint32_t from, size_t amount)
Read bytes from a scratchpad file.
Definition: bl_interface.h:436
bl_flash_info_t::sector_erase_call_time
uint32_t sector_erase_call_time
Definition: bl_interface.h:84
bl_memory_area_isBusy_f
bool(* bl_memory_area_isBusy_f)(bl_memory_area_id_t id)
Checks if underlying flash driver is busy.
Definition: bl_interface.h:344
BL_SCRAT_WRITE_STATUS_INVALID_NUM_BYTES
@ BL_SCRAT_WRITE_STATUS_INVALID_NUM_BYTES
Definition: bl_interface.h:155
dflow_services_t
Definition: bl_interface.h:546
scratchpad_services_t::getValidity
bl_scrat_getValidity_f getValidity
Definition: bl_interface.h:531
BL_RES_NODRIVER
@ BL_RES_NODRIVER
Definition: bl_interface.h:30
BL_SCRAT_TYPE_PROCESS
@ BL_SCRAT_TYPE_PROCESS
Definition: bl_interface.h:138
bl_scrat_clear_f
bl_interface_res_e(* bl_scrat_clear_f)(void(*clear_wdt)(void))
Erase the scratchpad area.
Definition: bl_interface.h:443
memory_area_services_t::getAreaInfo
bl_memory_area_getAreaInfo_f getAreaInfo
Definition: bl_interface.h:522
memory_area_services_t::getIdfromType
bl_memory_area_getIdfromType_f getIdfromType
Definition: bl_interface.h:524
BL_SCRAT_IS_VALID
@ BL_SCRAT_IS_VALID
Definition: bl_interface.h:180
bl_memory_area_type_e
bl_memory_area_type_e
Types of Memory Areas.
Definition: bl_interface.h:44
bl_memory_area_header_t::devel
uint8_t devel
Definition: bl_interface.h:127
bl_scrat_info_t::modem_fw_data
uint32_t modem_fw_data
Definition: bl_interface.h:210
bl_hardware_capabilities_t::platform
bl_platform_t platform
Definition: bl_interface.h:276
bl_flash_info_t
Flash memory info definition.
Definition: bl_interface.h:56
bl_memory_area_header_t::maint
uint8_t maint
Definition: bl_interface.h:125
bl_interface_t::dflow_services_p
const dflow_services_t * dflow_services_p
Definition: bl_interface.h:560
bl_scrat_info_t::type
uint32_t type
Definition: bl_interface.h:203
BL_SCRAT_WRITE_STATUS_OK
@ BL_SCRAT_WRITE_STATUS_OK
Definition: bl_interface.h:145
bl_memory_area_id_t
uint32_t bl_memory_area_id_t
Memory Area id definition.
Definition: bl_interface.h:41
bl_memory_area_info_t::flash
bl_flash_info_t flash
Definition: bl_interface.h:99
BL_RES_INVALID_AREA
@ BL_RES_INVALID_AREA
Definition: bl_interface.h:32
bl_scrat_info_t::dedicated
bool dedicated
Definition: bl_interface.h:207
BL_RES_PARAM
@ BL_RES_PARAM
Definition: bl_interface.h:31
bl_memory_area_header_t::major
uint8_t major
Definition: bl_interface.h:121
bl_scrat_getInfo_f
bl_interface_res_e(* bl_scrat_getInfo_f)(bl_scrat_info_t *info)
Fills a structure with info about the scratchpad.
Definition: bl_interface.h:489
scratchpad_services_t::write
bl_scrat_write_f write
Definition: bl_interface.h:535
app_lib_joining_received_beacon_s::type
uint32_t type
Definition: wms_joining.h:139
BL_MEM_AREA_TYPE_BOOTLOADER
@ BL_MEM_AREA_TYPE_BOOTLOADER
Definition: bl_interface.h:46
BL_SCRAT_IS_INVALID_CRC
@ BL_SCRAT_IS_INVALID_CRC
Definition: bl_interface.h:176
BL_SCRAT_WRITE_STATUS_INVALID_NULL_BYTES
@ BL_SCRAT_WRITE_STATUS_INVALID_NULL_BYTES
Definition: bl_interface.h:159
bl_scrat_begin_f
bl_interface_res_e(* bl_scrat_begin_f)(uint32_t num_bytes, uint8_t seq, void(*clear_wdt)(void))
Prepare scratchpad memory for storing new data.
Definition: bl_interface.h:456
bl_flash_info_t::write_page_size
size_t write_page_size
Definition: bl_interface.h:61
bl_memory_area_header_t::minor
uint8_t minor
Definition: bl_interface.h:123
bl_memory_area_getAreaInfo_f
bl_interface_res_e(* bl_memory_area_getAreaInfo_f)(bl_memory_area_id_t id, bl_memory_area_info_t *info)
Fills a structure with info about memory area.
Definition: bl_interface.h:356
memory_area_services_t::startRead
bl_memory_area_startRead_f startRead
Definition: bl_interface.h:518
bl_hardware_capabilities_t::crystal_32k
bool crystal_32k
Definition: bl_interface.h:268
BL_RES_INVALID_STATE
@ BL_RES_INVALID_STATE
Definition: bl_interface.h:34
app_lib_joining_received_beacon_s::num_bytes
size_t num_bytes
Definition: wms_joining.h:137
bl_scrat_getValidity_f
bl_interface_res_e(* bl_scrat_getValidity_f)(bl_scrat_valid_e *validity)
Check if the scratchpad contains valid data.
Definition: bl_interface.h:421
bl_memory_area_info_t
Memory Area info definition.
Definition: bl_interface.h:90
memory_area_services_t
Definition: bl_interface.h:516
bl_interface_t::memory_area_services_p
const memory_area_services_t * memory_area_services_p
Definition: bl_interface.h:557
bl_scrat_type_e
bl_scrat_type_e
Scratchpad type enum.
Definition: bl_interface.h:131
bl_scrat_setStatus_f
bl_interface_res_e(* bl_scrat_setStatus_f)(uint32_t status)
Definition: bl_interface.h:500
BL_MEM_AREA_TYPE_USER
@ BL_MEM_AREA_TYPE_USER
Definition: bl_interface.h:51
memory_area_services_t::getAreaHeader
bl_memory_area_getAreaHeader_f getAreaHeader
Definition: bl_interface.h:525
memory_area_services_t::getAreaList
bl_memory_area_getAreaList_f getAreaList
Definition: bl_interface.h:523