Pin Tool Annotations

Pin Tool annotations are used to annotate configuration options related to a device pinout, and certain other options related to device resource allocation. These annotations are parsed and made use of by the Pin Tool in Simplicity Studio.

Like CMSIS annotations, Pin Tool annotations are confined to a part of the header file enclosed between a start tag and an end tag. These are

// <<< sl:start pin_tool >>>

and

// <<< sl:end pin_tool >>>

There may be one such area in each header file, containing one or more configuration blocks.

Each Pin Tool annotated configuration block consists of two sections:

• requirement section
• output section

Requirement Section

The Requirement section represents a query to the Pin Tool where a device resource with a specific set of properties or capabilities is requested. This allows the Pin Tool to highlight possible selections of peripherals that would serve as solutions to this requirement.

A requirement has the format

// <type options> name description

Where type is the type of requirement, typically the type of peripheral that is being requested. options is an optional list of key=value pairs that further constrains the capabilities and properties of the peripheral that is required. name is the name of the requirement, and serves as the prefix for configuration defines that are generated in response to the selection of a specific peripheral as the solution for a requirement. description is text describing the requirement. The option with key label is interpreted as a human-readable string used in GUIs. If no label is set, the name is used as a GUI label.

Output Section

The output section is where the Pin Tool performs source code generation based on the solution to the requirement. This section is enclosed between the tags

// $[TYPE_NAME]

// [TYPE_NAME]$

where TYPE and NAME are the uppercase transformations of the type and name requested in the corresponding requirement section.

Example GPIO Output

// <gpio label="GPIO Pin"> NAME My named GPIO pin used to toggle a switch

// $[GPIO_NAME]
#define NAME_PORT       gpioPortA
#define NAME_PIN        1
// [GPIO_NAME]$

// <gpio capability=em4 label="The Other Pin"> OTHER

// $[GPIO_OTHER]
#define OTHER_PORT      gpioPortB
#define OTHER_PIN       3
// [GPIO_OTHER]$

Example Peripheral Signal Output

// <usart signal=TX,RX> NAME

// $[USART_NAME]
#define NAME_PERIPHERAL     USART1
#define NAME_PERIPHERAL_NO  1

#define NAME_TX_PORT        gpioPortA
#define NAME_TX_PIN         0
#define NAME_TX_LOC         0

#define NAME_RX_PORT        gpioPortA
#define NAME_RX_PIN         1
#define NAME_RX_LOC         0
// [USART_NAME]$

Note: On devices with multiple pins behind the same location selector (Series 0 devices and some peripherals on Series 1 devices), the TX_LOC and RX_LOC above become ROUTE_LOC, where ROUTE is the name of the location selector (typically ROUTE when the peripheral only has a single selector). On Series 2 devices, no _LOC #defines are emitted, since the DBUS uses port and pin information instead.

Example PRS Output

// <prs gpio=true> NAME

// $[PRS_NAME]
#define NAME_CHANNEL    0

#define NAME_PORT       gpioPortA
#define NAME_PIN        1
#define NAME_LOC        0
// [PRS_NAME]$

Example TIMER Channel Output

// <timer channel=FOO> NAME

// $[TIMER_NAME]
#define NAME_PERIPHERAL     TIMER0
#define NAME_PERIPHERAL_NO  0

#define NAME_FOO_CHANNEL    0
#define NAME_FOO_PORT       gpioPortA
#define NAME_FOO_PIN        1
#define NAME_FOO_LOC        0
// [TIMER_NAME]$

Peripheral Types

In general, peripheral types used by the Pin Tool map closely to the name of the hardware peripherals on the device. Silicon Labs provides drivers for most hardware peripherals using these configuration annotations. These may be used as a reference for what peripheral types are available.

Requirement Options

The following table lists all allowed options. The option is expected to take a value, and the expected format is key=value.

Key	Value Type	Description
label	String	Human-readable label for the requirement.
optional	boolean (true or false)	Default false. If set to true, this requirement is optional, and does not need to be fulfilled by the tool. Warnings/errors will not be generated if not fulfilled.
capability	Comma-separated list of strings	The peripheral needs to have the listed capabilities. See below for valid capabilities for different peripheral types.
signal	Comma-separated list of strings	The peripheral must have the listed signals, they must be enabled and routed to a location. If enclosed in parentheses, the signal is optional.
follow	name string	The peripheral selected for this requirement must immediately follow the peripheral selected for the requirement with the given name.

In addition to the above options that can be used with all peripheral types, certain peripheral types support additional options, as described below:

timer

Key	Value Type	Description
channel	Comma-separated list of strings	The timer peripheral selected for this requirement must have compare/capture channels with the names given.

prs

Key	Value Type	Description
gpio	boolean (true or false)	Default false. If set to true, the PRS channel's associated GPIO output must be enabled and routed to a location.

Capability Values

gpio

Capability	Description
em4	GPIO pin is EM4 wakeup capable
em2	GPIO pin is EM2 wakeup capable (Note: not currently implemented in the tools)
5v	GPIO pin is 5V tolerant

usart

Capability	Description
irda	USART is IrDA capable
i2s	USART is I2S capable

timer

Capability	Description
dti	TIMER has DTI support
32b	TIMER CNT register is at least 32 bits wide

Advanced Requirement Examples

EM4 wakeup capable, 5V tolerant GPIO

// <gpio capability=em4,5v> MY_GPIO

32-bit timer with 4 channels

// <timer capability=32b channel=R,G,B,W> MY_BULB

Two successive PRS channel with GPIO output

// <prs gpio=true> FIRST
// <prs gpio=true follow=FIRST> SECOND