ARM DS-5 Debugger User Guide : 7.13 Defining the Options for usecase scripts

7.13 Defining the Options for usecase scripts

Each usecase has a list of options which specify a set of values which can be supplied on the command-line to a particular usecase to configure what values are supplied when usecase is run.

When you define options, you can group or nest them to organize and provide a more descriptive set of options.

The method which provides the options is defined with the $Options$ tag in a usecase definition block. The $Options$ tag provides the name of a method in the script which returns a single list of options.

Example 7-9 Examples

...
$Options$ myOptions
...

def myOptions():
      return [list_of_options]

It is important that the function that supplies the options takes no arguments and returns a list of options in the same format as described below. If the $Options$ tag is defined, and the function named in this tag is not present in the script or the function used to supply the options takes arguments, then an error occurs when running the script.

There are 5 types of option that can be used to define options to a usecase script. These are:

UseCaseScript.booleanOption.
UseCaseScript.enumOption.
UseCaseScript.radioEnumOption.
UseCaseScript.integerOption.
UseCaseScript.stringOption.

All of these options require:

A variable name, that is used to refer to the option in a usecase script.
A display name.
A default value that must be of the same type as the defined option.

UseCaseScript.booleanOption: Describes a boolean. Possible values are True or False.
UseCaseScript.integerOption: Describes a whole integer value such as: 4, 99 or 100001. In addition to the fields required by all options, a minimum and a maximum value can be supplied which restricts the range of integers this option allows. Additionally, an output format of the integer option can be defined, which can be either decimal (base 10) or hexadecimal (base 16).
UseCaseScript.stringOption: Describes a string such as traceCapture or etmv4 which can be used, for example, to refer to the Coresight components in the current system by name.
UseCaseScript.enumOption
UseCaseScript.radioEnumOption: Both these describe enumerations. These can be used to describe a list of values that are allowed for this option. Enumeration values can be strings or integers.

Example 7-10 Examples

UseCaseScript.booleanOption(name="timestamps", displayName="Enable global timestamping", defaultValue=True)

Defines a boolean option “timestamps” which is true by default.

UseCaseScript.stringOption(name="traceBuffer", "Trace Capture Method", defaultValue="none")

Defines a string option “traceBuffer” with a default value “none”.

UseCaseScript.integerOption(name="cores", displayName="Number of cores", defaultValue=1, min=1, max=16, format=UseCaseScript.DEC)

Defines an integer option “cores” with a default value of 1, minimum value of 1 and maximum value of 16. The output format is in decimal (base 10).

UseCaseScript.integerOption(name="retries", displayName="Attempts to retry", defaultValue=5, min=1, format=UseCaseScript.HEX)

Defines an integer option “retries” with a default value of 5, minimum value of 1 and no maximum value. The output will be in hexadecimal (base 16).

UseCaseScript.enumOption(name="contextid", displayName="Context ID Size",  values = [("8", "8 bits"), ("16", "16 bits"), ("32", "32 bits")] , defaultValue="32")

Defines an enumeration “contextid” with default value of “32”, the values are restricted to members of the enumeration: "8", "16" or "32".

Nesting Options

Options can be organized or grouped using the following:

UseCaseScript.tabSet.
UseCaseScript.tabPage.
UseCaseScript.infoOption.
UseCaseScript.optionGroup.

The groups are not associated with a value, and do not require a default. You can use the groups with the option names to construct a complete set of options.

To specify the nesting of options, each option can include an optional childOptions keyword which is a list of other options which are nested within this option. An example set of nested options can be seen below.

Example 7-11 Examples

The following example shows an options method, complete with a set of options.

def myOptions():
      return [
          UseCaseScript.optionGroup(             
          name="options",         
          displayName="Usecase Options",                  
          childOptions=[                      
              UseCaseScript.optionGroup(                         
                  name="connection",                         
                  displayName="Connection Options",                         
                  childOptions=[            
                      UseCaseScript.integerOption(
                         name="cores",                                        
                         displayName="Number of cores",
                         defaultValue=1,
                         min=1,
                         max=16),
                      UseCaseScript.stringOption(
                         name="traceBuffer",
                         displayName="Trace Capture Method",
                         defaultValue="none"),
                  ]
              ),  
              UseCaseScript.enumOption(                     
              name="contextID",                     
              displayName="Context ID Size",                      
              values = [("8", "8 bits"), ("16", "16 bits"), ("32", "32 bits")] ,                      
              defaultValue="32"),
              ]
          ),  
      ]

Options are accessed according to how they are nested within the list of options. In this example there is a group called options with two child options:

options.contextID

This is an enumeration within the options group, and stores the value of the contextID in this example.

options.connection

This is another group for nesting options. It does not store any value. It contains the options:

options.connection.cores: This is an integer that accesses cores variable.
options.connection.traceBuffer: This is a string that accesses traceBuffer variables in the list of options.

Using options in the script

The entry point and validation functions both take an options object, as the required first parameter, which can be used to get and set the option values. The functions that are provided to work with defined options are getOptionValue(name) and

setOptionValue(name,
						value)

For the name of the option, use the full name, for example group.subgroup.variable. The value must be of the correct type for the named variable, for example string, integer or a member of the enumeration.

To find out the full name of the option, either see the definition of options in the usecase script or issue a

usecase help
						script_name.py

on the command-line.

DTSL Options

Options are defined in a similar way to the Debug and Trace Services Layer (DTSL) options, using the same parameters and way of nesting child options.

See 15.6 DTSL options and the example usecase scripts in your DS-5 installation for more information on how to construct a list of options.

Non-Confidential	PDF version	ARM DUI0446W
Copyright © 2010-2015 ARM. All rights reserved.