diff --git a/contribute/index.rst b/contribute/index.rst index f7def6ee..b03a15e1 100644 --- a/contribute/index.rst +++ b/contribute/index.rst @@ -14,4 +14,5 @@ patches for code, documentation, tests, and more, directly to the project. dox-source-code.rst process/bug-tracking process/docbuild + process/abiprocess linux/development_tree diff --git a/contribute/linux/development_tree.rst b/contribute/linux/development_tree.rst index c776dcb9..a3668c0d 100644 --- a/contribute/linux/development_tree.rst +++ b/contribute/linux/development_tree.rst @@ -43,11 +43,12 @@ change tracker: https://github.com/orgs/thesofproject/projects/2 +Process for firmware ABI changes is documented in :ref:`SOF_ABI_changes`. + When the ABI is not backwards-compatible, the Pull Requests on the kernel side shall include code that deals with older firmware and topology files. - Development branch ================== @@ -84,6 +85,7 @@ as audio codecs, or bug fixes may be contributed by the community. SOF Linux maintainers will, on a regular basis (typically weekly), merge all upstream contributions into the SOF tree. +.. _sof_drv_maintainer_list: Development flow **************** diff --git a/contribute/process/abiprocess.rst b/contribute/process/abiprocess.rst new file mode 100644 index 00000000..eb08d9c3 --- /dev/null +++ b/contribute/process/abiprocess.rst @@ -0,0 +1,60 @@ +.. _SOF_ABI_changes: + +SOF ABI Change Process +###################### + +SOF ABI Definitions +******************* + +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 `FW Source kernel/abi.h`_ + +.. _FW Source kernel/abi.h: https://github.com/thesofproject/sof/blob/master/src/include/kernel/abi.h#L8 + +Change Process +************** + +When a firmware change requires extending or modifying the public +SOF ABI, developer needs to go through the ABI change process as defined +in this section. It is responsibility of the developer to drive this +process, contact the stakeholders, request reviews (and re-reviews when +needed) and e.g. coordinate with the driver maintainers. + +The main steps of the process are depicted in the following +state diagram: + +.. _ABI Change Tracker: https://github.com/orgs/thesofproject/projects/2 + +The pull requests are classified in GitHub using the following +official `ABI Change Tracker`_ + +.. uml:: images/abiprocess.pu + :caption: ABI process state diagram + +When the ABI change is not backwards-compatible, the Pull Requests on the +kernel side shall include code that deals with older firmware and +topology files. See :ref:`development_tree` for kernel side +documentation. + +ABI Change Approvers +******************** + +TSC +--- + +Approval from SOF :ref:`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. Current +list of members is maintained in :ref:`sof_drv_maintainer_list` diff --git a/contribute/process/images/abiprocess.pu b/contribute/process/images/abiprocess.pu new file mode 100644 index 00000000..e80e41b9 --- /dev/null +++ b/contribute/process/images/abiprocess.pu @@ -0,0 +1,23 @@ +[*] --> 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