SOF ABI Change Process

SOF ABI definitions

The SOF ABI consists of public structs used in host-FW communication defined in:

  • src/include/kernel/

  • src/include/ipc/

  • src/include/user/

SOF ABI versioning is defined in firmware source code documentation: https://github.com/thesofproject/sof/tree/master/src/include/kernel/abi.h

Change process

When a firmware change requires extending or modifying the public SOF ABI, the developer must go through the ABI change process as defined in this section. The developer must drive this process, contact the stakeholders, request reviews (and re-reviews when needed) and coordinate with the driver maintainers.

The main steps of the process are depicted in the following state diagram:

The pull requests are classified in GitHub using the following official ABI Change Tracker.

[*] --> NewABIChange: Firmware feature that requires ABI change NewABIChange --> RFC: Send RFC Pull Request\ncovering interface changes\n and rationale for the change note right of RFC : RFC stage is intended to\navoid wasted effort via early\n engagement with the ABI users RFC --> RFCApproved: a) Approve+1 from at least\none Driver and one FW Maintainer,\n b) Owners assigned for FW and driver impl NewABIChange --> FWImplementation: Fast path implementation\nonly when no driver impact RFCApproved --> FWImplementation: Implementation done, submit as non-RFC PR FWImplementation --> ABIClassification: Tag PR for ABI classifier ABIClassification --> ABIApproved: TSC member approval and\nABI MAJOR.MINOR classification done ABIApproved --> DriverPRCheck: If driver change is needed,\nwait until both sides ready for merge DriverPRCheck --> FWChangeMerged: No driver change:\nAfter review and validation ok, merge DriverPRCheck --> DrvChangeMerged: After review and\nvalidation ok, merge DrvChangeMerged --> FWChangeMerged: After review and\nvalidation ok, merge

Figure 146 ABI process state diagram

When the ABI change is not backwards-compatible, Pull Requests on the kernel side shall include code that deals with older firmware and topology files. See Linux SOF drivers for kernel side documentation.

Document modified fields

When the interface is extended with a backwards-compatible (MINOR) interface change, each added or modified interface field must be documented with a reference to the interface version where the change was first implemented.

Some code examples:

struct foo {
        uint8_t group_id;           /**< group ID, 0 means no group (ABI3.17) */
} __attribute__((packed));

enum bar {
      EXT_MAN_ELEM_FOO_DATA = 7,    /**< ABI3.18 */
};

ABI change approvers

TSC

Approval from an SOF Technical Steering Committee (TSC) member is needed for all ABI changes.

SOF driver

Linux driver team approval for changes can be granted by any member of the SOF Linux driver maintainer team. The current list of members is maintained in Development flow.