APX IDL v1.2

This is the specification for the APX Interface Definition Language (IDL) v1.2.

Definition files

APX IDL is used when writing definition files that use the .apx file extension. Preferably these files should be generated by a toolchain, but they can also be written by hand.

Each file shall be used to describe one APX node. Placing multiple node declarations in the same file is not permitted.

Line endings

The only acceptable line ending (EOL) is the UNIX line ending (\n). If you are a Windows developer, remember to convert your APX definition file to UNIX line endings before use.

Structure of an APX Definition File

1. APX Header

2. Node Declaration

3. Type Declaration(s) (Optional)

4. Port Declaration(s)

Example:

APX/1.2
N"Example"
T"VehicleSpeed_T"S
T"EngineSpeed_T"S
P"VehicleSpeed"T[0]:=65535
P"EngineSpeed"T[1]:=65535

APX Header

The first line of the definition file must contain an APX header. Inspired by HTTP headers, it consists of the prefix APX/ followed by the IDL version number.

Example:

APX/1.2

Statements and specifiers

Following the APX header line are one or more APX statement lines. The first letter of each line selects the statement type:

Statement Specifier	Statement Type
N	Node Declaration
T	Type Declaration
R	Require-Port Declaration
P	Provide-Port Declaration

There can be at most one statement per line; there is no statement separator in APX IDL other than the end-of-line (EOL) character.

Node Declarations

A node declaration begins a new APX node. All subsequent lines belong to that node. Each node has a name (string literal enclosed in quotes) that must be unique within the APX client. There can only be a single node declaration per definition file.

A Node declaration does not have an attribute section.

Example:

N"MyNode"

Type Declarations

A type declaration statement creates a new named type that can be referenced later by one or more port declarations.

‘T’ Name Data-Signature

Example:

# Type "VehicleSpeed_T" with type uint16
T"VehicleSpeed_T"S

You can also include an optional type attribute section separated by a : character:

‘T’ Name Data-Signature : Type-Attribute

Example:

# Type "OffOn_T" with type uint8, range 0..3 and ValueTable
T"OffOn_T"C(0,3):VT("OffOn_Off", "OffOn_On", "OffOn_Error", "OffOn_NotAvailable")

Data Signatures

Primitive Type Codes

APX uses single-letter primitive type codes. In general, lowercase letters represent signed types and uppercase letters represent unsigned types.

Type Code	Platform Type	Bits	Lower Limit	Upper Limit
c	int8	8	-128	127
s	int16	16	-32768	32767
l	int32	32	-2147483648	2147483647
u	int64	64	-(2^63)	(2^63)-1
C	uint8	8	0	255
S	uint16	16	0	65535
L	uint32	32	0	4294967295
U	uint64	64	0	(2^64)-1
a	unsigned char	8	0	255

Array Types

Any primitive type code can be followed by [n], where n is the number of array elements.

Examples:

C[3]     # type: uint8, array-length: 3, memory-size: 3 bytes
S[4]     # type: uint16, array-length: 4, memory-size: 8 bytes

Strings

Declaring an array using the a type code turns the type into a string. The array length declares how many bytes the string can contain (at most).

APX allows writing of strings whose length is shorter than or equal to the maximum number of array elements (bytes). In that case, APX automatically sets the remaining bytes to null (\0).

Examples:

a[10]    # type string, array-length: 10, memory-size: 10 bytes
a[40]    # type string, array-length: 40, memory-size: 40 bytes

Data Limits

All primitive type codes can have an optional lower/upper limit by appending (Lower, Upper) immediately after the type code:

• Lower: Lower data limit (decimal integer)

• Upper: Upper data limit (decimal integer)

When combined with an array declaration, the limit is placed before the array brackets.

Examples:

C(0,1)       # type: uint8, lower-limit: 0, upper-limit: 1
C(0,3)       # type: uint8, lower-limit: 0, upper-limit: 3
S(0,10000)   # type: uint16, lower-limit: 0, upper-limit: 10000
C            # type: uint8, lower-limit: 0 (implicit), upper-limit: 255 (implicit)
S            # type: uint16, lower-limit: 0 (implicit), upper-limit: 65535 (implicit)
C(0,3)[10]   # type: uint8 array, length: 10, limits: 0..3 for each element

Record Types

Record types (structs) are declared in APX by wrapping the data signature in braces {}.

Each record element consists of two parts:

• Element name: String literal enclosed in quotes

• Element signature: Data Signature

Record elements are placed consecutively without whitespace or separators.

Examples:

# Record with 2 elements: "UserId" (uint32) and "UserName" (string of max 64 bytes)
{"UserId"L"UserName"a[64]}

