1 /* TSI 2023.xmo */ 2 /******************************************************************************* 3 * Copyright (c) 2023 Think Silicon Single Member PC 4 * 5 * Permission is hereby granted, free of charge, to any person obtaining a copy 6 * of this header file and/or associated documentation files to use, copy, 7 * modify, merge, publish, distribute, sublicense, and/or sell copies of the 8 * Materials, and to permit persons to whom the Materials are furnished to do 9 * so, subject to the following conditions: 10 * 11 * The above copyright notice and this permission notice shall be included in 12 * all copies or substantial portions of the Materials. 13 * 14 * MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS 15 * NEMAGFX API. THE UNMODIFIED, NORMATIVE VERSIONS OF THINK-SILICON NEMAGFX 16 * SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT: 17 * https://think-silicon.com/products/software/nemagfx-api 18 * 19 * The software is provided 'as is', without warranty of any kind, express or 20 * implied, including but not limited to the warranties of merchantability, 21 * fitness for a particular purpose and noninfringement. In no event shall 22 * Think Silicon Single Member PC be liable for any claim, damages or other 23 * liability, whether in an action of contract, tort or otherwise, arising 24 * from, out of or in connection with the software or the use or other dealings 25 * in the software. 26 ******************************************************************************/ 27 28 29 #ifndef NEMA_HAL_H__ 30 #define NEMA_HAL_H__ 31 32 #include "nema_sys_defs.h" 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 typedef struct nema_buffer_t_ { 39 int size; /**< Size of buffer */ 40 int fd; /**< File Descriptor of buffer */ 41 void *base_virt; /**< Virtual address of buffer */ 42 uintptr_t base_phys; /**< Physical address of buffer */ 43 } nema_buffer_t; 44 45 /** \brief Initialize system. Implementor defined. Called in nema_init() 46 * 47 * \param void 48 * \return 0 if no errors occurred 49 * \see nema_init() 50 * 51 */ 52 int32_t nema_sys_init(void); 53 54 55 /** \brief Wait for interrupt from the GPU 56 * 57 * \param void 58 * \return 0 on success 59 * 60 */ 61 int nema_wait_irq(void); 62 63 /** \brief Wait for a Command List to finish 64 * 65 * \param cl_id Command List ID 66 * \return 0 on success 67 * 68 */ 69 int nema_wait_irq_cl(int cl_id); 70 71 /** \brief Wait for a Breakpoint 72 * 73 * \param cl_id Breakpoint ID 74 * \return 0 on success 75 * 76 */ 77 int nema_wait_irq_brk(int brk_id); 78 79 /** \brief Read Hardware register 80 * 81 * \param reg Register to read 82 * \return Value read from the register 83 * \see nema_reg_write 84 * 85 */ 86 uint32_t nema_reg_read(uint32_t reg); 87 88 /** \brief Write Hardware Register 89 * 90 * \param reg Register to write 91 * \param value Value to be written 92 * \return void() 93 * \see nema_reg_read() 94 * 95 */ 96 void nema_reg_write(uint32_t reg, uint32_t value); 97 98 /** \brief Create memory buffer 99 * 100 * \param size Size of buffer in bytes 101 * \return nema_buffer_t struct 102 * 103 */ 104 nema_buffer_t nema_buffer_create(int size); 105 106 /** \brief Create memory buffer at a specific pool 107 * 108 * \param pool ID of the desired memory pool 109 * \param size Size of buffer in bytes 110 * \return nema_buffer_t struct 111 * 112 */ 113 nema_buffer_t nema_buffer_create_pool(int pool, int size); 114 115 /** \brief Maps buffer 116 * 117 * \param bo Pointer to buffer struct 118 * \return Virtual pointer of the buffer (same as in bo->base_virt) 119 * 120 */ 121 void *nema_buffer_map(nema_buffer_t *bo); 122 123 /** \brief Unmaps buffer 124 * 125 * \param bo Pointer to buffer struct 126 * \return void 127 * 128 */ 129 void nema_buffer_unmap(nema_buffer_t *bo); 130 131 /** \brief Destroy/deallocate buffer 132 * 133 * \param bo Pointer to buffer struct 134 * \return void 135 * 136 */ 137 void nema_buffer_destroy(nema_buffer_t *bo); 138 139 /** \brief Get physical (GPU) base address of a given buffer 140 * 141 * \param bo Pointer to buffer struct 142 * \return Physical base address of a given buffer 143 * 144 */ 145 uintptr_t nema_buffer_phys(nema_buffer_t *bo); 146 147 /** \brief Write-back buffer from cache to main memory 148 * 149 * \param bo Pointer to buffer struct 150 * \return void 151 * 152 */ 153 void nema_buffer_flush(nema_buffer_t * bo); 154 155 /** \brief Allocate memory for CPU to use (typically, standard malloc() is called) 156 * 157 * \param size Size in bytes 158 * \return Pointer to allocated memory (virtual) 159 * \see nema_host_free() 160 * 161 */ 162 void *nema_host_malloc(size_t size); 163 164 /** \brief Free memory previously allocated with nema_host_malloc() 165 * 166 * \param ptr Pointer to allocated memory (virtual) 167 * \return void 168 * \see nema_host_malloc() 169 * 170 */ 171 void nema_host_free(void *ptr ); 172 173 /** \private */ 174 typedef struct nema_ringbuffer_t_ { 175 nema_buffer_t bo; 176 int offset; //number of 32-bit entries 177 int last_submission_id; 178 } nema_ringbuffer_t; 179 180 181 /** \brief Initialize Ring Buffer. Should be called from inside nema_sys_init(). 182 * This is a private function, the user should never call it. 183 * 184 * \param *rb Pointer to nema_ring_buffer_t struct 185 * \param reset Resets the Ring Buffer if non-zero 186 * \return Negative number on error 187 * \see nema_sys_init() 188 * 189 */ 190 /** \private */ 191 int nema_rb_init(nema_ringbuffer_t *rb, int reset); 192 193 #define MUTEX_RB 0 194 #define MUTEX_MALLOC 1 195 #define MUTEX_FLUSH 2 196 #define MUTEX_MAX 2 197 198 /** \brief Mutex Lock for multiple processes/threads 199 * 200 * \param MUTEX_RB or MUTEX_MALLOC 201 * \return int 202 * 203 */ 204 int nema_mutex_lock(int mutex_id); 205 206 /** \brief Mutex Unlock for multiple processes/threads 207 * 208 * \param MUTEX_RB or MUTEX_MALLOC 209 * \return int 210 * 211 */ 212 int nema_mutex_unlock(int mutex_id); 213 214 #ifdef __cplusplus 215 } 216 #endif 217 218 #endif 219
