2 * This confidential and proprietary software may be used only as
3 * authorised by a licensing agreement from ARM Limited
4 * (C) COPYRIGHT 2008-2013 ARM Limited
6 * The entire notice above must be reproduced on all authorised
7 * copies and copies may only be made to the extent permitted
8 * by a licensing agreement from ARM Limited.
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 * @brief OSK Error codes
70 * Each OS may use its own set of error codes, and may require that the
71 * User/Kernel interface take certain error code. This means that the common
72 * error codes need to be sufficiently rich to pass the correct error code
73 * thorugh from the OSK to U/K layer, across all OSs.
75 * The result is that some error codes will appear redundant on some OSs.
76 * Under all OSs, the OSK layer must translate native OS error codes to
77 * _mali_osk_errcode_t codes. Similarly, the U/K layer must translate from
78 * _mali_osk_errcode_t codes to native OS error codes.
81 _MALI_OSK_ERR_OK
= 0, /**< Success. */
82 _MALI_OSK_ERR_FAULT
= -1, /**< General non-success */
83 _MALI_OSK_ERR_INVALID_FUNC
= -2, /**< Invalid function requested through User/Kernel interface (e.g. bad IOCTL number) */
84 _MALI_OSK_ERR_INVALID_ARGS
= -3, /**< Invalid arguments passed through User/Kernel interface */
85 _MALI_OSK_ERR_NOMEM
= -4, /**< Insufficient memory */
86 _MALI_OSK_ERR_TIMEOUT
= -5, /**< Timeout occurred */
87 _MALI_OSK_ERR_RESTARTSYSCALL
= -6, /**< Special: On certain OSs, must report when an interruptable mutex is interrupted. Ignore otherwise. */
88 _MALI_OSK_ERR_ITEM_NOT_FOUND
= -7, /**< Table Lookup failed */
89 _MALI_OSK_ERR_BUSY
= -8, /**< Device/operation is busy. Try again later */
90 _MALI_OSK_ERR_UNSUPPORTED
= -9, /**< Optional part of the interface used, and is unsupported */
91 } _mali_osk_errcode_t
;
93 /** @} */ /* end group _mali_osk_miscellaneous */
95 /** @defgroup _mali_osk_wq OSK work queues
98 /** @brief Private type for work objects */
99 typedef struct _mali_osk_wq_work_s _mali_osk_wq_work_t
;
100 typedef struct _mali_osk_wq_delayed_work_s _mali_osk_wq_delayed_work_t
;
102 /** @brief Work queue handler function
104 * This function type is called when the work is scheduled by the work queue,
105 * e.g. as an IRQ bottom-half handler.
107 * Refer to \ref _mali_osk_wq_schedule_work() for more information on the
108 * work-queue and work handlers.
110 * @param arg resource-specific data
112 typedef void (*_mali_osk_wq_work_handler_t
)( void * arg
);
114 /* @} */ /* end group _mali_osk_wq */
116 /** @defgroup _mali_osk_irq OSK IRQ handling
119 /** @brief Private type for IRQ handling objects */
120 typedef struct _mali_osk_irq_t_struct _mali_osk_irq_t
;
122 /** @brief Optional function to trigger an irq from a resource
124 * This function is implemented by the common layer to allow probing of a resource's IRQ.
125 * @param arg resource-specific data */
126 typedef void (*_mali_osk_irq_trigger_t
)( void * arg
);
128 /** @brief Optional function to acknowledge an irq from a resource
130 * This function is implemented by the common layer to allow probing of a resource's IRQ.
131 * @param arg resource-specific data
132 * @return _MALI_OSK_ERR_OK if the IRQ was successful, or a suitable _mali_osk_errcode_t on failure. */
133 typedef _mali_osk_errcode_t (*_mali_osk_irq_ack_t
)( void * arg
);
135 /** @brief IRQ 'upper-half' handler callback.
137 * This function is implemented by the common layer to do the initial handling of a
138 * resource's IRQ. This maps on to the concept of an ISR that does the minimum
139 * work necessary before handing off to an IST.
141 * The communication of the resource-specific data from the ISR to the IST is
142 * handled by the OSK implementation.
144 * On most systems, the IRQ upper-half handler executes in IRQ context.
145 * Therefore, the system may have restrictions about what can be done in this
148 * If an IRQ upper-half handler requires more work to be done than can be
149 * acheived in an IRQ context, then it may defer the work with
150 * _mali_osk_wq_schedule_work(). Refer to \ref _mali_osk_wq_create_work() for
153 * @param arg resource-specific data
154 * @return _MALI_OSK_ERR_OK if the IRQ was correctly handled, or a suitable
155 * _mali_osk_errcode_t otherwise.
157 typedef _mali_osk_errcode_t (*_mali_osk_irq_uhandler_t
)( void * arg
);
160 /** @} */ /* end group _mali_osk_irq */
163 /** @defgroup _mali_osk_atomic OSK Atomic counters
166 /** @brief Public type of atomic counters
168 * This is public for allocation on stack. On systems that support it, this is just a single 32-bit value.
169 * On others, it could be encapsulating an object stored elsewhere.
171 * Regardless of implementation, the \ref _mali_osk_atomic functions \b must be used
172 * for all accesses to the variable's value, even if atomicity is not required.
173 * Do not access u.val or u.obj directly.
180 } _mali_osk_atomic_t
;
181 /** @} */ /* end group _mali_osk_atomic */
184 /** @defgroup _mali_osk_lock OSK Mutual Exclusion Locks
188 /** @brief OSK Mutual Exclusion Lock ordered list
190 * This lists the various types of locks in the system and is used to check
191 * that locks are taken in the correct order.
193 * - Holding more than one lock of the same order at the same time is not
195 * - Taking a lock of a lower order than the highest-order lock currently held
202 /* _||_ taken in _||_ */
206 _MALI_OSK_LOCK_ORDER_FIRST
= 0,
208 _MALI_OSK_LOCK_ORDER_SESSIONS
,
209 _MALI_OSK_LOCK_ORDER_MEM_SESSION
,
210 _MALI_OSK_LOCK_ORDER_MEM_INFO
,
211 _MALI_OSK_LOCK_ORDER_MEM_PT_CACHE
,
212 _MALI_OSK_LOCK_ORDER_DESCRIPTOR_MAP
,
213 _MALI_OSK_LOCK_ORDER_GROUP_VIRTUAL
,
214 _MALI_OSK_LOCK_ORDER_GROUP
,
215 _MALI_OSK_LOCK_ORDER_TIMELINE_SYSTEM
,
216 _MALI_OSK_LOCK_ORDER_SCHEDULER
,
217 _MALI_OSK_LOCK_ORDER_SCHEDULER_DEFERRED
,
218 _MALI_OSK_LOCK_ORDER_PM_CORE_STATE
,
219 _MALI_OSK_LOCK_ORDER_L2_COMMAND
,
220 _MALI_OSK_LOCK_ORDER_DMA_COMMAND
,
221 _MALI_OSK_LOCK_ORDER_PROFILING
,
222 _MALI_OSK_LOCK_ORDER_L2_COUNTER
,
223 _MALI_OSK_LOCK_ORDER_UTILIZATION
,
224 _MALI_OSK_LOCK_ORDER_PM_EXECUTE
,
225 _MALI_OSK_LOCK_ORDER_SESSION_PENDING_JOBS
,
226 _MALI_OSK_LOCK_ORDER_PM_DOMAIN
,
227 _MALI_OSK_LOCK_ORDER_PMU
,
229 _MALI_OSK_LOCK_ORDER_LAST
,
230 } _mali_osk_lock_order_t
;
233 /** @brief OSK Mutual Exclusion Lock flags type
235 * - Any lock can use the order parameter.
238 _MALI_OSK_LOCKFLAG_UNORDERED
= 0x1, /**< Indicate that the order of this lock should not be checked */
239 _MALI_OSK_LOCKFLAG_ORDERED
= 0x2,
240 /** @enum _mali_osk_lock_flags_t
242 * Flags from 0x10000--0x80000000 are RESERVED for User-mode */
244 } _mali_osk_lock_flags_t
;
246 /** @brief Mutual Exclusion Lock Mode Optimization hint
248 * The lock mode is used to implement the read/write locking of locks when we call
249 * functions _mali_osk_mutex_rw_init/wait/signal/term/. In this case, the RO mode can
250 * be used to allow multiple concurrent readers, but no writers. The RW mode is used for
251 * writers, and so will wait for all readers to release the lock (if any present).
252 * Further readers and writers will wait until the writer releases the lock.
254 * The mode is purely an optimization hint: for example, it is permissible for
255 * all locks to behave in RW mode, regardless of that supplied.
257 * It is an error to attempt to use locks in anything other that RW mode when
258 * call functions _mali_osk_mutex_rw_wait/signal().
262 _MALI_OSK_LOCKMODE_UNDEF
= -1, /**< Undefined lock mode. For internal use only */
263 _MALI_OSK_LOCKMODE_RW
= 0x0, /**< Read-write mode, default. All readers and writers are mutually-exclusive */
264 _MALI_OSK_LOCKMODE_RO
, /**< Read-only mode, to support multiple concurrent readers, but mutual exclusion in the presence of writers. */
265 /** @enum _mali_osk_lock_mode_t
267 * Lock modes 0x40--0x7F are RESERVED for User-mode */
268 } _mali_osk_lock_mode_t
;
270 /** @brief Private types for Mutual Exclusion lock objects */
271 typedef struct _mali_osk_lock_debug_s _mali_osk_lock_debug_t
;
272 typedef struct _mali_osk_spinlock_s _mali_osk_spinlock_t
;
273 typedef struct _mali_osk_spinlock_irq_s _mali_osk_spinlock_irq_t
;
274 typedef struct _mali_osk_mutex_s _mali_osk_mutex_t
;
275 typedef struct _mali_osk_mutex_rw_s _mali_osk_mutex_rw_t
;
277 /** @} */ /* end group _mali_osk_lock */
279 /** @defgroup _mali_osk_low_level_memory OSK Low-level Memory Operations
283 * @brief Private data type for use in IO accesses to/from devices.
285 * This represents some range that is accessible from the device. Examples
287 * - Device Registers, which could be readable and/or writeable.
288 * - Memory that the device has access to, for storing configuration structures.
290 * Access to this range must be made through the _mali_osk_mem_ioread32() and
291 * _mali_osk_mem_iowrite32() functions.
293 typedef struct _mali_io_address
* mali_io_address
;
295 /** @defgroup _MALI_OSK_CPU_PAGE CPU Physical page size macros.
297 * The order of the page size is supplied for
298 * ease of use by algorithms that might require it, since it is easier to know
299 * it ahead of time rather than calculating it.
301 * The Mali Page Mask macro masks off the lower bits of a physical address to
302 * give the start address of the page for that physical address.
304 * @note The Mali device driver code is designed for systems with 4KB page size.
305 * Changing these macros will not make the entire Mali device driver work with
306 * page sizes other than 4KB.
308 * @note The CPU Physical Page Size has been assumed to be the same as the Mali
309 * Physical Page Size.
314 /** CPU Page Order, as log to base 2 of the Page size. @see _MALI_OSK_CPU_PAGE_SIZE */
315 #define _MALI_OSK_CPU_PAGE_ORDER ((u32)12)
316 /** CPU Page Size, in bytes. */
317 #define _MALI_OSK_CPU_PAGE_SIZE (((u32)1) << (_MALI_OSK_CPU_PAGE_ORDER))
318 /** CPU Page Mask, which masks off the offset within a page */
319 #define _MALI_OSK_CPU_PAGE_MASK (~((((u32)1) << (_MALI_OSK_CPU_PAGE_ORDER)) - ((u32)1)))
320 /** @} */ /* end of group _MALI_OSK_CPU_PAGE */
322 /** @defgroup _MALI_OSK_MALI_PAGE Mali Physical Page size macros
324 * Mali Physical page size macros. The order of the page size is supplied for
325 * ease of use by algorithms that might require it, since it is easier to know
326 * it ahead of time rather than calculating it.
328 * The Mali Page Mask macro masks off the lower bits of a physical address to
329 * give the start address of the page for that physical address.
331 * @note The Mali device driver code is designed for systems with 4KB page size.
332 * Changing these macros will not make the entire Mali device driver work with
333 * page sizes other than 4KB.
335 * @note The Mali Physical Page Size has been assumed to be the same as the CPU
336 * Physical Page Size.
341 /** Mali Page Order, as log to base 2 of the Page size. @see _MALI_OSK_MALI_PAGE_SIZE */
342 #define _MALI_OSK_MALI_PAGE_ORDER ((u32)12)
343 /** Mali Page Size, in bytes. */
344 #define _MALI_OSK_MALI_PAGE_SIZE (((u32)1) << (_MALI_OSK_MALI_PAGE_ORDER))
345 /** Mali Page Mask, which masks off the offset within a page */
346 #define _MALI_OSK_MALI_PAGE_MASK (~((((u32)1) << (_MALI_OSK_MALI_PAGE_ORDER)) - ((u32)1)))
347 /** @} */ /* end of group _MALI_OSK_MALI_PAGE*/
349 /** @brief flags for mapping a user-accessible memory range
351 * Where a function with prefix '_mali_osk_mem_mapregion' accepts flags as one
352 * of the function parameters, it will use one of these. These allow per-page
353 * control over mappings. Compare with the mali_memory_allocation_flag type,
354 * which acts over an entire range
356 * These may be OR'd together with bitwise OR (|), but must be cast back into
357 * the type after OR'ing.
360 _MALI_OSK_MEM_MAPREGION_FLAG_OS_ALLOCATED_PHYSADDR
= 0x1, /**< Physical address is OS Allocated */
361 } _mali_osk_mem_mapregion_flags_t
;
362 /** @} */ /* end group _mali_osk_low_level_memory */
364 /** @defgroup _mali_osk_notification OSK Notification Queues
367 /** @brief Private type for notification queue objects */
368 typedef struct _mali_osk_notification_queue_t_struct _mali_osk_notification_queue_t
;
370 /** @brief Public notification data object type */
371 typedef struct _mali_osk_notification_t_struct
{
372 u32 notification_type
; /**< The notification type */
373 u32 result_buffer_size
; /**< Size of the result buffer to copy to user space */
374 void * result_buffer
; /**< Buffer containing any type specific data */
375 } _mali_osk_notification_t
;
377 /** @} */ /* end group _mali_osk_notification */
380 /** @defgroup _mali_osk_timer OSK Timer Callbacks
383 /** @brief Function to call when a timer expires
385 * When a timer expires, this function is called. Note that on many systems,
386 * a timer callback will be executed in IRQ context. Therefore, restrictions
387 * may apply on what can be done inside the timer callback.
389 * If a timer requires more work to be done than can be acheived in an IRQ
390 * context, then it may defer the work with a work-queue. For example, it may
391 * use \ref _mali_osk_wq_schedule_work() to make use of a bottom-half handler
392 * to carry out the remaining work.
394 * Stopping the timer with \ref _mali_osk_timer_del() blocks on compeletion of
395 * the callback. Therefore, the callback may not obtain any mutexes also held
396 * by any callers of _mali_osk_timer_del(). Otherwise, a deadlock may occur.
398 * @param arg Function-specific data */
399 typedef void (*_mali_osk_timer_callback_t
)(void * arg
);
401 /** @brief Private type for Timer Callback Objects */
402 typedef struct _mali_osk_timer_t_struct _mali_osk_timer_t
;
403 /** @} */ /* end group _mali_osk_timer */
406 /** @addtogroup _mali_osk_list OSK Doubly-Linked Circular Lists
409 /** @brief Public List objects.
411 * To use, add a _mali_osk_list_t member to the structure that may become part
412 * of a list. When traversing the _mali_osk_list_t objects, use the
413 * _MALI_OSK_CONTAINER_OF() macro to recover the structure from its
414 *_mali_osk_list_t member
416 * Each structure may have multiple _mali_osk_list_t members, so that the
417 * structure is part of multiple lists. When traversing lists, ensure that the
418 * correct _mali_osk_list_t member is used, because type-checking will be
419 * lost by the compiler.
421 typedef struct _mali_osk_list_s
{
422 struct _mali_osk_list_s
*next
;
423 struct _mali_osk_list_s
*prev
;
425 /** @} */ /* end group _mali_osk_list */
427 /** @addtogroup _mali_osk_miscellaneous
430 /** @brief resource description struct
432 * Platform independent representation of a Mali HW resource
434 typedef struct _mali_osk_resource
{
435 const char * description
; /**< short description of the resource */
436 u32 base
; /**< Physical base address of the resource, as seen by Mali resources. */
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 */
455 #endif /* __MALI_OSK_TYPES_H__ */