contributing: Add section on process for SOF FW ABI changes

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

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
 ****************

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`

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