Modbus Library Test Coverage Report

lib/queue/
File: queue.c
Date: 2025-11-06 14:02:28
Lines:
57 of 57, 0 excluded
100.0%
Functions:
7 of 7, 0 excluded
100.0%
Branches:
28 of 32, 0 excluded
87.5%
Line Branch Exec Source
1 /**
2 * @file queue.c
3 * @brief Generic FIFO queue implementation for embedded safety-critical use.
4 * @version 1.0.3
5 * @date 2025-11-06
6 *
7 * @details
8 * Provides deterministic enqueue/dequeue operations on a caller-supplied
9 * memory buffer. Implementation uses explicit byte-wise copying and avoids
10 * standard library dependencies to ensure predictable timing.
11 *
12 * MISRA Deviation: DV-QUEUE-001 (Rule 11.4)
13 * Controlled cast from `void*` to `uint8_t*` for raw byte access.
14 * Safe because data is not type-reinterpreted.
15 *
16 * @ingroup queue
17 */
18
19 #include "queue.h"
20 #include <stddef.h> /* for NULL */
21
22 /* PRIVATE macro controls linkage:
23 * - static in production builds
24 * - global in UNIT_TESTS build for unit test visibility.
25 */
26 #ifdef UNIT_TESTS
27 #define PRIVATE
28 #else
29 #define PRIVATE static
30 #endif
31
32 /* Internal helper: byte-wise deterministic copy.
33 * @note MISRA Deviation DV-QUEUE-001 applies here.
34 * Do not expose externally; tested via queue_push/queue_pop. */
35 PRIVATE void copy_bytes(uint8_t *dst, const uint8_t *src, uint16_t size);
36 static bool validate_init_arg(const queue_t *q, const void *buffer, uint16_t buffer_element_size, uint16_t queue_capacity);
37
38 /* -------------------------- */
39 /* Queue API implementation */
40 /* -------------------------- */
41
42 35 queue_status_t queue_init(queue_t *q, void *buffer, uint16_t buffer_element_size, uint16_t queue_capacity)
43 {
44 35 queue_status_t ret_status = QUEUE_OK;
45
46
2/2
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 27 times.
 35 if (validate_init_arg(q, buffer, buffer_element_size, queue_capacity))
47 {
48 8 ret_status = QUEUE_ERROR;
49 }
50 else
51 {
52 27 q->buffer = buffer;
53 27 q->buffer_element_size = buffer_element_size;
54 27 q->capacity = queue_capacity;
55 27 q->head = 0U;
56 27 q->tail = 0U;
57 27 q->count = 0U;
58 }
59
60 35 return ret_status;
61 }
62
63 31 queue_status_t queue_push(queue_t *q, const void *item)
64 {
65 31 queue_status_t ret_status = QUEUE_OK;
66
67
3/4
✓ Branch 0 taken 31 times.
✗ Branch 1 not taken.
✓ Branch 2 taken 2 times.
✓ Branch 3 taken 29 times.
 31 if ((q == NULL) || (item == NULL))
68 {
69 2 ret_status = QUEUE_ERROR;
70 }
71
2/2
✓ Branch 0 taken 1 time.
✓ Branch 1 taken 28 times.
 29 else if (q->count >= q->capacity)
72 {
73 1 ret_status = QUEUE_FULL;
74 }
75 else
76 {
77 /* MISRA Deviation DV-QUEUE-001: controlled cast for byte-wise copy */
78 28 uint8_t *base = (uint8_t *)q->buffer;
79 28 const uint32_t offset = (uint32_t)q->tail * (uint32_t)q->buffer_element_size;
80
81 28 copy_bytes(&base[offset], (const uint8_t *)item, q->buffer_element_size);
82
83 28 q->tail = (uint16_t)(((uint32_t)q->tail + 1U) % (uint32_t)q->capacity);
84 28 q->count = (uint16_t)((uint32_t)q->count + 1U);
85 }
86
87 31 return ret_status;
88 }
89
90 21 queue_status_t queue_pop(queue_t *q, void *item)
91 {
92 21 queue_status_t ret_status = QUEUE_OK;
93
94
3/4
✓ Branch 0 taken 21 times.
✗ Branch 1 not taken.
✓ Branch 2 taken 2 times.
✓ Branch 3 taken 19 times.
 21 if ((q == NULL) || (item == NULL))
95 {
96 2 ret_status = QUEUE_ERROR;
97 }
98
2/2
✓ Branch 0 taken 1 time.
✓ Branch 1 taken 18 times.
 19 else if (q->count == 0U)
99 {
100 1 ret_status = QUEUE_EMPTY;
101 }
102 else
103 {
104 /* MISRA Deviation DV-QUEUE-001: controlled cast for byte-wise copy */
105 18 const uint8_t *base = (const uint8_t *)q->buffer;
106 18 const uint32_t offset = (uint32_t)q->head * (uint32_t)q->buffer_element_size;
107
108 18 copy_bytes((uint8_t *)item, &base[offset], q->buffer_element_size);
109
110 18 q->head = (uint16_t)(((uint32_t)q->head + 1U) % (uint32_t)q->capacity);
111 18 q->count = (uint16_t)((uint32_t)q->count - 1U);
112 }
113
114 21 return ret_status;
115 }
116
117 7 bool queue_is_empty(const queue_t *q)
118 {
119 7 bool is_empty = true;
120
121
1/2
✓ Branch 0 taken 7 times.
✗ Branch 1 not taken.
 7 if (q != NULL)
122 {
123 7 is_empty = (q->count == 0U);
124 }
125
126 7 return is_empty;
127 }
128
129 4 bool queue_is_full(const queue_t *q)
130 {
131 4 bool is_full = false;
132
133
1/2
✓ Branch 0 taken 4 times.
✗ Branch 1 not taken.
 4 if (q != NULL)
134 {
135 4 is_full = (q->count == q->capacity);
136 }
137
138 4 return is_full;
139 }
140
141 /* -------------------------- */
142 /* Internal helper functions */
143 /* -------------------------- */
144 /**
145 * @defgroup queue_internal Queue Internal Functions
146 * @ingroup queue
147 * @brief Internal helper functions for the queue module (not part of public API).
148 * @details
149 * These functions are local to `queue.c` and not exposed in `queue.h`.
150 * They support deterministic byte copying and argument validation.
151 * @{
152 */
153
154 /**
155 * @brief Deterministic byte-wise copy of memory.
156 *
157 * @param[out] dst Destination buffer (non-NULL).
158 * @param[in] src Source buffer (non-NULL).
159 * @param[in] size Number of bytes to copy.
160 *
161 * @details
162 * Used internally by queue_push/queue_pop to copy arbitrary elements
163 * in a deterministic, type-agnostic way.
164 *
165 * @note MISRA Deviation DV-QUEUE-001 applies.
166 */
167 49 PRIVATE void copy_bytes(uint8_t *dst, const uint8_t *src, uint16_t size)
168 {
169
4/4
✓ Branch 0 taken 47 times.
✓ Branch 1 taken 2 times.
✓ Branch 2 taken 46 times.
✓ Branch 3 taken 1 time.
 49 if ((dst != NULL) && (src != NULL))
170 {
171
2/2
✓ Branch 0 taken 178 times.
✓ Branch 1 taken 46 times.
 224 for (uint16_t i = 0U; i < size; i = (uint16_t)(i + 1U))
172 {
173 178 dst[i] = src[i];
174 }
175 }
176 else
177 {
178 /* Defensive path: do nothing if invalid pointers */
179 }
180 49 }
181
182 /**
183 * @brief Validate queue initialization parameters.
184 *
185 * @param[in] q Queue structure pointer.
186 * @param[in] buffer Data buffer pointer.
187 * @param[in] buffer_element_size Element size in bytes.
188 * @param[in] queue_capacity Maximum number of elements.
189 *
190 * @return true — invalid argument(s).
191 * @return false — all parameters valid.
192 */
193 35 static bool validate_init_arg(const queue_t *q, const void *buffer, uint16_t buffer_element_size, uint16_t queue_capacity)
194 {
195 35 bool invalid = false;
196
197
4/4
✓ Branch 0 taken 33 times.
✓ Branch 1 taken 2 times.
✓ Branch 2 taken 31 times.
✓ Branch 3 taken 2 times.
 35 if ((q == NULL) ||
198
2/2
✓ Branch 0 taken 29 times.
✓ Branch 1 taken 2 times.
 31 (buffer == NULL) ||
199
2/2
✓ Branch 0 taken 2 times.
✓ Branch 1 taken 27 times.
 29 (buffer_element_size == 0U) ||
200 (queue_capacity == 0U))
201 {
202 8 invalid = true;
203 }
204
205 35 return invalid;
206 }
207
208 /** @} */ /* end of queue_internal group */
209