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