contributing: Add section on process for SOF FW ABI changes

Document revised process for ABI changes including a new step
for Request-for-Comments phase. This is intended to ensure
early engagement of interface changes across driver and firmware
teams, to avoid wasting effort when concerns are raised at
the very end of the process.

Add cross-links between kernel driver and firmware sections.
Also add link to ABI versioning definition in kernel/abi.h
and pointers to TSC and driver maintainer team and who are
the members.

Signed-off-by: Kai Vehmanen <kai.vehmanen@linux.intel.com>

Author: kv2019i

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