Nios® V Processor Software Developer Handbook

ID 743810
Date 7/20/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

13.4.3.1. Intel HAL BSP

hal.enable_instruction_related_exceptions_api

  • Identifier:ALT_INCLUDE_INSTRUCTION_RELATED_EXCEPTION_API
  • Type: Boolean definition
  • Default Value: false
  • Destination File: system.h
  • Description: Enables application program interface (API) for registering handlers to service instruction-related exceptions. These exception types can be generated if various processor options are enabled, such as the memory management unit (MMU), memory protection unit (MPU), or other advanced exception types. Enabling this setting increases the size of the exception entry code.
  • Restrictions: none

hal.max_file_descriptors

  • Identifier: ALT_MAX_FD
  • Type: Decimal number
  • Default Value: 32
  • Destination File: system.h
  • Description: Determines the number of file descriptors statically allocated.
  • Restriction: If hal.enable_lightweight_device_driver_api is true, there are no file descriptors so this setting is ignored. If hal.enable_lightweight_device_driver_api is false, this setting must be at least 4 because HAL needs a file descriptor for /dev/null, /dev/stdin, /dev/stdout, and /dev/stderr. This setting defines the value of ALT_MAX_FD in system.h.

hal.sys_clk_timer

  • Identifier: ALT_SYS_CLK
  • Type: Unquoted string
  • Default Value: none
  • Destination File: system.h
  • Description: Slave descriptor of the system clock timer device. This device provides a periodic interrupt ("tick") and is typically required for RTOS use. This setting defines the value of ALT_SYS_CLK in system.h.
  • Restriction: none

hal.timestamp_timer

  • Identifier: ALT_TIMESTAMP_CLK
  • Type: Unquoted string
  • Default Value: none
  • Destination File: system.h
  • Description: Slave descriptor of timestamp timer device. This device is used by Intel HAL timestamp drivers for high-resolution time measurement. This setting defines the value of ALT_TIMESTAMP_CLK in system.h.
  • Restriction: none

hal.linker.allow_code_at_reset

  • Identifier: none
  • Type: Boolean assignment
  • Default Value: 0
  • Destination File: none
  • Description: Indicates if initialization code is allowed at the reset address. If true, defines the macro ALT_ALLOW_CODE_AT_RESET in linker.h.
  • Restriction: This setting is typically false if an external bootloader (e.g. flash bootloader) is present.

hal.linker.enable_alt_load

  • Identifier: none
  • Type: Boolean assignment
  • Default Value: 1
  • Destination File: none
  • Description: Enables the alt_load() facility. The alt_load() facility copies sections from the .text memory into RAM. If true, this setting sets up the VMA/LMA (virtual memory address/low memory address) of sections in linker.x to allow them to be loaded into the .text memory.
  • Restriction: This setting is typically false if an external bootloader (e.g. flash bootloader) is present.

hal.linker.enable_alt_load_copy_exceptions

  • Identifier: none
  • Type: Boolean assignment
  • Default Value: 0
  • Destination File: none
  • Description: Causes the alt_load() facility to copy the .exceptions section. If true, this setting defines the macro ALT_LOAD_COPY_EXCEPTIONS in linker.h.
  • Restriction: none

hal.linker.enable_alt_load_copy_rodata

  • Identifier: none
  • Type: Boolean assignment
  • Default Value: 0
  • Destination File: none
  • Description: Causes the alt_load() facility to copy the .rodata section. If true, this setting defines the macro ALT_LOAD_COPY_RODATA in linker.h.
  • Restriction: none

hal.linker.enable_alt_load_copy_rwdata

  • Identifier: none
  • Type: Boolean assignment
  • Default Value: 0
  • Destination File: none
  • Description: Causes the initialization code to copy the .rwdata section. If true, this setting defines the macro ALT_LOAD_COPY_RWDATA in linker.h.
  • Restriction: none

hal.linker.enable_exception_stack

  • Identifier: none
  • Type: Boolean assignment
  • Default Value: 0
  • Destination File: none
  • Description: Enables use of a separate exception stack. If true, defines the macro ALT_EXCEPTION_STACK in linker.h, adds a memory region called exception_stack to linker.x, and provides the symbols __alt_exception_stack_pointer and __alt_exception_stack_limit in linker.x.
  • Restriction: The hal.linker.exception_stack_size and hal.linker.exception_stack_memory_region_name settings must also be valid. This setting must be false for MicroC/OS-II BSPs. The exception stack can be used to improve interrupt and other exception performance if an EIC is not implemented.

