nomali.h revision 11313
110259SAndrew.Bardsley@arm.com/* 210259SAndrew.Bardsley@arm.com * Copyright (c) 2014-2016 ARM Limited 310259SAndrew.Bardsley@arm.com * All rights reserved 410259SAndrew.Bardsley@arm.com * 510259SAndrew.Bardsley@arm.com * Licensed under the Apache License, Version 2.0 (the "License"); 610259SAndrew.Bardsley@arm.com * you may not use this file except in compliance with the License. 710259SAndrew.Bardsley@arm.com * You may obtain a copy of the License at 810259SAndrew.Bardsley@arm.com * 910259SAndrew.Bardsley@arm.com * http://www.apache.org/licenses/LICENSE-2.0 1010259SAndrew.Bardsley@arm.com * 1110259SAndrew.Bardsley@arm.com * Unless required by applicable law or agreed to in writing, software 1210259SAndrew.Bardsley@arm.com * distributed under the License is distributed on an "AS IS" BASIS, 1310259SAndrew.Bardsley@arm.com * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1410259SAndrew.Bardsley@arm.com * See the License for the specific language governing permissions and 1510259SAndrew.Bardsley@arm.com * limitations under the License. 1610259SAndrew.Bardsley@arm.com * 1710259SAndrew.Bardsley@arm.com * Authors: Andreas Sandberg 1810259SAndrew.Bardsley@arm.com */ 1910259SAndrew.Bardsley@arm.com 2010259SAndrew.Bardsley@arm.com#ifndef _LIBNOMALI_NOMALI_HH 2110259SAndrew.Bardsley@arm.com#define _LIBNOMALI_NOMALI_HH 2210259SAndrew.Bardsley@arm.com 2310259SAndrew.Bardsley@arm.com#include <stdint.h> 2410259SAndrew.Bardsley@arm.com 2510259SAndrew.Bardsley@arm.com#ifdef __cplusplus 2610259SAndrew.Bardsley@arm.comextern "C" { 2710259SAndrew.Bardsley@arm.com#endif 2810259SAndrew.Bardsley@arm.com 2910259SAndrew.Bardsley@arm.com/** 3010259SAndrew.Bardsley@arm.com * @file libnomali/nomali.h 3110259SAndrew.Bardsley@arm.com * @short This header defines the NoMali stub GPU model interface. 3210259SAndrew.Bardsley@arm.com * 3310259SAndrew.Bardsley@arm.com */ 3410259SAndrew.Bardsley@arm.com 3510259SAndrew.Bardsley@arm.com/** Opaque NoMali model handle. */ 3610259SAndrew.Bardsley@arm.comtypedef void* nomali_handle_t; 3710259SAndrew.Bardsley@arm.com 3810259SAndrew.Bardsley@arm.com/** 3910259SAndrew.Bardsley@arm.com * NoMali error codes. 4010259SAndrew.Bardsley@arm.com */ 4110259SAndrew.Bardsley@arm.comenum { 4210259SAndrew.Bardsley@arm.com /** No error */ 4310259SAndrew.Bardsley@arm.com NOMALI_E_OK = 0, 4410259SAndrew.Bardsley@arm.com /** Unknown error */ 4510259SAndrew.Bardsley@arm.com NOMALI_E_UNKNOWN, 4610259SAndrew.Bardsley@arm.com /** Memory allocation failed */ 4710259SAndrew.Bardsley@arm.com NOMALI_E_MEMORY, 4810259SAndrew.Bardsley@arm.com /** Invalid model handle */ 4910259SAndrew.Bardsley@arm.com NOMALI_E_HANDLE, 5010913Sandreas.sandberg@arm.com /** Invalid parameter */ 5110259SAndrew.Bardsley@arm.com NOMALI_E_INVALID, 5210259SAndrew.Bardsley@arm.com 5310259SAndrew.Bardsley@arm.com /** 5410259SAndrew.Bardsley@arm.com * Number of errors defined 5510259SAndrew.Bardsley@arm.com * 5610259SAndrew.Bardsley@arm.com * @note This error, and higher error numbers, can be issued if 5710259SAndrew.Bardsley@arm.com * the library is newer than the header file. Software should 5810259SAndrew.Bardsley@arm.com * tread this condition as an unknown error. 5910259SAndrew.Bardsley@arm.com */ 6010259SAndrew.Bardsley@arm.com NOMALI_E_NUM_ERRORS 6110259SAndrew.Bardsley@arm.com}; 6210259SAndrew.Bardsley@arm.comtypedef int nomali_error_t; 6310259SAndrew.Bardsley@arm.com 6410259SAndrew.Bardsley@arm.comenum { 6510259SAndrew.Bardsley@arm.com NOMALI_GPU_T60X = 0, 6610259SAndrew.Bardsley@arm.com NOMALI_GPU_T62X, 6710259SAndrew.Bardsley@arm.com NOMALI_GPU_T76X, 6810259SAndrew.Bardsley@arm.com 6910259SAndrew.Bardsley@arm.com NOMALI_GPU_T760 = NOMALI_GPU_T76X, 7010259SAndrew.Bardsley@arm.com}; 7110259SAndrew.Bardsley@arm.comtypedef int nomali_gpu_type_t; 7210259SAndrew.Bardsley@arm.com 7310259SAndrew.Bardsley@arm.comtypedef struct { 7410259SAndrew.Bardsley@arm.com nomali_gpu_type_t type; 7510259SAndrew.Bardsley@arm.com 7610259SAndrew.Bardsley@arm.com unsigned ver_maj; 7710259SAndrew.Bardsley@arm.com unsigned ver_min; 7810259SAndrew.Bardsley@arm.com unsigned ver_status; 7910259SAndrew.Bardsley@arm.com} nomali_config_t; 8010259SAndrew.Bardsley@arm.com 8110259SAndrew.Bardsley@arm.comenum { 8210259SAndrew.Bardsley@arm.com /** Model is signalling an interrupt */ 8310259SAndrew.Bardsley@arm.com NOMALI_CALLBACK_INT = 0, 8410259SAndrew.Bardsley@arm.com /** Model read physical memory callback */ 8510259SAndrew.Bardsley@arm.com NOMALI_CALLBACK_MEMREAD, 8610259SAndrew.Bardsley@arm.com /** Model write physical memory callback */ 8710259SAndrew.Bardsley@arm.com NOMALI_CALLBACK_MEMWRITE, 8810259SAndrew.Bardsley@arm.com /** Model reset callback */ 8910259SAndrew.Bardsley@arm.com NOMALI_CALLBACK_RESET, 9010259SAndrew.Bardsley@arm.com 9110259SAndrew.Bardsley@arm.com /** Number of defined callbacks */ 9210259SAndrew.Bardsley@arm.com NOMALI_CALLBACK_NUM_CALLBACKS 9310259SAndrew.Bardsley@arm.com}; 9410259SAndrew.Bardsley@arm.comtypedef int nomali_callback_type_t; 9510259SAndrew.Bardsley@arm.com 9610259SAndrew.Bardsley@arm.comenum { 9710259SAndrew.Bardsley@arm.com NOMALI_INT_GPU = 0, 9810259SAndrew.Bardsley@arm.com NOMALI_INT_JOB, 9910259SAndrew.Bardsley@arm.com NOMALI_INT_MMU, 10010259SAndrew.Bardsley@arm.com}; 10110259SAndrew.Bardsley@arm.comtypedef int nomali_int_t; 10210259SAndrew.Bardsley@arm.com 10310259SAndrew.Bardsley@arm.comtypedef uint64_t nomali_addr_t; 10410259SAndrew.Bardsley@arm.comtypedef uint64_t nomali_size_t; 10510259SAndrew.Bardsley@arm.com 10610259SAndrew.Bardsley@arm.com/** 10710259SAndrew.Bardsley@arm.com * Callback information structure. 10810259SAndrew.Bardsley@arm.com */ 10910259SAndrew.Bardsley@arm.comtypedef struct { 11010259SAndrew.Bardsley@arm.com /** Callback type */ 11110259SAndrew.Bardsley@arm.com nomali_callback_type_t type; 11210259SAndrew.Bardsley@arm.com /** Pointer to user-defined data associated with callback */ 11310259SAndrew.Bardsley@arm.com void *usr; 11410259SAndrew.Bardsley@arm.com /** Pointer to callback function */ 11510259SAndrew.Bardsley@arm.com union { 11610259SAndrew.Bardsley@arm.com /** 11710259SAndrew.Bardsley@arm.com * Interrupt state change 11810259SAndrew.Bardsley@arm.com * 11910259SAndrew.Bardsley@arm.com * @param h Model instance handle. 12010259SAndrew.Bardsley@arm.com * @param usr User-defined data associated with callback. 12110259SAndrew.Bardsley@arm.com * @param intno Interrupt number. 12210259SAndrew.Bardsley@arm.com * @param set Non-zero if raising an interrupt, zero if clearing. 12310259SAndrew.Bardsley@arm.com */ 12410259SAndrew.Bardsley@arm.com void (*interrupt)(nomali_handle_t h, void *usr, 12510259SAndrew.Bardsley@arm.com nomali_int_t intno, int set); 12610259SAndrew.Bardsley@arm.com void (*memwrite)(nomali_handle_t h, void *usr, 12710259SAndrew.Bardsley@arm.com nomali_addr_t addr, uint32_t value); 12810259SAndrew.Bardsley@arm.com uint32_t (*memread)(nomali_handle_t h, void *usr, 12910259SAndrew.Bardsley@arm.com nomali_addr_t addr); 13010259SAndrew.Bardsley@arm.com void (*reset)(nomali_handle_t h, void *usr); 13110259SAndrew.Bardsley@arm.com } func; 13210905Sandreas.sandberg@arm.com} nomali_callback_t; 13310259SAndrew.Bardsley@arm.com 13410905Sandreas.sandberg@arm.com/** 13510259SAndrew.Bardsley@arm.com * GPU information struct. See nomali_get_info(). 13610259SAndrew.Bardsley@arm.com */ 13710259SAndrew.Bardsley@arm.comtypedef struct { 13810905Sandreas.sandberg@arm.com /** Size (in bytes) of the register window used by the GPU */ 13910259SAndrew.Bardsley@arm.com nomali_size_t reg_size; 14010259SAndrew.Bardsley@arm.com} nomali_info_t; 14110259SAndrew.Bardsley@arm.com 14210259SAndrew.Bardsley@arm.comtypedef uint32_t nomali_api_version_t; 14310905Sandreas.sandberg@arm.com 14410259SAndrew.Bardsley@arm.com/** 14510259SAndrew.Bardsley@arm.com * Current version of the NoMali API 14610259SAndrew.Bardsley@arm.com * 14710905Sandreas.sandberg@arm.com * This version number will increase whenever the API changes. 14810259SAndrew.Bardsley@arm.com * 14910905Sandreas.sandberg@arm.com * @see nomali_api_version() 15010905Sandreas.sandberg@arm.com */ 15110259SAndrew.Bardsley@arm.com#define NOMALI_API_VERSION 0 15210259SAndrew.Bardsley@arm.com 15310259SAndrew.Bardsley@arm.com/** 15410905Sandreas.sandberg@arm.com * Get the version of the API implemented by the library. 15510259SAndrew.Bardsley@arm.com * 15610905Sandreas.sandberg@arm.com * Before instantiating a NoMali model, the driving application need 15710905Sandreas.sandberg@arm.com * to ensure that the library implements a compatible version of the 15810259SAndrew.Bardsley@arm.com * NoMali API. This is done by calling this function and matching the 15910259SAndrew.Bardsley@arm.com * return value with the NOMALI_API_VERSION define. The result of any 16010259SAndrew.Bardsley@arm.com * call to the NoMali library is undefined if there is a miss-match 16110259SAndrew.Bardsley@arm.com * between the two. 16210259SAndrew.Bardsley@arm.com */ 16310259SAndrew.Bardsley@arm.comnomali_api_version_t nomali_api_version(); 16410259SAndrew.Bardsley@arm.com 16510259SAndrew.Bardsley@arm.com/** 16610259SAndrew.Bardsley@arm.com * Create an instance of the NoMali model. 16710259SAndrew.Bardsley@arm.com * 16810259SAndrew.Bardsley@arm.com * @param[out] h Handle of the new NoMali model instance, undefined on 16910259SAndrew.Bardsley@arm.com * error. 17010259SAndrew.Bardsley@arm.com * 17110259SAndrew.Bardsley@arm.com * @param[in] cfg NoMali GPU configuration. 17210259SAndrew.Bardsley@arm.com * 17310259SAndrew.Bardsley@arm.com * @errors 17410259SAndrew.Bardsley@arm.com * @error NOMALI_E_OK on success. 17510259SAndrew.Bardsley@arm.com * @error NOMALI_E_MEMORY if a memory allocation failed. 17610259SAndrew.Bardsley@arm.com * @error NOMALI_E_INVALID if a pointer to an output parameter is 17710259SAndrew.Bardsley@arm.com * invalid. 17810259SAndrew.Bardsley@arm.com */ 17910259SAndrew.Bardsley@arm.comnomali_error_t nomali_create(nomali_handle_t *h, const nomali_config_t *cfg); 18010259SAndrew.Bardsley@arm.com/** 18110259SAndrew.Bardsley@arm.com * Destroy and free resources used by an existing NoMali instance. 18210259SAndrew.Bardsley@arm.com * 18310259SAndrew.Bardsley@arm.com * @param[in] h Model instance handle. 18410259SAndrew.Bardsley@arm.com * 18510259SAndrew.Bardsley@arm.com * @errors 18610259SAndrew.Bardsley@arm.com * @error NOMALI_E_OK on success. 18710259SAndrew.Bardsley@arm.com * @error NOMALI_E_HANDLE if the handle was invalid. 18810259SAndrew.Bardsley@arm.com */ 18910259SAndrew.Bardsley@arm.comnomali_error_t nomali_destroy(nomali_handle_t h); 19010259SAndrew.Bardsley@arm.com 19110407Smitch.hayenga@arm.com 19210946Sandreas.sandberg@arm.com/** 19310946Sandreas.sandberg@arm.com * Get a textual description of an error number. 19410946Sandreas.sandberg@arm.com * 19510946Sandreas.sandberg@arm.com * @param[in] error Error number to resolve. 19610946Sandreas.sandberg@arm.com * 19710946Sandreas.sandberg@arm.com * @return Pointer to a constant, null-terminated, string describing 19810946Sandreas.sandberg@arm.com * an error number. 19910259SAndrew.Bardsley@arm.com */ 20010259SAndrew.Bardsley@arm.comconst char *nomali_errstr(nomali_error_t error); 20110913Sandreas.sandberg@arm.com 20210913Sandreas.sandberg@arm.com/** 20310259SAndrew.Bardsley@arm.com * Setup callbacks from the model. 20410949Sandreas.sandberg@arm.com * 20510949Sandreas.sandberg@arm.com * @param[in] h Model instance handle. 20610949Sandreas.sandberg@arm.com * @param[in] callback Structure describing the new callback to be 20710949Sandreas.sandberg@arm.com * installed. 20810949Sandreas.sandberg@arm.com * 20910259SAndrew.Bardsley@arm.com * @errors 21010259SAndrew.Bardsley@arm.com * @error NOMALI_E_OK on success. 21110259SAndrew.Bardsley@arm.com * @error NOMALI_E_HANDLE if the handle was invalid. 21210259SAndrew.Bardsley@arm.com * @error NOMALI_E_INVALID if the callback type was invalid. 21310913Sandreas.sandberg@arm.com * 21410259SAndrew.Bardsley@arm.com * @see nomali_callback_t 21510913Sandreas.sandberg@arm.com */ 21610913Sandreas.sandberg@arm.comnomali_error_t nomali_set_callback(nomali_handle_t h, 21710259SAndrew.Bardsley@arm.com const nomali_callback_t *callback); 21810913Sandreas.sandberg@arm.com 21910913Sandreas.sandberg@arm.com/** 22010259SAndrew.Bardsley@arm.com * Get information about the hardware simulated by the model. 22110259SAndrew.Bardsley@arm.com * 22210259SAndrew.Bardsley@arm.com * @param[in] h Model instance handle. 22310259SAndrew.Bardsley@arm.com * @param[out] info Structure describing the model. 22410259SAndrew.Bardsley@arm.com * 22510259SAndrew.Bardsley@arm.com * @errors 22610945Sandreas.sandberg@arm.com * @error NOMALI_E_OK on success. 22710259SAndrew.Bardsley@arm.com * @error NOMALI_E_HANDLE if the handle was invalid. 22810259SAndrew.Bardsley@arm.com * @error NOMALI_E_INVALID if info is not pointing to a valid 22910259SAndrew.Bardsley@arm.com * location. 23010259SAndrew.Bardsley@arm.com * 23110259SAndrew.Bardsley@arm.com * @see nomali_info_t 23210259SAndrew.Bardsley@arm.com */ 23310259SAndrew.Bardsley@arm.comnomali_error_t nomali_get_info(nomali_handle_t h, 23410259SAndrew.Bardsley@arm.com nomali_info_t *info); 23510259SAndrew.Bardsley@arm.com 23610259SAndrew.Bardsley@arm.com/** 23710259SAndrew.Bardsley@arm.com * Perform a reset of the device. 23810259SAndrew.Bardsley@arm.com * 23910259SAndrew.Bardsley@arm.com * @param[in] h Model instance handle. 24010259SAndrew.Bardsley@arm.com * 24110259SAndrew.Bardsley@arm.com * @errors 24210259SAndrew.Bardsley@arm.com * @error NOMALI_E_OK on success. 24310259SAndrew.Bardsley@arm.com * @error NOMALI_E_HANDLE if the handle was invalid. 24410259SAndrew.Bardsley@arm.com */ 24510259SAndrew.Bardsley@arm.comnomali_error_t nomali_reset(nomali_handle_t h); 24610259SAndrew.Bardsley@arm.com 24710259SAndrew.Bardsley@arm.com/** 24810259SAndrew.Bardsley@arm.com * Read a register within the device. 24910259SAndrew.Bardsley@arm.com * 25010259SAndrew.Bardsley@arm.com * @param[in] h Model instance handle. 25110259SAndrew.Bardsley@arm.com * @param[out] value Pointer to output. 25210259SAndrew.Bardsley@arm.com * @param[in] addr Address to read. 25310259SAndrew.Bardsley@arm.com * 25410259SAndrew.Bardsley@arm.com * @errors 25510259SAndrew.Bardsley@arm.com * @error NOMALI_E_OK on success. 25610259SAndrew.Bardsley@arm.com * @error NOMALI_E_HANDLE if the handle was invalid. 25710259SAndrew.Bardsley@arm.com * @error NOMALI_E_INVALID if an invalid register was specified or if the 25810259SAndrew.Bardsley@arm.com * pointer to the output location was invalid. 25910259SAndrew.Bardsley@arm.com */ 26010259SAndrew.Bardsley@arm.comnomali_error_t nomali_reg_read(nomali_handle_t h, uint32_t *value, 26110259SAndrew.Bardsley@arm.com nomali_addr_t addr); 26210259SAndrew.Bardsley@arm.com 26310259SAndrew.Bardsley@arm.com/** 26410259SAndrew.Bardsley@arm.com * Write to a register within the device. 26510259SAndrew.Bardsley@arm.com * 26610259SAndrew.Bardsley@arm.com * @param[in] h Model instance handle. 26710259SAndrew.Bardsley@arm.com * @param[in] addr Address to read. 26810259SAndrew.Bardsley@arm.com * @param[in] value Value to write to the register. 26910259SAndrew.Bardsley@arm.com * 27010259SAndrew.Bardsley@arm.com * @errors 27110259SAndrew.Bardsley@arm.com * @error NOMALI_E_OK on success. 27210259SAndrew.Bardsley@arm.com * @error NOMALI_E_HANDLE if the handle was invalid. 27310259SAndrew.Bardsley@arm.com * @error NOMALI_E_INVALID if an invalid register was specified. 27410259SAndrew.Bardsley@arm.com */ 27510259SAndrew.Bardsley@arm.comnomali_error_t nomali_reg_write(nomali_handle_t h, 27610259SAndrew.Bardsley@arm.com nomali_addr_t addr, uint32_t value); 27710407Smitch.hayenga@arm.com 27810259SAndrew.Bardsley@arm.com/** 27910407Smitch.hayenga@arm.com * Read a register without side effects. 28010259SAndrew.Bardsley@arm.com * 28110259SAndrew.Bardsley@arm.com * @param[in] h Model instance handle. 28210259SAndrew.Bardsley@arm.com * @param[out] value Pointer to output. 28310259SAndrew.Bardsley@arm.com * @param[in] addr Address to read. 28410407Smitch.hayenga@arm.com * 28510407Smitch.hayenga@arm.com * @errors 28610259SAndrew.Bardsley@arm.com * @error NOMALI_E_OK on success. 28710259SAndrew.Bardsley@arm.com * @error NOMALI_E_HANDLE if the handle was invalid. 28810407Smitch.hayenga@arm.com * @error NOMALI_E_INVALID if an invalid register was specified or if the 28910407Smitch.hayenga@arm.com * pointer to the output location was invalid. 29010407Smitch.hayenga@arm.com */ 29110259SAndrew.Bardsley@arm.comnomali_error_t nomali_reg_read_raw(nomali_handle_t h, uint32_t *value, 29210259SAndrew.Bardsley@arm.com nomali_addr_t addr); 29310259SAndrew.Bardsley@arm.com 29410259SAndrew.Bardsley@arm.com/** 29510259SAndrew.Bardsley@arm.com * Write to a register without side effects. 29610259SAndrew.Bardsley@arm.com * 29710259SAndrew.Bardsley@arm.com * @param[in] h Model instance handle. 29810259SAndrew.Bardsley@arm.com * @param[in] addr Address to read. 29910259SAndrew.Bardsley@arm.com * @param[in] value Value to write to the register. 30010259SAndrew.Bardsley@arm.com * 30110259SAndrew.Bardsley@arm.com * @errors 30210259SAndrew.Bardsley@arm.com * @error NOMALI_E_OK on success. 30310259SAndrew.Bardsley@arm.com * @error NOMALI_E_HANDLE if the handle was invalid. 30410259SAndrew.Bardsley@arm.com * @error NOMALI_E_INVALID if an invalid register was specified. 30510259SAndrew.Bardsley@arm.com */ 30610259SAndrew.Bardsley@arm.comnomali_error_t nomali_reg_write_raw(nomali_handle_t h, 30710259SAndrew.Bardsley@arm.com nomali_addr_t addr, uint32_t value); 30810259SAndrew.Bardsley@arm.com 30910259SAndrew.Bardsley@arm.com/** 31010259SAndrew.Bardsley@arm.com * Get the state of an interrupt line 31110259SAndrew.Bardsley@arm.com * 31210259SAndrew.Bardsley@arm.com * This function queries the state of one of the GPU's interrupt 31310259SAndrew.Bardsley@arm.com * lines. The state of the interrupt line is returned in 'state', 31410259SAndrew.Bardsley@arm.com * which is 1 if the interrupt is being asserted and 0 otherwise. The 31510259SAndrew.Bardsley@arm.com * value of the state variable is undefined if the function call 31610259SAndrew.Bardsley@arm.com * fails. 31710259SAndrew.Bardsley@arm.com * 31810259SAndrew.Bardsley@arm.com * @param[in] h Model instance handle. 31910259SAndrew.Bardsley@arm.com * @param[out] state Pointer to output, 1 if the interrupt is 32010259SAndrew.Bardsley@arm.com * asserted, 0 otherwise. 32110259SAndrew.Bardsley@arm.com * @param[in] intno Interrupt to query. 32210259SAndrew.Bardsley@arm.com * 32310259SAndrew.Bardsley@arm.com * @errors 32410259SAndrew.Bardsley@arm.com * @error NOMALI_E_OK on success. 32510259SAndrew.Bardsley@arm.com * @error NOMALI_E_HANDLE if the handle was invalid. 32610259SAndrew.Bardsley@arm.com * @error NOMALI_E_INVALID if an invalid interrupt was specified or if 32710259SAndrew.Bardsley@arm.com * pointer to the output location was invalid. 32810259SAndrew.Bardsley@arm.com */ 32910259SAndrew.Bardsley@arm.comnomali_error_t nomali_int_state(nomali_handle_t h, int *state, 33010259SAndrew.Bardsley@arm.com nomali_int_t intno); 33110259SAndrew.Bardsley@arm.com 33210259SAndrew.Bardsley@arm.com#ifdef __cplusplus 33310259SAndrew.Bardsley@arm.com}; 33410259SAndrew.Bardsley@arm.com#endif 33510259SAndrew.Bardsley@arm.com 33610259SAndrew.Bardsley@arm.com#endif /* _LIBNOMALI_NOMALI_HH */ 33710259SAndrew.Bardsley@arm.com