OrgACRN
/
sof
mirror of https://github.com/thesofproject/sof.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

ipc: add IPC documentation to header.h 

Collect key IPC documentation to header.h and ensure it is
included in public API documentation in the doxygen output.

Specifically move the IPC compatibility rules documented in ipc/handler.c.
This is important information to all IPC implementers for host
and DSP, so should be part of API documentation.

Signed-off-by: Kai Vehmanen <kai.vehmanen@linux.intel.com>
This commit is contained in:
Kai Vehmanen 2020-07-09 13:58:37 +03:00 committed by Liam Girdwood
parent b70b13cc1a
commit bccc9cb2ca
2 changed files with 34 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
src/include/ipc/header.h
View File

@ -19,7 +19,10 @@
#include <stdint.h>
/** \addtogroup sof_uapi uAPI
* SOF uAPI specification.
* SOF uAPI specification
*
* Message structure
* -----------------
*
* IPC messages have a prefixed 32 bit identifier made up as follows :-
*
@ -28,9 +31,36 @@
* - C is command type (12 bits)
* - N is the ID number (16 bits) - monotonic and overflows
*
* This is sent at the start of the IPM message in the mailbox. Messages should
* not be sent in the doorbell (special exceptions for firmware).
* IPC ABI version compatibility rules
* -----------------------------------
*
* 1. FW binaries will only support one MAJOR ABI version which is advertised
* to host at FW boot.
*
* 2. Host drivers will support the current and older MAJOR ABI versions of
* the IPC ABI (up to a certain age to be determined by market information).
*
* 3. MINOR and PATCH ABI versions can differ between host and FW but must be
* backwards compatible on both host and FW.
*
* IPC messages sizes can be different for sender and receiver if MINOR or
* PATCH ABI versions differ as new fields can be added to the end of
* messages.
*
* i) Sender > receiver: receiver only copies its own ABI structure size.
*
* ii) Receiver > sender: receiver copies its own ABI size and zero pads
* new fields. i.e. new structure fields must be non
* zero to be activated.
*
* Guidelines for extending ABI compatible messages :-
*
* - i) Use reserved fields.
*
* - ii) Grow structure at the end.
*
* - iii) Iff (i) and (ii) are not possible then MAJOR ABI is bumped.
*
* @{
*/

29
src/ipc/handler.c
View File

@ -59,35 +59,6 @@
#define iGS(x) ((x) & SOF_GLB_TYPE_MASK)
#define iCS(x) ((x) & SOF_CMD_TYPE_MASK)
/*
* IPC ABI version compatibility rules :-
*
* 1) FW binaries will only support one MAJOR ABI version which is advertised
* to host at FW boot.
*
* 2) Host drivers will support the current and older MAJOR ABI versions of
* the IPC ABI (up to a certain age to be determined by market information).
*
* 3) MINOR and PATCH ABI versions can differ between host and FW but must be
* backwards compatible on both host and FW.
*
* IPC messages sizes can be different for sender and receiver if MINOR or
* PATCH ABI versions differ as new fields can be added to the end of
* messages.
*
* i) Sender > receiver: receiver only copies it's own ABI structure size.
*
* ii) Receiver > sender: receiver copies its's own ABI size and zero pads
* new fields. i.e. new structure fields must be non
* zero to be activated.
*
* Guidelines for extending ABI compatible messages :-
*
* i) Use reserved fields.
* ii) Grow structure at the end.
* iii) Iff (i) and (ii) are not possible then MAJOR ABI is bumped.
*/
#define _IPC_COPY_CMD(rx, tx, rx_size) \
do { \
int ___ret; \