-
Notifications
You must be signed in to change notification settings - Fork 570
/
soc_flash_nrf.h
193 lines (174 loc) · 6.5 KB
/
soc_flash_nrf.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
/*
* Copyright (c) 2020 Nordic Semiconductor ASA
*
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef __SOC_FLASH_NRF_H__
#define __SOC_FLASH_NRF_H__
#include <zephyr/kernel.h>
#include <soc.h>
#define FLASH_OP_DONE (0) /* 0 for compliance with the driver API. */
#define FLASH_OP_ONGOING 1
struct flash_context {
uint32_t data_addr; /* Address of data to write. */
uint32_t flash_addr; /* Address of flash to write or erase. */
uint32_t len; /* Size of data to write or erase [B]. */
#ifndef CONFIG_SOC_FLASH_NRF_RADIO_SYNC_NONE
uint8_t enable_time_limit; /* set execution limited to the execution
* window.
*/
#endif /* !CONFIG_SOC_FLASH_NRF_RADIO_SYNC_NONE */
#if defined(CONFIG_SOC_FLASH_NRF_PARTIAL_ERASE)
uint32_t flash_addr_next;
#endif /* CONFIG_SOC_FLASH_NRF_PARTIAL_ERASE */
}; /*< Context type for f. @ref write_op @ref erase_op */
#ifndef CONFIG_SOC_FLASH_NRF_RADIO_SYNC_NONE
/* The timeout is multiplied by CONFIG_SOC_FLASH_NRF_TIMEOUT_MULTIPLIER/10
* because switching tasks may take a significant portion of time.
*/
#define FLASH_TIMEOUT_MS ((FLASH_PAGE_ERASE_MAX_TIME_US) * \
(FLASH_PAGE_MAX_CNT) / 1000 * \
CONFIG_SOC_FLASH_NRF_TIMEOUT_MULTIPLIER / 10)
/**
* @defgroup nrf_flash_sync sync backend API
*
* API declared below contains prototypes of function which shall be
* implemented by the synchronization backend.
* @{
*/
/**
* Callback which executes the flash operation.
*
* @param context pointer to flash_context structure.
* @retval @ref FLASH_OP_DONE once operation was done, @ref FLASH_OP_ONGOING if
* operation needs more time for execution and a negative error code if
* operation was aborted.
*/
typedef int (*flash_op_handler_t) (void *context);
struct flash_op_desc {
flash_op_handler_t handler;
struct flash_context *context; /* [in,out] */
};
/**
* Synchronization backend driver initialization procedure.
*
* This will be run within flash driver initialization
*/
int nrf_flash_sync_init(void);
/**
* Set synchronization context for synchronous operations.
*
* This function set backend's internal context for expected timing parameter.
*
* @param duration Duration of the execution window [us]
*/
void nrf_flash_sync_set_context(uint32_t duration);
/**
* Check if the operation need to be run synchronous with radio.
*
* @retval True if operation need to be run synchronously, otherwise False
*/
bool nrf_flash_sync_is_required(void);
/**
* Execute the flash operation synchronously along the radio operations.
*
* Function executes callbacks op_desc->handler() in execution windows according
* to timing settings requested by nrf_flash_sync_set_context().
* This routine need to be called the handler as many time as it returns
* FLASH_OP_ONGOING, however an operation timeout should be implemented.
* When the handler() returns FLASH_OP_DONE or an error code, no further
* execution windows are needed so function should return as the handler()
* finished its operation.
*
* @retval 0 if op_desc->handler() was executed and finished its operation
* successfully. Otherwise (handler returned error, timeout, couldn't schedule
* execution...) a negative error code.
*
* execution window
* Driver task task
* | |
* | |
* nrf_flash_sync_ # |
* set_context() # |
* | |
* | |
* call nrf_flash_ # |
* sync_exe() # |
* #---------------->|
* | |
* | # execution window 0
* | # call flash_op_handler_t handler()
* | #
* | #
* | # flash_op_handler_t handler() return
* | # FLASH_OP_ONGOING
* | # {backend request/allow
* | | the next execution window}
* . .
* . .
* . .
* | |
* | # execution window N
* | # call flash_op_handler_t handler()
* | #
* | #
* | #
* | # flash_op_handler_t handler() returns
* | # FLASH_OP_DONE
* |<----------------# {backend transfer execution
* # | to the driver back}
* nrf_flash_ # |
* sync_exe() | |
* return | |
*/
int nrf_flash_sync_exe(struct flash_op_desc *op_desc);
/**
* @}
*/
/**
* @defgroup nrf_flash_sync_timing sync timing backend API
* @ingroup nrf_flash_sync
* @{
*
* API which is used by nrf flash driver for check where execution fill in
* the execution window.
*
* API is used as follows:
* begin of execution window
* call flash_op_handler_t handler()
* nrf_flash_sync_get_timestamp_begin()
* [does some chunk of work]
* nrf_flash_sync_check_time_limit() == false
* [does some chunk of work]
* nrf_flash_sync_check_time_limit() == false
* [does some chunk of work]
* ...
* nrf_flash_sync_check_time_limit() == true
* [preserve work context for next execution window]
* return form flash_op_handler_t handler()
* [return from execution window]
* end of execution window
*/
/**
* Get timestamp and store it in synchronization backend
* context data as operation beginning time reference.
* This timestamp will be used by @ref nrf_flash_sync_check_time_limit()
* as the execution window begin reference.
*/
void nrf_flash_sync_get_timestamp_begin(void);
/**
* Estimate whether next iteration will fit in time constraints.
* This function fetch current timestamp and compare it with the operation
* beginning timestamp reference stored by
* @ref nrf_flash_sync_get_timestamp_begin() in the synchronization backend
* context data.
*
* @param iteration iteration number.
* @retval true if estimated time excess, false otherwise.
*/
bool nrf_flash_sync_check_time_limit(uint32_t iteration);
/**
* @}
*/
#endif /* !CONFIG_SOC_FLASH_NRF_RADIO_SYNC_NONE */
#endif /* !__SOC_FLASH_NRF_H__ */