Command-line usage
Gapy can be invoked with the following command:
gapy <options> <commands>
<commands> is a list of commands that gapy should process in the order they are specified, from left to right.
<options> is a list of options used to configure the commands to be executed.
Options
The list of options can be obtained with the following option:
gapy --help
Some options are added only when other options are specified, for exemple depending on the target specified. These additional options can always be obtained with the option –help combined with other options.
Here are some generic options, the other ones will be explained throughout the rest of the documentation:
Option |
Description |
|---|---|
–verbose=<string> |
Configure Gapy verbosity. By default nothing is printed. Can be debug, info, warning, error or critical. |
–work-dir=<string> |
Configure the working directory. This is where all the output files such as flash images will be generated. Also, any shell command will be executed from this directory. |
–platform=<string> |
Platform on which the target is used. This is useful to use the same target on board and various simulators. |
Commands
The list of available commands can be obtained with this command:
gapy commands
Since some commands are only available on some targets, the list of commands depends on the options specified, in particular on the target specified.
Here are the main commands:
Command Name |
Description |
|---|---|
commands |
Show the list of available commands |
targets |
Show the list of available targets |
image |
Generate the target images needed to run execution |
flash |
Upload the flash contents to the target |
flash_layout |
Dump the layout of the flashes |
flash_dump_sections |
Dump all sections of the flash, as would be flashed |
flash_dump_app_sections |
Dump application related sections of the flash, as would be flashed |
flash_properties |
Dump the the properties for each flash and each flash section |
run |
Start execution on the target |
Choosing the target
A target is the system on which Gapy will manage the execution. This can be a board or a more complex system like a set of boards connected together.
A target is described through a Python module. Gapy needs to be specified where it should look for such modules in order to know what are the availabel targets. This must be specified through the option –target_dir and can be used several times to specify multiple directories. Gapy contains one directory with the common Gap targets such as the Gap9 EVK.
The list of available targets can be displayed with the following command:
gapy targets
Each target correspond to a python module that Gapy found from the specified target directories.
The target to be used can then be specified with the option –target=<name> where <name> corresponds to one target name shown by the targets command.
Not that once a target is specified, target-specific options may then be available.
Target options
Each target or platform can have its own options. The main ones are exposed through classic command-line options. For targets or platforms having too many options, like for simulators, options can be specified as key-value properties through the command-line option –target-opt=<name>=<value> like in this example:
gapy --target-opt=**/l2/size=10000000
This option can be used several times to specifies several properties. The list of target options are passed as a list of key-value properties to the target, which will take care of them. See the documentation of each target and platform for more information.