hal.linker.exception_stack_memory_region_name

  • Identifier: none
  • Type: Unquoted string
  • Default Value: none
  • Destination File: none
  • Description: Name of the existing memory region to be divided up to create the exception_stack memory region. The selected region name is adjusted automatically when the BSP is generated to create the exception_stack memory region.
  • Restriction: Only used if hal.linker.enable_exception_stack is true.

hal.linker.use_picolibc

  • Identifier: USE_PICOLIBC
  • Type: Boolean assignment
  • Default Value: false
  • Destination File: toolchain.cmake
  • Description: Use Picolibc in place of Newlib to provide C library support.
  • Restriction: none

hal.linker.exception_stack_size

  • Identifier: none
  • Type: Decimal number
  • Default Value: 1024
  • Destination File: none
  • Description: Size of the exception stack in bytes.
  • Restriction: Only used if hal.linker.enable_exception_stack is true. none

hal.toolchain.ar

  • Identifier: CMAKE_AR
  • Type: Unquoted string
  • Default Value: riscv32-unknown-elf-ar
  • Destination File: toolchain.cmake
  • Description: Archiver command. Creates library files.
  • Restriction: none

hal.toolchain.as

  • Identifier: CMAKE_ASM_COMPILER
  • Type: Unquoted string
  • Default Value: riscv32-unknown-elf-gcc
  • Destination File: toolchain.cmake
  • Description: Assembler command. Note that CC is used for Nios® V processor assembly language source files (.S).
  • Restriction: none

hal.make.asflags

  • Identifier: COMPILE_LANGUAGE:ASM
  • Type: Unquoted string
  • Default Value: -Wa,-gdwarf2
  • Destination File: toolchain.cmake
  • Description: Custom flags only passed to the assembler. This setting defines the value of COMPILE_LANGUAGE:ASM in toolchain.cmake.
  • Restriction: none

hal.make.cflags_debug

  • Identifier: CMAKE_C_FLAGS_DEBUG and CMAKE_CXX_FLAGS_DEBUG
  • Type: Unquoted string
  • Default Value: -g
  • Destination File: toolchain.cmake
  • Description: C/C++ compiler debug level when CMAKE_BUILD_TYPE=Debug. -g provides the default set of debug symbols required to debug a typical application. Omitting -g removes debug symbols from the .elf file. This setting defines the value of CMAKE_C_FLAGS_DEBUG and CMAKE_CXX_FLAGS_DEBUG in toolchain.cmake.
  • Restriction: Run cmake command with the flag, CMAKE_BUILD_TYPE=Debug

hal.make.cflags_defined_symbols

  • Identifier: none
  • Type: Unquoted string
  • Default Value: none
  • Destination File: toolchain.cmake
  • Description: Preprocessor macros to define. A macro definition in this setting has the same effect as a #define in source code. Adding -DALT_DEBUG to this setting has the same effect as #define ALT_DEBUG in a source file. Adding -DFOO=1 to this setting is equivalent to the macro #define FOO 1 in a source file. Macros defined with this setting are applied to all . S , C source ( .c ), and C++ files in the BSP. This setting defines the value of preprocessor macros in the toolchain.cmake.
  • Restriction: none

hal.make.cflags_optimization

  • Identifier: CMAKE_C_FLAGS_RELEASE and CMAKE_CXX_FLAGS_RELEASE
  • Type: Unquoted string
  • Default Value: -O2
  • Destination File: toolchain.cmake
  • Description: C/C++ compiler optimization level when CMAKE__BUILD_TYPE=Release. -O0 = no optimization, -O2 = normal optimization, etc. -O0 is recommended for code that you want to debug since compiler optimization can remove variables and produce non-sequential execution of code while debugging. This setting defines the value of CMAKE_C_FLAGS_RELEASE and CMAKE_CXX_FLAGS_RELEASE in toolchain.cmake.
  • Restriction: Run cmake command with the flag, CMAKE_BUILD_TYPE=Release

hal.make.cflags_undefined_symbols

  • Identifier: none
  • Type: Unquoted string
  • Default Value: none
  • Destination File: toolchain.cmake
  • Description: Preprocessor macros to undefine. Undefined macros are similar to defined macros, but replicate the #undef directive in source code. To undefine the macro FOO use the syntax -u FOO in this setting. This is equivalent to #undef FOO in a source file. Note: the syntax differs from macro definition (there is a space, i.e. -u FOO versus -DFOO). Macros defined with this setting are applied to all . S , . c , and C++ files in the BSP. This setting undefines preprocessor macros in the toolchain.cmake.
  • Restriction: none

