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
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
|
/* ----> DO NOT REMOVE THE FOLLOWING NOTICE <----
Copyright (c) 2014-2017 Datalight, Inc.
All Rights Reserved Worldwide.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; use version 2 of the License.
This program is distributed in the hope that it will be useful,
but "AS-IS," WITHOUT ANY WARRANTY; without even the implied warranty
of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
/* Businesses and individuals that for commercial or other reasons cannot
comply with the terms of the GPLv2 license may obtain a commercial license
before incorporating Reliance Edge into proprietary software for
distribution in any form. Visit http://www.datalight.com/reliance-edge for
more information.
*/
/** @file
@brief Macros to encapsulate MISRA C:2012 deviations in OS-specific code.
*/
#ifndef REDOSDEVIATIONS_H
#define REDOSDEVIATIONS_H
#if REDCONF_OUTPUT == 1
/* Needed for PRINT_ASSERT() and OUTPUT_CHARACTER().
*/
#include <stdio.h>
#endif
#if (REDCONF_ASSERTS == 1) && (REDCONF_OUTPUT == 1)
/** @brief Print a formatted message for an assertion.
Usages of this macro deviate from MISRA C:2012 Rule 21.6 (required). Using
printf() is the most convenient way to output this information; and the risk
of "unspecified, undefined and implementation-defined" behavior causing
problems (as cited in the rationale for the rule) is small. The driver does
not depend on this string being outputted correctly. Furthermore, use of
printf() disappears when either asserts or output are disabled.
As Rule 21.6 is required, a separate deviation record is required.
*/
#define PRINT_ASSERT(file, line) \
printf("Assertion failed in \"%s\" at line %u\n\r", ((file) == NULL) ? "" : (file), (unsigned)(line))
#endif
/** @brief Cast a value to unsigned long.
Usages of this macro deviate from MISRA C:2012 Directive 4.6. This macro is
used in two places to cast a uint64_t value (used by the block device
abstraction for sector numbers) to unsigned long, since third-party code
which is not under the control of this project uses unsigned long for sector
numbers. The cast is guaranteed to not lose any information, since when the
disk is opened the sector count is verified to be less than or equal to an
unsigned long value. The text of the directive mentions that "it might be
desirable not to apply this guideline when interfacing with ... code outside
the project's control", which describes the situation for this deviation.
As Directive 4.6 is advisory, a deviation record is not required. This
notice is the only record of the deviation.
*/
#define CAST_ULONG(ull) ((unsigned long)(ull))
/** @brief Cast a const-qualified pointer to a pointer which is *not*
const-qualified.
Usages of this macro deviate from MISRA C:2012 Rule 11.8. This macro is
used in exactly one place in order to cope with a poorly designed
third-party interface. Reliance Edge, at every level of the stack, uses
const-qualified pointers for buffers used in write operations, since the
data is read from the buffer, and the buffer does not need to be modified
(consistent with Rule 8.13). One of the third-party block device interfaces
that Reliance Edge interfaces with does not follow this convention: it uses
an unqualified pointer for the buffer parameter of its sector write
function. This forces the need for the cast to avoid warnings. The
implementation of the sector write function is provided by the user, so it
is to be hoped that the buffer is not actually modified.
As Rule 11.8 is required, a separate deviation record is required.
*/
#define CAST_AWAY_CONST(type, ptr) ((type *)(ptr))
/** @brief Allocate zero-initialized (cleared) memory.
All usages of this macro deviate from MISRA C:2012 Directive 4.12 (required)
and Rule 21.3 (required). In the context of the single place it is actually
used, this macro also deviates from Rule 22.1 (required).
This macro is used in the FreeRTOS block device code in order to allocate a
RAM disk, when that implementation of the block device is selected. The
primary rationale for all these deviations is that a) the RAM disk cannot be
allocated statically (since the volume information is stored in a
structure), and b) the RAM disk is primarily intended as a temporary testing
tool for users who want to try out Reliance Edge before the real storage
media is available. In most real systems, Reliance Edge is used with
non-volatile storage like SD/MMC or eMMC, not with RAM disks.
Rule 22.1 states that all resources which are allocated must also be
explicitly freed. The RAM disk is allocated and never freed, deviating from
that rule. This is done because the data in the RAM disk is emulating a
non-volatile storage medium, and thus needs to persist even after the block
device is closed, to allow the file system to be ormatted and then mounted,
or unmounted and remounted in the course of a test. Thus the memory will
remain allocated until the target device is rebooted. This is assumed to be
acceptable for the primary purpose of the RAM disk, which is preliminary
testing.
As Directive 4.12, Rule 21.3, and Rule 22.1 are all required, separate
deviation records are required.
*/
#define ALLOCATE_CLEARED_MEMORY(nelem, elsize) calloc(nelem, elsize)
#if REDCONF_OUTPUT == 1
/** @brief Output a character to a serial port or other display device.
Usages of this macro deviate from MISRA C:2012 Rule 21.6 (required).
FreeRTOS does not include a standard method of printing characters, so
putchar() is the most convenient and portable way to accomplish the task.
The risk of "unspecified, undefined and implementation-defined" behavior
causing problems (as cited in the rationale for the rule) is small. The
driver does not depend on the character being outputted correctly.
Furthermore, use of putchar() disappears when output is disabled.
As Rule 21.6 is required, a separate deviation record is required.
*/
#define OUTPUT_CHARACTER(ch) (void)putchar(ch)
#endif
#if (REDCONF_TASK_COUNT > 1U) && (REDCONF_API_POSIX == 1)
/** @brief Cast a TaskHandle_t (a pointer type) to uintptr_t.
Usage of this macro deivate from MISRA-C:2012 Rule 11.4 (advisory). This
macro is used for the FreeRTOS version of RedOsTaskId(). Some RTOSes
natively use an integer for task IDs; others use pointers. RedOsTaskId()
uses integers, FreeRTOS uses pointers; to reconcile this difference, the
pointer must be cast to integer. This is fairly safe, since the resulting
integer is never cast back to a pointer; and although the integer
representation of a pointer is implementation-defined, the representation is
irrelevant provided that unique pointers are converted to unique integers.
As Rule 11.4 is advisory, a deviation record is not required. This notice
is the only record of the deviation.
*/
#define CAST_TASK_PTR_TO_UINTPTR(taskptr) ((uintptr_t)(taskptr))
#endif
/** @brief Ignore the return value of a function (cast to void)
Usages of this macro deviate from MISRA C:2012 Directive 4.7, which states
that error information must be checked immediately after a function returns
potential error information.
If asserts and output are enabled, then this macro is used to document that
the return value of printf() is ignored. A failure of printf() does not
impact the filesystem core, nor is there anything the filesystem can do to
respond to such an error (especially since it occurs within an assert).
Thus, the most reasonable action is to ignore the error.
In the STM32 SDIO block device implementation, errors are also ignored in an
IRQ interrupt handler. This is the most reasonable action to take for two
reasons: (a) it would be dangerous to spend processor time responding to the
error inside the IRQ handler; (b) it has been verified that the same error
is propegated to the DiskRead/Write method, which does return the error to
the core.
In the Atmel SD/MMC block device implementation, error information from
sd_mmc_read_capacity() is ignored. This is a reasonable action because all
of the possible error conditions were eliminated by a previous check.
sd_mmc_read_capacity() fails under the same conditions as
sd_mmc_test_unit_ready(), which was checked ealier in the same function.
In the mutex module, error information returned from the mutex release
function is ignored when asserts are disabled. This is a reasonable action
because the mutex release function (xSemaphoreGive) is documented only to
fail if the mutex was not obtained correctly, which can be demonstrably
avoided.
As Directive 4.7 is required, a separate deviation record is required.
*/
#define IGNORE_ERRORS(fn) ((void) (fn))
/** @brief Determine whether a pointer is aligned on a 32-bit boundary.
This is used to determine whether a data buffer meets the requirements of
the underlying block device implementation. When transferring data via
DMA (Direct Memory Access) on an STM32 device, the data buffer must be cast
as a uint32 pointer, and unexpected behavior may occur if the buffer is not
aligned correctly.
There is no way to perform this check without deviating from MISRA C rules
against casting pointers to integer types. Usage of this macro deviates
from MISRA C:2012 Rule 11.4 (advisory). The main rationale the rule cites
against converting pointers to integers is that the chosen integer type may
not be able to represent the pointer; this is a non-issue here since we use
uintptr_t. The text says the rule still applies when using uintptr_t due to
concern about unaligned pointers, but that is not an issue here since the
integer value of the pointer is not saved and not converted back into a
pointer and dereferenced. The result of casting a pointer to a sufficiently
large integer is implementation-defined, but macros similar to this one have
been used by Datalight for a long time in a wide variety of environments and
they have always worked as expected.
This deviation only occurs when using the STM32 SDIO block device
implementation.
As Rule 11.4 is advisory, a deviation record is not required. This notice
is the only record of deviation.
*/
#define IS_UINT32_ALIGNED_PTR(ptr) (((uintptr_t)(ptr) & (sizeof(uint32_t) - 1U)) == 0U)
/** @brief Cast a 32-bit aligned void pointer to a uint32 pointer.
Usages of this macro deviate from MISRA C:2012 Rule 11.5 (advisory). A
cast from a void pointer to an object pointer is discouraged because of
potential alignment issues. However, this macro is only used to cast
pointers that have already been tested to be 32-bit aligned, so the
operation will be safe.
This deviation only occurs when using the STM32 SDIO block device
implementation.
As rule 11.5 is advisory, a deviation record is not required. This notice
is the only record of the deviation.
*/
#define CAST_UINT32_PTR(ptr) ((uint32_t *) (ptr))
#endif
|
