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