cfn_hal.h File Reference

Core Hardware Abstraction Layer definitions and macros. More...

#include "cfn_hal_types.h"
#include <stddef.h>

Go to the source code of this file.

Macros
#define	CFN_HAL_USE_LOCK   0
	Enable RTOS-aware thread safety for the HAL.
#define	CFN_HAL_INLINE   static inline
	Macro for inlining HAL wrapper functions. Can be overridden with attribute((always_inline)) for performance-critical ports.
#define	CFN_HAL_MAX_DELAY   (UINT32_MAX)
#define	CFN_HAL_STATIC_ASSERT   _Static_assert
	Cross-compiler static assertion macro. Uses C++11 static_assert or C11 _Static_assert to avoid dependency on <assert.h>.
#define	CFN_HAL_BIT(x)   ((1UL) << (uint32_t) (x))
#define	CFN_HAL_BIT_SET(x, y)   ((x) |= (CFN_HAL_BIT(y)))
#define	CFN_HAL_BIT_CLEAR(x, y)   ((x) &= ~(CFN_HAL_BIT(y)))
#define	CFN_HAL_BIT_TOGGLE(x, y)   ((x) ^= (CFN_HAL_BIT(y)))
#define	CFN_HAL_BIT_CHECK(x, y)   ((x) & (CFN_HAL_BIT(y)))
#define	CFN_HAL_BIT_IS_SET(x, y)   ((CFN_HAL_BIT_CHECK(x, y)) != 0)
#define	CFN_HAL_STR_STRINGIFY(x)   #x
#define	CFN_HAL_INTERNAL_CONCAT(x, y)   x##y
#define	CFN_HAL_CONCAT(x, y)   CFN_HAL_INTERNAL_CONCAT(x, y)
#define	CFN_HAL_UNUSED(x)   (void) (x)
#define	CFN_HAL_CONTAINER_OF(ptr, type, member)   ((type *) ((char *) (ptr) - offsetof(type, member)))
#define	CFN_HAL_GET_DRIVER_FROM_BASE(ptr, type)   CFN_HAL_CONTAINER_OF(ptr, type, base)
	Helper macro to get the peripheral driver pointer from a base driver pointer.
#define	CFN_HAL_CREATE_DRIVER_TYPE(prefix, config_type, api_type, phy_type, cb_type)
#define	CFN_HAL_CHECK_AND_CALL_FUNC(expected_peripheral_type, func, driver, result)
#define	CFN_HAL_CHECK_AND_CALL_FUNC_VARG(expected_peripheral_type, func, driver, result, ...)
#define	CFN_HAL_GET_LOCK_MACRO(_1, _2, _3, _4, _5, _6, _7, _8, _9, NAME, ...)   NAME
#define	CFN_HAL_LOCK(driver, timeout)   (CFN_HAL_ERROR_OK)
#define	CFN_HAL_UNLOCK(driver)   (CFN_HAL_ERROR_OK)
#define	CFN_HAL_WITH_LOCK_NO_LOCK_0(driver, timeout, result, function)
#define	CFN_HAL_WITH_LOCK_NO_LOCK_N(driver, timeout, result, function, ...)
#define	CFN_HAL_WITH_LOCK(...)
	Helper macro to execute a driver function (Locking disabled).

Detailed Description

Core Hardware Abstraction Layer definitions and macros.

Copyright (c) 2026 Hisham Moussa Daou https://www.whileone.me

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Macro Definition Documentation

CFN_HAL_BIT

#define CFN_HAL_BIT

(

x

)

((1UL) << (uint32_t) (x))

Bit position

CFN_HAL_BIT_CHECK

#define CFN_HAL_BIT_CHECK	(		x,
			y
	)		((x) & (CFN_HAL_BIT(y)))

Check if bit y is set in variable x

CFN_HAL_BIT_CLEAR

#define CFN_HAL_BIT_CLEAR	(		x,
			y
	)		((x) &= ~(CFN_HAL_BIT(y)))

Clear bit y of the variable x

CFN_HAL_BIT_IS_SET

#define CFN_HAL_BIT_IS_SET	(		x,
			y
	)		((CFN_HAL_BIT_CHECK(x, y)) != 0)

