nomali.h revision 10915
12068SN/A/* 22068SN/A * Copyright (c) 2014-2015 ARM Limited 32188SN/A * All rights reserved 42068SN/A * 52068SN/A * Licensed under the Apache License, Version 2.0 (the "License"); 62068SN/A * you may not use this file except in compliance with the License. 72068SN/A * You may obtain a copy of the License at 82068SN/A * 92068SN/A * http://www.apache.org/licenses/LICENSE-2.0 102068SN/A * 112068SN/A * Unless required by applicable law or agreed to in writing, software 122068SN/A * distributed under the License is distributed on an "AS IS" BASIS, 132068SN/A * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 142068SN/A * See the License for the specific language governing permissions and 152068SN/A * limitations under the License. 162068SN/A * 172068SN/A * Authors: Andreas Sandberg 182068SN/A */ 192068SN/A 202068SN/A#ifndef _LIBNOMALI_NOMALI_HH 212068SN/A#define _LIBNOMALI_NOMALI_HH 222068SN/A 232068SN/A#include <stdint.h> 242068SN/A 252068SN/A#ifdef __cplusplus 262068SN/Aextern "C" { 272068SN/A#endif 282665Ssaidi@eecs.umich.edu 292665Ssaidi@eecs.umich.edu/** 302068SN/A * @file libnomali/nomali.h 312649Ssaidi@eecs.umich.edu * @short This header defines the NoMali stub GPU model interface. 322649Ssaidi@eecs.umich.edu * 332649Ssaidi@eecs.umich.edu */ 342649Ssaidi@eecs.umich.edu 352649Ssaidi@eecs.umich.edu/** Opaque NoMali model handle. */ 362068SN/Atypedef void* nomali_handle_t; 372068SN/A 382068SN/A/** 392068SN/A * NoMali error codes. 402068SN/A */ 412068SN/Aenum { 422068SN/A /** No error */ 432068SN/A NOMALI_E_OK = 0, 442075SN/A /** Unknown error */ 452075SN/A NOMALI_E_UNKNOWN, 462075SN/A /** Memory allocation failed */ 472075SN/A NOMALI_E_MEMORY, 482075SN/A /** Invalid model handle */ 492075SN/A NOMALI_E_HANDLE, 502735Sktlim@umich.edu /** Invalid parameter */ 512069SN/A NOMALI_E_INVALID, 522069SN/A 532075SN/A /** 542735Sktlim@umich.edu * Number of errors defined 552068SN/A * 562068SN/A * @note This error, and higher error numbers, can be issued if 572068SN/A * the library is newer than the header file. Software should 582075SN/A * tread this condition as an unknown error. 592075SN/A */ 602068SN/A NOMALI_E_NUM_ERRORS 612068SN/A}; 622075SN/Atypedef int nomali_error_t; 632075SN/A 642068SN/Aenum { 652068SN/A NOMALI_GPU_T60X = 0, 662068SN/A NOMALI_GPU_T62X, 672075SN/A NOMALI_GPU_T76X, 682075SN/A 692075SN/A NOMALI_GPU_T760 = NOMALI_GPU_T76X, 702075SN/A}; 712075SN/Atypedef int nomali_gpu_type_t; 722075SN/A 732075SN/Atypedef struct { 742735Sktlim@umich.edu nomali_gpu_type_t type; 752069SN/A 762069SN/A unsigned ver_maj; 772075SN/A unsigned ver_min; 782735Sktlim@umich.edu unsigned ver_status; 792068SN/A} nomali_config_t; 802068SN/A 812068SN/Aenum { 822075SN/A /** Model is signalling an interrupt */ 832068SN/A NOMALI_CALLBACK_INT = 0, 842069SN/A /** Model read physical memory callback */ 852068SN/A NOMALI_CALLBACK_MEMREAD, 862068SN/A /** Model write physical memory callback */ 872336SN/A NOMALI_CALLBACK_MEMWRITE, 882075SN/A 892068SN/A /** Number of defined callbacks */ 902069SN/A NOMALI_CALLBACK_NUM_CALLBACKS 912068SN/A}; 922068SN/Atypedef int nomali_callback_type_t; 932068SN/A 942068SN/Aenum { 952068SN/A NOMALI_INT_GPU = 0, 962068SN/A NOMALI_INT_JOB, 972068SN/A NOMALI_INT_MMU, 982068SN/A}; 992336SN/Atypedef int nomali_int_t; 1002068SN/A 1012068SN/Atypedef uint64_t nomali_addr_t; 1022068SN/Atypedef uint64_t nomali_size_t; 1032068SN/A 1042068SN/A/** 1052068SN/A * Callback information structure. 1062068SN/A */ 1072068SN/Atypedef struct { 1082068SN/A /** Callback type */ 1092068SN/A nomali_callback_type_t type; 1102068SN/A /** Pointer to user-defined data associated with callback */ 1112068SN/A void *usr; 1122147SN/A /** Pointer to callback function */ 1132068SN/A union { 1142068SN/A /** 1152068SN/A * Interrupt state change 1162068SN/A * 1172068SN/A * @param h Model instance handle. 1182068SN/A * @param usr User-defined data associated with callback. 1192068SN/A * @param intno Interrupt number. 1202068SN/A * @param set Non-zero if raising an interrupt, zero if clearing. 1212068SN/A */ 1222068SN/A void (*interrupt)(nomali_handle_t h, void *usr, 1232068SN/A nomali_int_t intno, int set); 1242147SN/A void (*memwrite)(nomali_handle_t h, void *usr, 1252068SN/A nomali_addr_t addr, uint32_t value); 1262068SN/A uint32_t (*memread)(nomali_handle_t h, void *usr, 1272068SN/A nomali_addr_t addr); 1282068SN/A } func; 1292068SN/A} nomali_callback_t; 1302068SN/A 1312068SN/A/** 1322068SN/A * GPU information struct. See nomali_get_info(). 1332068SN/A */ 1342068SN/Atypedef struct { 1352068SN/A /** Size (in bytes) of the register window used by the GPU */ 1362068SN/A nomali_size_t reg_size; 1372068SN/A} nomali_info_t; 1382147SN/A 1392068SN/Atypedef uint32_t nomali_api_version_t; 1402068SN/A 1412068SN/A/** 1422068SN/A * Current version of the NoMali API 1432068SN/A * 1442068SN/A * This version number will increase whenever the API changes. 1452068SN/A * 1462068SN/A * @see nomali_api_version() 1472068SN/A */ 1482068SN/A#define NOMALI_API_VERSION 0 1492068SN/A 1502068SN/A/** 1512068SN/A * Get the version of the API implemented by the library. 1522147SN/A * 1532068SN/A * Before instantiating a NoMali model, the driving application need 1542068SN/A * to ensure that the library implements a compatible version of the 1552068SN/A * NoMali API. This is done by calling this function and matching the 1562068SN/A * return value with the NOMALI_API_VERSION define. The result of any 1572068SN/A * call to the NoMali library is undefined if there is a miss-match 1582068SN/A * between the two. 1592068SN/A */ 1602068SN/Anomali_api_version_t nomali_api_version(); 1612068SN/A 1622068SN/A/** 1632068SN/A * Create an instance of the NoMali model. 1642068SN/A * 1652068SN/A * @param[out] h Handle of the new NoMali model instance, undefined on 1662068SN/A * error. 1672068SN/A * 1682068SN/A * @param[in] cfg NoMali GPU configuration. 1692068SN/A * 1702068SN/A * @errors 1712068SN/A * @error NOMALI_E_OK on success. 1722068SN/A * @error NOMALI_E_MEMORY if a memory allocation failed. 1732068SN/A * @error NOMALI_E_INVALID if a pointer to an output parameter is 1742068SN/A * invalid. 1752068SN/A */ 1762068SN/Anomali_error_t nomali_create(nomali_handle_t *h, const nomali_config_t *cfg); 1772068SN/A/** 1782068SN/A * Destroy and free resources used by an existing NoMali instance. 1792068SN/A * 1802068SN/A * @param[in] h Model instance handle. 1812068SN/A * 1822068SN/A * @errors 1832068SN/A * @error NOMALI_E_OK on success. 1842068SN/A * @error NOMALI_E_HANDLE if the handle was invalid. 1852068SN/A */ 1862068SN/Anomali_error_t nomali_destroy(nomali_handle_t h); 1872068SN/A 1882068SN/A 1892068SN/A/** 1902068SN/A * Get a textual description of an error number. 1912068SN/A * 1922068SN/A * @param[in] error Error number to resolve. 1932068SN/A * 1942068SN/A * @return Pointer to a constant, null-terminated, string describing 1952068SN/A * an error number. 1962068SN/A */ 1972068SN/Aconst char *nomali_errstr(nomali_error_t error); 1982068SN/A 1992068SN/A/** 2002068SN/A * Setup callbacks from the model. 2012068SN/A * 2022068SN/A * @param[in] h Model instance handle. 2032068SN/A * @param[in] callback Structure describing the new callback to be 2042068SN/A * installed. 2052068SN/A * 2062068SN/A * @errors 2072068SN/A * @error NOMALI_E_OK on success. 2082068SN/A * @error NOMALI_E_HANDLE if the handle was invalid. 2092068SN/A * @error NOMALI_E_INVALID if the callback type was invalid. 2102068SN/A * 2112068SN/A * @see nomali_callback_t 2122068SN/A */ 2132068SN/Anomali_error_t nomali_set_callback(nomali_handle_t h, 2142068SN/A const nomali_callback_t *callback); 2152068SN/A 2162068SN/A/** 2172068SN/A * Get information about the hardware simulated by the model. 2182068SN/A * 2192068SN/A * @param[in] h Model instance handle. 2202068SN/A * @param[out] info Structure describing the model. 2212068SN/A * 2222068SN/A * @errors 2232068SN/A * @error NOMALI_E_OK on success. 2242068SN/A * @error NOMALI_E_HANDLE if the handle was invalid. 2252068SN/A * @error NOMALI_E_INVALID if info is not pointing to a valid 2262068SN/A * location. 2272068SN/A * 2282068SN/A * @see nomali_info_t 2292068SN/A */ 2302068SN/Anomali_error_t nomali_get_info(nomali_handle_t h, 2312068SN/A nomali_info_t *info); 2322068SN/A 2332068SN/A/** 2342068SN/A * Perform a reset of the device. 2352068SN/A * 2362068SN/A * @param[in] h Model instance handle. 2372068SN/A * 2382068SN/A * @errors 2392068SN/A * @error NOMALI_E_OK on success. 2402068SN/A * @error NOMALI_E_HANDLE if the handle was invalid. 2412068SN/A */ 2422068SN/Anomali_error_t nomali_reset(nomali_handle_t h); 2432068SN/A 2442068SN/A/** 2452068SN/A * Read a register within the device. 2462068SN/A * 2472068SN/A * @param[in] h Model instance handle. 2482068SN/A * @param[out] value Pointer to output. 2492068SN/A * @param[in] addr Address to read. 2502068SN/A * 2512068SN/A * @errors 2522068SN/A * @error NOMALI_E_OK on success. 2532068SN/A * @error NOMALI_E_HANDLE if the handle was invalid. 2542068SN/A * @error NOMALI_E_INVALID if an invalid register was specified or if the 2552068SN/A * pointer to the output location was invalid. 2562068SN/A */ 2572068SN/Anomali_error_t nomali_reg_read(nomali_handle_t h, uint32_t *value, 2582068SN/A nomali_addr_t addr); 2592068SN/A 2602068SN/A/** 2612068SN/A * Write to a register within the device. 2622068SN/A * 2632068SN/A * @param[in] h Model instance handle. 2642068SN/A * @param[in] addr Address to read. 2652068SN/A * @param[in] value Value to write to the register. 2662068SN/A * 2672068SN/A * @errors 2682068SN/A * @error NOMALI_E_OK on success. 2692068SN/A * @error NOMALI_E_HANDLE if the handle was invalid. 2702068SN/A * @error NOMALI_E_INVALID if an invalid register was specified. 2712068SN/A */ 2722068SN/Anomali_error_t nomali_reg_write(nomali_handle_t h, 2732068SN/A nomali_addr_t addr, uint32_t value); 2742068SN/A 2752068SN/A/** 2762068SN/A * Read a register without side effects. 2772068SN/A * 2782068SN/A * @param[in] h Model instance handle. 2792068SN/A * @param[out] value Pointer to output. 2802068SN/A * @param[in] addr Address to read. 2812068SN/A * 2822068SN/A * @errors 2832068SN/A * @error NOMALI_E_OK on success. 2842068SN/A * @error NOMALI_E_HANDLE if the handle was invalid. 2852068SN/A * @error NOMALI_E_INVALID if an invalid register was specified or if the 2862068SN/A * pointer to the output location was invalid. 2872068SN/A */ 2882068SN/Anomali_error_t nomali_reg_read_raw(nomali_handle_t h, uint32_t *value, 2892068SN/A nomali_addr_t addr); 2902068SN/A 2912068SN/A/** 2922068SN/A * Write to a register without side effects. 2932068SN/A * 2942068SN/A * @param[in] h Model instance handle. 2952068SN/A * @param[in] addr Address to read. 2962068SN/A * @param[in] value Value to write to the register. 2972068SN/A * 2982068SN/A * @errors 2992068SN/A * @error NOMALI_E_OK on success. 3002068SN/A * @error NOMALI_E_HANDLE if the handle was invalid. 3012068SN/A * @error NOMALI_E_INVALID if an invalid register was specified. 3022068SN/A */ 3032068SN/Anomali_error_t nomali_reg_write_raw(nomali_handle_t h, 3042068SN/A nomali_addr_t addr, uint32_t value); 3052068SN/A 3062068SN/A/** 3072068SN/A * Get the state of an interrupt line 3082068SN/A * 3092068SN/A * This function queries the state of one of the GPU's interrupt 3102068SN/A * lines. The state of the interrupt line is returned in 'state', 3112068SN/A * which is 1 if the interrupt is being asserted and 0 otherwise. The 3122068SN/A * value of the state variable is undefined if the function call 3132147SN/A * fails. 3142068SN/A * 3152068SN/A * @param[in] h Model instance handle. 3162068SN/A * @param[out] state Pointer to output, 1 if the interrupt is 3172068SN/A * asserted, 0 otherwise. 3182068SN/A * @param[in] intno Interrupt to query. 3192068SN/A * 3202068SN/A * @errors 3212068SN/A * @error NOMALI_E_OK on success. 3222068SN/A * @error NOMALI_E_HANDLE if the handle was invalid. 3232068SN/A * @error NOMALI_E_INVALID if an invalid interrupt was specified or if 3242147SN/A * pointer to the output location was invalid. 3252068SN/A */ 3262068SN/Anomali_error_t nomali_int_state(nomali_handle_t h, int *state, 3272068SN/A nomali_int_t intno); 3282068SN/A 3292068SN/A#ifdef __cplusplus 3302068SN/A}; 3312068SN/A#endif 3322068SN/A 3332068SN/A#endif /* _LIBNOMALI_NOMALI_HH */ 3342068SN/A