Nios® II Software Developer Handbook

ID 683525
Date 8/28/2023
Public
Document Table of Contents

8.6. Accessing Hardware

Software accesses the hardware with macros that abstract the memory-mapped interface to the device. This section describes the macros that define the hardware interface for each device.

All components provide a directory that defines the device hardware and software. For example, each component provided in the Intel® Quartus® Prime software has its own directory in the <Intel FPGA installation>/ip/altera/sopc_builder_ip directory. Many components provide a header file that defines their hardware interface. The header file is named <component name>_regs.h, included in the inc subdirectory for the specific component. For example, the Intel FPGA-provided JTAG UART component defines its hardware interface in the file <Intel FPGA installation>/ip/altera/sopc_builder_ip/altera_avalon_jtag_uart/inc/altera_avalon_jtag_uart_regs.h.

The _regs.h header file defines the following access macros for the component:

  • Register access macros that provide either or both a read or write macro for each register in the component that supports the operation. The macros are:
    • IORD_ <component name>_<register name> (<component base address>)
    • IOWR_ <component name>_<register name> (<component base address>, <data>)

      For example, altera_avalon_jtag_uart_regs.h defines the following macros:

    • IORD_ALTERA_AVALON_JTAG_UART_DATA()
    • IOWR_ALTERA_AVALON_JTAG_UART_DATA()
    • IORD_ALTERA_AVALON_JTAG_UART_CONTROL()
    • IOWR_ALTERA_AVALON_JTAG_UART_CONTROL()
  • Register address macros that return the physical address for each register in a component. The address register returned is the component’s base address + the specified register offset value. These macros are named IOADDR_<component name>_<register name> (<component base address>).

    For example, altera_avalon_jtag_uart_regs.h defines the following macros:

    • IOADDR_ALTERA_AVALON_JTAG_UART_DATA()
    • IOADDR_ALTERA_AVALON_JTAG_UART_CONTROL()

      Use these macros only as parameters to a function that requires the specific address of a data source or destination. For example, a routine that reads a stream of data from a particular source register in a component might require the physical address of the register as a parameter.

  • Bit-field masks and offsets that provide access to individual bit-fields in a register. These macros have the following names:
    • <component name>_<register name>_<name of field>_MSK—A bit-mask of the field
    • <component name>_<register name>_<name of field>_OFST—The bit offset of the start of the field

      For example, ALTERA_AVALON_UART_STATUS_PE_MSK and ALTERA_AVALON_UART_STATUS_PE_OFST access the pe field of the status register.

Access a device’s registers only with the macros defined in the _regs.h file. You must use the register access functions to ensure that the processor bypasses the data cache when reading and or writing the device. Do not use hard-coded constants, because they make your software susceptible to changes in the underlying hardware.

If you are writing the driver for a completely new hardware device, you must prepare the _regs.h header file.

For more information about a complete example of the _regs.h file, refer to the component directory for any of the Intel FPGA-supplied components, such as <Intel FPGA installation>/ip/sopc_builder_ip/altera_avalon_jtag_uart/inc.