Check if bit y is set in variable x

CFN_HAL_BIT_SET

#define CFN_HAL_BIT_SET	(		x,
			y
	)		((x) |= (CFN_HAL_BIT(y)))

Set bit y of the variable X

CFN_HAL_BIT_TOGGLE

#define CFN_HAL_BIT_TOGGLE	(		x,
			y
	)		((x) ^= (CFN_HAL_BIT(y)))

Toggle bit y of the variable x

CFN_HAL_CHECK_AND_CALL_FUNC

#define CFN_HAL_CHECK_AND_CALL_FUNC	(		expected_peripheral_type,
			func,
			driver,
			result
	)

Value:

    do                                                                                                                 \
    {                                                                                                                  \
        if ((driver) && (driver)->base.type == (expected_peripheral_type) && (driver)->api)                            \
        {                                                                                                              \
            if ((driver)->api->func)                                                                                   \
            {                                                                                                          \
                (result) = (driver)->api->func((driver));                                                              \
            }                                                                                                          \
            else                                                                                                       \
            {                                                                                                          \
                (result) = CFN_HAL_ERROR_NOT_SUPPORTED;                                                                \
            }                                                                                                          \
        }                                                                                                              \
        else                                                                                                           \
        {                                                                                                              \
            (result) = CFN_HAL_ERROR_BAD_PARAM;                                                                        \
        }                                                                                                              \
    } while (0)

CFN_HAL_CHECK_AND_CALL_FUNC_VARG

#define CFN_HAL_CHECK_AND_CALL_FUNC_VARG	(		expected_peripheral_type,
			func,
			driver,
			result,
			...
	)

Value:

    do                                                                                                                 \
    {                                                                                                                  \
        if ((driver) && (driver)->base.type == (expected_peripheral_type) && (driver)->api)                            \
        {                                                                                                              \
            if ((driver)->api->func)                                                                                   \
            {                                                                                                          \
                (result) = (driver)->api->func((driver), __VA_ARGS__);                                                 \
            }                                                                                                          \
            else                                                                                                       \
            {                                                                                                          \
                (result) = CFN_HAL_ERROR_NOT_SUPPORTED;                                                                \
            }                                                                                                          \
        }                                                                                                              \
        else                                                                                                           \
        {                                                                                                              \
            (result) = CFN_HAL_ERROR_BAD_PARAM;                                                                        \
        }                                                                                                              \
    } while (0)

CFN_HAL_CONCAT

#define CFN_HAL_CONCAT	(		x,
			y
	)		CFN_HAL_INTERNAL_CONCAT(x, y)

Actual concat, can be called

CFN_HAL_CONTAINER_OF

#define CFN_HAL_CONTAINER_OF	(		ptr,
			type,
			member
	)		((type *) ((char *) (ptr) - offsetof(type, member)))

CFN_HAL_CREATE_DRIVER_TYPE

#define CFN_HAL_CREATE_DRIVER_TYPE	(		prefix,
			config_type,
			api_type,
			phy_type,
			cb_type
	)

Value:

    struct cfn_hal_##prefix##_s                                                                                        \
    {                                                                                                                  \
        cfn_hal_driver_t   base;                                                                                       \
        const config_type *config;                                                                                     \
        const api_type    *api;                                                                                        \
        const phy_type    *phy;                                                                                        \
        cb_type            cb;                                                                                         \
        void              *cb_user_arg;                                                                                \
    };                                                                                                                 \
    typedef struct cfn_hal_##prefix##_s cfn_hal_##prefix##_t

CFN_HAL_GET_DRIVER_FROM_BASE

#define CFN_HAL_GET_DRIVER_FROM_BASE	(		ptr,
			type
	)		CFN_HAL_CONTAINER_OF(ptr, type, base)

Helper macro to get the peripheral driver pointer from a base driver pointer.

Parameters

ptr	Pointer to the base cfn_hal_driver_t structure.
type	Peripheral prefix (e.g. cfn_hal_uart_t, cfn_hal_spi_t, cfn_hal_gpio_t).

Returns

Typed pointer to the peripheral driver structure.

CFN_HAL_GET_LOCK_MACRO

