blob: bf6a5787b448013ea9608a0780ee2b5b61e4d571 [file] [log] [blame]
Kristofer Jonsson49bdee82020-04-06 13:21:21 +02001/*
Kristofer Jonssonb3cde3c2022-01-27 17:30:15 +01002 * Copyright (c) 2019-2022 Arm Limited. All rights reserved.
Kristofer Jonsson49bdee82020-04-06 13:21:21 +02003 *
4 * SPDX-License-Identifier: Apache-2.0
5 *
6 * Licensed under the Apache License, Version 2.0 (the License); you may
7 * not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
14 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
Kristofer Jonsson3c439172020-08-05 09:38:40 +020019#ifndef ETHOSU_DRIVER_H
20#define ETHOSU_DRIVER_H
Kristofer Jonsson49bdee82020-04-06 13:21:21 +020021
22/******************************************************************************
23 * Includes
24 ******************************************************************************/
25
Jonny Svärd136810f2021-10-13 16:04:26 +020026#include "ethosu_types.h"
Bhavik Pateldae5be02020-06-18 15:25:15 +020027
28#include <stdbool.h>
Kristofer Jonsson2b201c32020-09-02 16:42:43 +020029#include <stddef.h>
Kristofer Jonsson49bdee82020-04-06 13:21:21 +020030#include <stdint.h>
31
32#ifdef __cplusplus
33extern "C" {
34#endif
35
36/******************************************************************************
Jonny Svärda830f172021-06-07 16:57:00 +020037 * Defines
38 ******************************************************************************/
39
40#define ETHOSU_DRIVER_VERSION_MAJOR 0 ///< Driver major version
41#define ETHOSU_DRIVER_VERSION_MINOR 16 ///< Driver minor version
42#define ETHOSU_DRIVER_VERSION_PATCH 0 ///< Driver patch version
43
44/******************************************************************************
Kristofer Jonsson49bdee82020-04-06 13:21:21 +020045 * Types
46 ******************************************************************************/
47
Jonny Svärd136810f2021-10-13 16:04:26 +020048// Forward declare
49struct ethosu_device;
50
Jonny Svärd1a3bb922022-02-25 16:28:21 +010051enum ethosu_job_state
52{
53 ETHOSU_JOB_IDLE = 0,
54 ETHOSU_JOB_RUNNING,
55 ETHOSU_JOB_DONE
56};
57
58struct ethosu_job
59{
60 volatile enum ethosu_job_state state;
61 const void *custom_data_ptr;
62 int custom_data_size;
63 const uint64_t *base_addr;
64 const size_t *base_addr_size;
65 int num_base_addr;
66 void *user_arg;
67};
68
Bhavik Pateldae5be02020-06-18 15:25:15 +020069struct ethosu_driver
70{
Jonny Svärd136810f2021-10-13 16:04:26 +020071 struct ethosu_device *dev;
Jonny Svärda830f172021-06-07 16:57:00 +020072 struct ethosu_driver *next;
Jonny Svärd1a3bb922022-02-25 16:28:21 +010073 struct ethosu_job job;
Jonny Svärda830f172021-06-07 16:57:00 +020074 void *semaphore;
Kristofer Jonsson2b201c32020-09-02 16:42:43 +020075 uint64_t fast_memory;
76 size_t fast_memory_size;
Bhavik Patel5f8dad12020-09-30 09:06:52 +020077 bool status_error;
Anton Moberg8d65b6f2020-12-21 09:37:18 +010078 bool dev_power_always_on;
Anton Moberg61da4d32020-12-22 16:00:31 +010079 bool reserved;
Anton Moberg0a614292021-03-24 14:08:22 +010080 uint8_t clock_request;
81 uint8_t power_request;
Bhavik Pateldae5be02020-06-18 15:25:15 +020082};
83
Jonny Svärda830f172021-06-07 16:57:00 +020084struct ethosu_driver_version
Kristofer Jonsson49bdee82020-04-06 13:21:21 +020085{
Jonny Svärda830f172021-06-07 16:57:00 +020086 uint8_t major;
87 uint8_t minor;
88 uint8_t patch;
Kristofer Jonsson49bdee82020-04-06 13:21:21 +020089};
90
Anton Moberg0a614292021-03-24 14:08:22 +010091enum ethosu_request_clients
92{
93 ETHOSU_PMU_REQUEST = 0,
94 ETHOSU_INFERENCE_REQUEST = 1,
95};
96
Kristofer Jonsson49bdee82020-04-06 13:21:21 +020097/******************************************************************************
Jonny Svärda830f172021-06-07 16:57:00 +020098 * Prototypes (weak functions in driver)
Kristofer Jonsson4dc73dc2020-10-16 12:33:47 +020099 ******************************************************************************/
100
Jonny Svärda830f172021-06-07 16:57:00 +0200101/**
102 * Interrupt handler to be called on IRQ from Ethos-U
103 */
104void ethosu_irq_handler(struct ethosu_driver *drv);
105
106/*
107 * Flush/clean the data cache by address and size. Passing NULL as p argument
108 * expects the whole cache to be flushed.
109 */
110
111void ethosu_flush_dcache(uint32_t *p, size_t bytes);
112/*
113 * Invalidate the data cache by address and size. Passing NULL as p argument
114 * expects the whole cache to be invalidated.
115 */
116void ethosu_invalidate_dcache(uint32_t *p, size_t bytes);
117
118/*
119 * Minimal sempahore and mutex implementation for baremetal applications. See
120 * ethosu_driver.c.
121 */
122void *ethosu_mutex_create(void);
123void ethosu_mutex_lock(void *mutex);
124void ethosu_mutex_unlock(void *mutex);
125void *ethosu_semaphore_create(void);
126void ethosu_semaphore_take(void *sem);
127void ethosu_semaphore_give(void *sem);
128
129/*
Kristofer Jonssonb3cde3c2022-01-27 17:30:15 +0100130 * Callbacks for begin/end of inference. user_data pointer is passed to the
131 * ethosu_invoke() call and forwarded to the callback functions.
Jonny Svärda830f172021-06-07 16:57:00 +0200132 */
Kristofer Jonssonb3cde3c2022-01-27 17:30:15 +0100133void ethosu_inference_begin(struct ethosu_driver *drv, void *user_arg);
134void ethosu_inference_end(struct ethosu_driver *drv, void *user_arg);
Kristofer Jonsson4dc73dc2020-10-16 12:33:47 +0200135
136/******************************************************************************
Kristofer Jonsson49bdee82020-04-06 13:21:21 +0200137 * Prototypes
138 ******************************************************************************/
139
140/**
141 * Initialize the Ethos-U driver.
142 */
Anton Mobergeffc7aa2021-05-03 09:25:06 +0200143int ethosu_init(struct ethosu_driver *drv,
144 const void *base_address,
145 const void *fast_memory,
146 const size_t fast_memory_size,
147 uint32_t secure_enable,
148 uint32_t privilege_enable);
Kristofer Jonsson49bdee82020-04-06 13:21:21 +0200149
150/**
Anton Moberg547ca532021-06-14 09:43:53 +0200151 * Deinitialize the Ethos-U driver.
152 */
153void ethosu_deinit(struct ethosu_driver *drv);
154
155/**
Jonny Svärda830f172021-06-07 16:57:00 +0200156 * Get Ethos-U driver version.
Kristofer Jonsson49bdee82020-04-06 13:21:21 +0200157 */
Jonny Svärda830f172021-06-07 16:57:00 +0200158void ethosu_get_driver_version(struct ethosu_driver_version *ver);
159
160/**
161 * Get Ethos-U hardware information.
162 */
163void ethosu_get_hw_info(struct ethosu_driver *drv, struct ethosu_hw_info *hw);
Kristofer Jonsson49bdee82020-04-06 13:21:21 +0200164
165/**
166 * Invoke Vela command stream.
167 */
Kristofer Jonssonb3cde3c2022-01-27 17:30:15 +0100168int ethosu_invoke_v3(struct ethosu_driver *drv,
169 const void *custom_data_ptr,
170 const int custom_data_size,
171 const uint64_t *base_addr,
172 const size_t *base_addr_size,
173 const int num_base_addr,
174 void *user_arg);
175
176#define ethosu_invoke(drv, custom_data_ptr, custom_data_size, base_addr, base_addr_size, num_base_addr) \
177 ethosu_invoke_v3(drv, custom_data_ptr, custom_data_size, base_addr, base_addr_size, num_base_addr, 0)
Kristofer Jonsson2b201c32020-09-02 16:42:43 +0200178
Kristofer Jonsson49bdee82020-04-06 13:21:21 +0200179/**
Jonny Svärd1a3bb922022-02-25 16:28:21 +0100180 * Invoke Vela command stream using async interface.
181 * Must be followed by call(s) to ethosu_wait() upon successful return.
182 * Returns
183 * -1 on error
184 * 0 on success
185 */
186int ethosu_invoke_async(struct ethosu_driver *drv,
187 const void *custom_data_ptr,
188 const int custom_data_size,
189 const uint64_t *base_addr,
190 const size_t *base_addr_size,
191 const int num_base_addr,
192 void *user_arg);
193
194/**
195 * Wait for inference to complete (block=true)
196 * Poll status or finish up if inference is complete (block=false)
197 * (This function is only intended to be used in conjuction with ethosu_invoke_async)
198 * Returns
199 * 1 on inference running (only for block=false)
200 * 0 on inference success
201 * -1 on inference error
202 * -2 on inference not invoked
203 */
204int ethosu_wait(struct ethosu_driver *drv, bool block);
205
206/**
Anton Moberg8d65b6f2020-12-21 09:37:18 +0100207 * Set Ethos-U power mode.
208 */
Anton Mobergeffc7aa2021-05-03 09:25:06 +0200209void ethosu_set_power_mode(struct ethosu_driver *drv, bool always_on);
Anton Moberg61da4d32020-12-22 16:00:31 +0100210
211/**
Anton Mobergdf386e02021-02-02 11:26:48 +0100212 * Reserves a driver to execute inference with
Anton Moberg61da4d32020-12-22 16:00:31 +0100213 */
214struct ethosu_driver *ethosu_reserve_driver(void);
215
216/**
217 * Change driver status to available
218 */
219void ethosu_release_driver(struct ethosu_driver *drv);
Anton Moberg8d65b6f2020-12-21 09:37:18 +0100220
Anton Mobergdf386e02021-02-02 11:26:48 +0100221/**
Anton Moberg0a614292021-03-24 14:08:22 +0100222 * Set clock and power request bits
223 */
224enum ethosu_error_codes set_clock_and_power_request(struct ethosu_driver *drv,
225 enum ethosu_request_clients client,
226 enum ethosu_clock_q_request clock_request,
227 enum ethosu_power_q_request power_request);
228
Kristofer Jonssonbe0bc462021-06-28 11:44:42 +0000229/**
230 * Static inline for backwards-compatibility
231 */
232static inline int ethosu_invoke_v2(const void *custom_data_ptr,
233 const int custom_data_size,
234 const uint64_t *base_addr,
235 const size_t *base_addr_size,
236 const int num_base_addr)
237{
238 struct ethosu_driver *drv = ethosu_reserve_driver();
Kristofer Jonssonb3cde3c2022-01-27 17:30:15 +0100239 int result = ethosu_invoke_v3(drv, custom_data_ptr, custom_data_size, base_addr, base_addr_size, num_base_addr, 0);
Kristofer Jonssonbe0bc462021-06-28 11:44:42 +0000240 ethosu_release_driver(drv);
241 return result;
242}
243
Kristofer Jonsson49bdee82020-04-06 13:21:21 +0200244#ifdef __cplusplus
245}
246#endif
Kristofer Jonsson3c439172020-08-05 09:38:40 +0200247
248#endif // ETHOSU_DRIVER_H