From d04a0f9ac67dde5a59ae33b2b4bee644c043c192 Mon Sep 17 00:00:00 2001 From: Kai Vehmanen Date: Mon, 7 Sep 2020 16:24:36 +0300 Subject: [PATCH] contribute: Add section on ABI change field annotation Add a new section and guidance on how new and/or modified ABI fields and enumerations must be documented in the header files. Signed-off-by: Kai Vehmanen --- contribute/process/abiprocess.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/contribute/process/abiprocess.rst b/contribute/process/abiprocess.rst index b32f6973..10dd0b35 100644 --- a/contribute/process/abiprocess.rst +++ b/contribute/process/abiprocess.rst @@ -41,6 +41,26 @@ kernel side shall include code that deals with older firmware and topology files. See :ref:`development_tree` for kernel side documentation. +Documenting 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: + +.. code-block:: c + + struct foo { + uint8_t group_id; /**< group ID, 0 means no group (ABI3.17) */ + } __attribute__((packed)); + +.. code-block:: c + + enum bar { + EXT_MAN_ELEM_FOO_DATA = 7, /**< ABI3.18 */ + }; + ABI change approvers ********************