Skip to content

Commit dd1737a

Browse files
mmaka1deb-intel
mmaka1
authored and
deb-intel
committed
components: document comp_ops and module_interface dependencies
This chapter documents dependencies between various component (module) interfaces in firmware. It also documents the direction of transition towards a single, simpler native module interface. Signed-off-by: Marcin Maka <[email protected]>
1 parent a919d90 commit dd1737a

File tree

5 files changed

+267
-0
lines changed

5 files changed

+267
-0
lines changed

‎architectures/firmware/sof-common/components/component-module-api.rst‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
.. apps-comp-world:
2+
3+
Component & Module Interfaces
4+
#############################
5+
6+
Introduction of the Module Adapter, an intermediate layer which provides common
7+
code for different module API adapters, created multi-level sequences of calls
8+
to functions and this mechanism is very expensive during run-time processing
9+
with regards to additional cycles consumed for parameter translation and copying
10+
as well as the additional memory for extra buffers, contexts, and the call
11+
stack. The `module_adapter` translates the `comp_ops` interface required by the
12+
existing infrastructure (pipelines etc.) into the `module_interface`. Then
13+
appropriate adapter translates the `module_interface` into the final module
14+
interface like `Cadence Codec API` or `IADK ProcessingModuleInterface`. These
15+
dependencies are illustrated in the next figure.
16+
17+
.. uml:: images/comp-module-api.pu
18+
:caption: Component & Module API
19+
20+
Maintenance of two base component (alias module) interfaces is expensive and
21+
also confusing for the developers who wants to create a module that provides SOF
22+
native module API. It is unclear whether this should be the `comp_ops` or the
23+
`module_interface`. The latter is much more convenient since it is tailored for
24+
the audio processing modules while the `comp_ops` is a multipurpose interface
25+
cluttered with many optional operations required for *dai-comp* modules only.
26+
27+
Therefore the `module_interface` should become the only SOF native module
28+
interface that the rest of underlying infrastructure would interact with
29+
directly. The `comp_ops` would become obsolete and eventually would be removed
30+
from the SOF.
31+
32+
The cost of extra memory required at the moment for intermediate audio data
33+
buffers allocated inside the `module_adapter` layer (see the *Preparation Flow*
34+
figure below) as well as cost of extra cycles required to copy the data to/from
35+
the intermediate buffers (see the *Processing Flow* figure below) could be
36+
avoided by removing the `comp_ops` as well.
37+
38+
.. uml:: images/comp-prepare-flow.pu
39+
:caption: Preparation Flow
40+
41+
.. uml:: images/comp-copy-flow.pu
42+
:caption: Processing Flow

‎architectures/firmware/sof-common/components/images/comp-copy-flow.pu‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
actor pipeline
2+
box "Module Adapter\no-- comp_ops"
3+
participant "module_adapter" as module_adapter
4+
end box
5+
box "IADK Module Adapter\no-- module_interface"
6+
participant "iadk_adapter" as iadk_adapter
7+
end box
8+
box "IADK Module\no-- ProcessingModuleInterface"
9+
participant iadk_module
10+
end box
11+
12+
pipeline -> module_adapter : <b>(1) ops->module_adapter_copy()</b>
13+
activate module_adapter
14+
15+
module_adapter -> module_adapter : find min bytes\nto process
16+
17+
note left of module_adapter
18+
This logic is WRONG for some modules!!
19+
end note
20+
21+
module_adapter -> module_adapter : copy input from sources\nto internal buffers
22+
23+
module_adapter -> module_adapter : module_process()
24+
activate module_adapter
25+
note left of module_adapter
26+
Why all those extra internal calls
27+
used only once??
28+
end note
29+
30+
module_adapter -> iadk_adapter : <b>(2) ops->process()</b>
31+
activate iadk_adapter
32+
iadk_adapter -> iadk_module : <b>(3) processing</b>
33+
module_adapter <-- iadk_adapter
34+
deactivate iadk_adapter
35+
36+
deactivate module_adapter
37+
38+
module_adapter -> module_adapter : module_adapter_process_output()
39+
activate module_adapter
40+
module_adapter -> module_adapter : copy output from internal buffers\ntosinks
41+
deactivate module_adapter
42+
pipeline <-- module_adapter

