nomali.h revision 11313
16019Shines@cs.fsu.edu/* 210037SARM gem5 Developers * Copyright (c) 2014-2016 ARM Limited 310037SARM gem5 Developers * All rights reserved 410037SARM gem5 Developers * 510037SARM gem5 Developers * Licensed under the Apache License, Version 2.0 (the "License"); 610037SARM gem5 Developers * you may not use this file except in compliance with the License. 710037SARM gem5 Developers * You may obtain a copy of the License at 810037SARM gem5 Developers * 910037SARM gem5 Developers * http://www.apache.org/licenses/LICENSE-2.0 1010037SARM gem5 Developers * 1110037SARM gem5 Developers * Unless required by applicable law or agreed to in writing, software 1210037SARM gem5 Developers * distributed under the License is distributed on an "AS IS" BASIS, 1310037SARM gem5 Developers * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 146019Shines@cs.fsu.edu * See the License for the specific language governing permissions and 156019Shines@cs.fsu.edu * limitations under the License. 166019Shines@cs.fsu.edu * 176019Shines@cs.fsu.edu * Authors: Andreas Sandberg 186019Shines@cs.fsu.edu */ 196019Shines@cs.fsu.edu 206019Shines@cs.fsu.edu#ifndef _LIBNOMALI_NOMALI_HH 216019Shines@cs.fsu.edu#define _LIBNOMALI_NOMALI_HH 226019Shines@cs.fsu.edu 236019Shines@cs.fsu.edu#include <stdint.h> 246019Shines@cs.fsu.edu 256019Shines@cs.fsu.edu#ifdef __cplusplus 266019Shines@cs.fsu.eduextern "C" { 276019Shines@cs.fsu.edu#endif 286019Shines@cs.fsu.edu 296019Shines@cs.fsu.edu/** 306019Shines@cs.fsu.edu * @file libnomali/nomali.h 316019Shines@cs.fsu.edu * @short This header defines the NoMali stub GPU model interface. 326019Shines@cs.fsu.edu * 336019Shines@cs.fsu.edu */ 346019Shines@cs.fsu.edu 356019Shines@cs.fsu.edu/** Opaque NoMali model handle. */ 366019Shines@cs.fsu.edutypedef void* nomali_handle_t; 376019Shines@cs.fsu.edu 386019Shines@cs.fsu.edu/** 396019Shines@cs.fsu.edu * NoMali error codes. 406019Shines@cs.fsu.edu */ 416019Shines@cs.fsu.eduenum { 426019Shines@cs.fsu.edu /** No error */ 436019Shines@cs.fsu.edu NOMALI_E_OK = 0, 446019Shines@cs.fsu.edu /** Unknown error */ 456019Shines@cs.fsu.edu NOMALI_E_UNKNOWN, 466019Shines@cs.fsu.edu /** Memory allocation failed */ 476019Shines@cs.fsu.edu NOMALI_E_MEMORY, 488229Snate@binkert.org /** Invalid model handle */ 4910037SARM gem5 Developers NOMALI_E_HANDLE, 507096Sgblack@eecs.umich.edu /** Invalid parameter */ 516019Shines@cs.fsu.edu NOMALI_E_INVALID, 526019Shines@cs.fsu.edu 536019Shines@cs.fsu.edu /** 546019Shines@cs.fsu.edu * Number of errors defined 556019Shines@cs.fsu.edu * 566019Shines@cs.fsu.edu * @note This error, and higher error numbers, can be issued if 576019Shines@cs.fsu.edu * the library is newer than the header file. Software should 586019Shines@cs.fsu.edu * tread this condition as an unknown error. 596019Shines@cs.fsu.edu */ 607096Sgblack@eecs.umich.edu NOMALI_E_NUM_ERRORS 617096Sgblack@eecs.umich.edu}; 627096Sgblack@eecs.umich.edutypedef int nomali_error_t; 6310037SARM gem5 Developers 6410037SARM gem5 Developersenum { 6510037SARM gem5 Developers NOMALI_GPU_T60X = 0, 6610037SARM gem5 Developers NOMALI_GPU_T62X, 6710037SARM gem5 Developers NOMALI_GPU_T76X, 6810037SARM gem5 Developers 6910037SARM gem5 Developers NOMALI_GPU_T760 = NOMALI_GPU_T76X, 7010037SARM gem5 Developers}; 7110037SARM gem5 Developerstypedef int nomali_gpu_type_t; 7210037SARM gem5 Developers 736019Shines@cs.fsu.edutypedef struct { 748216Ssaidi@eecs.umich.edu nomali_gpu_type_t type; 756019Shines@cs.fsu.edu 766019Shines@cs.fsu.edu unsigned ver_maj; 7710037SARM gem5 Developers unsigned ver_min; 7810037SARM gem5 Developers unsigned ver_status; 7910037SARM gem5 Developers} nomali_config_t; 8010037SARM gem5 Developers 8110037SARM gem5 Developersenum { 8210037SARM gem5 Developers /** Model is signalling an interrupt */ 8310037SARM gem5 Developers NOMALI_CALLBACK_INT = 0, 8410037SARM gem5 Developers /** Model read physical memory callback */ 8510037SARM gem5 Developers NOMALI_CALLBACK_MEMREAD, 8610037SARM gem5 Developers /** Model write physical memory callback */ 8710037SARM gem5 Developers NOMALI_CALLBACK_MEMWRITE, 8810037SARM gem5 Developers /** Model reset callback */ 8910037SARM gem5 Developers NOMALI_CALLBACK_RESET, 9010037SARM gem5 Developers 9110037SARM gem5 Developers /** Number of defined callbacks */ 9210037SARM gem5 Developers NOMALI_CALLBACK_NUM_CALLBACKS 9310037SARM gem5 Developers}; 946019Shines@cs.fsu.edutypedef int nomali_callback_type_t; 959552Sandreas.hansson@arm.com 966701Sgblack@eecs.umich.eduenum { 976020Sgblack@eecs.umich.edu NOMALI_INT_GPU = 0, 986020Sgblack@eecs.umich.edu NOMALI_INT_JOB, 996019Shines@cs.fsu.edu NOMALI_INT_MMU, 1006019Shines@cs.fsu.edu}; 10110299Salexandru.dutu@amd.comtypedef int nomali_int_t; 10210299Salexandru.dutu@amd.com 10310299Salexandru.dutu@amd.comtypedef uint64_t nomali_addr_t; 1046019Shines@cs.fsu.edutypedef uint64_t nomali_size_t; 1056019Shines@cs.fsu.edu 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