1 /*
2 * Copyright (c) 2018 Intel Corporation.
3 *
4 * Author: Sathish Kuttan <sathish.k.kuttan@intel.com>
5 *
6 * SPDX-License-Identifier: Apache-2.0
7 */
8
9 /**
10 * @file
11 * @brief Public API header file for Intel GNA driver
12 */
13
14 #ifndef __INCLUDE_GNA__
15 #define __INCLUDE_GNA__
16
17 /**
18 * @defgroup gna_interface GNA Interface
19 * @ingroup io_interfaces
20 * @{
21 *
22 * This file contains the driver APIs for Intel's
23 * Gaussian Mixture Model and Neural Network Accelerator (GNA)
24 */
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30 /**
31 * GNA driver configuration structure.
32 * Currently empty.
33 */
34 struct gna_config {
35 #ifdef __cplusplus
36 char no_empty_structs; /* technically a gcc C extension */
37 #endif
38 };
39
40 /**
41 * GNA Neural Network model header
42 * Describes the key parameters of the neural network model
43 */
44 struct gna_model_header {
45 uint32_t labase_offset;
46 uint32_t model_size;
47 uint32_t gna_mode;
48 uint32_t layer_count;
49 uint32_t bytes_per_input;
50 uint32_t bytes_per_output;
51 uint32_t num_input_nodes;
52 uint32_t num_output_nodes;
53 uint32_t input_ptr_offset;
54 uint32_t output_ptr_offset;
55 uint32_t rw_region_size;
56 uint32_t input_scaling_factor;
57 uint32_t output_scaling_factor;
58 };
59
60 /**
61 * GNA Neural Network model information to be provided by application
62 * during model registration
63 */
64 struct gna_model_info {
65 struct gna_model_header *header;
66 void *rw_region;
67 void *ro_region;
68 };
69
70 /**
71 * Request to perform inference on the given neural network model
72 */
73 struct gna_inference_req {
74 void *model_handle;
75 void *input;
76 void *output;
77 void *intermediate;
78 };
79
80 /**
81 * Statistics of the inference operation returned after completion
82 */
83 struct gna_inference_stats {
84 uint32_t total_cycles;
85 uint32_t stall_cycles;
86 uint32_t cycles_per_sec;
87 };
88
89 /**
90 * Result of an inference operation
91 */
92 enum gna_result {
93 GNA_RESULT_INFERENCE_COMPLETE,
94 GNA_RESULT_SATURATION_OCCURRED,
95 GNA_RESULT_OUTPUT_BUFFER_FULL_ERROR,
96 GNA_RESULT_PARAM_OUT_OF_RANGE_ERROR,
97 GNA_RESULT_GENERIC_ERROR,
98 };
99
100 /**
101 * Structure containing a response to the inference request
102 */
103 struct gna_inference_resp {
104 enum gna_result result;
105 void *output;
106 size_t output_len;
107 struct gna_inference_stats stats;
108 };
109
110 /**
111 * @cond INTERNAL_HIDDEN
112 *
113 * Internal documentation. Skip in public documentation
114 */
115 typedef int (*gna_callback)(struct gna_inference_resp *result);
116
117 typedef int (*gna_api_config)(const struct device *dev,
118 struct gna_config *cfg);
119 typedef int (*gna_api_register)(const struct device *dev,
120 struct gna_model_info *model,
121 void **model_handle);
122 typedef int (*gna_api_deregister)(const struct device *dev,
123 void *model_handle);
124 typedef int (*gna_api_infer)(const struct device *dev,
125 struct gna_inference_req *req,
126 gna_callback callback);
127
128 struct gna_driver_api {
129 gna_api_config configure;
130 gna_api_register register_model;
131 gna_api_deregister deregister_model;
132 gna_api_infer infer;
133 };
134
135 /**
136 * @endcond
137 */
138
139 /**
140 * @brief Configure the GNA device.
141 *
142 * Configure the GNA device. The GNA device must be configured before
143 * registering a model or performing inference
144 *
145 * @param dev Pointer to the device structure for the driver instance.
146 * @param cfg Device configuration information
147 *
148 * @retval 0 If the configuration is successful
149 * @retval A negative error code in case of a failure.
150 */
gna_configure(const struct device * dev,struct gna_config * cfg)151 static inline int gna_configure(const struct device *dev,
152 struct gna_config *cfg)
153 {
154 const struct gna_driver_api *api =
155 (const struct gna_driver_api *)dev->api;
156
157 return api->configure(dev, cfg);
158 }
159
160 /**
161 * @brief Register a neural network model
162 *
163 * Register a neural network model with the GNA device
164 * A model needs to be registered before it can be used to perform inference
165 *
166 * @param dev Pointer to the device structure for the driver instance.
167 * @param model Information about the neural network model
168 * @param model_handle Handle to the registered model if registration succeeds
169 *
170 * @retval 0 If registration of the model is successful.
171 * @retval A negative error code in case of a failure.
172 */
gna_register_model(const struct device * dev,struct gna_model_info * model,void ** model_handle)173 static inline int gna_register_model(const struct device *dev,
174 struct gna_model_info *model,
175 void **model_handle)
176 {
177 const struct gna_driver_api *api =
178 (const struct gna_driver_api *)dev->api;
179
180 return api->register_model(dev, model, model_handle);
181 }
182
183 /**
184 * @brief De-register a previously registered neural network model
185 *
186 * De-register a previously registered neural network model from the GNA device
187 * De-registration may be done to free up memory for registering another model
188 * Once de-registered, the model can no longer be used to perform inference
189 *
190 * @param dev Pointer to the device structure for the driver instance.
191 * @param model Model handle output by gna_register_model API
192 *
193 * @retval 0 If de-registration of the model is successful.
194 * @retval A negative error code in case of a failure.
195 */
gna_deregister_model(const struct device * dev,void * model)196 static inline int gna_deregister_model(const struct device *dev, void *model)
197 {
198 const struct gna_driver_api *api =
199 (const struct gna_driver_api *)dev->api;
200
201 return api->deregister_model(dev, model);
202 }
203
204 /**
205 * @brief Perform inference on a model with input vectors
206 *
207 * Make an inference request on a previously registered model with an of
208 * input data vector
209 * A callback is provided for notification of inference completion
210 *
211 * @param dev Pointer to the device structure for the driver instance.
212 * @param req Information required to perform inference on a neural network
213 * @param callback A callback function to notify inference completion
214 *
215 * @retval 0 If the request is accepted
216 * @retval A negative error code in case of a failure.
217 */
gna_infer(const struct device * dev,struct gna_inference_req * req,gna_callback callback)218 static inline int gna_infer(const struct device *dev,
219 struct gna_inference_req *req,
220 gna_callback callback)
221 {
222 const struct gna_driver_api *api =
223 (const struct gna_driver_api *)dev->api;
224
225 return api->infer(dev, req, callback);
226 }
227
228 #ifdef __cplusplus
229 }
230 #endif
231
232 /**
233 * @}
234 */
235
236 #endif /* __INCLUDE_GNA__ */
237
