Mandatory Driver Functionality

Driver initialization

All HAL interfaces have an initialization function named init(). This function is responsible for loading the module configuration, pin MUX setup, and clock source setup found in the configuration file. This function is also responsible for initializing the HAL device handle, with references to the hardware interface and buffers if needed. The parameter list of this function shall start with the HAL device handle, followed by a pointer to the hardware register interface of the module instance to be associated with this HAL device. Any parameters after the first two parameters are interface specific. After this call, the module is enabled and ready for use, if not an error code should be returned to the application.

Name convention

[namespace]_init(struct [namespace]_descriptor *desc, adc *hw, ...);

Example

adc_sync_init(struct adc_sync_descriptor *adc, adc *hw, ...);

Driver deinitialization

All high-level HAL interfaces have a deinitialization function named deinit(). This function is responsible for releasing the hardware module and any resource allocated by this module. This includes disabling any clock source for the module, resetting any pin MUX setting and resetting the module itself.

Name convention

[namespace]_deinit(struct [namespace)_descriptor *desc);

Example

adc_sync_deinit(struct adc_sync_descriptor *adc);

Register interrupt handler callback

APIs supporting interrupts have a function to register different interrupt handlers. When this function returns, the interrupt is enabled in the module and is ready for use. This function does not change the state of the global interrupt flag. Registering a NULL pointer as handler disables the interrupt used by the driver.

Name convention

[namespace]_register_callback(struct [namespace]_descriptor *desc, [namespace]_callback_type type);

Example

adc_async_register_callback(struct adc_async_descriptor *adc, adc_async_callback_type type);

Get driver version

All HAL drivers are tagged with a version number. The version number has the format 0x00xxyyzz and can be retrieved using the [namespace]_get_version() function, e.g. adc_sync_get_version().

• xx: Major version number
  • Additions/changes to the driver and/or driver API
  • Driver does not need to stay backward compatible
• yy: Minor version number
  • Additions to the API
  • Bug-fixes and/or optimization to the implementation
  • The driver shall stay backward compatible
• zz: Revision number
  • Bug-fixes and/or optimizations of the driver
  • The API shall not be changed
  • The driver shall stay backward compatible

Get I/O descriptor

For APIs with I/O system support, there is a function to extract the I/O descriptor from the device descriptor. This function returns a pointer to the generic I/O descriptor type.

Name convention

[namespace]_get_io_descriptor(struct [namespace]_descriptor *descriptor, struct io_descriptor **io);

Example

usart_sync_get_io_descriptor(struct usart_sync_descriptor *descriptor, struct io_descriptor **io);