From 32995d7003ed9d72f26d241c99a11d9347b565d3 Mon Sep 17 00:00:00 2001
From: Keyon Jie <yang.jie@linux.intel.com>
Date: Mon, 1 Jun 2020 17:08:47 +0800
Subject: [PATCH] developers_guides: add UUID usage guide for SOF

Add a page to describe how to use UUID on SOF, the UUID will be the
replacement of the traditional component type.

Signed-off-by: Keyon Jie <yang.jie@linux.intel.com>
---
 developer_guides/index.rst      |   1 +
 developer_guides/uuid/index.rst | 118 ++++++++++++++++++++++++++++++++
 2 files changed, 119 insertions(+)
 create mode 100644 developer_guides/uuid/index.rst

diff --git a/developer_guides/index.rst b/developer_guides/index.rst
index 5d0deaa4..c1298c5e 100644
--- a/developer_guides/index.rst
+++ b/developer_guides/index.rst
@@ -13,6 +13,7 @@ terminology before reading further.
    firmware/index
    unit_tests
    topology/topology
+   uuid/index.rst
    debugability/index
    tuning/sof-ctl
    rimage/index.rst
diff --git a/developer_guides/uuid/index.rst b/developer_guides/uuid/index.rst
new file mode 100644
index 00000000..1721e59b
--- /dev/null
+++ b/developer_guides/uuid/index.rst
@@ -0,0 +1,118 @@
+.. _uuid:
+
+UUID Usage in SOF
+#################
+
+We use universally unique identifier (UUID) for component type
+definition in SOF, and for the whole SOF stack, the UUID usage is
+following below rules:
+
+UUID allocation
+***************
+The UUID of a specific component should be specified in the firmware
+component dirver, e.g. for src component, in sof/src/audio/src.c:
+
+.. code-block:: none
+
+   /* c1c5326d-8390-46b4-aa47-95c3beca6550 */
+   DECLARE_SOF_UUID("src", src_uuid, 0xc1c5326d, 0x8390, 0x46b4,
+                    0xaa, 0x47, 0x95, 0xc3, 0xbe, 0xca, 0x65, 0x50);
+
+UUID in topology
+****************
+We should provide UUID string in topology .m4 file in the exactly same
+format as commented in the firmware, e.g for host it is
+c1c5326d-8390-46b4-aa47-95c3beca6550, so in the topology .m4 file
+tools/topology/m4/src.m4:
+
+.. code-block:: none
+
+   dnl Defines the macro for SRC widget
+   define(SRC_UUID_ARRAY, UUID_ARRAY("c1c5326d-8390-46b4-aa47-95c3beca6550"))
+
+We have a .m4 macro UUID_ARRAY() will help to transfer format in #2 (36
+digits) to 16 Bytes byte array, after compiled, the corresponding ALSA
+UUID token defined here will be generated:
+
+.. code-block:: none
+
+   /* vendor tuple for uuid */
+   struct snd_soc_tplg_vendor_uuid_elem {
+           __le32 token;
+           char uuid[16];
+   } __attribute__((packed));
+
+Linux topology driver
+*********************
+The topology driver will parse the 16Bytes UUID token and sent it to the
+firmware in component creation stage, **for all components**.
+
+.. code-block:: none
+
+   /* Generic component tokens */
+   static const struct sof_topology_token comp_tokens[] = {
+           {SOF_TKN_COMP_CORE_ID,
+               SND_SOC_TPLG_TUPLE_TYPE_WORD, get_token_u32,
+               offsetof(struct sof_ipc_comp, core), 0},
+           {SOF_TKN_COMP_UUID,
+               SND_SOC_TPLG_TUPLE_TYPE_UUID, get_token_uuid,
+               offsetof(struct sof_ipc_comp, uuid), 0},
+   };
+
+.. code-block:: none
+
+   static int sof_widget_ready(struct snd_soc_component *scomp, int index,
+                               struct snd_soc_dapm_widget *w,
+                               struct snd_soc_tplg_dapm_widget *tw)
+   {
+   ...
+           ret = sof_parse_tokens(scomp, &template, comp_tokens,
+                                  ARRAY_SIZE(comp_tokens), tw->priv.array,
+                                  le32_to_cpu(tw->priv.size));
+   ...
+   }
+
+UUID arrays stored section
+**************************
+The UUID arrays are stored to SRAM in firmware, though it will lead to a
+1~4KB (depends on how many modules are compiled) memory consumption
+increase. e.g. in src/platform/cannonlake/cannonlake.x.in:
+
+.. code-block:: none
+
+  .fw_ready : ALIGN(4)
+  {
+    KEEP (*(.fw_ready))
+    KEEP (*(.fw_ready_metadata))
+  } >sof_fw :sof_fw_phdr
+
+UUID to component driver mapping
+********************************
+The firmware will use UUID byte array as the first choice to match the
+component driver, and fallback to use traditional component type if
+failed:
+
+.. code-block:: none
+
+   struct comp_dev *comp_new(struct sof_ipc_comp *comp)
+   {
+           struct comp_dev *cdev;
+           const struct comp_driver *drv;
+
+           /* find the driver for our new component with uuid */
+           drv = get_drv_from_uuid(comp->uuid);
+           if (!drv) {
+                   tr_warn(&comp_tr, "comp_new(), no matched uuid, fallback to use type");
+                   drv = get_drv(comp->type);
+                   if (!drv) {
+                           tr_err(&comp_tr, "comp_new(): driver not found, comp->type = %u",
+                                  comp->type);
+                           return NULL;
+                   }
+           }
+   ...
+   }
+
+For UUID definition details, please refer to wikepedia page:
+https://en.wikipedia.org/wiki/Universally_unique_identifier
+