Dawn Descriptor

Overview

Descriptor is the single runtime definition for Dawn object graph creation. It decides which IO/PROG/PROTO objects exist, with what configuration, and how they are exposed for binding.

If descriptor content changes, runtime behavior changes. No other artifact has the same authority at object-graph level.

For the supported descriptor source forms, including YAML-generated and hand-written C++ descriptors, see Descriptor Format.

For ObjectID/ConfigID bit layouts and per-field encoding details, see Dawn Object.

Boot-Time Role

During CDawn::load_descriptor() the descriptor drives the whole setup flow:

  1. CDescriptor::loadBin() attaches and validates descriptor binary.

  2. IO handler allocates/configures/initializes IO objects from descriptor.

  3. PROG handler allocates/configures/initializes PROG objects.

  4. PROTO handler allocates/configures/initializes PROTO objects.

  5. special IO bindings (Config/Control/Trigger targets) are resolved.

In other words, descriptor is consumed before runtime starts and defines the object topology used by subsequent startAll() phases.

Object Order

Object entries keep the order from the descriptor source. Each handler walks the descriptor in that order, accepts entries for its object type, and stores them in the same relative order. Lifecycle phases then run over that stored order:

  • configure() and init() run from first matching descriptor entry to last matching descriptor entry,

  • start() also runs from first to last,

  • stop(), deinit(), and object deletion run in reverse order.

This ordering is observable for descriptors that compose objects through runtime-created resources. For example, many programs initialize output virt IOs during their own init(). A later program that consumes that virt as a notify-capable source must appear after the producer program in the programs: list; otherwise the consumer may see an uninitialized virt with no notification support.

As a rule, list producers before consumers when the consumer depends on producer-owned initialization side effects such as virt shape, notification support, runtime buffers, or writable config/control targets. Pure object references are resolved by ObjectID, but initialization side effects still follow descriptor order within each handler.

Current Support and Target Features

Currently supported:

  • descriptor binary loaded via CDescriptor::loadBin(),

  • descriptor-driven object allocation for IO/PROG/PROTO handlers,

  • multi-slot descriptor storage via CDevDescriptor slots,

  • FLASH-baked multi-descriptor slots: multiple uint32_t arrays compiled into the firmware and registered at boot via dawn_register_flash_slots(), defined with descriptor0/descriptor1/… blocks in a single YAML file,

  • runtime descriptor upload into writable slots via CIODescriptor seeked writes,

  • runtime slot switching via CIODescSelector + CDescSwitch,

  • rollback by selecting slot 0 (boot descriptor),

  • runtime writable volatile updates for RW-enabled config items (via object config APIs; reset on reboot),

  • descriptor checksum field in format.

Target / desired features (not supported yet):

  • source-agnostic descriptor loading (file/other memory regions/transport),

  • persistent runtime configuration storage and restore,

  • full descriptor image replacement with policy-managed rollback/fallback.

Binary Container Contract

Descriptor is a stream of 32-bit words with this outer shape:

  1. header magic: DAWN_DESCRIPTOR_HDR

  2. object count field (stored in descriptor header)

  3. object-entry stream

  4. footer magic: DAWN_DESCRIPTOR_FOOT

  5. checksum word

Object-entry format:

  • objid (1 word)

  • config-item count (1 word)

  • repeated config items:

    • cfgid header (1 word)

    • cfgid.size data words

All lengths are 32-bit-word based.

Allocation Semantics

Handlers do not parse arbitrary descriptor bytes on their own. They rely on CDescriptor::alloc_objects() iteration and object validity checks to receive relevant entries.

Allocation behavior:

  • each handler accepts only matching object types/classes,

  • matching entries are wrapped as dawn::CDescObject,

  • factories create concrete runtime instances from wrapped entries,

  • duplicate ObjectID detection is logged during allocation.

Metadata Semantics

Entries with objid.type == OBJTYPE_ANY are descriptor-level metadata/global options. They are not instantiated as normal IO/PROG/PROTO runtime objects.

Common descriptor metadata IDs:

  • DESC_CFG_VERSION

  • DESC_CFG_STRING

Validation Model

CDescriptor::binValid() is the primary gate before allocation. Validation is layered:

  1. container markers and top-level sanity checks,

  2. dtype support checks for object IDs and config IDs,

  3. structural walk consistency across all object/config entries,

  4. object-level descriptor validation.

CRC check behavior:

  • required when CONFIG_DAWN_DESC_SLOTS > 1,

  • for single-slot builds, controlled by CONFIG_DAWN_DESC_VALID_CRC32.

Binary Word Examples

Example 1: minimal descriptor, two IO objects, no config items.

[0]  0x0d0a0302  // DAWN_DESCRIPTOR_HDR
[1]  0x00000002  // object count

[2]  0x40270001  // ObjectID: IO, cls=1, dtype=UINT32, priv=1
[3]  0x00000000  // config item count

[4]  0x40270002  // ObjectID: IO, cls=1, dtype=UINT32, priv=2
[5]  0x00000000  // config item count

[6]  0x02030a0d  // DAWN_DESCRIPTOR_FOOT
[7]  0xdeadbeef  // checksum word

Example 2: metadata object + one IO object.

[0]  0x0d0a0302  // DAWN_DESCRIPTOR_HDR
[1]  0x00000002  // object count (metadata + one IO)

[2]  0x00000000  // ObjectID: OBJTYPE_ANY metadata object
[3]  0x00000001  // metadata config item count
[4]  0x00070021  // ConfigID: DESC_CFG_VERSION, UINT32, size=1
[5]  0x00020001  // version value

[6]  0x40270001  // ObjectID: IO, cls=1, dtype=UINT32, priv=1
[7]  0x00000000  // config item count

[8]  0x02030a0d  // DAWN_DESCRIPTOR_FOOT
[9]  0xdeadbeef  // checksum word

Checksum behavior:

  • with CONFIG_DAWN_DESC_VALID_CRC32 enabled, checksum must validate,

  • otherwise checksum word is still present, but CRC check is not enforced.

ObjectID/ConfigID bit packing reference: Dawn Object.

Resource and Performance Impact

Memory

  • descriptor storage cost is linear to descriptor size (4 * number_of_words bytes),

  • CDescriptor keeps a pointer/length view of that binary and a vector of CDescObject wrappers for allocated entries,

  • descriptor config payload is not duplicated by loader; wrappers reference descriptor memory.

Performance

  • descriptor validation and parsing are startup-time linear walks over descriptor words,

  • handlers perform descriptor allocation passes during initialization,

Compiler Optimization and Footprint Tuning

Descriptor-driven allocation is runtime-selectable, so compile-time optimizer cannot always prove which object classes are never used by a given deployment. For small systems, footprint tuning should rely on Kconfig to enable only the required Dawn components and features.

Doxygen