cfn_hal_base.h File Reference

Base driver Hardware Abstraction Layer declarations. More...

#include "cfn_hal.h"
#include "cfn_hal_types.h"
#include "cfn_hal_base_impl.h"

Go to the source code of this file.

Data Structures
struct	cfn_hal_api_base_s
	Base API structure for all peripheral drivers. Every peripheral-specific API struct MUST have this as its first member. More...

Macros
#define	CFN_HAL_BASE_API   static inline
	API visibility macro for the base driver.
#define	CFN_HAL_VMT_CHECK(api_struct_type)
	Compile-time check to ensure a peripheral API struct is compatible with the base layer. All peripheral APIs must have 'cfn_hal_api_base_t base' as their FIRST member.

Typedefs
typedef struct cfn_hal_api_base_s	cfn_hal_api_base_t
	Base API structure for all peripheral drivers. Every peripheral-specific API struct MUST have this as its first member.

Functions
CFN_HAL_BASE_API cfn_hal_error_code_t	cfn_hal_base_init (cfn_hal_driver_t *base, cfn_hal_peripheral_type_t expected_type)
	Generic initialization for any driver. Handles board-level hooks, type validation, and hardware-specific commitment.
CFN_HAL_BASE_API cfn_hal_error_code_t	cfn_hal_base_deinit (cfn_hal_driver_t *base, cfn_hal_peripheral_type_t expected_type)
	Generic deinitialization for any driver. Returns the driver to the CONSTRUCTED state and releases board resources.
CFN_HAL_BASE_API cfn_hal_error_code_t	cfn_hal_base_config_set (cfn_hal_driver_t *base, cfn_hal_peripheral_type_t expected_type, const void *config)
	Generic configuration setter for any driver.
CFN_HAL_BASE_API cfn_hal_error_code_t	cfn_hal_base_config_validate (const cfn_hal_driver_t *base, cfn_hal_peripheral_type_t expected_type, const void *config)
	Generic validation for a configuration.
CFN_HAL_BASE_API cfn_hal_error_code_t	cfn_hal_base_callback_register (cfn_hal_driver_t *base, cfn_hal_peripheral_type_t expected_type, cfn_hal_callback_t callback, void *user_arg)
	Generic callback registration for any driver.
CFN_HAL_BASE_API cfn_hal_error_code_t	cfn_hal_power_state_set (cfn_hal_driver_t *base, cfn_hal_peripheral_type_t expected_type, cfn_hal_power_state_t state)
	Generic power state transition for any driver.
CFN_HAL_BASE_API cfn_hal_power_state_t	cfn_hal_power_state_get (const cfn_hal_driver_t *base)
	Generic power state getter. Returns the current power state from the software shadow.
CFN_HAL_BASE_API cfn_hal_error_code_t	cfn_hal_base_event_enable (cfn_hal_driver_t *base, cfn_hal_peripheral_type_t expected_type, uint32_t event_mask)
	Generic event enable for any driver. Activates nominal hardware triggers based on the provided mask.
CFN_HAL_BASE_API cfn_hal_error_code_t	cfn_hal_base_event_disable (cfn_hal_driver_t *base, cfn_hal_peripheral_type_t expected_type, uint32_t event_mask)
	Generic event disable for any driver. Deactivates nominal hardware triggers based on the provided mask.
CFN_HAL_BASE_API cfn_hal_error_code_t	cfn_hal_base_event_get (cfn_hal_driver_t *base, cfn_hal_peripheral_type_t expected_type, uint32_t *event_mask)
	Generic event status getter for any driver. Retrieves the current nominal hardware triggers/flags.
CFN_HAL_BASE_API cfn_hal_error_code_t	cfn_hal_base_error_enable (cfn_hal_driver_t *base, cfn_hal_peripheral_type_t expected_type, uint32_t error_mask)
	Generic error enable for any driver. Activates exception-flow hardware triggers based on the provided mask.
