ChibiOS/HAL  7.0.3
hal_wspi.h
Go to the documentation of this file.
1 /*
2  ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio
3 
4  Licensed under the Apache License, Version 2.0 (the "License");
5  you may not use this file except in compliance with the License.
6  You may obtain a copy of the License at
7 
8  http://www.apache.org/licenses/LICENSE-2.0
9 
10  Unless required by applicable law or agreed to in writing, software
11  distributed under the License is distributed on an "AS IS" BASIS,
12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  See the License for the specific language governing permissions and
14  limitations under the License.
15 */
16 
17 /**
18  * @file hal_wspi.h
19  * @brief WSPI Driver macros and structures.
20  *
21  * @addtogroup WSPI
22  * @{
23  */
24 
25 #ifndef HAL_WSPI_H
26 #define HAL_WSPI_H
27 
28 #if (HAL_USE_WSPI == TRUE) || defined(__DOXYGEN__)
29 
30 /*===========================================================================*/
31 /* Driver constants. */
32 /*===========================================================================*/
33 
34 /*===========================================================================*/
35 /* Driver pre-compile time settings. */
36 /*===========================================================================*/
37 
38 /**
39  * @name WSPI configuration options
40  * @{
41  */
42 /**
43  * @brief Enables synchronous APIs.
44  * @note Disabling this option saves both code and data space.
45  */
46 #if !defined(WSPI_USE_WAIT) || defined(__DOXYGEN__)
47 #define WSPI_USE_WAIT TRUE
48 #endif
49 
50 /**
51  * @brief Enables the @p wspiAcquireBus() and @p wspiReleaseBus() APIs.
52  * @note Disabling this option saves both code and data space.
53  */
54 #if !defined(WSPI_USE_MUTUAL_EXCLUSION) || defined(__DOXYGEN__)
55 #define WSPI_USE_MUTUAL_EXCLUSION TRUE
56 #endif
57 /** @} */
58 
59 /*===========================================================================*/
60 /* Derived constants and error checks. */
61 /*===========================================================================*/
62 
63 /*===========================================================================*/
64 /* Driver data structures and types. */
65 /*===========================================================================*/
66 
67 /**
68  * @brief Driver state machine possible states.
69  */
70 typedef enum {
71  WSPI_UNINIT = 0, /**< Not initialized. */
72  WSPI_STOP = 1, /**< Stopped. */
73  WSPI_READY = 2, /**< Ready. */
74  WSPI_ACTIVE = 3, /**< Exchanging data. */
75  WSPI_COMPLETE = 4, /**< Asynchronous operation complete. */
76  WSPI_MEMMAP = 5 /**< In memory mapped mode. */
77 } wspistate_t;
78 
79 /**
80  * @brief Type of a structure representing an WSPI driver.
81  */
82 typedef struct hal_wspi_driver WSPIDriver;
83 
84 /**
85  * @brief Type of a structure representing an WSPI driver configuration.
86  */
87 typedef struct hal_wspi_config WSPIConfig;
88 
89 /**
90  * @brief Type of a WSPI notification callback.
91  *
92  * @param[in] wspip pointer to the @p WSPIDriver object triggering the
93  * callback
94  */
95 typedef void (*wspicallback_t)(WSPIDriver *wspip);
96 
97 /**
98  * @brief Type of a WSPI command descriptor.
99  */
100 typedef struct {
101  /**
102  * @brief Transfer configuration field.
103  */
104  uint32_t cfg;
105  /**
106  * @brief Command phase data.
107  */
108  uint32_t cmd;
109  /**
110  * @brief Address phase data.
111  */
112  uint32_t addr;
113  /**
114  * @brief Alternate phase data.
115  */
116  uint32_t alt;
117  /**
118  * @brief Number of dummy cycles to be inserted.
119  */
120  uint32_t dummy;
122 
123 /* Including the low level driver header, it exports information required
124  for completing types.*/
125 #include "hal_wspi_lld.h"
126 
127 #if !defined(WSPI_SUPPORTS_MEMMAP)
128 #error "low level does not define WSPI_SUPPORTS_MEMMAP"
129 #endif
130 
131 #if !defined(WSPI_DEFAULT_CFG_MASKS)
132 #error "low level does not define WSPI_DEFAULT_CFG_MASKS"
133 #endif
134 
135 /**
136  * @brief Driver configuration structure.
137  */
139  /**
140  * @brief Operation complete callback or @p NULL.
141  */
143  /* End of the mandatory fields.*/
144  wspi_lld_config_fields;
145 };
146 
147 /**
148  * @brief Structure representing an WSPI driver.
149  */
151  /**
152  * @brief Driver state.
153  */
155  /**
156  * @brief Current configuration data.
157  */
159 #if (WSPI_USE_WAIT == TRUE) || defined(__DOXYGEN__)
160  /**
161  * @brief Waiting thread.
162  */
164 #endif /* WSPI_USE_WAIT */
165 #if (WSPI_USE_MUTUAL_EXCLUSION == TRUE) || defined(__DOXYGEN__)
166  /**
167  * @brief Mutex protecting the peripheral.
168  */
170 #endif /* WSPI_USE_MUTUAL_EXCLUSION */
171 #if defined(WSPI_DRIVER_EXT_FIELDS)
172  WSPI_DRIVER_EXT_FIELDS
173 #endif
174  /* End of the mandatory fields.*/
176 };
177 
178 /*===========================================================================*/
179 /* Driver macros. */
180 /*===========================================================================*/
181 
182 #if (WSPI_DEFAULT_CFG_MASKS == TRUE) || defined(__DOXYGEN__)
183 /**
184  * @name Transfer options
185  * @note The low level driver has the option to override the following
186  * definitions and use its own ones. In must take care to use
187  * the same name for the same function or compatibility is not
188  * ensured.
189  * @{
190  */
191 #define WSPI_CFG_CMD_MODE_MASK (7LU << 0LU)
192 #define WSPI_CFG_CMD_MODE_NONE (0LU << 0LU)
193 #define WSPI_CFG_CMD_MODE_ONE_LINE (1LU << 0LU)
194 #define WSPI_CFG_CMD_MODE_TWO_LINES (2LU << 0LU)
195 #define WSPI_CFG_CMD_MODE_FOUR_LINES (3LU << 0LU)
196 #define WSPI_CFG_CMD_MODE_EIGHT_LINES (4LU << 0LU)
197 
198 #define WSPI_CFG_CMD_DTR (1LU << 3LU)
199 
200 #define WSPI_CFG_CMD_SIZE_MASK (3LU << 4LU)
201 #define WSPI_CFG_CMD_SIZE_8 (0LU << 4LU)
202 #define WSPI_CFG_CMD_SIZE_16 (1LU << 4LU)
203 #define WSPI_CFG_CMD_SIZE_24 (2LU << 4LU)
204 #define WSPI_CFG_CMD_SIZE_32 (3LU << 4LU)
205 
206 #define WSPI_CFG_ADDR_MODE_MASK (7LU << 8LU)
207 #define WSPI_CFG_ADDR_MODE_NONE (0LU << 8LU)
208 #define WSPI_CFG_ADDR_MODE_ONE_LINE (1LU << 8LU)
209 #define WSPI_CFG_ADDR_MODE_TWO_LINES (2LU << 8LU)
210 #define WSPI_CFG_ADDR_MODE_FOUR_LINES (3LU << 8LU)
211 #define WSPI_CFG_ADDR_MODE_EIGHT_LINES (4LU << 8LU)
212 
213 #define WSPI_CFG_ADDR_DTR (1LU << 11LU)
214 
215 #define WSPI_CFG_ADDR_SIZE_MASK (3LU << 12LU)
216 #define WSPI_CFG_ADDR_SIZE_8 (0LU << 12LU)
217 #define WSPI_CFG_ADDR_SIZE_16 (1LU << 12LU)
218 #define WSPI_CFG_ADDR_SIZE_24 (2LU << 12LU)
219 #define WSPI_CFG_ADDR_SIZE_32 (3LU << 12LU)
220 
221 #define WSPI_CFG_ALT_MODE_MASK (7LU << 16LU)
222 #define WSPI_CFG_ALT_MODE_NONE (0LU << 16LU)
223 #define WSPI_CFG_ALT_MODE_ONE_LINE (1LU << 16LU)
224 #define WSPI_CFG_ALT_MODE_TWO_LINES (2LU << 16LU)
225 #define WSPI_CFG_ALT_MODE_FOUR_LINES (3LU << 16LU)
226 #define WSPI_CFG_ALT_MODE_EIGHT_LINES (4LU << 16LU)
227 
228 #define WSPI_CFG_ALT_DTR (1LU << 19LU)
229 
230 #define WSPI_CFG_ALT_SIZE_MASK (3LU << 20LU)
231 #define WSPI_CFG_ALT_SIZE_8 (0LU << 20LU)
232 #define WSPI_CFG_ALT_SIZE_16 (1LU << 20LU)
233 #define WSPI_CFG_ALT_SIZE_24 (2LU << 20LU)
234 #define WSPI_CFG_ALT_SIZE_32 (3LU << 20LU)
235 
236 #define WSPI_CFG_DATA_MODE_MASK (7LU << 24LU)
237 #define WSPI_CFG_DATA_MODE_NONE (0LU << 24LU)
238 #define WSPI_CFG_DATA_MODE_ONE_LINE (1LU << 24LU)
239 #define WSPI_CFG_DATA_MODE_TWO_LINES (2LU << 24LU)
240 #define WSPI_CFG_DATA_MODE_FOUR_LINES (3LU << 24LU)
241 #define WSPI_CFG_DATA_MODE_EIGHT_LINES (4LU << 24LU)
242 
243 #define WSPI_CFG_DATA_DTR (1LU << 27LU)
244 
245 #define WSPI_CFG_DQS_ENABLE (1LU << 29LU)
246 
247 #define WSPI_CFG_SIOO (1LU << 31LU)
248 
249 #define WSPI_CFG_ALL_DTR (WSPI_CFG_CMD_DTR | \
250  WSPI_CFG_ADDR_DTR | \
251  WSPI_CFG_ALT_DTR | \
252  WSPI_CFG_DATA_DTR)
253 /** @} */
254 #endif /* WSPI_USE_DEFAULT_CFG_MASKS == TRUE */
255 
256 /**
257  * @name Macro Functions
258  * @{
259  */
260 /**
261  * @brief Sends a command without data phase.
262  * @post At the end of the operation the configured callback is invoked.
263  *
264  * @param[in] wspip pointer to the @p WSPIDriver object
265  * @param[in] cmdp pointer to the command descriptor
266  *
267  * @iclass
268  */
269 #define wspiStartCommandI(wspip, cmdp) { \
270  osalDbgAssert(((cmdp)->cfg & WSPI_CFG_DATA_MODE_MASK) == \
271  WSPI_CFG_DATA_MODE_NONE, \
272  "data mode specified"); \
273  (wspip)->state = WSPI_ACTIVE; \
274  wspi_lld_command(wspip, cmdp); \
275 }
276 
277 /**
278  * @brief Sends data over the WSPI bus.
279  * @details This asynchronous function starts a transmit operation.
280  * @post At the end of the operation the configured callback is invoked.
281  *
282  * @param[in] wspip pointer to the @p WSPIDriver object
283  * @param[in] cmdp pointer to the command descriptor
284  * @param[in] n number of bytes to send or zero if no data phase
285  * @param[in] txbuf the pointer to the transmit buffer
286  *
287  * @iclass
288  */
289 #define wspiStartSendI(wspip, cmdp, n, txbuf) { \
290  osalDbgAssert(((cmdp)->cfg & WSPI_CFG_DATA_MODE_MASK) != \
291  WSPI_CFG_DATA_MODE_NONE, \
292  "data mode required"); \
293  (wspip)->state = WSPI_ACTIVE; \
294  wspi_lld_send(wspip, cmdp, n, txbuf); \
295 }
296 
297 /**
298  * @brief Receives data from the WSPI bus.
299  * @details This asynchronous function starts a receive operation.
300  * @post At the end of the operation the configured callback is invoked.
301  *
302  * @param[in] wspip pointer to the @p WSPIDriver object
303  * @param[in] cmdp pointer to the command descriptor
304  * @param[in] n number of bytes to receive or zero if no data phase
305  * @param[out] rxbuf the pointer to the receive buffer
306  *
307  * @iclass
308  */
309 #define wspiStartReceiveI(wspip, cmdp, n, rxbuf) { \
310  osalDbgAssert(((cmdp)->cfg & WSPI_CFG_DATA_MODE_MASK) != \
311  WSPI_CFG_DATA_MODE_NONE, \
312  "data mode required"); \
313  (wspip)->state = WSPI_ACTIVE; \
314  wspi_lld_receive(wspip, cmdp, n, rxbuf); \
315 }
316 
317 #if (WSPI_SUPPORTS_MEMMAP == TRUE) || defined(__DOXYGEN__)
318 /**
319  * @brief Maps in memory space a WSPI flash device.
320  * @pre The memory flash device must be initialized appropriately
321  * before mapping it in memory space.
322  *
323  * @param[in] wspip pointer to the @p WSPIDriver object
324  * @param[in] cmdp pointer to the command descriptor
325  * @param[out] addrp pointer to the memory start address of the mapped
326  * flash or @p NULL
327  *
328  * @iclass
329  */
330 #define wspiMapFlashI(wspip, cmdp, addrp) \
331  wspi_lld_map_flash(wspip, cmdp, addrp)
332 
333 /**
334  * @brief Maps in memory space a WSPI flash device.
335  * @post The memory flash device must be re-initialized for normal
336  * commands exchange.
337  *
338  * @param[in] wspip pointer to the @p WSPIDriver object
339  *
340  * @iclass
341  */
342 #define wspiUnmapFlashI(wspip) \
343  wspi_lld_unmap_flash(wspip)
344 #endif /* WSPI_SUPPORTS_MEMMAP == TRUE */
345 /** @} */
346 
347 /**
348  * @name Low level driver helper macros
349  * @{
350  */
351 #if (WSPI_USE_WAIT == TRUE) || defined(__DOXYGEN__)
352 /**
353  * @brief Wakes up the waiting thread.
354  *
355  * @param[in] wspip pointer to the @p WSPIDriver object
356  *
357  * @notapi
358  */
359 #define _wspi_wakeup_isr(wspip) { \
360  osalSysLockFromISR(); \
361  osalThreadResumeI(&(wspip)->thread, MSG_OK); \
362  osalSysUnlockFromISR(); \
363 }
364 #else /* !WSPI_USE_WAIT */
365 #define _wspi_wakeup_isr(wspip)
366 #endif /* !WSPI_USE_WAIT */
367 
368 /**
369  * @brief Common ISR code.
370  * @details This code handles the portable part of the ISR code:
371  * - Callback invocation.
372  * - Waiting thread wakeup, if any.
373  * - Driver state transitions.
374  * .
375  * @note This macro is meant to be used in the low level drivers
376  * implementation only.
377  *
378  * @param[in] wspip pointer to the @p WSPIDriver object
379  *
380  * @notapi
381  */
382 #define _wspi_isr_code(wspip) { \
383  if ((wspip)->config->end_cb) { \
384  (wspip)->state = WSPI_COMPLETE; \
385  (wspip)->config->end_cb(wspip); \
386  if ((wspip)->state == WSPI_COMPLETE) \
387  (wspip)->state = WSPI_READY; \
388  } \
389  else \
390  (wspip)->state = WSPI_READY; \
391  _wspi_wakeup_isr(wspip); \
392 }
393 /** @} */
394 
395 /*===========================================================================*/
396 /* External declarations. */
397 /*===========================================================================*/
398 
399 #ifdef __cplusplus
400 extern "C" {
401 #endif
402  void wspiInit(void);
403  void wspiObjectInit(WSPIDriver *wspip);
404  void wspiStart(WSPIDriver *wspip, const WSPIConfig *config);
405  void wspiStop(WSPIDriver *wspip);
406  void wspiStartCommand(WSPIDriver *wspip, const wspi_command_t *cmdp);
407  void wspiStartSend(WSPIDriver *wspip, const wspi_command_t *cmdp,
408  size_t n, const uint8_t *txbuf);
409  void wspiStartReceive(WSPIDriver *wspip, const wspi_command_t *cmdp,
410  size_t n, uint8_t *rxbuf);
411 #if WSPI_USE_WAIT == TRUE
412  void wspiCommand(WSPIDriver *wspip, const wspi_command_t *cmdp);
413  void wspiSend(WSPIDriver *wspip, const wspi_command_t *cmdp,
414  size_t n, const uint8_t *txbuf);
415  void wspiReceive(WSPIDriver *wspip, const wspi_command_t *cmdp,
416  size_t n, uint8_t *rxbuf);
417 #endif
418 #if WSPI_SUPPORTS_MEMMAP == TRUE
419 void wspiMapFlash(WSPIDriver *wspip,
420  const wspi_command_t *cmdp,
421  uint8_t **addrp);
422 void wspiUnmapFlash(WSPIDriver *wspip);
423 #endif
424 #if WSPI_USE_MUTUAL_EXCLUSION == TRUE
425  void wspiAcquireBus(WSPIDriver *wspip);
426  void wspiReleaseBus(WSPIDriver *wspip);
427 #endif
428 #ifdef __cplusplus
429 }
430 #endif
431 
432 #endif /* HAL_USE_WSPI == TRUE */
433 
434 #endif /* HAL_WSPI_H */
435 
436 /** @} */
void wspiMapFlash(WSPIDriver *wspip, const wspi_command_t *cmdp, uint8_t **addrp)
Maps in memory space a WSPI flash device.
Definition: hal_wspi.c:313
wspicallback_t end_cb
Operation complete callback or NULL.
Definition: hal_wspi.h:142
void wspiStartSend(WSPIDriver *wspip, const wspi_command_t *cmdp, size_t n, const uint8_t *txbuf)
Sends a command with data over the WSPI bus.
Definition: hal_wspi.c:165
void wspiAcquireBus(WSPIDriver *wspip)
Gains exclusive access to the WSPI bus.
Definition: hal_wspi.c:366
uint32_t dummy
Number of dummy cycles to be inserted.
Definition: hal_wspi.h:120
Structure representing an WSPI driver.
Definition: hal_wspi.h:150
void wspiStart(WSPIDriver *wspip, const WSPIConfig *config)
Configures and activates the WSPI peripheral.
Definition: hal_wspi.c:91
void wspiSend(WSPIDriver *wspip, const wspi_command_t *cmdp, size_t n, const uint8_t *txbuf)
Sends a command with data over the WSPI bus.
Definition: hal_wspi.c:249
void wspiStop(WSPIDriver *wspip)
Deactivates the WSPI peripheral.
Definition: hal_wspi.c:116
Driver configuration structure.
Definition: hal_wspi.h:138
void wspiInit(void)
WSPI Driver initialization.
Definition: hal_wspi.c:56
void wspiReleaseBus(WSPIDriver *wspip)
Releases exclusive access to the WSPI bus.
Definition: hal_wspi.c:382
void(* wspicallback_t)(WSPIDriver *wspip)
Type of a WSPI notification callback.
Definition: hal_wspi.h:95
void wspiUnmapFlash(WSPIDriver *wspip)
Unmaps from memory space a WSPI flash device.
Definition: hal_wspi.c:339
uint32_t addr
Address phase data.
Definition: hal_wspi.h:112
void wspiStartReceive(WSPIDriver *wspip, const wspi_command_t *cmdp, size_t n, uint8_t *rxbuf)
Sends a command then receives data over the WSPI bus.
Definition: hal_wspi.c:191
const WSPIConfig * config
Current configuration data.
Definition: hal_wspi.h:158
void wspiObjectInit(WSPIDriver *wspip)
Initializes the standard part of a WSPIDriver structure.
Definition: hal_wspi.c:68
wspistate_t state
Driver state.
Definition: hal_wspi.h:154
uint32_t alt
Alternate phase data.
Definition: hal_wspi.h:116
thread_reference_t thread
Waiting thread.
Definition: hal_wspi.h:163
uint32_t cmd
Command phase data.
Definition: hal_wspi.h:108
mutex_t mutex
Mutex protecting the peripheral.
Definition: hal_wspi.h:169
void * thread_reference_t
Type of a thread reference.
Definition: osal.h:180
void wspiReceive(WSPIDriver *wspip, const wspi_command_t *cmdp, size_t n, uint8_t *rxbuf)
Sends a command then receives data over the WSPI bus.
Definition: hal_wspi.c:281
Type of a WSPI command descriptor.
Definition: hal_wspi.h:100
void wspiCommand(WSPIDriver *wspip, const wspi_command_t *cmdp)
Sends a command without data phase.
Definition: hal_wspi.c:219
void wspiStartCommand(WSPIDriver *wspip, const wspi_command_t *cmdp)
Sends a command without data phase.
Definition: hal_wspi.c:141
uint32_t mutex_t
Type of a mutex.
Definition: osal.h:223
PLATFORM WSPI subsystem low level driver header.
uint32_t cfg
Transfer configuration field.
Definition: hal_wspi.h:104
#define wspi_lld_driver_fields
Low level fields of the WSPI driver structure.
Definition: hal_wspi_lld.h:75
wspistate_t
Driver state machine possible states.
Definition: hal_wspi.h:70