fifo.h 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668
  1. /**
  2. * \file
  3. *
  4. * \brief This file controls the software FIFO management.
  5. *
  6. * These functions manages FIFOs thanks to simple a API. The FIFO can
  7. * be 100% full thanks to a double-index range implementation. For example,
  8. * a FIFO of 4 elements can be implemented: the FIFO can really hold up to 4
  9. * elements.
  10. * This is particularly well suited for any kind of application needing a lot of
  11. * small FIFO.
  12. *
  13. * Copyright (c) 2010-2015 Atmel Corporation. All rights reserved.
  14. *
  15. * \asf_license_start
  16. *
  17. * \page License
  18. *
  19. * Redistribution and use in source and binary forms, with or without
  20. * modification, are permitted provided that the following conditions are met:
  21. *
  22. * 1. Redistributions of source code must retain the above copyright notice,
  23. * this list of conditions and the following disclaimer.
  24. *
  25. * 2. Redistributions in binary form must reproduce the above copyright notice,
  26. * this list of conditions and the following disclaimer in the documentation
  27. * and/or other materials provided with the distribution.
  28. *
  29. * 3. The name of Atmel may not be used to endorse or promote products derived
  30. * from this software without specific prior written permission.
  31. *
  32. * 4. This software may only be redistributed and used in connection with an
  33. * Atmel microcontroller product.
  34. *
  35. * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
  36. * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  37. * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
  38. * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
  39. * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  40. * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  41. * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  42. * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  43. * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  44. * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  45. * POSSIBILITY OF SUCH DAMAGE.
  46. *
  47. * \asf_license_stop
  48. *
  49. */
  50. /*
  51. * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
  52. */
  53. #ifndef _FIFO_H_
  54. #define _FIFO_H_
  55. #include "compiler.h"
  56. /**
  57. * \defgroup fifo_group First-In-First-Out Buffer (FIFO)
  58. *
  59. * See \ref fifo_quickstart.
  60. *
  61. * These functions manages FIFOs thanks to simple a API. The FIFO can
  62. * be 100% full thanks to a double-index range implementation. For example,
  63. * a FIFO of 4 elements can be implemented: the FIFO can really hold up to 4
  64. * elements. This is particularly well suited for any kind of application
  65. * needing a lot of small FIFO. The maximum fifo size is 128 items (uint8,
  66. * uint16 or uint32). Note that the driver, thanks to its conception, does
  67. * not use interrupt protection.
  68. *
  69. * @{
  70. */
  71. //! Error codes used by FIFO driver.
  72. enum {
  73. FIFO_OK = 0, //!< Normal operation.
  74. FIFO_ERROR_OVERFLOW, //!< Attempt to push something in a FIFO that is full.
  75. FIFO_ERROR_UNDERFLOW, //!< Attempt to pull something from a FIFO that is empty
  76. FIFO_ERROR, //!< Error condition during FIFO initialization
  77. };
  78. //! FIFO descriptor used by FIFO driver.
  79. struct fifo_desc {
  80. union
  81. {
  82. uint32_t *u32ptr; //!< Pointer to unsigned-32 bits location
  83. uint16_t *u16ptr; //!< Pointer to unsigned-16 bits location
  84. uint8_t *u8ptr; //!< Pointer to unsigned-8 bits location
  85. } buffer;
  86. volatile uint8_t read_index; //!< Read index
  87. volatile uint8_t write_index; //!< Write index
  88. uint8_t size; //!< Size of the FIFO (unit is in number of 'element')
  89. uint8_t mask; //!< Mask used to speed up FIFO operation (wrapping)
  90. };
  91. typedef struct fifo_desc fifo_desc_t;
  92. /**
  93. * \brief Initializes a new software FIFO for a certain 'size'.
  94. *
  95. * \pre Both fifo descriptor and buffer must be allocated by the caller before.
  96. *
  97. * \param fifo_desc Pointer on the FIFO descriptor.
  98. * \param buffer Pointer on the FIFO buffer.
  99. * \param size Size of the buffer (unit is in number of 'elements').
  100. * It must be a 2-power and <= to 128.
  101. *
  102. * \return Status
  103. * \retval FIFO_OK when no error occurred.
  104. * \retval FIFO_ERROR when the size is not a 2-power.
  105. */
  106. int fifo_init(fifo_desc_t *fifo_desc, void *buffer, uint8_t size);
  107. /**
  108. * \brief Returns the number of elements in the FIFO.
  109. *
  110. * \param fifo_desc The FIFO descriptor.
  111. *
  112. * \return The number of used elements.
  113. */
  114. static inline uint8_t fifo_get_used_size(fifo_desc_t *fifo_desc)
  115. {
  116. return ((fifo_desc->write_index - fifo_desc->read_index) & fifo_desc->mask);
  117. }
  118. /**
  119. * \brief Returns the remaining free spaces of the FIFO (in number of elements).
  120. *
  121. * \param fifo_desc The FIFO descriptor.
  122. *
  123. * \return The number of free elements.
  124. */
  125. static inline uint8_t fifo_get_free_size(fifo_desc_t *fifo_desc)
  126. {
  127. return fifo_desc->size - fifo_get_used_size(fifo_desc);
  128. }
  129. /**
  130. * \brief Tests if a FIFO is empty.
  131. *
  132. * \param fifo_desc The FIFO descriptor.
  133. *
  134. * \return Status
  135. * \retval true when the FIFO is empty.
  136. * \retval false when the FIFO is not empty.
  137. */
  138. static inline bool fifo_is_empty(fifo_desc_t *fifo_desc)
  139. {
  140. return (fifo_desc->write_index == fifo_desc->read_index);
  141. }
  142. /**
  143. * \brief Tests if a FIFO is full.
  144. *
  145. * \param fifo_desc The FIFO descriptor.
  146. *
  147. * \return Status
  148. * \retval true when the FIFO is full.
  149. * \retval false when the FIFO is not full.
  150. */
  151. static inline bool fifo_is_full(fifo_desc_t *fifo_desc)
  152. {
  153. return (fifo_get_used_size(fifo_desc) == fifo_desc->size);
  154. }
  155. /**
  156. * \brief Puts a new 8-bits element into the FIFO.
  157. *
  158. * \param fifo_desc The FIFO descriptor.
  159. * \param item extracted element.
  160. */
  161. static inline void fifo_push_uint8_nocheck(fifo_desc_t *fifo_desc, uint32_t item)
  162. {
  163. uint8_t write_index;
  164. write_index = fifo_desc->write_index;
  165. fifo_desc->buffer.u8ptr[write_index & (fifo_desc->mask >> 1)] = item;
  166. write_index = (write_index + 1) & fifo_desc->mask;
  167. // Must be the last thing to do.
  168. barrier();
  169. fifo_desc->write_index = write_index;
  170. }
  171. /**
  172. * \brief Puts a new 8-bits element into the FIFO and
  173. * checks for a possible overflow.
  174. *
  175. * \param fifo_desc The FIFO descriptor.
  176. * \param item extracted element.
  177. *
  178. * \return Status
  179. * \retval FIFO_OK when no error occurred.
  180. * \retval FIFO_ERROR_UNDERFLOW when the FIFO was empty.
  181. */
  182. static inline int fifo_push_uint8(fifo_desc_t *fifo_desc, uint32_t item)
  183. {
  184. uint8_t write_index;
  185. if (fifo_is_full(fifo_desc)) {
  186. return FIFO_ERROR_OVERFLOW;
  187. }
  188. write_index = fifo_desc->write_index;
  189. fifo_desc->buffer.u8ptr[write_index & (fifo_desc->mask >> 1)] = item;
  190. write_index = (write_index + 1) & fifo_desc->mask;
  191. // Must be the last thing to do.
  192. barrier();
  193. fifo_desc->write_index = write_index;
  194. return FIFO_OK;
  195. }
  196. /**
  197. * \brief Puts a new 16-bits element into the FIFO.
  198. *
  199. * \param fifo_desc The FIFO descriptor.
  200. * \param item extracted element.
  201. */
  202. static inline void fifo_push_uint16_nocheck(fifo_desc_t *fifo_desc, uint32_t item)
  203. {
  204. uint8_t write_index;
  205. write_index = fifo_desc->write_index;
  206. fifo_desc->buffer.u16ptr[write_index & (fifo_desc->mask >> 1)] = item;
  207. write_index = (write_index + 1) & fifo_desc->mask;
  208. // Must be the last thing to do.
  209. barrier();
  210. fifo_desc->write_index = write_index;
  211. }
  212. /**
  213. * \brief Puts a new 16-bits element into the FIFO and
  214. * checks for a possible overflow.
  215. *
  216. * \param fifo_desc The FIFO descriptor.
  217. * \param item extracted element.
  218. *
  219. * \return Status
  220. * \retval FIFO_OK when no error occurred.
  221. * \retval FIFO_ERROR_UNDERFLOW when the FIFO was empty.
  222. */
  223. static inline int fifo_push_uint16(fifo_desc_t *fifo_desc, uint32_t item)
  224. {
  225. uint8_t write_index;
  226. if (fifo_is_full(fifo_desc)) {
  227. return FIFO_ERROR_OVERFLOW;
  228. }
  229. write_index = fifo_desc->write_index;
  230. fifo_desc->buffer.u16ptr[write_index & (fifo_desc->mask >> 1)] = item;
  231. write_index = (write_index + 1) & fifo_desc->mask;
  232. // Must be the last thing to do.
  233. barrier();
  234. fifo_desc->write_index = write_index;
  235. return FIFO_OK;
  236. }
  237. /**
  238. * \brief Puts a new 32-bits element into the FIFO.
  239. *
  240. * \param fifo_desc The FIFO descriptor.
  241. * \param item extracted element.
  242. */
  243. static inline void fifo_push_uint32_nocheck(fifo_desc_t *fifo_desc, uint32_t item)
  244. {
  245. uint8_t write_index;
  246. write_index = fifo_desc->write_index;
  247. fifo_desc->buffer.u32ptr[write_index & (fifo_desc->mask >> 1)] = item;
  248. write_index = (write_index + 1) & fifo_desc->mask;
  249. // Must be the last thing to do.
  250. barrier();
  251. fifo_desc->write_index = write_index;
  252. }
  253. /**
  254. * \brief Puts a new 32-bits element into the FIFO and
  255. * checks for a possible overflow.
  256. *
  257. * \param fifo_desc The FIFO descriptor.
  258. * \param item extracted element.
  259. *
  260. * \return Status
  261. * \retval FIFO_OK when no error occurred.
  262. * \retval FIFO_ERROR_UNDERFLOW when the FIFO was empty.
  263. */
  264. static inline int fifo_push_uint32(fifo_desc_t *fifo_desc, uint32_t item)
  265. {
  266. uint8_t write_index;
  267. if (fifo_is_full(fifo_desc)) {
  268. return FIFO_ERROR_OVERFLOW;
  269. }
  270. write_index = fifo_desc->write_index;
  271. fifo_desc->buffer.u32ptr[write_index & (fifo_desc->mask >> 1)] = item;
  272. write_index = (write_index + 1) & fifo_desc->mask;
  273. // Must be the last thing to do.
  274. barrier();
  275. fifo_desc->write_index = write_index;
  276. return FIFO_OK;
  277. }
  278. /**
  279. * \brief Gets a 8-bits element from the FIFO.
  280. *
  281. * \param fifo_desc The FIFO descriptor.
  282. *
  283. * \return extracted element.
  284. */
  285. static inline uint8_t fifo_pull_uint8_nocheck(fifo_desc_t *fifo_desc)
  286. {
  287. uint8_t read_index;
  288. uint8_t item;
  289. read_index = fifo_desc->read_index;
  290. item = fifo_desc->buffer.u8ptr[read_index & (fifo_desc->mask >> 1)];
  291. read_index = (read_index + 1) & fifo_desc->mask;
  292. // Must be the last thing to do.
  293. barrier();
  294. fifo_desc->read_index = read_index;
  295. return item;
  296. }
  297. /**
  298. * \brief Gets a 8-bits element from the FIFO and
  299. * checks for a possible underflow.
  300. *
  301. * \param fifo_desc The FIFO descriptor.
  302. * \param item extracted element.
  303. *
  304. * \return Status
  305. * \retval FIFO_OK when no error occurred.
  306. * \retval FIFO_ERROR_UNDERFLOW when the FIFO was empty.
  307. */
  308. static inline int fifo_pull_uint8(fifo_desc_t *fifo_desc, uint8_t *item)
  309. {
  310. uint8_t read_index;
  311. if (fifo_is_empty(fifo_desc)) {
  312. return FIFO_ERROR_UNDERFLOW;
  313. }
  314. read_index = fifo_desc->read_index;
  315. *item = fifo_desc->buffer.u8ptr[read_index & (fifo_desc->mask >> 1)];
  316. read_index = (read_index + 1) & fifo_desc->mask;
  317. // Must be the last thing to do.
  318. barrier();
  319. fifo_desc->read_index = read_index;
  320. return FIFO_OK;
  321. }
  322. /**
  323. * \brief Gets a 16-bits element from the FIFO.
  324. *
  325. * \param fifo_desc The FIFO descriptor.
  326. *
  327. * \return extracted element.
  328. */
  329. static inline uint16_t fifo_pull_uint16_nocheck(fifo_desc_t *fifo_desc)
  330. {
  331. uint8_t read_index;
  332. uint16_t item;
  333. read_index = fifo_desc->read_index;
  334. item = fifo_desc->buffer.u16ptr[read_index & (fifo_desc->mask >> 1)];
  335. read_index = (read_index + 1) & fifo_desc->mask;
  336. // Must be the last thing to do.
  337. barrier();
  338. fifo_desc->read_index = read_index;
  339. return item;
  340. }
  341. /**
  342. * \brief Gets a 16-bits element from the FIFO and
  343. * checks for a possible underflow.
  344. *
  345. * \param fifo_desc The FIFO descriptor.
  346. * \param item extracted element.
  347. *
  348. * \return Status
  349. * \retval FIFO_OK when no error occurred.
  350. * \retval FIFO_ERROR_UNDERFLOW when the FIFO was empty.
  351. */
  352. static inline int fifo_pull_uint16(fifo_desc_t *fifo_desc, uint16_t *item)
  353. {
  354. uint8_t read_index;
  355. if (fifo_is_empty(fifo_desc)) {
  356. return FIFO_ERROR_UNDERFLOW;
  357. }
  358. read_index = fifo_desc->read_index;
  359. *item = fifo_desc->buffer.u16ptr[read_index & (fifo_desc->mask >> 1)];
  360. read_index = (read_index + 1) & fifo_desc->mask;
  361. // Must be the last thing to do.
  362. barrier();
  363. fifo_desc->read_index = read_index;
  364. return FIFO_OK;
  365. }
  366. /**
  367. * \brief Gets a 32-bits element from the FIFO
  368. *
  369. * \param fifo_desc The FIFO descriptor.
  370. *
  371. * \return extracted element.
  372. */
  373. static inline uint32_t fifo_pull_uint32_nocheck(fifo_desc_t *fifo_desc)
  374. {
  375. uint8_t read_index;
  376. uint32_t item;
  377. read_index = fifo_desc->read_index;
  378. item = fifo_desc->buffer.u32ptr[read_index & (fifo_desc->mask >> 1)];
  379. read_index = (read_index + 1) & fifo_desc->mask;
  380. // Must be the last thing to do.
  381. barrier();
  382. fifo_desc->read_index = read_index;
  383. return item;
  384. }
  385. /**
  386. * \brief Gets a 32-bits element from the FIFO and
  387. * checks for a possible underflow.
  388. *
  389. * \param fifo_desc The FIFO descriptor.
  390. * \param item extracted element.
  391. *
  392. * \return Status
  393. * \retval FIFO_OK when no error occurred.
  394. * \retval FIFO_ERROR_UNDERFLOW when the FIFO was empty.
  395. */
  396. static inline int fifo_pull_uint32(fifo_desc_t *fifo_desc, uint32_t *item)
  397. {
  398. uint8_t read_index;
  399. if (fifo_is_empty(fifo_desc)) {
  400. return FIFO_ERROR_UNDERFLOW;
  401. }
  402. read_index = fifo_desc->read_index;
  403. *item = fifo_desc->buffer.u32ptr[read_index & (fifo_desc->mask >> 1)];
  404. read_index = (read_index + 1) & fifo_desc->mask;
  405. // Must be the last thing to do.
  406. barrier();
  407. fifo_desc->read_index = read_index;
  408. return FIFO_OK;
  409. }
  410. /**
  411. * \brief Gets a 32-bits element from the FIFO but does
  412. * not remove it from the FIFO.
  413. *
  414. * \param fifo_desc The FIFO descriptor.
  415. *
  416. * \retval item extracted element.
  417. */
  418. static inline uint32_t fifo_peek_uint32(fifo_desc_t *fifo_desc)
  419. {
  420. return fifo_desc->buffer.u32ptr[fifo_desc->read_index & (fifo_desc->mask >> 1)];
  421. }
  422. /**
  423. * \brief Gets a 16-bits element from the FIFO but does
  424. * not remove it from the FIFO.
  425. *
  426. * \param fifo_desc The FIFO descriptor.
  427. *
  428. * \retval item extracted element.
  429. */
  430. static inline uint16_t fifo_peek_uint16(fifo_desc_t *fifo_desc)
  431. {
  432. return fifo_desc->buffer.u16ptr[fifo_desc->read_index & (fifo_desc->mask >> 1)];
  433. }
  434. /**
  435. * \brief Gets a 8-bits element from the FIFO but does
  436. * not remove it from the FIFO.
  437. *
  438. * \param fifo_desc The FIFO descriptor.
  439. *
  440. * \retval item extracted element.
  441. */
  442. static inline uint8_t fifo_peek_uint8(fifo_desc_t *fifo_desc)
  443. {
  444. return fifo_desc->buffer.u8ptr[fifo_desc->read_index & (fifo_desc->mask >> 1)];
  445. }
  446. /**
  447. * \brief Flushes a software FIFO.
  448. *
  449. * \param fifo_desc The FIFO descriptor.
  450. */
  451. static inline void fifo_flush(fifo_desc_t *fifo_desc)
  452. {
  453. // Fifo starts empty.
  454. fifo_desc->read_index = fifo_desc->write_index = 0;
  455. }
  456. /**
  457. * @}
  458. */
  459. /**
  460. * \page fifo_quickstart Quick start guide for First-In-First-Out Buffer (FIFO)
  461. *
  462. * This is the quick start guide for the \ref fifo_group, with
  463. * step-by-step instructions on how to configure and use the driver in a
  464. * selection of use cases.
  465. *
  466. * The use cases contain several code fragments. The code fragments in the
  467. * steps for setup can be copied into a custom initialization function, while
  468. * the steps for usage can be copied into, e.g., the main application function.
  469. *
  470. * \section fifo_use_cases FIFO use cases
  471. * - \ref fifo_basic_use_case
  472. * - \subpage fifo_use_case_1
  473. *
  474. * \section fifo_basic_use_case Basic use case - Push and pull
  475. * In this use case, an element will be pushed to the FIFO, and the same
  476. * element will be pulled from it.
  477. *
  478. * \section fifo_basic_use_case_setup Setup steps
  479. *
  480. * \subsection fifo_basic_use_case_setup_code Example code
  481. * The following must be added to the project:
  482. * \code
  483. #define FIFO_BUFFER_LENGTH 4
  484. #define PUSH_VALUE 0x12345678
  485. union buffer_element {
  486. uint8_t byte;
  487. uint16_t halfword;
  488. uint32_t word;
  489. };
  490. \endcode
  491. *
  492. * Add to application initialization:
  493. * \code
  494. union buffer_element fifo_buffer[FIFO_BUFFER_LENGTH];
  495. fifo_desc_t fifo_desc;
  496. fifo_init(&fifo_desc, fifo_buffer, FIFO_BUFFER_LENGTH);
  497. \endcode
  498. *
  499. * \subsection fifo_basic_use_case_setup_flow Workflow
  500. * -# Create a FIFO buffer of FIFO_BUFFER_LENGTH elements, capable
  501. * of holding a byte, halfword or word:
  502. * - \code union buffer_element fifo_buffer[FIFO_BUFFER_LENGTH]; \endcode
  503. * -# Create a FIFO buffer descriptor that contains information about the
  504. * location of the FIFO buffer, its size and where to read from or write to
  505. * upon the next buffer pull or push:
  506. * - \code fifo_desc_t fifo_desc; \endcode
  507. * -# Initialize the FIFO:
  508. * - \code fifo_init(&fifo_desc, fifo_buffer, FIFO_BUFFER_LENGTH); \endcode
  509. *
  510. * \section fifo_basic_use_case_usage Usage steps
  511. *
  512. * \subsection fifo_basic_use_case_usage_code Example code
  513. * Add to application C-file:
  514. * \code
  515. uint8_t status;
  516. uint8_t pull_value;
  517. status = fifo_push_uint8(&fifo_desc, PUSH_VALUE & 0xff);
  518. status = fifo_pull_uint8(&fifo_desc, &pull_value);
  519. \endcode
  520. *
  521. * \subsection fifo_basic_use_case_usage_flow Workflow
  522. * -# Create a variable to hold the return status from the FIFO:
  523. * - \code uint8_t status; \endcode
  524. * -# Create a variable to hold the pulled value from the FIFO:
  525. * - \code uint8_t pull_value; \endcode
  526. * -# Put a new 8-bit element into the FIFO:
  527. * - \code status = fifo_push_uint8(&fifo_desc, PUSH_VALUE & 0xff); \endcode
  528. * \note The status variable will contain \ref FIFO_OK if no error occurred.
  529. * -# Get the 8-bit element from the FIFO:
  530. * - \code status = fifo_pull_uint8(&fifo_desc, &pull_value); \endcode
  531. * \note The status variable will contain \ref FIFO_OK if no error occurred.
  532. */
  533. /**
  534. * \page fifo_use_case_1 Push and flush
  535. *
  536. * In this use case, two elements will be pushed to the FIFO, and the FIFO
  537. * will be flushed.
  538. *
  539. * \section fifo_use_case_1_setup Setup steps
  540. *
  541. * \subsection fifo_use_case_1_setup_code Example code
  542. * The following must be added to the project:
  543. * \code
  544. #define FIFO_BUFFER_LENGTH 4
  545. #define PUSH_VALUE 0x12345678
  546. union buffer_element {
  547. uint8_t byte;
  548. uint16_t halfword;
  549. uint32_t word;
  550. };
  551. \endcode
  552. *
  553. * Add to application initialization:
  554. * \code
  555. union buffer_element fifo_buffer[FIFO_BUFFER_LENGTH];
  556. fifo_desc_t fifo_desc;
  557. fifo_init(&fifo_desc, fifo_buffer, FIFO_BUFFER_LENGTH);
  558. \endcode
  559. *
  560. * \subsection fifo_use_case_1_setup_flow Workflow
  561. * -# Create a FIFO buffer of FIFO_BUFFER_LENGTH elements, capable
  562. * of holding a byte, halfword or word:
  563. * - \code union buffer_element fifo_buffer[FIFO_BUFFER_LENGTH]; \endcode
  564. * -# Create a FIFO buffer descriptor that containing information about the
  565. * location of the FIFO buffer, its size and where to read from or write to
  566. * upon the next buffer pull or push:
  567. * - \code fifo_desc_t fifo_desc; \endcode
  568. * -# Initialize the FIFO:
  569. * - \code fifo_init(&fifo_desc, fifo_buffer, FIFO_BUFFER_LENGTH); \endcode
  570. * \section fifo_use_case_1_usage Usage steps
  571. *
  572. * \subsection fifo_use_case_1_usage_code Example code
  573. * Add to application C-file:
  574. * \code
  575. uint8_t status;
  576. bool fifo_empty;
  577. status = fifo_push_uint16(&fifo_desc, PUSH_VALUE & 0xffff);
  578. status = fifo_push_uint16(&fifo_desc, PUSH_VALUE & 0xffff);
  579. fifo_flush(&fifo_desc);
  580. fifo_empty = fifo_is_empty(&fifo_desc);
  581. \endcode
  582. *
  583. * \subsection fifo_use_case_1_usage_flow Workflow
  584. * -# Create a variable to hold the return status from the FIFO:
  585. * - \code uint8_t status; \endcode
  586. * -# Create a variable to hold the pulled value from the FIFO:
  587. * - \code uint16_t pull_value; \endcode
  588. * -# Put two new 16-bit element into the FIFO:
  589. * - \code status = fifo_push_uint16(&fifo_desc, PUSH_VALUE & 0xffff); \endcode
  590. * - \code status = fifo_push_uint16(&fifo_desc, PUSH_VALUE & 0xffff); \endcode
  591. * \note The status variable will contain \ref FIFO_OK if no error occurred.
  592. * -# Flush the FIFO:
  593. * - \code fifo_flush(&fifo_desc); \endcode
  594. * -# Check that the FIFO is empty after flushing:
  595. * - \code fifo_empty = fifo_is_empty(&fifo_desc); \endcode
  596. * \note The fifo_empty variable will be true if the FIFO is empty.
  597. */
  598. #endif // _FIFO_H_