1/*
2 * Copyright (c) 2014-2016 ARM Limited
3 * All rights reserved
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 * Authors: Andreas Sandberg
18 */
19
20#ifndef _LIBNOMALI_NOMALI_HH
21#define _LIBNOMALI_NOMALI_HH
22
23#include <stdint.h>
24
25#ifdef __cplusplus
26extern "C" {
27#endif
28
29/**
30 * @file libnomali/nomali.h
31 * @short This header defines the NoMali stub GPU model interface.
32 *
33 */
34
35/** Opaque NoMali model handle. */
36typedef void* nomali_handle_t;
37
38/**
39 * NoMali error codes.
40 */
41enum {
42    /** No error */
43    NOMALI_E_OK = 0,
44    /** Unknown error */
45    NOMALI_E_UNKNOWN,
46    /** Memory allocation failed */
47    NOMALI_E_MEMORY,
48    /** Invalid model handle */
49    NOMALI_E_HANDLE,
50    /** Invalid parameter */
51    NOMALI_E_INVALID,
52
53    /**
54     * Number of errors defined
55     *
56     * @note This error, and higher error numbers, can be issued if
57     * the library is newer than the header file. Software should
58     * tread this condition as an unknown error.
59     */
60    NOMALI_E_NUM_ERRORS
61};
62typedef int nomali_error_t;
63
64enum {
65    NOMALI_GPU_T60X = 0,
66    NOMALI_GPU_T62X,
67    NOMALI_GPU_T76X,
68
69    NOMALI_GPU_T760 = NOMALI_GPU_T76X,
70};
71typedef int nomali_gpu_type_t;
72
73typedef struct {
74    nomali_gpu_type_t type;
75
76    unsigned ver_maj;
77    unsigned ver_min;
78    unsigned ver_status;
79} nomali_config_t;
80
81enum {
82    /** Model is signalling an interrupt */
83    NOMALI_CALLBACK_INT = 0,
84    /** Model read physical memory callback */
85    NOMALI_CALLBACK_MEMREAD,
86    /** Model write physical memory callback */
87    NOMALI_CALLBACK_MEMWRITE,
88    /** Model reset callback */
89    NOMALI_CALLBACK_RESET,
90
91    /** Number of defined callbacks */
92    NOMALI_CALLBACK_NUM_CALLBACKS
93};
94typedef int nomali_callback_type_t;
95
96enum {
97    NOMALI_INT_GPU = 0,
98    NOMALI_INT_JOB,
99    NOMALI_INT_MMU,
100};
101typedef int nomali_int_t;
102
103typedef uint64_t nomali_addr_t;
104typedef uint64_t nomali_size_t;
105
106/**
107 * Callback information structure.
108 */
109typedef struct {
110    /** Callback type */
111    nomali_callback_type_t type;
112    /** Pointer to user-defined data associated with callback */
113    void *usr;
114    /** Pointer to callback function */
115    union {
116        /**
117         * Interrupt state change
118         *
119         * @param h Model instance handle.
120         * @param usr User-defined data associated with callback.
121         * @param intno Interrupt number.
122         * @param set Non-zero if raising an interrupt, zero if clearing.
123         */
124        void (*interrupt)(nomali_handle_t h, void *usr,
125                          nomali_int_t intno, int set);
126        void (*memwrite)(nomali_handle_t h, void *usr,
127                         nomali_addr_t addr, uint32_t value);
128        uint32_t (*memread)(nomali_handle_t h, void *usr,
129                            nomali_addr_t addr);
130        void (*reset)(nomali_handle_t h, void *usr);
131    } func;
132} nomali_callback_t;
133
134/**
135 * GPU information struct. See nomali_get_info().
136 */
137typedef struct {
138    /** Size (in bytes) of the register window used by the GPU */
139    nomali_size_t reg_size;
140} nomali_info_t;
141
142typedef uint32_t nomali_api_version_t;
143
144/**
145 * Current version of the NoMali API
146 *
147 * This version number will increase whenever the API changes.
148 *
149 * @see nomali_api_version()
150 */
151#define NOMALI_API_VERSION 0
152
153/**
154 * Get the version of the API implemented by the library.
155 *
156 * Before instantiating a NoMali model, the driving application need
157 * to ensure that the library implements a compatible version of the
158 * NoMali API. This is done by calling this function and matching the
159 * return value with the NOMALI_API_VERSION define. The result of any
160 * call to the NoMali library is undefined if there is a miss-match
161 * between the two.
162 */
163nomali_api_version_t nomali_api_version();
164
165/**
166 * Create an instance of the NoMali model.
167 *
168 * @param[out] h Handle of the new NoMali model instance, undefined on
169 *               error.
170 *
171 * @param[in] cfg NoMali GPU configuration.
172 *
173 * @errors
174 * @error NOMALI_E_OK on success.
175 * @error NOMALI_E_MEMORY if a memory allocation failed.
176 * @error NOMALI_E_INVALID if a pointer to an output parameter is
177 *                         invalid.
178 */
179nomali_error_t nomali_create(nomali_handle_t *h, const nomali_config_t *cfg);
180/**
181 * Destroy and free resources used by an existing NoMali instance.
182 *
183 * @param[in] h Model instance handle.
184 *
185 * @errors
186 * @error NOMALI_E_OK on success.
187 * @error NOMALI_E_HANDLE if the handle was invalid.
188 */
189nomali_error_t nomali_destroy(nomali_handle_t h);
190
191
192/**
193 * Get a textual description of an error number.
194 *
195 * @param[in] error Error number to resolve.
196 *
197 * @return Pointer to a constant, null-terminated, string describing
198 * an error number.
199 */
200const char *nomali_errstr(nomali_error_t error);
201
202/**
203 * Setup callbacks from the model.
204 *
205 * @param[in] h        Model instance handle.
206 * @param[in] callback Structure describing the new callback to be
207 *                     installed.
208 *
209 * @errors
210 * @error NOMALI_E_OK on success.
211 * @error NOMALI_E_HANDLE if the handle was invalid.
212 * @error NOMALI_E_INVALID if the callback type was invalid.
213 *
214 * @see nomali_callback_t
215 */
216nomali_error_t nomali_set_callback(nomali_handle_t h,
217                                   const nomali_callback_t *callback);
218
219/**
220 * Get information about the hardware simulated by the model.
221 *
222 * @param[in]  h       Model instance handle.
223 * @param[out] info    Structure describing the model.
224 *
225 * @errors
226 * @error NOMALI_E_OK on success.
227 * @error NOMALI_E_HANDLE if the handle was invalid.
228 * @error NOMALI_E_INVALID if info is not pointing to a valid
229 *                         location.
230 *
231 * @see nomali_info_t
232 */
233nomali_error_t nomali_get_info(nomali_handle_t h,
234                               nomali_info_t *info);
235
236/**
237 * Perform a reset of the device.
238 *
239 * @param[in]  h     Model instance handle.
240 *
241 * @errors
242 * @error NOMALI_E_OK on success.
243 * @error NOMALI_E_HANDLE if the handle was invalid.
244 */
245nomali_error_t nomali_reset(nomali_handle_t h);
246
247/**
248 * Read a register within the device.
249 *
250 * @param[in]  h     Model instance handle.
251 * @param[out] value Pointer to output.
252 * @param[in]  addr  Address to read.
253 *
254 * @errors
255 * @error NOMALI_E_OK on success.
256 * @error NOMALI_E_HANDLE if the handle was invalid.
257 * @error NOMALI_E_INVALID if an invalid register was specified or if the
258 *                         pointer to the output location was invalid.
259 */
260nomali_error_t nomali_reg_read(nomali_handle_t h, uint32_t *value,
261                               nomali_addr_t addr);
262
263/**
264 * Write to a register within the device.
265 *
266 * @param[in] h     Model instance handle.
267 * @param[in] addr  Address to read.
268 * @param[in] value Value to write to the register.
269 *
270 * @errors
271 * @error NOMALI_E_OK on success.
272 * @error NOMALI_E_HANDLE if the handle was invalid.
273 * @error NOMALI_E_INVALID if an invalid register was specified.
274 */
275nomali_error_t nomali_reg_write(nomali_handle_t h,
276                                nomali_addr_t addr, uint32_t value);
277
278/**
279 * Read a register without side effects.
280 *
281 * @param[in]  h     Model instance handle.
282 * @param[out] value Pointer to output.
283 * @param[in]  addr  Address to read.
284 *
285 * @errors
286 * @error NOMALI_E_OK on success.
287 * @error NOMALI_E_HANDLE if the handle was invalid.
288 * @error NOMALI_E_INVALID if an invalid register was specified or if the
289 *                         pointer to the output location was invalid.
290 */
291nomali_error_t nomali_reg_read_raw(nomali_handle_t h, uint32_t *value,
292                                   nomali_addr_t addr);
293
294/**
295 * Write to a register without side effects.
296 *
297 * @param[in] h     Model instance handle.
298 * @param[in] addr  Address to read.
299 * @param[in] value Value to write to the register.
300 *
301 * @errors
302 * @error NOMALI_E_OK on success.
303 * @error NOMALI_E_HANDLE if the handle was invalid.
304 * @error NOMALI_E_INVALID if an invalid register was specified.
305 */
306nomali_error_t nomali_reg_write_raw(nomali_handle_t h,
307                                    nomali_addr_t addr, uint32_t value);
308
309/**
310 * Get the state of an interrupt line
311 *
312 * This function queries the state of one of the GPU's interrupt
313 * lines. The state of the interrupt line is returned in 'state',
314 * which is 1 if the interrupt is being asserted and 0 otherwise. The
315 * value of the state variable is undefined if the function call
316 * fails.
317 *
318 * @param[in]  h     Model instance handle.
319 * @param[out] state Pointer to output, 1 if the interrupt is
320 *                   asserted, 0 otherwise.
321 * @param[in]  intno Interrupt to query.
322 *
323 * @errors
324 * @error NOMALI_E_OK on success.
325 * @error NOMALI_E_HANDLE if the handle was invalid.
326 * @error NOMALI_E_INVALID if an invalid interrupt was specified or if
327 *                         pointer to the output location was invalid.
328 */
329nomali_error_t nomali_int_state(nomali_handle_t h, int *state,
330                                nomali_int_t intno);
331
332#ifdef __cplusplus
333};
334#endif
335
336#endif /* _LIBNOMALI_NOMALI_HH */
337