#define CFN_HAL_GET_LOCK_MACRO	(		_1,
			_2,
			_3,
			_4,
			_5,
			_6,
			_7,
			_8,
			_9,
			NAME,
			...
	)		NAME

CFN_HAL_INLINE

#define CFN_HAL_INLINE   static inline

Macro for inlining HAL wrapper functions. Can be overridden with attribute((always_inline)) for performance-critical ports.

CFN_HAL_INTERNAL_CONCAT

#define CFN_HAL_INTERNAL_CONCAT	(		x,
			y
	)		x##y

Internal concat, not to be used

CFN_HAL_LOCK

#define CFN_HAL_LOCK	(		driver,
			timeout
	)		(CFN_HAL_ERROR_OK)

CFN_HAL_MAX_DELAY

#define CFN_HAL_MAX_DELAY   (UINT32_MAX)

CFN_HAL_STATIC_ASSERT

#define CFN_HAL_STATIC_ASSERT   _Static_assert

Cross-compiler static assertion macro. Uses C++11 static_assert or C11 _Static_assert to avoid dependency on <assert.h>.

CFN_HAL_STR_STRINGIFY

#define CFN_HAL_STR_STRINGIFY

(

x

)

#x

Stringify

CFN_HAL_UNLOCK

#define CFN_HAL_UNLOCK

(

driver

)

(CFN_HAL_ERROR_OK)

CFN_HAL_UNUSED

#define CFN_HAL_UNUSED

(

x

)

(void) (x)

CFN_HAL_USE_LOCK

#define CFN_HAL_USE_LOCK   0

Enable RTOS-aware thread safety for the HAL.

If set to 1, the HAL adds a 'lock_obj' opaque pointer to the base driver structure and enables the CFN_HAL_WITH_LOCK macro.

Note

To use locking, the hardware port implementation MUST:

1. Implement the 'lock' and 'unlock' hooks in the VMT base layer.
2. Assign a valid RTOS mutex or semaphore to the 'lock_obj' member during the initialization phase (on_config INIT).
3. Handle timeout logic within the 'lock' VMT implementation.

CFN_HAL_WITH_LOCK

#define CFN_HAL_WITH_LOCK

(

...

)

Value:

    CFN_HAL_GET_LOCK_MACRO(__VA_ARGS__,                                                                                \
                           CFN_HAL_WITH_LOCK_NO_LOCK_N,                                                                \
                           CFN_HAL_WITH_LOCK_NO_LOCK_N,                                                                \
                           CFN_HAL_WITH_LOCK_NO_LOCK_N,                                                                \
                           CFN_HAL_WITH_LOCK_NO_LOCK_N,                                                                \
                           CFN_HAL_WITH_LOCK_NO_LOCK_N,                                                                \
                           CFN_HAL_WITH_LOCK_NO_LOCK_0)                                                                \
    (__VA_ARGS__)

Helper macro to execute a driver function (Locking disabled).

CFN_HAL_WITH_LOCK_NO_LOCK_0

#define CFN_HAL_WITH_LOCK_NO_LOCK_0	(		driver,
			timeout,
			result,
			function
	)

Value:

    do                                                                                                                 \
    {                                                                                                                  \
        (void) (timeout);                                                                                              \
        if ((driver) != NULL)                                                                                          \
        {                                                                                                              \
            (result) = function((driver));                                                                             \
        }                                                                                                              \
        else                                                                                                           \
        {                                                                                                              \
            (result) = CFN_HAL_ERROR_BAD_PARAM;                                                                        \
        }                                                                                                              \
    } while (0)

CFN_HAL_WITH_LOCK_NO_LOCK_N

#define CFN_HAL_WITH_LOCK_NO_LOCK_N	(		driver,
			timeout,
			result,
			function,
			...
	)

Value:

    do                                                                                                                 \
    {                                                                                                                  \
        (void) (timeout);                                                                                              \
        if ((driver) != NULL)                                                                                          \
        {                                                                                                              \
            (result) = function((driver), __VA_ARGS__);                                                                \
        }                                                                                                              \
        else                                                                                                           \
        {                                                                                                              \
            (result) = CFN_HAL_ERROR_BAD_PARAM;                                                                        \
        }                                                                                                              \
    } while (0)