Configuration Files

On startup the Panda Server loads its configuration from three files: config, registers, description. These are loaded from the config_d directory in build directory when running the basic simulation, and on Panda the configuration files are loaded from /opt/share/panda/config_d.

The syntax of each configuration file is documented here. The format of each field definition closely follows the format documented in Blocks, Fields and Attributes.

The three files have the following distinct functions.

File

Description

config

Configuration: defines list of blocks, fields in each block, and the behaviour of each field.

registers

Registers: for each block and field defines the associated register offsets.

description

Description: optionally defines a description string for each block and field.

All files have a common structure and indentation is used for structure. Comments begin with #, blocks are identified by their name in the first column, and fields are listed at the next level of indentation.

Configuration file config

This file defines all of the blocks and fields available to this instance of Panda and is processed first.

The syntax of a block definition is:

block-name [ "[" count "]" ]
    [ field-definition ]*

This means that a block definition consists of a block-name, which can be any word used to name the block, optionally followed by a block count enclosed in square brackets, followed by any number of indented field-definitions.

The syntax of a field definition is:

field-name field-type [ field-type-data ]

The field-name names the field, the field-type is a single word from the list documented below, and the field-type-data depended on the field type as documented.

The field type determines the basic function of the field, what actions can be performed on the field, and how the field interacts with the hardware. Typically each field corresponds to a single register or function of the block.

Many field type have an associated field subtype which is used to convert between the values show to the user of the server and the values written to or read from registers.

Field type

The following field types are defined.

Field

param field-subtype [ = value ]

read field-subtype

write field-subtype

time

bit_out

pos_out [ scale [ offset [ units ]]]

ext_out ( timestamp | samples | bits group )

bit_mux [ = value ]

pos_mux

table

param field-subtype [ = value ]

A param field is used to define a single 32-bit value written to a register. The field-subtype must be specified. Optionally an initial value (only relevant when no state file has been loaded) can be specified. In this case the initial value is read as a raw unsigned integer which is written directly to the hardware on startup.

read field-subtype

A read field is used for read-only registers. The field-subtype must be specified.

write field-subtype

A write field is used for write-only registers which trigger immediate actions on a block. The field-subtype must be specified, and the action subtype is useful for write fields which take no data.

time

Time fields behave like param fields, but need special treatment because the underlying value is 64-bits and so two registers need to be written.

bit_out

This identifies an output bit.

pos_out [ scale [ offset [ units ]]]

This identifies a position bus output. Optionally default values for the scale, offset, and units fields can be specified in the config file. Note that these are only effective when there is no persistence file to load.

ext_out ext-extra

This identifies an entry on the extension bus which needs special treatment. The ext-extra field must be one of the following values:

ext-extra

Description

timestamp

Capture timestamp as a 64-bit value

samples

Captures sample count for data capture.

bits group

Defines fields which allow the bit bus to be captured. The group number identifies which 32-bit group of 128 bits is captured.

bit_mux [ = value ]
pos_mux

These two are configuration settings for selecting inputs, and behave like param fields. As for param a default value can be assigned to bit_mux, but the only useful value is 129 (ONE).

table [ row-words ]

Tables are treated specially.

Field subtype

The following field subtype can follow a param, read or write field type:

Type

uint [ max-value ]

int

scalar scale [ offset [ units ]]

bit

action

lut

enum

position

time

Note that enum must be followed by indented lines each consisting of a number followed by a string: the string is the enumeration value written to the user, the number is the value written to the register.

Register file registers

This file defines the register assignments for each block and register. The body of this file should contain a sequencer of block and field definitions repeating the config file, except that the field type specification is replaced by a type specific register definition.

So a block definition is:

block-name { [ "S" ] block-register | "X" } [ extension-module ]
    [ field-definition ]*

If the block-register number is prefixed with S then the same block register number can be shared with multiple blocks: this allows a single hardware implementation to be presented as multiple software blocks. If X is used instead of specifying block-register then no fields can use registers, so must be extension fields with no register linkage.

The register number can be followed by an extension-module which is used to identify this block to the extension server, and will enable use of the extension register syntax defined below.

A field definition is:

field-definition = field-name register-specification

where register-specification depends on the associated field type as follows:

Class

Register syntax

param

register | write-extension

read

register | read-extension

write

register | write-extension

time

low-register high-register

bit_out

( bit-index )N

pos_out

( pos-index )N

ext_out timestamp

ext-index ext-index

ext_out other

ext-index

bit_mux

register

pos_mux

register

table

short size init-reg fill-reg length-reg

table

long 2^size base-reg length-reg

where the syntax (...)N means that the given register number is repeated N times where N is the number of instances of the block. See below for an explanation of read-extension and write-extension.

Extension register syntax

If the extension server is enabled (with the -X command line option on the server) and if an extension module has been loaded as part of the block specification then param, read, and write subtypes can all be redirected to the extension server using the read-extension and write-extension syntax:

read-extension = [ read-reg ]* "X" field-spec
write-extension = [ read-reg ]* [ "W" [ write-reg ]* ] "X" field-spec

In this syntax field-spec is passed through to the associated extension-module to create the binding between this field and the extension server. The specified read-regs and write-regs will be used when processing this field.

See Extension Server for more details on extension fields.

Description file description

The entire content of the description file is optional. The basic syntax is:

block-name block-description
    [ field ]*

where field is:

field-name field-description

and the description is any newline terminated string in UTF-8 format.