nomali.h revision 11313:89fd4a775287
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