‎architectures/firmware/sof-common/components/images/comp-module-api.pu‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
scale 1024 width
2+
3+
component "pipelines" {
4+
class pipeline
5+
hide pipeline methods
6+
hide pipeline attributes
7+
}
8+
component "component" {
9+
10+
class comp_driver <<struct>> {
11+
}
12+
hide comp_driver methods
13+
hide comp_driver attributes
14+
15+
class comp_dev <<struct>> {
16+
state
17+
position
18+
frames
19+
pipeline
20+
min_sink_bytes
21+
min_source_bytes
22+
task
23+
size
24+
period
25+
...
26+
}
27+
hide comp_dev methods
28+
29+
interface buffer
30+
hide buffer methods
31+
hide buffer attributes
32+
33+
interface comp_ops {
34+
create() : comp_dev*
35+
free(comp_dev*)
36+
params(params)
37+
dai_get_hw_params(params, dir)
38+
dai_config(dai_config, dai_spec_config)
39+
cmd(int cmd, void *data)
40+
trigger(int cmd)
41+
prepare()
42+
reset()
43+
copy()
44+
position()
45+
get_attribute()
46+
set_attribute()
47+
dai_ts_config()
48+
dai_ts_start()
49+
dai_ts_stop()
50+
unbind()
51+
get_large_config()
52+
set_large_config()
53+
}
54+
hide comp_ops attributes
55+
56+
57+
comp_driver -> comp_dev : creates
58+
comp_dev *-right- comp_ops
59+
}
60+
pipeline -> comp_ops : calls
61+
62+
component "module_adapter" {
63+
64+
class module_adapter <<struct>> {
65+
ops : comp_ops =
66+
.create = adapter_shim_new
67+
.prepare = module_adapter_prepare
68+
.params = module_adapter_params
69+
.copy = module_adapter_copy
70+
71+
adapter_shim_new()
72+
module_adapter_prepare()
73+
module_adapter_params()
74+
module_adapter_copy()
75+
}
76+
77+
interface module_interface {
78+
init(processing_module*)
79+
prepare(processing_module*)
80+
process(processing_module*)
81+
set_configuration()
82+
get_configuration()
83+
set_processing_mode()
84+
get_processing_mode()
85+
reset()
86+
free()
87+
}
88+
hide module_interface attributes
89+
90+
class processing_module <<struct>> {
91+
stream_params
92+
sink_buffer_list
93+
period_bytes
94+
deep_buff_bytes
95+
output_buffer_size
96+
input_buffers[]
97+
output_buffers[]
98+
}
99+
hide processing_module methods
100+
101+
module_adapter -left-> processing_module : creates
102+
module_adapter -> module_interface : calls
103+
104+
}
105+
module_adapter -up-|> comp_ops
106+
107+
component "cadence adapter" {
108+
class cadence_codec {
109+
cadence_codec_init()
110+
cadence_codec_prepare()
111+
cadence_codec_process()
112+
cadence_codec_set_configuration()
113+
cadence_codec_reset()
114+
cadence_codec_free()
115+
}
116+
hide cadence_codec attributes
117+
118+
interface "Cadence Codec API" as cadence_codec_api
119+
hide cadence_codec_api methods
120+
hide cadence_codec_api attributes
121+
122+
cadence_codec -> cadence_codec_api : calls
123+
}
124+
cadence_codec -up-|> module_interface
125+
126+
component "custom extensions" {
127+
class "mp3 codec" as mp3_codec
128+
hide mp3_codec methods
129+
hide mp3_codec attributes
130+
131+
class "aac codec" as aac_codec
132+
hide aac_codec methods
133+
hide aac_codec attributes
134+
}
135+
mp3_codec -up-|> cadence_codec_api
136+
aac_codec -up-|> cadence_codec_api
137+
138+
component "IADK adapter" {
139+
class adp_interface {
140+
intel_modules_init()
141+
intel_modules_prepare()
142+
intel_modules_process()
143+
}
144+
hide adp_interface attributes
145+
146+
interface ProcessingModuleInterface <<C++>> {
147+
Init()
148+
Delete()
149+
Process()
150+
Reset()
151+
SetProcessingMode()
152+
GetProcessingMode()
153+
SetConfiguration(config_id, fragment_pos, data_in, data_out)
154+
GetConfiguration(config_id, fragment_pos, data_out)
155+
}
156+
hide ProcessingModuleInterface attributes
157+
158+
adp_interface -> ProcessingModuleInterface : calls
159+
}
160+
adp_interface -up-|> module_interface

‎architectures/firmware/sof-common/components/images/comp-prepare-flow.pu‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
actor pipeline
2+
box "Module Adapter\no-- comp_ops"
3+
participant "module_adapter" as module_adapter
4+
end box
5+
box "IADK Module Adapter\no-- module_interface"
6+
participant "iadk_adapter" as iadk_adapter
7+
end box
8+
box "IADK Module\no-- ProcessingModuleInterface"
9+
participant iadk_module
10+
end box
11+
12+
pipeline -> module_adapter : <b>(1) ops->module_adapter_prepare()</b>
13+
activate module_adapter
14+
module_adapter -> module_adapter : module_prepare()
15+
activate module_adapter
16+
module_adapter -> iadk_adapter : <b>(2) ops->prepare()</b>
17+
activate iadk_adapter
18+
iadk_adapter -> iadk_module : <b>(3) preparation</b>
19+
module_adapter <-- iadk_adapter
20+
deactivate iadk_adapter
21+
module_adapter -> module_adapter : alloc buf descriptors
22+
module_adapter -> module_adapter : alloc buffers

‎architectures/firmware/sof-common/components/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,4 @@ Components
88

99
component-overview
1010
component-mgmt-api
11+
component-module-api

0 commit comments

Comments
 (0)