Nios® V Processor Software Developer Handbook

ID 743810
Date 10/02/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.5.4.2. add_sw_setting

Usage

add_sw_setting <type> <destination> <displayName> <identifier> <value> <description>

Options

  • <type>: Setting type - Boolean, QuotedString, UnquotedString.
  • <destination>: The destination BSP file associated with the setting, or the module generator that processes this setting.
  • <displayName>: Setting name.
  • <identifier>: Name of the macro created for a generated destination file.
  • <value>: Default value of the setting.
  • <description>: Setting description.

Description

This command creates a BSP setting associated with a software package or device driver. The setting is available whenever the software package or device driver is present in the BSP. niosv-bsp converts the setting and its value into either a C preprocessor macro or BSP makefile variable. add_sw_setting passes macro definitions to the compiler using the -D command line option, or adds them to the system.h file as #define statements.

The setting only exists once even if there are multiple instances of a software package. You can use the BSP Tcl commands set_setting and get_setting to set or get the setting. The value of the setting persists in the BSP settings file.

To create a setting, you must define each of the following parameters.
  • type—This parameter formats the setting value during BSP generation. The following supported types and usage restrictions apply:
    • boolean_define_only—Defines a macro if the setting’s value is 1 or true. Example: #define LCD_PRESENT. No macro is defined if the setting’s value is 0 or false. This setting type supports the system_h_define and public_mk_define destinations, defined below.
    • boolean—Defines a macro or makefile variable and sets it to 1 (if the value is 1 or true) or 0 (if the value is 0 or false). Example: #define LCD_PRESENT 1. This type supports all destinations.
    • character—Defines a macro as a single character with single quotes around the character. Example: #define DELIMITER ':'. This type supports the system_h_define destination, defined below.
    • decimal_number—Defines a macro or makefile variable and sets it with an unquoted decimal (integer) number. Example: #define NUM_COPROCESSORS 3. This type supports all destinations.
    • double—Defines a macro name and sets it to a value with a decimal point. Example: #define PI 3.1416. This type supports the system_h_define destination, defined below.
    • float—Defines a macro name and sets it to a value with a decimal point and f character. Example: #define PI 3.1416f. This type supports the system_h_define destination, defined below.
    • hex_number—Defines a macro name and sets it to a value with a 0x prepended to the value. Example: #define LCD_SIZE 0x1000. This type supports the system_h_define destination, defined below.
    • quoted_string—Quoted strings always have the macro name and setting value added to the destination files. In the destination, the setting value is enclosed in quotation marks. Example: #define DFLT_ERR "General error"
If the setting value contains white space, you must place quotation marks around the value string in the Tcl script. This type supports the system_h_define destination, defined below.
    • unquoted_string—Unquoted strings define a macro or makefile variable with setting name and value in the destination file. In the destination file, the setting value is not enclosed in quotation marks. Example: #define DFLT_ERROR Error This type supports all destinations.
  • destination—The destination parameter specifies where add_sw_setting puts the setting in the generated BSP. add_sw_settings supports the following destinations:
    • system_h_define—With this destination, add_sw_settings formats settings as #define <setting name> [<setting value>] macros in the system.h file
    • public_mk_define—With this destination, add_sw_settings formats settings as -D<setting name>[=<setting value>] additions to the ALT_CPPFLAGS variable in the BSP toolchain.cmake file. toolchain.cmake passes the flag to the C preprocessor for each source file in the BSP, and in applications and libraries using the BSP.
    • makefile_variable—With this destination, add_sw_settings formats settings as makefile variable additions to the BSP toolchain.cmake file. The variable name must be unique in the toolchain.cmake file.
  • displayName—The name of the setting. Settings exist in a hierarchical namespace. A period separates levels of the hierarchy. Settings created in your Tcl script are located in the hierarchy under the driver or software package name you specified in the create_driver or create_sw_package command. Example: my_driver.my_setting. The Nios® V processor BSP Editor adds the hierarchical prefix to the setting name.

  • identifier—The name of the macro or makefile variable being defined. In a setting added to the system.h file at generation time, this parameter corresponds to the text immediately following the #define statement.

  • value—The default value associated with the setting. If you do not assign a value to the option, its value is this default value. Valid initial values are TRUE, 1, FALSE, and 0 for boolean and boolean_define_only setting types, a single character for the character type, integer numbers for the decimal_number setting type, integer numbers with or without a 0x prefix for the hex_number type, numbers with decimals for float_number and double_number types, or an arbitrary string of text for quoted and unquoted string setting types. For string types, if the value contains any white space, you must enclose it in quotation marks.

  • description—Descriptive text that is inserted along with the setting value and name in the summary.html file. You must enclose the description in quotation marks if it contains any spaces. If the description includes any special characters (such as quotation marks), you must escape them with the backslash (\) character. The description field is mandatory, but can be an empty string ("").