Device Group Primer

This document provides a quick primer on what device group is and provides guidance on usage of device groups.

Introduction

A typical SoC has a large number of peripherals such as I2C, UART etc. In an optimized boot flow mode, we typically need to startup a limited set of peripherals and incrementally increase the usage of the SoC. Motivation for this usage can be one of two reasons:

  • Hardware functionality is limited for varied reasons (Such as voltage not enabled for a domain etc..).
  • Limited peripherals initialized implies lesser time required for initialization functions in System Firmware and applications can perform time critical activities earlier.

System Firmware provides a scheme where we can choose one of the two initialization models:

  • Bring up everything during the configuration sequences so that application software (HLOS/Bootloader..) can operate on any peripheral it desires.
  • Start up a limited set of peripheral set and incrementally add capability to control additional resources of the SoC.

The above mentioned schemes are mutually exclusive since the product use cases are specific in the manner of usage of peripheral sets. We shall go into more in-depth discussion later in this document.

Definition

In the simplest of terms, we call “Device Group” or DEVGRP as a concept to organize a logical set of peripherals to provide services.

Each device group enables a set of peripherals that can be operated upon when the domain initialization for that domain is invoked with the corresponding boardconfig API calls such as TISCI_MSG_BOARD_CONFIG

The specific grouping of device instances are documented in the SoC specific documentation.

DEVGRP values

Device group identification follows a generic bitfield format.

  • devgrp_t type is u8 (8 bits)
  • Values for the field is defined as follows:
Device Group Value Description
DEVGRP_ALL 0 SoC SYSFW devgrp any: NOT TO BE used for SoC data. This implies that specific sequenced devgrp is NOT used. This functionality is SoC boot mode specific. Allows for all peripherals for the specific domain to be used
DEVGRP_00 1 << 0 SoC specific Devgrp 0. Please refer to SoC information for validity in the specific SoC. This implies that specific sequenced devgrp is used. This enables the peripherals listed accessible for this group.
DEVGRP_01 1 << 1 SoC specific Devgrp 1. Please refer to SoC information for validity in the specific SoC. This implies that specific sequenced devgrp is used. This enables the peripherals listed accessible for this group.
DEVGRP_02 1 << 2 SoC specific Devgrp 2. Please refer to SoC information for validity in the specific SoC. This implies that specific sequenced devgrp is used. This enables the peripherals listed accessible for this group.
DEVGRP_03 1 << 3 SoC specific Devgrp 3. Please refer to SoC information for validity in the specific SoC. This implies that specific sequenced devgrp is used. This enables the peripherals listed accessible for this group.
DEVGRP_04 1 << 4 SoC specific Devgrp 4. Please refer to SoC information for validity in the specific SoC. This implies that specific sequenced devgrp is used. This enables the peripherals listed accessible for this group.
DEVGRP_05 1 << 5 SoC specific Devgrp 5. Please refer to SoC information for validity in the specific SoC. This implies that specific sequenced devgrp is used. This enables the peripherals listed accessible for this group.
DEVGRP_06 1 << 6 SoC specific Devgrp 6. Please refer to SoC information for validity in the specific SoC. This implies that specific sequenced devgrp is used. This enables the peripherals listed accessible for this group.

Warning

  • User MUST be careful NOT to use DEVGRP_ALL when using DEVGRP_00 to DEVGRP_06. The usage is mutually exclusive.
  • SoC specific peripheral grouping is predefined and NOT configurable by user.

Usage models

As mentioned in previous sections, there are two valid models of usage. This section deals with each valid mode of operation.

Usage Model 1: Enable all devices

In this usage model, we don’t really know upfront as to the usage of peripherals in the system. Typical example is running generic community software OR boot time is not of concern.

Sequence of calls could be:

In this sequence of initialization, all domains are initialized equally and further System Firmware services are now operational corresponding to that domain after each domain initialization is complete.

Warning

  • User MUST be careful NOT to mix DEVGRP_ALL usage with incremental initialization.
  • Because this usage model initializes the entire SoC at boot, applications sensitive to boot time latency should first try to use incremental initialization to optimize boot time by only initializing what is needed.

Usage Model 2: Incremental initialization

In this usage model, we don’t enable access to all resources on the SoC. Instead, we incrementally add responsibility for System Firmware to introduce control over wider parts of SoC. This is achieved by incrementally invoking increasing order of devgrp permitted by the SoC. Each devgrp indicates a specific group of peripherals and resources that System Firmware takes ownership of. The specific group of peripherals for a given devgrp can vary SoC to SoC.

For each of the DEVGRP_00, DEVGRP_01 definitions, please refer to SoC information devgrp section to get details corresponding to the SoC.

Sequence of calls could be:

To compare with Enable all model, if absolutely no operation is performed by the application other than invoking the boardconfig APIs, the state of the SoC at the end of initialization of all valid devgrps should be equal to the state of the SoC with DEVGRP_ALL being invoked.

Note

  • Even though it is permitted to use a bitfield mix such as DEVGRP_00|DEVGRP_01, users are expected to be familiar with hardware architecture to understand the dependencies and side effects of invalid usage.

Warning

  • User MUST be careful NOT to mix usage with Enable all.
  • Users are strongly recommended to read SoC information for validity of various devgrps in a specific SoC.
  • User must be careful NOT to access resources OR invoke system firmware services that can be impacted by peripherals or domains not initialized by each stage of devgrp. System Firmware does not provide protection schemes to prevent or detect such usage.
  • User must be careful NOT to confuse hardware “domains” with similar sounding names used in devgrps. devgrps is a software defined logical grouping of peripherals which may be a subset of a domain OR may span physical domains.
  • Users should be careful NOT to re-initialize a devgrp that is already initialized. Checks and protection for invalid attempts are not performed in sysfw in the interest of primary function of high speed initialization. You may use the debug functionality Board Config Debug to track down invalid usage.