Guidelines for Developing a Nios II HAL Device Driver

ID 683146
Date 6/12/2015
Public
Document Table of Contents

1.12.3.2. Using the Lightweight Device Drivers API Option

The Lightweight device driver API option generates a #define statement for ALT_USE_DIRECT_DRIVERS. To turn on this option, set hal.enable_lightweight_device_driver_api to true. Setting this option has the following effects on correctly-written UART device drivers:

  • Sets #define ALT_USE_DIRECT_DRIVERS.
  • Eliminates the option of using a file system. File descriptors cannot be created.
  • Disables stdio device descriptor redirection. alt_main() cannot call alt_io_redirect().
  • Disables the open() and close() functions. Attempting to call these functions generates a link time error.
  • Causes direct calls to your UART device driver using macros, bypassing the device manipulation function invocations normally accessed through the file descriptor structure. The macros are defined in alt_driver.h, which is in the BSP folder, in HAL/inc/sys.

For example, a call to alt_putstr() is normally treated as a call to the run-time library function fputs(). With lightweight device drivers enabled, alt_putstr() is translated to ALT_DRIVER_WRITE() (defined in alt_driver.h) and state-obtaining macros. The ALT_DRIVER_WRITE() macro in turn calls the ALT_DRIVER_FUNC_NAME() macro (also defined in alt_driver.h), and eventually ALTERA_AVALON_UART_WRITE(), which is defined in the altera_avalon_uart_write.c driver file for the UART, where the UART is defined for stdout. Calling ALT_DRIVER_FUNC_NAME(uart1, write) returns ALTERA_AVALON_UART_WRITE.

ALT_USE_DIRECT_DRIVERS is dual-purposed in the my_uart_driver device driver. It provides a convenient way to map the names of the ALTERA_AVALON_UART_INIT() and ALTERA_AVALON_UART_INSTANCE() macros, which are tied to the component name, to names that are specific to the my_uart_driver device driver. This setting of ALT_USE_DIRECT_DRIVERS already maps ALTERA_AVALON_UART_INIT() and ALTERA_AVALON_UART_INSTANCE() to macros that change based on the setting of ALT_USE_DIRECT_DRIVERS in altera_avalon_uart.h. At the same time, the ALTERA_AVALON_UART_INIT() and ALTERA_AVALON_UART_INSTANCE() macros have the ALTERA_AVALON portion of their names change to MY_UART. The resulting four macro name mappings are MY_UART_DEV_INIT(), MY_UART_STATE_INIT(), MY_UART_DEV_INSTANCE(), and MY_UART_STATE_INSTANCE().

The figure below shows excerpts from the summary.html file generated by the SBT for a BSP with lightweight device drivers enabled.

Figure 23. hal.enable_lightweight_device_driver_api in summary.html
Note: For more information about the Lightweight device driver API option, refer to "Reducing Code Footprint" in the "Developing Programs Using the Hardware Abstraction Layer" chapter and to "Reducing Code Footprint" in the "Developing Device Drivers for the Hardware Abstraction Layer" chapter of the Nios II Software Developer's Handbook.