hal.make.cflags_user_flags

  • Identifier: none
  • Type: Unquoted string
  • Default Value: none
  • Destination File: toolchain.cmake
  • Description: Custom flags passed to the compiler when compiling C, C++, and . S files . This setting defines the value of custom flags in toolchain.cmake.
  • Restriction: none

hal.make.cflags_warnings

  • Identifier: none
  • Type: Unquoted string
  • Default Value: -Wall-Wformat-security
  • Destination File: toolchain.cmake
  • Description: C/C++ compiler warning level. -Wall is commonly used. -Wformat-security warns about calls to printf and scanf functions, where the format string is not a string and there are no format arguments. This setting defines the warning levels in toolchain.cmake.
  • Restriction: none

hal.make.cxx_flags

  • Identifier: COMPILE_LANGUAGE:CXX
  • Type: Unquoted string
  • Default Value: none
  • Destination File: toolchain.cmake
  • Description: Custom flags only passed to the C++ compiler. This setting defines the value of COMPILE_LANGUAGE:CXX in toolchain.cmake.
  • Restriction: none

hal.make.link_flags

  • Identifier: none
  • Type: Unquoted string
  • Default Value: none
  • Destination File: toolchain.cmake
  • Description: Linker flags. This setting defines the linker flags in toolchain.cmake.
  • Restriction: none

hal.make.objdump_flags

  • Identifier: ToolchainObjdumpFlags
  • Type: Unquoted string
  • Default Value: -Sdtx
  • Destination File: toolchain.cmake
  • Description: Objdump flags. This setting defines ToolchainObjdumpFlags in toolchain.cmake.
  • Restriction: none

hal.toolchain.cc

  • Identifier: CMAKE_C_COMPILER
  • Type: Unquoted string
  • Default Value: riscv32-unknown-elf-gcc
  • Destination File: toolchain.cmake
  • Description: C compiler command
  • Restriction: none

hal.toolchain.cxx

  • Identifier: CMAKE_CXX_COMPILER
  • Type: Unquoted string
  • Default Value: riscv32-unknown-elf-g++
  • Destination File: toolchain.cmake
  • Description: C++ compiler command
  • Restriction: none

hal.toolchain.objdump

  • Identifier: ToolchainObjdump
  • Type: Unqouted string
  • Default Value: riscv32-unknown-elf-objdump
  • Destination File: toolchain.cmake
  • Description: Objdump command
  • Restriction: none

hal.make.enable_cflag_fstack_protector_strong

  • Identifier: none
  • Type: Boolean assignment
  • Default Value: 1
  • Destination File: toolchain.cmake
  • Description: Enable the fstack-protector-strong compiler flag in toolchain.cmake. If true, add -fstack-protector-strong.
  • Restriction: none

hal.make.enable_cflag_wformat_security

  • Identifier: none
  • Type: Boolean assignment
  • Default Value: 1
  • Destination File: toolchain.cmake
  • Description: Enable the Wformat and Wformat-security compiler flags in toolchain.cmake to warn against security problems when using format functions. If true, add -Wformat -Wformat-security.
  • Restriction: none

hal.toolchain.prefix

  • Identifier: ToolchainPrefix
  • Type: Unquoted string
  • Default Value: riscv32-unknown-elf-
  • Description: Prefix to be used for toolchain executables. The value affects the individual values of the archiver, assembler, compiler, and linker. Specifically, it affects the settings.
    • hal.toolchain.ar
    • hal.toolchain.as
    • hal.toolchain.cc
    • hal.toolchain.cxx
    • hal.toolchain.objdump
    Example of the value: ${hal.toolchain.prefix}gcc, ${hal.toolchain.prefix}objdump, and others.

    However, if the override setting hal.toolchain.enable_executable_overrides is enabled, the individual settings hal.toolchain.ar, hal.toolchain.as, hal.toolchain.cc, hal.toolchain.cxx, and hal.toolchain.objdump may be set to custom values and are not derived from this setting's value.

    The riscv32-unknown-elf toolchain is available with the Ashling* RiscFree* IDE for Intel FPGAs. You must install the Ashling* RiscFree* IDE for Intel FPGAs to use this toolchain.

  • Restriction: none

hal.toolchain.enable_executable_overrides

  • Identifier: none
  • Type: Boolean assignment
  • Default value: false
  • Description: Enable custom values to be set for the toolchain executables. You can set the settings for hal.toolchain.ar, hal.toolchain.as, hal.toolchain.cc, hal.toolchain.cxx, and hal.toolchain.objdump to custom values.
  • Restriction: none