CFN_HAL_BASE_API cfn_hal_error_code_t	cfn_hal_base_error_disable (cfn_hal_driver_t *base, cfn_hal_peripheral_type_t expected_type, uint32_t error_mask)
	Generic error disable for any driver. Deactivates exception-flow hardware triggers based on the provided mask.
CFN_HAL_BASE_API cfn_hal_error_code_t	cfn_hal_base_error_get (cfn_hal_driver_t *base, cfn_hal_peripheral_type_t expected_type, uint32_t *error_mask)
	Generic error status getter for any driver. Retrieves current exception-flow hardware flags/errors.

Detailed Description

Base driver Hardware Abstraction Layer declarations.

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_BASE_API

#define CFN_HAL_BASE_API   static inline

API visibility macro for the base driver.

This macro controls whether the base functions are 'static inline' (default), 'extern' (when linking against a pre-compiled library), or empty (when compiling the library source).

CFN_HAL_VMT_CHECK

#define CFN_HAL_VMT_CHECK

(

api_struct_type

)

Value:

    CFN_HAL_STATIC_ASSERT(offsetof(api_struct_type, base) == 0,                                                        \
                          "cfn_hal_api_base_t must be the first member of the VMT struct")

Compile-time check to ensure a peripheral API struct is compatible with the base layer. All peripheral APIs must have 'cfn_hal_api_base_t base' as their FIRST member.

Typedef Documentation

cfn_hal_api_base_t

typedef struct cfn_hal_api_base_s cfn_hal_api_base_t

Base API structure for all peripheral drivers. Every peripheral-specific API struct MUST have this as its first member.

Function Documentation

cfn_hal_base_callback_register()

CFN_HAL_BASE_API cfn_hal_error_code_t cfn_hal_base_callback_register	(	cfn_hal_driver_t *	base,
		cfn_hal_peripheral_type_t	expected_type,
		cfn_hal_callback_t	callback,
		void *	user_arg
	)

Generic callback registration for any driver.

Parameters

base	Pointer to the base driver structure.
expected_type	FourCC code for peripheral type validation.
callback	Generic callback function pointer.
user_arg	User-defined argument passed to the callback.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_base_config_set()

CFN_HAL_BASE_API cfn_hal_error_code_t cfn_hal_base_config_set	(	cfn_hal_driver_t *	base,
		cfn_hal_peripheral_type_t	expected_type,
		const void *	config
	)

Generic configuration setter for any driver.

Parameters

base	Pointer to the base driver structure.
expected_type	FourCC code for peripheral type validation.
config	Pointer to the peripheral-specific configuration structure.

Returns

cfn_hal_error_code_t status code.

cfn_hal_base_config_validate()

CFN_HAL_BASE_API cfn_hal_error_code_t cfn_hal_base_config_validate	(	const cfn_hal_driver_t *	base,
		cfn_hal_peripheral_type_t	expected_type,
		const void *	config
	)

Generic validation for a configuration.

Parameters

base	Pointer to the base driver structure.
expected_type	FourCC code for peripheral type validation.
config	Pointer to the configuration structure.

Returns

cfn_hal_error_code_t status code.

cfn_hal_base_deinit()

CFN_HAL_BASE_API cfn_hal_error_code_t cfn_hal_base_deinit	(	cfn_hal_driver_t *	base,
		cfn_hal_peripheral_type_t	expected_type
	)

Generic deinitialization for any driver. Returns the driver to the CONSTRUCTED state and releases board resources.

Parameters

base	Pointer to the base driver structure.
expected_type	FourCC code for peripheral type validation.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_base_error_disable()

CFN_HAL_BASE_API cfn_hal_error_code_t cfn_hal_base_error_disable	(	cfn_hal_driver_t *	base,
		cfn_hal_peripheral_type_t	expected_type,
		uint32_t	error_mask
	)

Generic error disable for any driver. Deactivates exception-flow hardware triggers based on the provided mask.

Parameters

base	Pointer to the base driver structure.
expected_type	FourCC code for peripheral type validation.
error_mask	Pointer to a peripheral-specific error mask.

Returns

cfn_hal_error_code_t status code.

cfn_hal_base_error_enable()