# Record with 3 uint8 elements
{"Red"C"Green"C"Blue"C}

Note: For APX IDL v1.2, implementations are not required to support nested records. APX IDL v1.3 introduces that conformance requirement.

Type References

Data signatures can reference a type definition using the capital letter T followed by the numeric type index enclosed in brackets [].

Example:

T"VehicleSpeed_T"S          # This type has index 0
T"EngineSpeed_T"S           # This type has index 1
P"VehicleSpeed"T[0]:=65535  # References VehicleSpeed_T
P"EngineSpeed"T[1]:=65535   # References EngineSpeed_T

Note: This version of the IDL does not support type reference by name (see APX IDL v1.3).

Type Attributes

In APX IDL v1.2 there is only a single type attribute, the ValueTable.

Value Table

A ValueTable maps enumeration names onto a data type. It uses the VT(...) syntax with a comma-separated list of string literals:

Example:

VT("OffOn_Off", "OffOn_On", "OffOn_Error", "OffOn_NotAvailable")

Port Declarations

There are two types of ports in APX:

• Require-ports (R): Input ports receiving data into the node.

• Provide-ports (P): Output ports transmitting data from the node.

Require-port Declaration

A Require-port declaration starts with capital letter R followed by its name and data signature:

‘R’ Name Data-Signature

# Require-port "VehicleSpeed" with data type uint16
R"VehicleSpeed"S
# Require-port "EngineSpeed" with type reference 1
R"EngineSpeed"T[1]

Optional port attributes are appended after a colon : separator:

‘R’ Name Data-Signature : Port-Attributes

# Require-port with init-value
R"VehicleSpeed"S:=65535

Provide-port Declaration

A Provide-port declaration starts with capital letter P followed by its name and data signature:

‘P’ Name Data-Signature

# Provide-port "VehicleSpeed" with data type uint16
P"VehicleSpeed"S
# Provide-port with init-value
P"VehicleSpeed"S:=65535

Port Attributes

Port attributes appear after the colon : separator in a port declaration. Multiple attributes are separated by commas.

Init-Value

The init-value attribute sets the initial value of the port data. If no init-value exists, the port data defaults to zero.

APX accepts four forms of initializers:

Decimal and Hexadecimal Initializers

=7               # Decimal init-value
=255             # Decimal init-value
=0xff            # Hexadecimal init-value
=0xffff          # Hexadecimal init-value

String Initializer

=""              # Empty string initializer

Record Initializer

={255, 255, 255} # Record initializer for data signature containing 3 members

Full Language Specification

Document
    ApxHeader '\n' Statements

ApxHeader
    'APX/1.2'

Statements
    Statement '\n'
    Statement '\n' Statement

Statement
   NodeDeclaration
   TypeDeclaration
   RequirePortDeclaration
   ProvidePortDeclaration

NodeDeclaration
    'N' Name

TypeDeclaration
    'T' Name TypeSignature
    'T' Name TypeSignature ':' TypeAttributes

RequirePortDeclaration
    'R' Name TypeSignature
    'R' Name TypeSignature ':' PortAttributes

ProvidePortDeclaration
    'P' Name TypeSignature
    'P' Name TypeSignature ':' PortAttributes

Name
    '"' NameChars '"'

Names
    Name
    Name ',' Names

NameChars
    NameChar
    NameChar NameChars

NameChar
    'a' . 'z'
    'A' . 'Z'
    '0' . '9'
    '_'
    '-'

TypeSignature
    PrimitiveType
    PrimitiveType '[' OneNine Digits ']'
    'T[' Digits ']'
    '{' RecordElements '}'

PrimitiveType
    c
    s
    l
    u
    C
    S
    L
    U

RecordElements
    Name TypeSignature
    Name TypeSignature ',' RecordElements

TypeAttributes
    TypeAttribute
    TypeAttribute ',' TypeAttributes

TypeAttribute
    VT(Names)

PortAttributes
    PortAttribute
    PortAttributes ',' PortAttributes

PortAttribute
    '=' Integer
    '=' StringLiteral

Integer
    Digit
    OneNine Digits
    '-' Digit
    '-' OneNine Digits
    '0x' HexDigits

Digits
    Digit
    Digit Digits

Digit
    '0'
    OneNine

OneNine
    '1' . '9'
HexDigits
    HexDigit
    HexDigit HexDigits

HexDigit
    Digit
    'a' . 'f'
    'A' . 'F'

StringLiteral
    '"' '"'
    '"' Characters '"'

Characters
    character
    character characters

character
    '0020' . '007F' - '"'