1 /* SPDX-License-Identifier: BSD-3-Clause
2 *
3 * Copyright(c) 2020 Intel Corporation. All rights reserved.
4 *
5 *
6 * \file common.h
7 * \brief Extract from generic.h definitions that need to be included
8 * in intel module adapter code.
9 * \author Jaroslaw Stelter <jaroslaw.stelter@intel.com>
10 *
11 */
12
13 #ifndef __SOF_MODULE_INTERFACE__
14 #define __SOF_MODULE_INTERFACE__
15
16 #include <sof/compiler_attributes.h>
17
18 /**
19 * \enum module_cfg_fragment_position
20 * \brief Fragment position in config
21 * MODULE_CFG_FRAGMENT_FIRST: first fragment of the large configuration
22 * MODULE_CFG_FRAGMENT_SINGLE: only fragment of the configuration
23 * MODULE_CFG_FRAGMENT_LAST: last fragment of the configuration
24 * MODULE_CFG_FRAGMENT_MIDDLE: intermediate fragment of the large configuration
25 */
26 enum module_cfg_fragment_position {
27 MODULE_CFG_FRAGMENT_MIDDLE = 0,
28 MODULE_CFG_FRAGMENT_FIRST,
29 MODULE_CFG_FRAGMENT_LAST,
30 MODULE_CFG_FRAGMENT_SINGLE,
31 };
32
33 /**
34 * \enum module_processing_mode
35 * MODULE_PROCESSING_NORMAL: Indicates that module is expected to apply its custom processing on
36 * the input signal
37 * MODULE_PROCESSING_BYPASS: Indicates that module is expected to skip custom processing on
38 * the input signal and act as a passthrough component
39 */
40
41 enum module_processing_mode {
42 MODULE_PROCESSING_NORMAL = 0,
43 MODULE_PROCESSING_BYPASS,
44 };
45
46 /**
47 * \struct input_stream_buffer
48 * \brief Input stream buffer
49 */
50 struct input_stream_buffer {
51 void __sparse_cache *data; /* data stream buffer */
52 uint32_t size; /* size of data in the buffer */
53 uint32_t consumed; /* number of bytes consumed by the module */
54
55 /* Indicates end of stream condition has occurred on the input stream */
56 bool end_of_stream;
57 };
58
59 /**
60 * \struct output_stream_buffer
61 * \brief Output stream buffer
62 */
63 struct output_stream_buffer {
64 void __sparse_cache *data; /* data stream buffer */
65 uint32_t size; /* size of data in the buffer */
66 };
67
68 struct processing_module;
69 /**
70 * \struct module_interface
71 * \brief 3rd party processing module interface
72 */
73 struct module_interface {
74 /**
75 * Module specific initialization procedure, called as part of
76 * module_adapter component creation in .new()
77 */
78 int (*init)(struct processing_module *mod);
79 /**
80 * Module specific prepare procedure, called as part of module_adapter
81 * component preparation in .prepare()
82 */
83 int (*prepare)(struct processing_module *mod);
84 /**
85 * Module specific processing procedure, called as part of module_adapter
86 * component copy in .copy(). This procedure is responsible to consume
87 * samples provided by the module_adapter and produce/output the processed
88 * ones back to module_adapter.
89 */
90 int (*process)(struct processing_module *mod, struct input_stream_buffer *input_buffers,
91 int num_input_buffers, struct output_stream_buffer *output_buffers,
92 int num_output_buffers);
93
94 /**
95 * Set module configuration for the given configuration ID
96 *
97 * If the complete configuration message is greater than MAX_BLOB_SIZE bytes, the
98 * transmission will be split into several smaller fragments.
99 * In this case the ADSP System will perform multiple calls to SetConfiguration() until
100 * completion of the configuration message sending.
101 * \note config_id indicates ID of the configuration message only on the first fragment
102 * sending, otherwise it is set to 0.
103 */
104 int (*set_configuration)(struct processing_module *mod,
105 uint32_t config_id,
106 enum module_cfg_fragment_position pos, uint32_t data_offset_size,
107 const uint8_t *fragment, size_t fragment_size, uint8_t *response,
108 size_t response_size);
109
110 /**
111 * Get module runtime configuration for the given configuration ID
112 *
113 * If the complete configuration message is greater than MAX_BLOB_SIZE bytes, the
114 * transmission will be split into several smaller fragments.
115 * In this case the ADSP System will perform multiple calls to GetConfiguration() until
116 * completion of the configuration message retrieval.
117 * \note config_id indicates ID of the configuration message only on the first fragment
118 * retrieval, otherwise it is set to 0.
119 */
120 int (*get_configuration)(struct processing_module *mod,
121 uint32_t config_id, uint32_t *data_offset_size,
122 uint8_t *fragment, size_t fragment_size);
123
124 /**
125 * Set processing mode for the module
126 */
127 int (*set_processing_mode)(struct processing_module *mod,
128 enum module_processing_mode mode);
129
130 /**
131 * Get the current processing mode for the module
132 */
133 enum module_processing_mode (*get_processing_mode)(struct processing_module *mod);
134
135 /**
136 * Module specific reset procedure, called as part of module_adapter component
137 * reset in .reset(). This should reset all parameters to their initial stage
138 * and free all memory allocated during prepare().
139 */
140 int (*reset)(struct processing_module *mod);
141 /**
142 * Module specific free procedure, called as part of module_adapter component
143 * free in .free(). This should free all memory allocated during module initialization.
144 */
145 int (*free)(struct processing_module *mod);
146 };
147
148 /* Convert first_block/last_block indicator to fragment position */
149 static inline enum module_cfg_fragment_position
first_last_block_to_frag_pos(bool first_block,bool last_block)150 first_last_block_to_frag_pos(bool first_block, bool last_block)
151 {
152 int frag_position = (last_block << 1) | first_block;
153
154 return (enum module_cfg_fragment_position)frag_position;
155 }
156
157 #endif /* __SOF_MODULE_INTERFACE__ */
158
