nomali.h revision 10915
1/* 2 * Copyright (c) 2014-2015 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 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); 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 */ 334