246 lines
12 KiB
C
246 lines
12 KiB
C
/* ----> 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
|
|
|