1 /* SPDX-License-Identifier: BSD-3-Clause
2  *
3  * Copyright(c) 2022 Intel Corporation. All rights reserved.
4  */
5 /*! \file processing_module_factory_interface.h */
6 
7 #ifndef _PROCESSING_MODULE_FACTORY_INTERFACE_H_
8 #define _PROCESSING_MODULE_FACTORY_INTERFACE_H_
9 
10 #include "processing_module_interface.h"
11 #include "system_agent_interface.h"
12 #include "processing_module_prerequisites.h"
13 #include "module_initial_settings.h"
14 
15 namespace intel_adsp
16 {
17 	/*! \brief defines type of the pin endpoint.
18 	 *
19 	 * A custom module is required to provide to the ADSP System some PinEndpoint value arrays.
20 	 * Arrays length shall be as long as it has input and output pins.
21 	 * (ref \ref ProcessingModuleFactoryInterface::Create()).
22 	 */
23 	typedef void *PinEndpoint;
24 	typedef struct { void *prt[2]; } FwdEvent;
25 
26 	/*! \brief holds information about pins of a module.
27 	 *
28 	 * For each custom module,
29 	 * input pins of a module are associated to some "sources" PinEndPoint and
30 	 * output pins are associated to some sinks "PinEndPoint" objects.
31 	 * Those sinks and sources objects shall be instantiated by the custom module and delivered
32 	 * to the ADSP System with this IoPinsInfo structure
33 	 * (through \ref ProcessingModuleFactoryInterface::Create()).
34 	 *
35 	 * \note The "pin" of a module is purely conceptual and has no programmatic correspondence.
36 	 * A module has as many input/output pins as input/output streams which can be
37 	 * driven through it.
38 	 */
39 	struct IoPinsInfo {
40 		/*!
41 		 * \brief pointer on a PinEndpoint array with "sources_count" elements
42 		 *
43 		 * A module is required to provide some PinEndpoint arrays to allow
44 		 * the ADSP System to drive streams into the module.
45 		 */
46 		PinEndpoint *sources;
47 		/*!
48 		 * \brief pointer on a PinEndpoint array with "sinks_count" elements
49 		 *
50 		 * A module is required to provide some PinEndpoint arrays to allow
51 		 * the ADSP System to drive stream out of the module.
52 		 */
53 		PinEndpoint *sinks;
54 		/*!
55 		 * \brief pointer on a FwdEvents array with "events_count" elements
56 		 *
57 		 * A module is required to provide some FwdEvents arrays to allow
58 		 * the ADSP System to handle key phrase detection.
59 		 */
60 		FwdEvent *events;
61 
62 		/*! \brief description of buffer reserved for DP queue objects and buffers
63 		 * used for all additional input and output pins (e.g. reference pin)
64 		 */
65 		uint8_t *pins_mem_pool;
66 		size_t pins_mem_pool_size;
67 	};
68 
69 	/*!
70 	 * \brief The ProcessingModuleFactoryInterface class defines requirements for creating
71 	 * a processing module controllable by the ADSP System.
72 	 */
73 	class ProcessingModuleFactoryInterface
74 	{
75 	public:
76 		/*!
77 		 * \brief Scoped enumeration of error code value which can be reported by
78 		 * a ProcessingModuleFactoryInterface object
79 		 */
80 		struct ErrorCode : intel_adsp::ErrorCode {
81 			/*! \brief list of named error codes specific to
82 			 * the ProcessingModuleFactoryInterface
83 			 */
84 			enum Enum {
85 				/*!< Reports that the given value of Input Buffer Size is invalid */
86 				INVALID_IBS = intel_adsp::ErrorCode::MaxValue + 1,
87 				/*!< Reports that the given value of Output Buffer Size is invalid*/
88 				INVALID_OBS,
89 				/*!< Reports that the given value of Cycles Per Chunk processing
90 				 * is invalid
91 				 */
92 				INVALID_CPC,
93 				/*!< Reports that the settings provided for module creation
94 				 * are invalid
95 				 */
96 				INVALID_SETTINGS
97 			};
98 			/*! \brief Indicates the minimal value of the enumeration */
99 			static Enum const MinValue = INVALID_IBS;
100 			/*! \brief Indicates the maximal value of the enumeration */
101 			static Enum const MaxValue = INVALID_SETTINGS;
102 
103 			/*!
104 			 * \brief Initializes a new instance of ErrorCode given a value
105 			 */
ErrorCodeErrorCode106 			explicit ErrorCode(Type value)
107 				:   intel_adsp::ErrorCode(value)
108 			{}
109 		};
110 
111 		/*!
112 		 * \brief Indicates the prerequisites for module instance creation.
113 		 *
114 		 * ADSP System calls this method before each module instance creation.
115 		 * \param [out] module_prereqs reports module prerequisites
116 		 *              that ADSP System needs to prepare the module creation.
117 		 */
118 		virtual void GetPrerequisites(ProcessingModulePrerequisites & module_prereqs
119 				) = 0;
120 		/*!
121 		 * \brief Creates a ProcessingModuleInstance instance in the given placeholder.
122 		 *
123 		 * The custom implementation of the Create method is expected to handle
124 		 * initialization of the custom module instances.
125 		 * \note The ADSP System will provide a dedicated memory \e placeholder for every
126 		 *       module instance to create.
127 		 *
128 		 * \param [in] system_agent the SystemAgentInterface object which can register the
129 		 *             module instance which is being initialized
130 		 * \param [in] module_placeholder the pointer to the memory location where the
131 		 *             module instance can be initialized using the "new placement syntax".
132 		 * Note that the size of the placeholder given by the System is worth
133 		 * the size of the processing module class given as parameter of the
134 		 * DECLARE_LOADABLE_MODULE macro
135 		 * \param [in] initial_settings  initial settings for module startup.
136 		 * \param [out] pins_info will report the IoPinsInfo data that ADSP System
137 		 *              requires to bind the input and output streams to the module.
138 		 * \return some ErrorCode value upon creation status.
139 		 */
140 		virtual ErrorCode::Type Create(SystemAgentInterface & system_agent,
141 				ModulePlaceholder * module_placeholder,
142 				ModuleInitialSettings initial_settings,
143 				IoPinsInfo & pins_info
144 			) = 0;
145 	}; /* class ProcessingModuleFactoryInterface */
146 
147 } /* namespace intel_adsp */
148 
149 #endif /* #ifndef _PROCESSING_MODULE_FACTORY_INTERFACE_H_ */
150