2 * Copyright (C) 2010-2016 ARM Limited. All rights reserved.
4 * This program is free software and is provided to you under the terms of the GNU General Public License version 2
5 * as published by the Free Software Foundation, and any use by you of this program is subject to the terms of such GNU licence.
7 * A copy of the licence is included with the program, and can also be obtained from Free Software
8 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
12 * @file mali_osk_types.h
13 * Defines types of the OS abstraction layer for the kernel device driver (OSK)
16 #ifndef __MALI_OSK_TYPES_H__
17 #define __MALI_OSK_TYPES_H__
24 * @addtogroup uddapi Unified Device Driver (UDD) APIs
30 * @addtogroup oskapi UDD OS Abstraction for Kernel-side (OSK) APIs
35 /** @defgroup _mali_osk_miscellaneous OSK Miscellaneous functions, constants and types
38 /* Define integer types used by OSK. Note: these currently clash with Linux so we only define them if not defined already */
40 typedef unsigned char u8;
41 typedef signed char s8;
42 typedef unsigned short u16;
43 typedef signed short s16;
44 typedef unsigned int u32;
45 typedef signed int s32;
46 typedef unsigned long long u64;
47 #define BITS_PER_LONG (sizeof(long)*8)
49 /* Ensure Linux types u32, etc. are defined */
50 #include <linux/types.h>
53 /** @brief Mali Boolean type which uses MALI_TRUE and MALI_FALSE
55 typedef unsigned long mali_bool;
58 #define MALI_TRUE ((mali_bool)1)
62 #define MALI_FALSE ((mali_bool)0)
65 #define MALI_HW_CORE_NO_COUNTER ((u32)-1)
68 #define MALI_S32_MAX 0x7fffffff
71 * @brief OSK Error codes
73 * Each OS may use its own set of error codes, and may require that the
74 * User/Kernel interface take certain error code. This means that the common
75 * error codes need to be sufficiently rich to pass the correct error code
76 * thorugh from the OSK to U/K layer, across all OSs.
78 * The result is that some error codes will appear redundant on some OSs.
79 * Under all OSs, the OSK layer must translate native OS error codes to
80 * _mali_osk_errcode_t codes. Similarly, the U/K layer must translate from
81 * _mali_osk_errcode_t codes to native OS error codes.
84 _MALI_OSK_ERR_OK = 0, /**< Success. */
85 _MALI_OSK_ERR_FAULT = -1, /**< General non-success */
86 _MALI_OSK_ERR_INVALID_FUNC = -2, /**< Invalid function requested through User/Kernel interface (e.g. bad IOCTL number) */
87 _MALI_OSK_ERR_INVALID_ARGS = -3, /**< Invalid arguments passed through User/Kernel interface */
88 _MALI_OSK_ERR_NOMEM = -4, /**< Insufficient memory */
89 _MALI_OSK_ERR_TIMEOUT = -5, /**< Timeout occurred */
90 _MALI_OSK_ERR_RESTARTSYSCALL = -6, /**< Special: On certain OSs, must report when an interruptable mutex is interrupted. Ignore otherwise. */
91 _MALI_OSK_ERR_ITEM_NOT_FOUND = -7, /**< Table Lookup failed */
92 _MALI_OSK_ERR_BUSY = -8, /**< Device/operation is busy. Try again later */
93 _MALI_OSK_ERR_UNSUPPORTED = -9, /**< Optional part of the interface used, and is unsupported */
94 } _mali_osk_errcode_t;
96 /** @} */ /* end group _mali_osk_miscellaneous */
98 /** @defgroup _mali_osk_wq OSK work queues
101 /** @brief Private type for work objects */
102 typedef struct _mali_osk_wq_work_s _mali_osk_wq_work_t;
103 typedef struct _mali_osk_wq_delayed_work_s _mali_osk_wq_delayed_work_t;
105 /** @brief Work queue handler function
107 * This function type is called when the work is scheduled by the work queue,
108 * e.g. as an IRQ bottom-half handler.
110 * Refer to \ref _mali_osk_wq_schedule_work() for more information on the
111 * work-queue and work handlers.
113 * @param arg resource-specific data
115 typedef void (*_mali_osk_wq_work_handler_t)(void *arg);
117 /* @} */ /* end group _mali_osk_wq */
119 /** @defgroup _mali_osk_irq OSK IRQ handling
122 /** @brief Private type for IRQ handling objects */
123 typedef struct _mali_osk_irq_t_struct _mali_osk_irq_t;
125 /** @brief Optional function to trigger an irq from a resource
127 * This function is implemented by the common layer to allow probing of a resource's IRQ.
128 * @param arg resource-specific data */
129 typedef void (*_mali_osk_irq_trigger_t)(void *arg);
131 /** @brief Optional function to acknowledge an irq from a resource
133 * This function is implemented by the common layer to allow probing of a resource's IRQ.
134 * @param arg resource-specific data
135 * @return _MALI_OSK_ERR_OK if the IRQ was successful, or a suitable _mali_osk_errcode_t on failure. */
136 typedef _mali_osk_errcode_t (*_mali_osk_irq_ack_t)(void *arg);
138 /** @brief IRQ 'upper-half' handler callback.
140 * This function is implemented by the common layer to do the initial handling of a
141 * resource's IRQ. This maps on to the concept of an ISR that does the minimum
142 * work necessary before handing off to an IST.
144 * The communication of the resource-specific data from the ISR to the IST is
145 * handled by the OSK implementation.
147 * On most systems, the IRQ upper-half handler executes in IRQ context.
148 * Therefore, the system may have restrictions about what can be done in this
151 * If an IRQ upper-half handler requires more work to be done than can be
152 * acheived in an IRQ context, then it may defer the work with
153 * _mali_osk_wq_schedule_work(). Refer to \ref _mali_osk_wq_create_work() for
156 * @param arg resource-specific data
157 * @return _MALI_OSK_ERR_OK if the IRQ was correctly handled, or a suitable
158 * _mali_osk_errcode_t otherwise.
160 typedef _mali_osk_errcode_t (*_mali_osk_irq_uhandler_t)(void *arg);
163 /** @} */ /* end group _mali_osk_irq */
166 /** @defgroup _mali_osk_atomic OSK Atomic counters
169 /** @brief Public type of atomic counters
171 * This is public for allocation on stack. On systems that support it, this is just a single 32-bit value.
172 * On others, it could be encapsulating an object stored elsewhere.
174 * Regardless of implementation, the \ref _mali_osk_atomic functions \b must be used
175 * for all accesses to the variable's value, even if atomicity is not required.
176 * Do not access u.val or u.obj directly.
183 } _mali_osk_atomic_t;
184 /** @} */ /* end group _mali_osk_atomic */
187 /** @defgroup _mali_osk_lock OSK Mutual Exclusion Locks
191 /** @brief OSK Mutual Exclusion Lock ordered list
193 * This lists the various types of locks in the system and is used to check
194 * that locks are taken in the correct order.
196 * - Holding more than one lock of the same order at the same time is not
198 * - Taking a lock of a lower order than the highest-order lock currently held
205 /* _||_ taken in _||_ */
209 _MALI_OSK_LOCK_ORDER_FIRST = 0,
211 _MALI_OSK_LOCK_ORDER_SESSIONS,
212 _MALI_OSK_LOCK_ORDER_MEM_SESSION,
213 _MALI_OSK_LOCK_ORDER_MEM_INFO,
214 _MALI_OSK_LOCK_ORDER_MEM_PT_CACHE,
215 _MALI_OSK_LOCK_ORDER_DESCRIPTOR_MAP,
216 _MALI_OSK_LOCK_ORDER_PM_EXECUTION,
217 _MALI_OSK_LOCK_ORDER_EXECUTOR,
218 _MALI_OSK_LOCK_ORDER_TIMELINE_SYSTEM,
219 _MALI_OSK_LOCK_ORDER_SCHEDULER,
220 _MALI_OSK_LOCK_ORDER_SCHEDULER_DEFERRED,
221 _MALI_OSK_LOCK_ORDER_PROFILING,
222 _MALI_OSK_LOCK_ORDER_L2,
223 _MALI_OSK_LOCK_ORDER_L2_COMMAND,
224 _MALI_OSK_LOCK_ORDER_UTILIZATION,
225 _MALI_OSK_LOCK_ORDER_SESSION_PENDING_JOBS,
226 _MALI_OSK_LOCK_ORDER_PM_STATE,
228 _MALI_OSK_LOCK_ORDER_LAST,
229 } _mali_osk_lock_order_t;
232 /** @brief OSK Mutual Exclusion Lock flags type
234 * - Any lock can use the order parameter.
237 _MALI_OSK_LOCKFLAG_UNORDERED = 0x1, /**< Indicate that the order of this lock should not be checked */
238 _MALI_OSK_LOCKFLAG_ORDERED = 0x2,
239 /** @enum _mali_osk_lock_flags_t
241 * Flags from 0x10000--0x80000000 are RESERVED for User-mode */
243 } _mali_osk_lock_flags_t;
245 /** @brief Mutual Exclusion Lock Mode Optimization hint
247 * The lock mode is used to implement the read/write locking of locks when we call
248 * functions _mali_osk_mutex_rw_init/wait/signal/term/. In this case, the RO mode can
249 * be used to allow multiple concurrent readers, but no writers. The RW mode is used for
250 * writers, and so will wait for all readers to release the lock (if any present).
251 * Further readers and writers will wait until the writer releases the lock.
253 * The mode is purely an optimization hint: for example, it is permissible for
254 * all locks to behave in RW mode, regardless of that supplied.
256 * It is an error to attempt to use locks in anything other that RW mode when
257 * call functions _mali_osk_mutex_rw_wait/signal().
261 _MALI_OSK_LOCKMODE_UNDEF = -1, /**< Undefined lock mode. For internal use only */
262 _MALI_OSK_LOCKMODE_RW = 0x0, /**< Read-write mode, default. All readers and writers are mutually-exclusive */
263 _MALI_OSK_LOCKMODE_RO, /**< Read-only mode, to support multiple concurrent readers, but mutual exclusion in the presence of writers. */
264 /** @enum _mali_osk_lock_mode_t
266 * Lock modes 0x40--0x7F are RESERVED for User-mode */
267 } _mali_osk_lock_mode_t;
269 /** @brief Private types for Mutual Exclusion lock objects */
270 typedef struct _mali_osk_lock_debug_s _mali_osk_lock_debug_t;
271 typedef struct _mali_osk_spinlock_s _mali_osk_spinlock_t;
272 typedef struct _mali_osk_spinlock_irq_s _mali_osk_spinlock_irq_t;
273 typedef struct _mali_osk_mutex_s _mali_osk_mutex_t;
274 typedef struct _mali_osk_mutex_rw_s _mali_osk_mutex_rw_t;
276 /** @} */ /* end group _mali_osk_lock */
278 /** @defgroup _mali_osk_low_level_memory OSK Low-level Memory Operations
282 * @brief Private data type for use in IO accesses to/from devices.
284 * This represents some range that is accessible from the device. Examples
286 * - Device Registers, which could be readable and/or writeable.
287 * - Memory that the device has access to, for storing configuration structures.
289 * Access to this range must be made through the _mali_osk_mem_ioread32() and
290 * _mali_osk_mem_iowrite32() functions.
292 typedef struct _mali_io_address *mali_io_address;
294 /** @defgroup _MALI_OSK_CPU_PAGE CPU Physical page size macros.
296 * The order of the page size is supplied for
297 * ease of use by algorithms that might require it, since it is easier to know
298 * it ahead of time rather than calculating it.
300 * The Mali Page Mask macro masks off the lower bits of a physical address to
301 * give the start address of the page for that physical address.
303 * @note The Mali device driver code is designed for systems with 4KB page size.
304 * Changing these macros will not make the entire Mali device driver work with
305 * page sizes other than 4KB.
307 * @note The CPU Physical Page Size has been assumed to be the same as the Mali
308 * Physical Page Size.
313 /** CPU Page Order, as log to base 2 of the Page size. @see _MALI_OSK_CPU_PAGE_SIZE */
314 #define _MALI_OSK_CPU_PAGE_ORDER ((u32)12)
315 /** CPU Page Size, in bytes. */
316 #define _MALI_OSK_CPU_PAGE_SIZE (((u32)1) << (_MALI_OSK_CPU_PAGE_ORDER))
317 /** CPU Page Mask, which masks off the offset within a page */
318 #define _MALI_OSK_CPU_PAGE_MASK (~((((u32)1) << (_MALI_OSK_CPU_PAGE_ORDER)) - ((u32)1)))
319 /** @} */ /* end of group _MALI_OSK_CPU_PAGE */
321 /** @defgroup _MALI_OSK_MALI_PAGE Mali Physical Page size macros
323 * Mali Physical page size macros. The order of the page size is supplied for
324 * ease of use by algorithms that might require it, since it is easier to know
325 * it ahead of time rather than calculating it.
327 * The Mali Page Mask macro masks off the lower bits of a physical address to
328 * give the start address of the page for that physical address.
330 * @note The Mali device driver code is designed for systems with 4KB page size.
331 * Changing these macros will not make the entire Mali device driver work with
332 * page sizes other than 4KB.
334 * @note The Mali Physical Page Size has been assumed to be the same as the CPU
335 * Physical Page Size.
340 /** Mali Page Order, as log to base 2 of the Page size. @see _MALI_OSK_MALI_PAGE_SIZE */
341 #define _MALI_OSK_MALI_PAGE_ORDER PAGE_SHIFT
342 /** Mali Page Size, in bytes. */
343 #define _MALI_OSK_MALI_PAGE_SIZE PAGE_SIZE
344 /** Mali Page Mask, which masks off the offset within a page */
345 #define _MALI_OSK_MALI_PAGE_MASK PAGE_MASK
346 /** @} */ /* end of group _MALI_OSK_MALI_PAGE*/
348 /** @brief flags for mapping a user-accessible memory range
350 * Where a function with prefix '_mali_osk_mem_mapregion' accepts flags as one
351 * of the function parameters, it will use one of these. These allow per-page
352 * control over mappings. Compare with the mali_memory_allocation_flag type,
353 * which acts over an entire range
355 * These may be OR'd together with bitwise OR (|), but must be cast back into
356 * the type after OR'ing.
359 _MALI_OSK_MEM_MAPREGION_FLAG_OS_ALLOCATED_PHYSADDR = 0x1, /**< Physical address is OS Allocated */
360 } _mali_osk_mem_mapregion_flags_t;
361 /** @} */ /* end group _mali_osk_low_level_memory */
363 /** @defgroup _mali_osk_notification OSK Notification Queues
366 /** @brief Private type for notification queue objects */
367 typedef struct _mali_osk_notification_queue_t_struct _mali_osk_notification_queue_t;
369 /** @brief Public notification data object type */
370 typedef struct _mali_osk_notification_t_struct {
371 u32 notification_type; /**< The notification type */
372 u32 result_buffer_size; /**< Size of the result buffer to copy to user space */
373 void *result_buffer; /**< Buffer containing any type specific data */
374 } _mali_osk_notification_t;
376 /** @} */ /* end group _mali_osk_notification */
379 /** @defgroup _mali_osk_timer OSK Timer Callbacks
382 /** @brief Function to call when a timer expires
384 * When a timer expires, this function is called. Note that on many systems,
385 * a timer callback will be executed in IRQ context. Therefore, restrictions
386 * may apply on what can be done inside the timer callback.
388 * If a timer requires more work to be done than can be acheived in an IRQ
389 * context, then it may defer the work with a work-queue. For example, it may
390 * use \ref _mali_osk_wq_schedule_work() to make use of a bottom-half handler
391 * to carry out the remaining work.
393 * Stopping the timer with \ref _mali_osk_timer_del() blocks on compeletion of
394 * the callback. Therefore, the callback may not obtain any mutexes also held
395 * by any callers of _mali_osk_timer_del(). Otherwise, a deadlock may occur.
397 * @param arg Function-specific data */
398 typedef void (*_mali_osk_timer_callback_t)(void *arg);
400 /** @brief Private type for Timer Callback Objects */
401 typedef struct _mali_osk_timer_t_struct _mali_osk_timer_t;
402 /** @} */ /* end group _mali_osk_timer */
405 /** @addtogroup _mali_osk_list OSK Doubly-Linked Circular Lists
408 /** @brief Public List objects.
410 * To use, add a _mali_osk_list_t member to the structure that may become part
411 * of a list. When traversing the _mali_osk_list_t objects, use the
412 * _MALI_OSK_CONTAINER_OF() macro to recover the structure from its
413 *_mali_osk_list_t member
415 * Each structure may have multiple _mali_osk_list_t members, so that the
416 * structure is part of multiple lists. When traversing lists, ensure that the
417 * correct _mali_osk_list_t member is used, because type-checking will be
418 * lost by the compiler.
420 typedef struct _mali_osk_list_s {
421 struct _mali_osk_list_s *next;
422 struct _mali_osk_list_s *prev;
424 /** @} */ /* end group _mali_osk_list */
426 /** @addtogroup _mali_osk_miscellaneous
429 /** @brief resource description struct
431 * Platform independent representation of a Mali HW resource
433 typedef struct _mali_osk_resource {
434 const char *description; /**< short description of the resource */
435 uintptr_t base; /**< Physical base address of the resource, as seen by Mali resources. */
436 const char *irq_name; /**< Name of irq belong to this resource */
437 u32 irq; /**< IRQ number delivered to the CPU, or -1 to tell the driver to probe for it (if possible) */
438 } _mali_osk_resource_t;
439 /** @} */ /* end group _mali_osk_miscellaneous */
441 /** @defgroup _mali_osk_wait_queue OSK Wait Queue functionality
443 /** @brief Private type for wait queue objects */
444 typedef struct _mali_osk_wait_queue_t_struct _mali_osk_wait_queue_t;
445 /** @} */ /* end group _mali_osk_wait_queue */
447 /** @} */ /* end group osuapi */
449 /** @} */ /* end group uddapi */
451 /** @brief Mali print ctx type which uses seq_file
453 typedef struct seq_file _mali_osk_print_ctx;
455 #define _MALI_OSK_BITMAP_INVALIDATE_INDEX -1
457 typedef struct _mali_osk_bitmap {
462 _mali_osk_spinlock_t *lock;
463 unsigned long *table;
464 } _mali_osk_bitmap_t;
471 #endif /* __MALI_OSK_TYPES_H__ */