-
Notifications
You must be signed in to change notification settings - Fork 73
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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>
- Loading branch information
Showing
2 changed files
with
119 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
|