hal.enable_c_plus_plus

  • Identifier: ALT_NO_C_PLUS_PLUS
  • Type: Boolean assignment
  • Default Value: 1
  • Destination File: toolchain.cmake
  • Description: Enable support for a subset of the C++ language. This option increases code footprint by adding support for C++ constructors. Certain features, such as multiple inheritance and exceptions are not supported. If false, add ALT_NO_C_PLUS_PLUS in toolchain.cmake, and reduce code footprint.
  • Restriction: none

hal.enable_clean_exit

  • Identifier: ALT_NO_CLEAN_EXIT
  • Type: Boolean assignment
  • Default Value: 1
  • Destination File: toolchain.cmake
  • Description: When your application exits, close file descriptors, call C++ destructors, etc. Code footprint can be reduced by disabling clean exit. If disabled, adds ALT_NO_CLEAN_EXIT and -Wl, --defsym, exit=_exit in toolchain.cmake.
  • Restriction: none

hal.enable_exit

  • Identifier: ALT_NO_EXIT
  • Type: Boolean assignment
  • Default Value: 1
  • Destination File: toolchain.cmake
  • Description: Add exit() support. This option increases code footprint if your main() routine returns or calls exit(). If false, adds ALT_NO_EXIT in toolchain.cmake, and reduces footprint.
  • Restriction: none

hal.enable_reduced_device_drivers

  • Identifier: ALT_USE_SMALL_DRIVERS
  • Type: Boolean assignment
  • Default Value: 0
  • Destination File: toolchain.cmake
  • Description: Certain drivers are compiled with reduced functionality to reduce code footprint. Not all drivers observe this setting. If true, adds ALT_USE_SMALL_DRIVERS in toolchain.cmake. Typically, drivers support this setting with a polled mode. For example, the altera_avalon_uart and altera_avalon_jtag_uart reduced drivers operate in polled mode.
  • Restriction: none

hal.enable_lightweight_device_driver_api

  • Identifier: ALT_USE_DIRECT_DRIVERS
  • Type: Boolean assignment
  • Default Value: 0
  • Destination File: toolchain.cmake
  • Description: Enable lightweight device driver API to reduces code and data footprint. If true, add ALT_USE_DIRECT_DRIVERS in toolchain.cmake.
  • Restriction: none

hal.enable_runtime_stack_checking

  • Identifier: ALT_STACK_CHECK
  • Type: Boolean assignment
  • Default Value: 0
  • Destination File: toolchain.cmake
  • Description: Turns on HAL runtime stack checking feature. Enabling this setting enables the HAL to check if the heap collide with the stack when allocating heap memory, such as with malloc(). If true, adds ALT_STACK_CHECK in toolchain.cmake.
  • Restriction: none

hal.enable_sim_optimize

  • Identifier: ALT_SIM_OPTIMIZE
  • Type: Boolean assignment
  • Default Value: 0
  • Destination File: toolchain.cmake
  • Description: The BSP is compiled with optimizations to speedup HDL simulation such as initializing the cache, clearing the .bss section, and skipping long delay loops. If true, adds ALT_SIM_OPTIMIZE in toolchain.cmake.
  • Restriction: When this setting is true, the BSP cannot run on hardware.

hal.log_port

  • Identifier: ALT_LOG_PORT
  • Type: Unquoted string
  • Default Value: none
  • Destination File: system.h
  • Description: Slave descriptor of debug logging character-mode device. If defined, it enables extra debug messages in the HAL source. This setting is used by the Intel FPGA logging functions.

hal.log_flags

  • Identifier: ALT_LOG_FLAGS
  • Type: Decimal Number
  • Default Value: 0
  • Destination File: toolchain.cmake
  • Description: The value is assigned to ALT_LOG_FLAGS in the generated toolchain.cmake. Refer to hal.log_port for further details. The valid range of this setting is -1 through 3.

hal.stderr

  • Identifier: ALT_STDERR
  • Type: Unquoted string
  • Default Value: none
  • Destination File: system.h
  • Description: Slave descriptor of STDERR character-mode device. This setting is used by the ALT_STDERR family of defines in system.h.

hal.stdin

  • Identifier:ALT_STDIN
  • Type: Unquoted string
  • Default Value: none
  • Destination File: system.h
  • Description: Slave descriptor of STDIN character-mode device. This setting is used by the ALT_STDIN family of defines in system.h.

hal.stdout

  • Identifier: ALT_STDOUT
  • Type: Unquoted string
  • Default Value: none
  • Destination File: system.h
  • Description: Slave descriptor of STDOUT character-mode device. This setting is used by the ALT_STDOUT family of defines in system.h.