1 /* SPDX-License-Identifier: BSD-3-Clause
2  *
3  * Copyright(c) 2022 Intel Corporation. All rights reserved.
4  */
5 /*! \file module_initial_settings.h */
6 
7 #ifndef _ADSP_MODULE_INITIAL_SETTINGS_H_
8 #define _ADSP_MODULE_INITIAL_SETTINGS_H_
9 
10 #include "adsp_stddef.h"
11 #include "fixed_array.h"
12 #include <ipc4/base-config.h>
13 
14 /* Mapping of IPC4 definitions into IADK naming counterpart */
15 typedef struct ipc4_base_module_cfg BaseModuleCfg;
16 typedef struct ipc4_base_module_cfg LegacyModuleInitialSettings;
17 typedef struct ipc4_input_pin_format InputPinFormat;
18 typedef struct ipc4_output_pin_format OutputPinFormat;
19 typedef struct ipc4_audio_format AudioFormat;
20 
21 #define INPUT_PIN_COUNT		(1 << 3)
22 #define OUTPUT_PIN_COUNT	(1 << 3)
23 
24 namespace intel_adsp
25 {
26 	/*! \brief Enumeration values of keys to access to the ModuleInitialSettings items */
27 	enum ModuleInitialSettingsKey {
28 		/*! \brief Key value to retrieve the LegacyModuleInitialSettings item from the
29 		 * ModuleInitialSettings.
30 		 *  \deprecated New module shall not work with this item as it will be removed
31 		 *  in next API release.
32 		 */
33 		LEGACY_STRUCT = 0,
34 		/*! \brief Key value to retrieve the array of InputPinFormat item from
35 		 * the ModuleInitialSettings.
36 		 */
37 		IN_PINS_FORMAT,
38 		/*! \brief Key value to retrieve the array of OutputPinFormat item from
39 		 * the ModuleInitialSettings.
40 		 */
41 		OUT_PINS_FORMAT
42 	};
43 
44 	/*!    \brief Helps to identify type of a ModuleInitialSettings item referenced by its KEY
45 	 *      \tparam KEY          identifying the settings item
46 	 */
47 	template < ModuleInitialSettingsKey KEY > struct ModuleInitialSettingsItem
48 	{
49 		/*! \brief value type of the SETTINGS item for the given KEY value.
50 		 * \note ValueType shall have copy constructor
51 		 */
52 		typedef void ValueType;
53 	};
54 
55 	/*! \brief Defines the interface to retrieve untyped items based
56 	 * on ModuleInitialSettingsKey values.
57 	 * \internal
58 	 */
59 	struct ModuleInitialSettingsInterface {
60 		/*! \internal */
61 		virtual void const *GetUntypedItem(ModuleInitialSettingsKey key,
62 						   size_t & length) = 0;
63 	};
64 
65 	namespace system
66 	{ class SystemAgent; }
67 
68 	/*! \brief The set of settings item given for initialization of a Module instance.
69 	 *
70 	 * The ModuleInitialSettings is a container of heterogeneous typed value items. Each item
71 	 * is a key-value pair where key is an enumeration value of ModuleInitialSettingsKey
72 	 */
73 	class ModuleInitialSettings
74 	{
75 		template < class DERIVED, class PROCESSING_MODULE >
76 				friend class ProcessingModuleFactory;
77 				friend class system::SystemAgent;
78 
79 	public:
80 		/*! \brief A FixedArray whose construction is only granted to
81 		 * ModuleInitialSettings
82 		 */
83 		template < class VALUE >
84 		struct Array : public FixedArray < VALUE >
85 		{
86 			friend class ModuleInitialSettings;
87 			typedef VALUE ValueType;
88 
89 		/*! \brief Initializes a new instance of Array.
90 		 */
ArrayArray91 		explicit Array(ValueType *array, size_t length) :
92 				FixedArray < ValueType > (array, length)
93 		{}
94 
95 		private:
96 			/*! \brief copy constructor is invalidated to prevent client code from
97 			 * working with dangling reference. Consider the Copy() operation if
98 			 * a copy of the settings item array is required.
99 			 */
100 			Array(Array < ValueType > const &);
101 
102 			/*! \brief copy-assignment operator is invalidated to prevent client code
103 			 * from working with dangling reference. Consider the Copy() operation if
104 			 * a copy of the settings item array is required.
105 			 */
106 			Array < ValueType > &operator = (Array < ValueType > const &);
107 		};
108 
109 		/*! \brief the type of keys to access to the ModuleInitialSettings items */
110 		typedef ModuleInitialSettingsKey Key;
111 
112 		/*! \brief Initializes a new instance of ModuleInitialSettings given some
113 		 * ModuleInitialSettingsInterface object
114 		 */
ModuleInitialSettings(ModuleInitialSettingsInterface & performer)115 		explicit ModuleInitialSettings(ModuleInitialSettingsInterface & performer) :
116 			performer_(performer)
117 		{}
118 
119 		/*! \brief Retrieves the item as an array of values for the given key.
120 		 *  \note Any item is represented as a value array even if it has a single value.
121 		 *  \remarks If no item is found for the given key, the returned array will
122 		 *  have null length.
123 		 *  \tparam key     value of the Key to retrieve the item.
124 		 */
125 		template < Key key >
126 		const Array < typename ModuleInitialSettingsItem < key >
GetItem()127 					:: ValueType const > GetItem()
128 		{
129 			size_t length;
130 
131 			return Array < typename ModuleInitialSettingsItem < key >
132 					:: ValueType const > (
133 			reinterpret_cast < typename ModuleInitialSettingsItem < key >
134 					:: ValueType const *>
135 					(performer_.GetUntypedItem(key, length)), length);
136 		}
137 
138 	private:
139 		/*! \brief For sake of safety ModuleInitialSettings is not "publicly" copy-able.
140 		 * Indeed, ModuleInitialSettings instance holds references on some ADSP System
141 		 * resources which are only available for a temporary lifetime.
142 		 */
ModuleInitialSettings(ModuleInitialSettings const & src)143 		ModuleInitialSettings(ModuleInitialSettings const &src) :
144 				performer_(src.performer_) { }
145 		/*! ModuleInitialSettings(ModuleInitialSettings const&) */
146 		ModuleInitialSettings operator = (ModuleInitialSettings const &src);
147 
148 		ModuleInitialSettingsInterface & performer_;
149 	};
150 
151 	/*! \brief Boilerplate to identify type of the ModuleInitialSettings item associated
152 	 * to the "LEGACY_STRUCT" key
153 	 *  \internal
154 	 */
155 	template < > struct ModuleInitialSettingsItem < LEGACY_STRUCT >
156 	{
157 		typedef LegacyModuleInitialSettings ValueType;
158 	};
159 
160 	/*! \brief Boilerplate to identify type of the ModuleInitialSettings item associated
161 	 * to the "IN_PINS_FORMAT" key
162 	 *  \internal
163 	 */
164 	template < > struct ModuleInitialSettingsItem < IN_PINS_FORMAT >
165 	{
166 		typedef InputPinFormat ValueType;
167 	};
168 
169 	/*! \brief Boilerplate to identify type of the ModuleInitialSettings item associated
170 	 * to the "OUT_PINS_FORMAT" key
171 	 *  \internal
172 	 */
173 	template < > struct ModuleInitialSettingsItem < OUT_PINS_FORMAT >
174 	{
175 		typedef OutputPinFormat ValueType;
176 	};
177 
178 } /*namespace intel_adsp */
179 
180 #endif /* #ifndef _ADSP_MODULE_INITIAL_SETTINGS_H_ */
181