Document toolboxDocument toolbox

Layout Variables

Owned by Luis Casarrubias
Last updated: Mar 07, 2023 by Catherine Spain
3 min read

When developing a layout, modules may have arguments created using system wide data such as HW input sample rate or HW input block size. Data such as this may be entered explicitly for module arguments (i.e. 48000 for sample rate), or a symbol can be defined and used instead. For example, system input parameters such as TOP_SAMPLERATE are automatically defined in Layout Variables, so rather than entering 48000 as a module argument, you can use $TOP_SAMPLERATE (the ‘$’ tells Designer to treat this as a symbol). When this data value changes, it changes everywhere else that it is used. For example, if  $TOP_SAMPLERATE is used across the layout (rather than explicitly defining 48000), it only needs to be changed in one place.

 

Note: Despite the name, Layout Variables are designed to work with Module Arguments, not Module Variables.

Defining Layout Variables

To open the Layout Variables dialog, select ‘Layout->Layout Variables’ from the Designer menu.

This will open the following dialog.

There are three sections: predefined variables, user variables, and variable usage.

Predefined Variables

The predefined variables section automatically defines symbols derived from the layout’s HW input pin. If the HW input attributes are changed, these symbol values will also change to match. The TOP convention is used in these variables to indicate that they represent the top level input and output pin values.

  • TOP_SAMPLERATE — the sample rate of the HW input pin

  • TOP_BLOCKSIZE — block size in samples of the HW input pin

  • TOP_BLOCKRATE — HW input sample rate divided by the HW input block size

  • TOP_NUMIN — HW input pin number of channels

  • TOP_NUMOUT — HW output pin number of channels

User Variables

The user variables section is where arbitrary symbols can be defined by the user. Symbols must be entered as <SYMBOL> = <VALUE>, one per line. Symbol names must begin with a letter. Symbol characters must be upper or lower case letters, digits, or underscore characters. No other characters or special symbols are allowed. If other text or spaces are entered they will be stripped out when the dialog is closed. For example, a user might define a symbol like “SIGNAL_NOISE_RATIO_THRESH”,  and then use it in any module argument field in the layout anywhere that SNR is evaluated.

Variable Usage

The variable usage section shows which module arguments are implementing a given symbol. If a symbol is deleted from the user variables section, the user may refer to the variable usage section to find which modules relied on that symbol. The user can then manually delete/replace the symbol for each of the afflicted module arguments.

Saving User Variables

User Variables are typically saved within the layout, however Designer also supports a separate User Variables file. 

Save to File

User variables, although typically saved with the layout, may optionally be saved to a file. To save user variables to a file click on the “Save to File” button and enter the file name to save.

Load from File

User variables previously saved to a file may be loaded from that file. To load user variables click on the “Load from File” button and select the file.

Loading user variables from a file will overwrite any existing user variables.

Using Layout Variables

To use a layout variable precede the symbol with a ‘$’.

The $NUM_PINS symbol has been defined with a value of 2 in the user variables dialog.

Simple arithmetic can also be used with the layout variables to define module arguments. For example, this Source module uses the predefined layout variables to specify its wire information arguments:

Note: As seen in the numChannels argument above, any expression must begin with a ‘$’, even if the first component is not a variable.