1 //*****************************************************************************
2 //
3 //  am_hal_queue.h
4 //! @file
5 //!
6 //! @brief Functions for implementing a queue system.
7 //!
8 //! @addtogroup Miscellaneous2 Software Features (MISC)
9 //! @ingroup apollo2hal
10 //! @{
11 //
12 //*****************************************************************************
13 
14 //*****************************************************************************
15 //
16 // Copyright (c) 2017, Ambiq Micro
17 // All rights reserved.
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
26 // notice, this list of conditions and the following disclaimer in the
27 // documentation and/or other materials provided with the distribution.
28 //
29 // 3. Neither the name of the copyright holder nor the names of its
30 // contributors may be used to endorse or promote products derived from this
31 // software without specific prior written permission.
32 //
33 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
34 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
35 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
36 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
37 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
38 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
39 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
40 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
41 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
42 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
43 // POSSIBILITY OF SUCH DAMAGE.
44 //
45 // This is part of revision 1.2.11 of the AmbiqSuite Development Package.
46 //
47 //*****************************************************************************
48 #ifndef AM_HAL_QUEUE_H
49 #define AM_HAL_QUEUE_H
50 
51 //*****************************************************************************
52 //
53 //! @brief A data structure that will operate as a queue.
54 //!
55 //! This data structure holds information necessary for operating a thread-safe
56 //! queue. When declaring a structure of type am_hal_queue_t, you will also need
57 //! to provide some working memory for the queue to use. For more information on
58 //! setting up and using the am_hal_queue_t structure, please see the
59 //! documentation for am_hal_queue_init().
60 //
61 //*****************************************************************************
62 typedef struct
63 {
64     uint32_t ui32WriteIndex;
65     uint32_t ui32ReadIndex;
66     uint32_t ui32Length;
67     uint32_t ui32Capacity;
68     uint32_t ui32ItemSize;
69     uint8_t *pui8Data;
70 }
71 am_hal_queue_t;
72 
73 //*****************************************************************************
74 //
75 // Function-like macros.
76 //
77 //*****************************************************************************
78 #define am_hal_queue_empty(psQueue)                                           \
79     ((psQueue)->ui32Length == 0)
80 
81 #define am_hal_queue_full(psQueue)                                            \
82     ((psQueue)->ui32Length == (psQueue)->ui32Capacity)
83 
84 #define am_hal_queue_space_left(psQueue)                                      \
85     ((psQueue)->ui32Capacity - (psQueue)->ui32Length)
86 
87 #define am_hal_queue_data_left(psQueue)                                       \
88     ((psQueue)->ui32Length)
89 
90 //*****************************************************************************
91 //
92 // Use this to make sure you get the size parameters right.
93 //
94 //*****************************************************************************
95 #define am_hal_queue_from_array(queue, array)                                 \
96     am_hal_queue_init((queue), (array), sizeof((array)[0]), sizeof(array))
97 
98 #ifdef __cplusplus
99 extern "C"
100 {
101 #endif
102 
103 //*****************************************************************************
104 //
105 // External function definitions.
106 //
107 //*****************************************************************************
108 extern void am_hal_queue_init(am_hal_queue_t *psQueue, void *pvData, uint32_t ui32ItemSize, uint32_t ui32ArraySize);
109 extern bool am_hal_queue_item_add(am_hal_queue_t *psQueue, const void *pvSource, uint32_t ui32NumItems);
110 extern bool am_hal_queue_item_get(am_hal_queue_t *psQueue, void *pvDest, uint32_t ui32NumItems);
111 
112 #ifdef __cplusplus
113 }
114 #endif
115 
116 #endif // AM_HAL_QUEUE_H
117 
118 //*****************************************************************************
119 //
120 // End Doxygen group.
121 //! @}
122 //
123 //*****************************************************************************
124