CFN_HAL_BASE_API cfn_hal_error_code_t cfn_hal_base_error_enable	(	cfn_hal_driver_t *	base,
		cfn_hal_peripheral_type_t	expected_type,
		uint32_t	error_mask
	)

Generic error enable for any driver. Activates exception-flow hardware triggers based on the provided mask.

Parameters

base	Pointer to the base driver structure.
expected_type	FourCC code for peripheral type validation.
error_mask	Pointer to a peripheral-specific error mask.

Returns

cfn_hal_error_code_t status code.

cfn_hal_base_error_get()

CFN_HAL_BASE_API cfn_hal_error_code_t cfn_hal_base_error_get	(	cfn_hal_driver_t *	base,
		cfn_hal_peripheral_type_t	expected_type,
		uint32_t *	error_mask
	)

Generic error status getter for any driver. Retrieves current exception-flow hardware flags/errors.

Parameters

base	Pointer to the base driver structure.
expected_type	FourCC code for peripheral type validation.
error_mask	[out] Pointer to a buffer to receive the error status.

Returns

cfn_hal_error_code_t status code.

cfn_hal_base_event_disable()

CFN_HAL_BASE_API cfn_hal_error_code_t cfn_hal_base_event_disable	(	cfn_hal_driver_t *	base,
		cfn_hal_peripheral_type_t	expected_type,
		uint32_t	event_mask
	)

Generic event disable for any driver. Deactivates nominal hardware triggers based on the provided mask.

Parameters

base	Pointer to the base driver structure.
expected_type	FourCC code for peripheral type validation.
event_mask	Pointer to a peripheral-specific event mask.

Returns

cfn_hal_error_code_t status code.

cfn_hal_base_event_enable()

CFN_HAL_BASE_API cfn_hal_error_code_t cfn_hal_base_event_enable	(	cfn_hal_driver_t *	base,
		cfn_hal_peripheral_type_t	expected_type,
		uint32_t	event_mask
	)

Generic event enable for any driver. Activates nominal hardware triggers based on the provided mask.

Parameters

base	Pointer to the base driver structure.
expected_type	FourCC code for peripheral type validation.
event_mask	Pointer to a peripheral-specific event mask.

Returns

cfn_hal_error_code_t status code.

cfn_hal_base_event_get()

CFN_HAL_BASE_API cfn_hal_error_code_t cfn_hal_base_event_get	(	cfn_hal_driver_t *	base,
		cfn_hal_peripheral_type_t	expected_type,
		uint32_t *	event_mask
	)

Generic event status getter for any driver. Retrieves the current nominal hardware triggers/flags.

Parameters

base	Pointer to the base driver structure.
expected_type	FourCC code for peripheral type validation.
event_mask	[out] Pointer to a buffer to receive the event status.

Returns

cfn_hal_error_code_t status code.

cfn_hal_base_init()

CFN_HAL_BASE_API cfn_hal_error_code_t cfn_hal_base_init	(	cfn_hal_driver_t *	base,
		cfn_hal_peripheral_type_t	expected_type
	)

Generic initialization for any driver. Handles board-level hooks, type validation, and hardware-specific commitment.

Parameters

base	Pointer to the base driver structure.
expected_type	FourCC code for peripheral type validation.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_power_state_get()

CFN_HAL_BASE_API cfn_hal_power_state_t cfn_hal_power_state_get

(

const cfn_hal_driver_t *

base

)

Generic power state getter. Returns the current power state from the software shadow.

Parameters

base	Pointer to the base driver structure.

Returns

Current cfn_hal_power_state_t.

cfn_hal_power_state_set()

CFN_HAL_BASE_API cfn_hal_error_code_t cfn_hal_power_state_set	(	cfn_hal_driver_t *	base,
		cfn_hal_peripheral_type_t	expected_type,
		cfn_hal_power_state_t	state
	)

Generic power state transition for any driver.

Parameters

base	Pointer to the base driver structure.
expected_type	FourCC code for peripheral type validation.
state	The target power state to transition to.

Returns

cfn_hal_error_code_t status code.