1/*
| 1/*
|
2 * Copyright (c) 2014-2015 ARM Limited
| 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,
| 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,
|
88
89 /** Number of defined callbacks */
90 NOMALI_CALLBACK_NUM_CALLBACKS
91};
92typedef int nomali_callback_type_t;
93
94enum {
95 NOMALI_INT_GPU = 0,
96 NOMALI_INT_JOB,
97 NOMALI_INT_MMU,
98};
99typedef int nomali_int_t;
100
101typedef uint64_t nomali_addr_t;
102typedef uint64_t nomali_size_t;
103
104/**
105 * Callback information structure.
106 */
107typedef struct {
108 /** Callback type */
109 nomali_callback_type_t type;
110 /** Pointer to user-defined data associated with callback */
111 void *usr;
112 /** Pointer to callback function */
113 union {
114 /**
115 * Interrupt state change
116 *
117 * @param h Model instance handle.
118 * @param usr User-defined data associated with callback.
119 * @param intno Interrupt number.
120 * @param set Non-zero if raising an interrupt, zero if clearing.
121 */
122 void (*interrupt)(nomali_handle_t h, void *usr,
123 nomali_int_t intno, int set);
124 void (*memwrite)(nomali_handle_t h, void *usr,
125 nomali_addr_t addr, uint32_t value);
126 uint32_t (*memread)(nomali_handle_t h, void *usr,
127 nomali_addr_t addr);
| 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);
|
128 } func;
129} nomali_callback_t;
130
131/**
132 * GPU information struct. See nomali_get_info().
133 */
134typedef struct {
135 /** Size (in bytes) of the register window used by the GPU */
136 nomali_size_t reg_size;
137} nomali_info_t;
138
139typedef uint32_t nomali_api_version_t;
140
141/**
142 * Current version of the NoMali API
143 *
144 * This version number will increase whenever the API changes.
145 *
146 * @see nomali_api_version()
147 */
148#define NOMALI_API_VERSION 0
149
150/**
151 * Get the version of the API implemented by the library.
152 *
153 * Before instantiating a NoMali model, the driving application need
154 * to ensure that the library implements a compatible version of the
155 * NoMali API. This is done by calling this function and matching the
156 * return value with the NOMALI_API_VERSION define. The result of any
157 * call to the NoMali library is undefined if there is a miss-match
158 * between the two.
159 */
160nomali_api_version_t nomali_api_version();
161
162/**
163 * Create an instance of the NoMali model.
164 *
165 * @param[out] h Handle of the new NoMali model instance, undefined on
166 * error.
167 *
168 * @param[in] cfg NoMali GPU configuration.
169 *
170 * @errors
171 * @error NOMALI_E_OK on success.
172 * @error NOMALI_E_MEMORY if a memory allocation failed.
173 * @error NOMALI_E_INVALID if a pointer to an output parameter is
174 * invalid.
175 */
176nomali_error_t nomali_create(nomali_handle_t *h, const nomali_config_t *cfg);
177/**
178 * Destroy and free resources used by an existing NoMali instance.
179 *
180 * @param[in] h Model instance handle.
181 *
182 * @errors
183 * @error NOMALI_E_OK on success.
184 * @error NOMALI_E_HANDLE if the handle was invalid.
185 */
186nomali_error_t nomali_destroy(nomali_handle_t h);
187
188
189/**
190 * Get a textual description of an error number.
191 *
192 * @param[in] error Error number to resolve.
193 *
194 * @return Pointer to a constant, null-terminated, string describing
195 * an error number.
196 */
197const char *nomali_errstr(nomali_error_t error);
198
199/**
200 * Setup callbacks from the model.
201 *
202 * @param[in] h Model instance handle.
203 * @param[in] callback Structure describing the new callback to be
204 * installed.
205 *
206 * @errors
207 * @error NOMALI_E_OK on success.
208 * @error NOMALI_E_HANDLE if the handle was invalid.
209 * @error NOMALI_E_INVALID if the callback type was invalid.
210 *
211 * @see nomali_callback_t
212 */
213nomali_error_t nomali_set_callback(nomali_handle_t h,
214 const nomali_callback_t *callback);
215
216/**
217 * Get information about the hardware simulated by the model.
218 *
219 * @param[in] h Model instance handle.
220 * @param[out] info Structure describing the model.
221 *
222 * @errors
223 * @error NOMALI_E_OK on success.
224 * @error NOMALI_E_HANDLE if the handle was invalid.
225 * @error NOMALI_E_INVALID if info is not pointing to a valid
226 * location.
227 *
228 * @see nomali_info_t
229 */
230nomali_error_t nomali_get_info(nomali_handle_t h,
231 nomali_info_t *info);
232
233/**
234 * Perform a reset of the device.
235 *
236 * @param[in] h Model instance handle.
237 *
238 * @errors
239 * @error NOMALI_E_OK on success.
240 * @error NOMALI_E_HANDLE if the handle was invalid.
241 */
242nomali_error_t nomali_reset(nomali_handle_t h);
243
244/**
245 * Read a register within the device.
246 *
247 * @param[in] h Model instance handle.
248 * @param[out] value Pointer to output.
249 * @param[in] addr Address to read.
250 *
251 * @errors
252 * @error NOMALI_E_OK on success.
253 * @error NOMALI_E_HANDLE if the handle was invalid.
254 * @error NOMALI_E_INVALID if an invalid register was specified or if the
255 * pointer to the output location was invalid.
256 */
257nomali_error_t nomali_reg_read(nomali_handle_t h, uint32_t *value,
258 nomali_addr_t addr);
259
260/**
261 * Write to a register within the device.
262 *
263 * @param[in] h Model instance handle.
264 * @param[in] addr Address to read.
265 * @param[in] value Value to write to the register.
266 *
267 * @errors
268 * @error NOMALI_E_OK on success.
269 * @error NOMALI_E_HANDLE if the handle was invalid.
270 * @error NOMALI_E_INVALID if an invalid register was specified.
271 */
272nomali_error_t nomali_reg_write(nomali_handle_t h,
273 nomali_addr_t addr, uint32_t value);
274
275/**
276 * Read a register without side effects.
277 *
278 * @param[in] h Model instance handle.
279 * @param[out] value Pointer to output.
280 * @param[in] addr Address to read.
281 *
282 * @errors
283 * @error NOMALI_E_OK on success.
284 * @error NOMALI_E_HANDLE if the handle was invalid.
285 * @error NOMALI_E_INVALID if an invalid register was specified or if the
286 * pointer to the output location was invalid.
287 */
288nomali_error_t nomali_reg_read_raw(nomali_handle_t h, uint32_t *value,
289 nomali_addr_t addr);
290
291/**
292 * Write to a register without side effects.
293 *
294 * @param[in] h Model instance handle.
295 * @param[in] addr Address to read.
296 * @param[in] value Value to write to the register.
297 *
298 * @errors
299 * @error NOMALI_E_OK on success.
300 * @error NOMALI_E_HANDLE if the handle was invalid.
301 * @error NOMALI_E_INVALID if an invalid register was specified.
302 */
303nomali_error_t nomali_reg_write_raw(nomali_handle_t h,
304 nomali_addr_t addr, uint32_t value);
305
306/**
307 * Get the state of an interrupt line
308 *
309 * This function queries the state of one of the GPU's interrupt
310 * lines. The state of the interrupt line is returned in 'state',
311 * which is 1 if the interrupt is being asserted and 0 otherwise. The
312 * value of the state variable is undefined if the function call
313 * fails.
314 *
315 * @param[in] h Model instance handle.
316 * @param[out] state Pointer to output, 1 if the interrupt is
317 * asserted, 0 otherwise.
318 * @param[in] intno Interrupt to query.
319 *
320 * @errors
321 * @error NOMALI_E_OK on success.
322 * @error NOMALI_E_HANDLE if the handle was invalid.
323 * @error NOMALI_E_INVALID if an invalid interrupt was specified or if
324 * pointer to the output location was invalid.
325 */
326nomali_error_t nomali_int_state(nomali_handle_t h, int *state,
327 nomali_int_t intno);
328
329#ifdef __cplusplus
330};
331#endif
332
333#endif /* _LIBNOMALI_NOMALI_HH */
| 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 */
|