Device tree parsing process

GAP_SDK provides a series of python scripts that aim to generate a C-coded version of the devicetree to allow the SDK to benefit from its content.

Here are the main objectives of the generated C files:

  • Provide data only about hardware required by the application from the devicetree

  • Instanciate a pi_device_t object for each driver

  • Create a generic API to open and close devices

  • Provide a list of available devices as a enum type.

  • Provide the initial value of pads registers

  • Provide overriden data from menuconfig interface

Process

To achieve these objectives, the parsing process is decomposed into multiple steps as described in the following figure :

../../../_images/devicetree_parsing_process_detailed.png

DeviceTree parsing process

Reading the device tree

The input file of this parsing process is a global devicetree blob file. Is it read thanks to the pyfdt python library. The reading goal is to identify nodes possessing a status property set to “ok”. If a node has it, the parser start to identify a device from this node.

Identify devices from node

After being identified, the parser analyze the node’s content and sort its properties into categories. For more information, please check the Device node section in Devicetree source files page.

Parsing the configuration file

As described in the Interaction with Kconfig page, kconfig options play a major role in the devicetree feature. They select, avoid or modify devicetree content before being outputed in C files. The configuration file parser expect kconfig option names to be formatted in specific way depending on their purpose. The parser aims to identify these options and give them attributes. Such attributes are then used to link kconfig options with devicetree content.

Here is a list of special keywords used by the parser to link kconfig option to the devicetree :

Config parser keywords

Keyword

Feature

CONFIG_CHIP

Represent a chip and a main dts file

CONFIG_BOARD

Represent a board and a dts plugin file

CONFIG_BOARD_[…]_OPTION_[…]

Represent a board option. This is useful when you link it to a board sub devicetree

CONFIG_DRIVER

Represent a driver to find in dts file

CONFIG_DRIVER_TYPE

Indicates the type of a driver (flash, ram, …)

DRIVER && DEFAULT

Indicates that a driver is selected by default

CONFIG_PLATFORM

Gives the platform on which the application will run

Note

More keywords can be added here to provide new mechanisms

After being parsed, kconfig options act like filters on devicetree content.

As an example, selecting a “driver option” leads to the parser picking the matching content in the devicetree and output it in C files.

Based on the driver name contained in the option name : CONFIG_DRIVER_<DRIVERNAME>, the parser is looking for a node in the devicetree that has the same name in its device_name property. If there is a match, the content is selected.

Use cases

  • CONFIG_BOARD_[…]_OPTION_[…]

Audio Addon V2.1 can be configured in a hardware way by solder or unsolder jumpers on the board. It leads to a different SAI configuration for the two SSM6515 devices embedded on the board. On for a PDM configuration and another one for the PCM configuration. Since the hardware configuration is different, two devicetrees are created to describe each configuration:

  • audio_addon_v2_1_option_ssm6515_pdm.dts

  • audio_addon_v2_1_option_ssm6515_pcm.dts

As other devicetree files, they are both linked to a kconfig option :

  • BOARD_AUDIO_ADDON_V2_1_OPTION_SSM6515_PDM

  • BOARD_AUDIO_ADDON_V2_1_OPTION_SSM6515_PCM

Instead a main board’s devicetree, these two devicetree files does not require a dedicated bsp. Audio addon v2.1’s one is convenient. Therefore, the option layout CONFIG_BOARD_[…]_OPTION_[…] allows to bypass the dedicated bsp inclusion dump process in dt.h file like :

  • #include “bsp/boards/bsp_audio_addon_v2_1.h”

Pads initialization

The devicetree offers a way to handle the configuration of the pads alternate function. The parser reunite the pad definition from all devices and compute the value to set in GAP’s PADFUN registers to get the desired behavior.

Dumping results

The last step of the parser is to dump all results into a source and a header file. Please check Devicetree output for a detailed explanation of their content.