1 /* SPDX-License-Identifier: BSD-3-Clause
2  *
3  * Copyright(c) 2022 Intel Corporation. All rights reserved.
4  */
5 /*! \internal \file system_agent_interface.h */
6 
7 #ifndef _ADSP_SYSTEM_AGENT_INTERFACE_H_
8 #define _ADSP_SYSTEM_AGENT_INTERFACE_H_
9 
10 #include "system_service.h"
11 #include "system_error.h"
12 
13 #include <stdint.h>
14 #include <stddef.h>
15 
16 namespace intel_adsp
17 {
18 	struct ModulePlaceholder;
19 	class ProcessingModuleFactoryInterface;
20 	class ProcessingModuleInterface;
21 	class DetectorModuleInterface;
22 	class ModuleInitialSettings;
23 	struct ProcessingModulePrerequisites;
24 	struct IoPinsInfo;
25 	class ModuleHandle;
26 	struct LogHandle;
27 
28 namespace internal
29 {
30 	class Endpoint;
31 } /* namespace internal */
32 
33 	/*! \brief The SystemAgentInterface is a mediator to allow loadable module to interact
34 	 *  with the ADSP System.
35 	 *
36 	 * It allows loadable module and factory to register themselves
37 	 * and provide the list of the service functions exposed by the ADSP System.
38 	 * \note user-defined code should not directly interact with the SystemAgentInterface
39 	 * and rather should take leverage of the ProcessingModule and ProcessingModuleInterface
40 	 * base classes.
41 	 */
42 	class SystemAgentInterface
43 	{
44 	public:
45 		/*!
46 		 * \brief Scoped enumeration of error code value which can be reported by
47 		 * a SystemAgentInterface object
48 		 */
49 		struct ErrorCode : intel_adsp::ErrorCode
50 		{
51 			/*! \brief list of named error codes specific to the SystemAgentInterface */
52 			enum Enum {
53 				/*!< Reports that ProcessingModuleFactoryInterface::Create()
54 				 * has exited with error
55 				 */
56 				MODULE_CREATION_FAILURE = intel_adsp::ErrorCode::MaxValue + 1
57 			};
58 			/*! \brief Indicates the minimal value of the enumeration */
59 			static Enum const MinValue = MODULE_CREATION_FAILURE;
60 			/*! \brief Indicates the maximal value of the enumeration */
61 			static Enum const MaxValue = MODULE_CREATION_FAILURE;
62 
63 			/*!
64 			 * \brief Initializes a new instance of ErrorCode given a value
65 			 */
ErrorCodeErrorCode66 			explicit ErrorCode(Type value)
67 				:   intel_adsp::ErrorCode(value)
68 			{}
69 		};
70 
71 		/*! \brief Allows a ProcessingModuleInterface instance to be registered in
72 		 * the ADSP System
73 		 *
74 		 * internal purpose.
75 		 */
76 		virtual void CheckIn(ProcessingModuleInterface & processing_module,
77 				     /**< the instance to register for later use in processing
78 				      * pipeline
79 				      */
80 				     ModuleHandle & module_handle,
81 				     /**< the object that is required by the ADSP System to handle
82 				      * the module
83 				      */
84 				     LogHandle * &log_handle /**< module logging context */
85 				    ) = 0;
86 
87 		/*! \brief Allows a ProcessingModuleFactoryInterface instance to be registered in
88 		 * the ADSP System
89 		 *
90 		 * internal purpose.
91 		 */
92 		virtual int CheckIn(ProcessingModuleFactoryInterface & module_factory,
93 				    /*!< the instance to register */
94 				    ModulePlaceholder * module_placeholder,
95 				    /*!< the place holder in memory for instantiation of
96 				     * a ProcessingModuleInterface instance
97 				     */
98 				    size_t,
99 				    uint32_t,
100 				    const void*,
101 				    void*,
102 				    void**) = 0;
103 
104 		/*!
105 		 * \brief Gets the SystemService instance which contains all the service functions
106 		 */
107 		virtual SystemService const &GetSystemService(void) = 0;
108 
109 		/*!
110 		 * \brief Gets the LogHandle required to send some log message
111 		 */
112 		virtual LogHandle const &GetLogHandle(void) = 0;
113 	};
114 
115 	class SystemAgentInterface2 : public SystemAgentInterface
116 	{
117 	public:
118 
119 		/*! \brief Allows a ProcessingModuleInterface instance to be registered in
120 		 * the ADSP System as detector module
121 		 *
122 		 * internal purpose.
123 		 */
124 		virtual void CheckInDetector(DetectorModuleInterface & processing_module,
125 					     /*!< the instance to register for later use in
126 					      * processing pipeline
127 					      */
128 					     ModuleHandle & module_handle,
129 					     /*!< the object that is required by the ADSP System
130 					      *  to handle the module
131 					      */
132 					     LogHandle * &log_handle
133 					     /*!< module logging context */
134 					    ) = 0;
135 	};
136 
137 } /* namespace intel_adsp */
138 
139 #endif /* _ADSP_SYSTEM_AGENT_H_ */
140