2 * Copyright (C) 2011-2012 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.
13 * Defines the OS abstraction layer for the kernel device driver (OSK)
16 #ifndef __MALI_OSK_H__
17 #define __MALI_OSK_H__
25 * @addtogroup uddapi Unified Device Driver (UDD) APIs
31 * @addtogroup oskapi UDD OS Abstraction for Kernel-side (OSK) APIs
36 /** @defgroup _mali_osk_miscellaneous OSK Miscellaneous functions, constants and types
39 /* Define integer types used by OSK. Note: these currently clash with Linux so we only define them if not defined already */
41 typedef unsigned char u8;
42 typedef signed char s8;
43 typedef unsigned short u16;
44 typedef signed short s16;
45 typedef unsigned int u32;
46 typedef signed int s32;
47 typedef unsigned long long u64;
48 #define BITS_PER_LONG (sizeof(long)*8)
50 /* Ensure Linux types u32, etc. are defined */
51 #include <linux/types.h>
54 /** @brief Mali Boolean type which uses MALI_TRUE and MALI_FALSE
56 typedef unsigned long mali_bool;
59 #define MALI_TRUE ((mali_bool)1)
63 #define MALI_FALSE ((mali_bool)0)
66 #define MALI_HW_CORE_NO_COUNTER ((u32)-1)
69 * @brief OSK Error codes
71 * Each OS may use its own set of error codes, and may require that the
72 * User/Kernel interface take certain error code. This means that the common
73 * error codes need to be sufficiently rich to pass the correct error code
74 * thorugh from the OSK to U/K layer, across all OSs.
76 * The result is that some error codes will appear redundant on some OSs.
77 * Under all OSs, the OSK layer must translate native OS error codes to
78 * _mali_osk_errcode_t codes. Similarly, the U/K layer must translate from
79 * _mali_osk_errcode_t codes to native OS error codes.
83 _MALI_OSK_ERR_OK = 0, /**< Success. */
84 _MALI_OSK_ERR_FAULT = -1, /**< General non-success */
85 _MALI_OSK_ERR_INVALID_FUNC = -2, /**< Invalid function requested through User/Kernel interface (e.g. bad IOCTL number) */
86 _MALI_OSK_ERR_INVALID_ARGS = -3, /**< Invalid arguments passed through User/Kernel interface */
87 _MALI_OSK_ERR_NOMEM = -4, /**< Insufficient memory */
88 _MALI_OSK_ERR_TIMEOUT = -5, /**< Timeout occurred */
89 _MALI_OSK_ERR_RESTARTSYSCALL = -6, /**< Special: On certain OSs, must report when an interruptable mutex is interrupted. Ignore otherwise. */
90 _MALI_OSK_ERR_ITEM_NOT_FOUND = -7, /**< Table Lookup failed */
91 _MALI_OSK_ERR_BUSY = -8, /**< Device/operation is busy. Try again later */
92 _MALI_OSK_ERR_UNSUPPORTED = -9, /**< Optional part of the interface used, and is unsupported */
93 } _mali_osk_errcode_t;
95 /** @} */ /* end group _mali_osk_miscellaneous */
97 /** @defgroup _mali_osk_wq OSK work queues
100 /** @brief Private type for work objects */
101 typedef struct _mali_osk_wq_work_t_struct _mali_osk_wq_work_t;
103 /** @brief Work queue handler function
105 * This function type is called when the work is scheduled by the work queue,
106 * e.g. as an IRQ bottom-half handler.
108 * Refer to \ref _mali_osk_wq_schedule_work() for more information on the
109 * work-queue and work handlers.
111 * @param arg resource-specific data
113 typedef void (*_mali_osk_wq_work_handler_t)( void * arg );
115 /* @} */ /* end group _mali_osk_wq */
117 /** @defgroup _mali_osk_irq OSK IRQ handling
120 /** @brief Private type for IRQ handling objects */
121 typedef struct _mali_osk_irq_t_struct _mali_osk_irq_t;
123 /** @brief Optional function to trigger an irq from a resource
125 * This function is implemented by the common layer to allow probing of a resource's IRQ.
126 * @param arg resource-specific data */
127 typedef void (*_mali_osk_irq_trigger_t)( void * arg );
129 /** @brief Optional function to acknowledge an irq from a resource
131 * This function is implemented by the common layer to allow probing of a resource's IRQ.
132 * @param arg resource-specific data
133 * @return _MALI_OSK_ERR_OK if the IRQ was successful, or a suitable _mali_osk_errcode_t on failure. */
134 typedef _mali_osk_errcode_t (*_mali_osk_irq_ack_t)( void * arg );
136 /** @brief IRQ 'upper-half' handler callback.
138 * This function is implemented by the common layer to do the initial handling of a
139 * resource's IRQ. This maps on to the concept of an ISR that does the minimum
140 * work necessary before handing off to an IST.
142 * The communication of the resource-specific data from the ISR to the IST is
143 * handled by the OSK implementation.
145 * On most systems, the IRQ upper-half handler executes in IRQ context.
146 * Therefore, the system may have restrictions about what can be done in this
149 * If an IRQ upper-half handler requires more work to be done than can be
150 * acheived in an IRQ context, then it may defer the work with
151 * _mali_osk_wq_schedule_work(). Refer to \ref _mali_osk_wq_create_work() for
154 * @param arg resource-specific data
155 * @return _MALI_OSK_ERR_OK if the IRQ was correctly handled, or a suitable
156 * _mali_osk_errcode_t otherwise.
158 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.
182 } _mali_osk_atomic_t;
183 /** @} */ /* end group _mali_osk_atomic */
186 /** @defgroup _mali_osk_lock OSK Mutual Exclusion Locks
190 /** @brief OSK Mutual Exclusion Lock ordered list
192 * This lists the various types of locks in the system and is used to check
193 * that locks are taken in the correct order.
195 * Holding more than one lock of the same order at the same time is not
201 _MALI_OSK_LOCK_ORDER_LAST = 0,
203 _MALI_OSK_LOCK_ORDER_SESSION_PENDING_JOBS,
204 _MALI_OSK_LOCK_ORDER_PM_EXECUTE,
205 _MALI_OSK_LOCK_ORDER_UTILIZATION,
206 _MALI_OSK_LOCK_ORDER_L2_COUNTER,
207 _MALI_OSK_LOCK_ORDER_PROFILING,
208 _MALI_OSK_LOCK_ORDER_L2_COMMAND,
209 _MALI_OSK_LOCK_ORDER_PM_CORE_STATE,
210 _MALI_OSK_LOCK_ORDER_SCHEDULER_DEFERRED,
211 _MALI_OSK_LOCK_ORDER_SCHEDULER,
212 _MALI_OSK_LOCK_ORDER_GROUP,
213 _MALI_OSK_LOCK_ORDER_GROUP_VIRTUAL,
214 _MALI_OSK_LOCK_ORDER_DESCRIPTOR_MAP,
215 _MALI_OSK_LOCK_ORDER_MEM_PT_CACHE,
216 _MALI_OSK_LOCK_ORDER_MEM_INFO,
217 _MALI_OSK_LOCK_ORDER_MEM_SESSION,
218 _MALI_OSK_LOCK_ORDER_SESSIONS,
220 _MALI_OSK_LOCK_ORDER_FIRST
221 } _mali_osk_lock_order_t;
224 /** @brief OSK Mutual Exclusion Lock flags type
226 * Flags are supplied at the point where the Lock is initialized. Each flag can
227 * be combined with others using bitwise OR, '|'.
229 * The flags must be sufficiently rich to cope with all our OSs. This means
230 * that on some OSs, certain flags can be completely ignored. We define a
231 * number of terms that are significant across all OSs:
233 * - Sleeping/non-sleeping mutexs. Sleeping mutexs can block on waiting, and so
234 * schedule out the current thread. This is significant on OSs where there are
235 * situations in which the current thread must not be put to sleep. On OSs
236 * without this restriction, sleeping and non-sleeping mutexes can be treated
237 * as the same (if that is required).
238 * - Interruptable/non-interruptable mutexes. For sleeping mutexes, it may be
239 * possible for the sleep to be interrupted for a reason other than the thread
240 * being able to obtain the lock. OSs behaving in this way may provide a
241 * mechanism to control whether sleeping mutexes can be interrupted. On OSs
242 * that do not support the concept of interruption, \b or they do not support
243 * control of mutex interruption, then interruptable mutexes may be treated
244 * as non-interruptable.
246 * Some constrains apply to the lock type flags:
248 * - Spinlocks are by nature, non-interruptable. Hence, they must always be
249 * combined with the NONINTERRUPTABLE flag, because it is meaningless to ask
250 * for a spinlock that is interruptable (and this highlights its
251 * non-interruptable-ness). For example, on certain OSs they should be used when
252 * you must not sleep.
253 * - Reader/writer is an optimization hint, and any type of lock can be
254 * reader/writer. Since this is an optimization hint, the implementation need
255 * not respect this for any/all types of lock. For example, on certain OSs,
256 * there's no interruptable reader/writer mutex. If such a thing were requested
257 * on that OS, the fact that interruptable was requested takes priority over the
258 * reader/writer-ness, because reader/writer-ness is not necessary for correct
260 * - Any lock can use the order parameter.
261 * - A onelock is an optimization hint specific to certain OSs. It can be
262 * specified when it is known that only one lock will be held by the thread,
263 * and so can provide faster mutual exclusion. This can be safely ignored if
264 * such optimization is not required/present.
266 * The absence of any flags (the value 0) results in a sleeping-mutex, which is interruptable.
270 _MALI_OSK_LOCKFLAG_SPINLOCK = 0x1, /**< Specifically, don't sleep on those architectures that require it */
271 _MALI_OSK_LOCKFLAG_NONINTERRUPTABLE = 0x2, /**< The mutex cannot be interrupted, e.g. delivery of signals on those architectures where this is required */
272 _MALI_OSK_LOCKFLAG_READERWRITER = 0x4, /**< Optimise for readers/writers */
273 _MALI_OSK_LOCKFLAG_ORDERED = 0x8, /**< Use the order parameter; otherwise use automatic ordering */
274 _MALI_OSK_LOCKFLAG_ONELOCK = 0x10, /**< Each thread can only hold one lock at a time */
275 _MALI_OSK_LOCKFLAG_SPINLOCK_IRQ = 0x20, /**< IRQ version of spinlock */
276 /** @enum _mali_osk_lock_flags_t
278 * Flags from 0x10000--0x80000000 are RESERVED for User-mode */
280 } _mali_osk_lock_flags_t;
282 /** @brief Mutual Exclusion Lock Mode Optimization hint
284 * The lock mode is used to implement the read/write locking of locks specified
285 * as _MALI_OSK_LOCKFLAG_READERWRITER. In this case, the RO mode can be used
286 * to allow multiple concurrent readers, but no writers. The RW mode is used for
287 * writers, and so will wait for all readers to release the lock (if any present).
288 * Further readers and writers will wait until the writer releases the lock.
290 * The mode is purely an optimization hint: for example, it is permissible for
291 * all locks to behave in RW mode, regardless of that supplied.
293 * It is an error to attempt to use locks in anything other that RW mode when
294 * _MALI_OSK_LOCKFLAG_READERWRITER is not supplied.
299 _MALI_OSK_LOCKMODE_UNDEF = -1, /**< Undefined lock mode. For internal use only */
300 _MALI_OSK_LOCKMODE_RW = 0x0, /**< Read-write mode, default. All readers and writers are mutually-exclusive */
301 _MALI_OSK_LOCKMODE_RO, /**< Read-only mode, to support multiple concurrent readers, but mutual exclusion in the presence of writers. */
302 /** @enum _mali_osk_lock_mode_t
304 * Lock modes 0x40--0x7F are RESERVED for User-mode */
305 } _mali_osk_lock_mode_t;
307 /** @brief Private type for Mutual Exclusion lock objects */
308 typedef struct _mali_osk_lock_t_struct _mali_osk_lock_t;
311 /** @brief Macro for asserting that the current thread holds a given lock
313 #define MALI_DEBUG_ASSERT_LOCK_HELD(l) MALI_DEBUG_ASSERT(_mali_osk_lock_get_owner(l) == _mali_osk_get_tid());
315 /** @brief returns a lock's owner (thread id) if debugging is enabled
317 u32 _mali_osk_lock_get_owner( _mali_osk_lock_t *lock );
319 #define MALI_DEBUG_ASSERT_LOCK_HELD(l) do {} while(0)
322 /** @} */ /* end group _mali_osk_lock */
324 /** @defgroup _mali_osk_low_level_memory OSK Low-level Memory Operations
328 * @brief Private data type for use in IO accesses to/from devices.
330 * This represents some range that is accessible from the device. Examples
332 * - Device Registers, which could be readable and/or writeable.
333 * - Memory that the device has access to, for storing configuration structures.
335 * Access to this range must be made through the _mali_osk_mem_ioread32() and
336 * _mali_osk_mem_iowrite32() functions.
338 typedef struct _mali_io_address * mali_io_address;
340 /** @defgroup _MALI_OSK_CPU_PAGE CPU Physical page size macros.
342 * The order of the page size is supplied for
343 * ease of use by algorithms that might require it, since it is easier to know
344 * it ahead of time rather than calculating it.
346 * The Mali Page Mask macro masks off the lower bits of a physical address to
347 * give the start address of the page for that physical address.
349 * @note The Mali device driver code is designed for systems with 4KB page size.
350 * Changing these macros will not make the entire Mali device driver work with
351 * page sizes other than 4KB.
353 * @note The CPU Physical Page Size has been assumed to be the same as the Mali
354 * Physical Page Size.
359 /** CPU Page Order, as log to base 2 of the Page size. @see _MALI_OSK_CPU_PAGE_SIZE */
360 #define _MALI_OSK_CPU_PAGE_ORDER ((u32)12)
361 /** CPU Page Size, in bytes. */
362 #define _MALI_OSK_CPU_PAGE_SIZE (((u32)1) << (_MALI_OSK_CPU_PAGE_ORDER))
363 /** CPU Page Mask, which masks off the offset within a page */
364 #define _MALI_OSK_CPU_PAGE_MASK (~((((u32)1) << (_MALI_OSK_CPU_PAGE_ORDER)) - ((u32)1)))
365 /** @} */ /* end of group _MALI_OSK_CPU_PAGE */
367 /** @defgroup _MALI_OSK_MALI_PAGE Mali Physical Page size macros
369 * Mali Physical page size macros. The order of the page size is supplied for
370 * ease of use by algorithms that might require it, since it is easier to know
371 * it ahead of time rather than calculating it.
373 * The Mali Page Mask macro masks off the lower bits of a physical address to
374 * give the start address of the page for that physical address.
376 * @note The Mali device driver code is designed for systems with 4KB page size.
377 * Changing these macros will not make the entire Mali device driver work with
378 * page sizes other than 4KB.
380 * @note The Mali Physical Page Size has been assumed to be the same as the CPU
381 * Physical Page Size.
386 /** Mali Page Order, as log to base 2 of the Page size. @see _MALI_OSK_MALI_PAGE_SIZE */
387 #define _MALI_OSK_MALI_PAGE_ORDER ((u32)12)
388 /** Mali Page Size, in bytes. */
389 #define _MALI_OSK_MALI_PAGE_SIZE (((u32)1) << (_MALI_OSK_MALI_PAGE_ORDER))
390 /** Mali Page Mask, which masks off the offset within a page */
391 #define _MALI_OSK_MALI_PAGE_MASK (~((((u32)1) << (_MALI_OSK_MALI_PAGE_ORDER)) - ((u32)1)))
392 /** @} */ /* end of group _MALI_OSK_MALI_PAGE*/
394 /** @brief flags for mapping a user-accessible memory range
396 * Where a function with prefix '_mali_osk_mem_mapregion' accepts flags as one
397 * of the function parameters, it will use one of these. These allow per-page
398 * control over mappings. Compare with the mali_memory_allocation_flag type,
399 * which acts over an entire range
401 * These may be OR'd together with bitwise OR (|), but must be cast back into
402 * the type after OR'ing.
406 _MALI_OSK_MEM_MAPREGION_FLAG_OS_ALLOCATED_PHYSADDR = 0x1, /**< Physical address is OS Allocated */
407 } _mali_osk_mem_mapregion_flags_t;
408 /** @} */ /* end group _mali_osk_low_level_memory */
410 /** @defgroup _mali_osk_notification OSK Notification Queues
413 /** @brief Private type for notification queue objects */
414 typedef struct _mali_osk_notification_queue_t_struct _mali_osk_notification_queue_t;
416 /** @brief Public notification data object type */
417 typedef struct _mali_osk_notification_t_struct
419 u32 notification_type; /**< The notification type */
420 u32 result_buffer_size; /**< Size of the result buffer to copy to user space */
421 void * result_buffer; /**< Buffer containing any type specific data */
422 } _mali_osk_notification_t;
424 /** @} */ /* end group _mali_osk_notification */
427 /** @defgroup _mali_osk_timer OSK Timer Callbacks
430 /** @brief Function to call when a timer expires
432 * When a timer expires, this function is called. Note that on many systems,
433 * a timer callback will be executed in IRQ context. Therefore, restrictions
434 * may apply on what can be done inside the timer callback.
436 * If a timer requires more work to be done than can be acheived in an IRQ
437 * context, then it may defer the work with a work-queue. For example, it may
438 * use \ref _mali_osk_wq_schedule_work() to make use of a bottom-half handler
439 * to carry out the remaining work.
441 * Stopping the timer with \ref _mali_osk_timer_del() blocks on compeletion of
442 * the callback. Therefore, the callback may not obtain any mutexes also held
443 * by any callers of _mali_osk_timer_del(). Otherwise, a deadlock may occur.
445 * @param arg Function-specific data */
446 typedef void (*_mali_osk_timer_callback_t)(void * arg );
448 /** @brief Private type for Timer Callback Objects */
449 typedef struct _mali_osk_timer_t_struct _mali_osk_timer_t;
450 /** @} */ /* end group _mali_osk_timer */
453 /** @addtogroup _mali_osk_list OSK Doubly-Linked Circular Lists
456 /** @brief Public List objects.
458 * To use, add a _mali_osk_list_t member to the structure that may become part
459 * of a list. When traversing the _mali_osk_list_t objects, use the
460 * _MALI_OSK_CONTAINER_OF() macro to recover the structure from its
461 *_mali_osk_list_t member
463 * Each structure may have multiple _mali_osk_list_t members, so that the
464 * structure is part of multiple lists. When traversing lists, ensure that the
465 * correct _mali_osk_list_t member is used, because type-checking will be
466 * lost by the compiler.
468 typedef struct _mali_osk_list_s
470 struct _mali_osk_list_s *next;
471 struct _mali_osk_list_s *prev;
474 /** @brief Initialize a list to be a head of an empty list
475 * @param exp the list to initialize. */
476 #define _MALI_OSK_INIT_LIST_HEAD(exp) _mali_osk_list_init(exp)
478 /** @brief Define a list variable, which is uninitialized.
479 * @param exp the name of the variable that the list will be defined as. */
480 #define _MALI_OSK_LIST_HEAD(exp) _mali_osk_list_t exp
482 /** @brief Define a list variable, which is initialized.
483 * @param exp the name of the variable that the list will be defined as. */
484 #define _MALI_OSK_LIST_HEAD_STATIC_INIT(exp) _mali_osk_list_t exp = { &exp, &exp }
486 /** @brief Find the containing structure of another structure
488 * This is the reverse of the operation 'offsetof'. This means that the
489 * following condition is satisfied:
491 * ptr == _MALI_OSK_CONTAINER_OF( &ptr->member, type, member )
493 * When ptr is of type 'type'.
495 * Its purpose it to recover a larger structure that has wrapped a smaller one.
497 * @note no type or memory checking occurs to ensure that a wrapper structure
498 * does in fact exist, and that it is being recovered with respect to the
501 * @param ptr the pointer to the member that is contained within the larger
503 * @param type the type of the structure that contains the member
504 * @param member the name of the member in the structure that ptr points to.
505 * @return a pointer to a \a type object which contains \a member, as pointed
508 #define _MALI_OSK_CONTAINER_OF(ptr, type, member) \
509 ((type *)( ((char *)ptr) - offsetof(type,member) ))
511 /** @brief Find the containing structure of a list
513 * When traversing a list, this is used to recover the containing structure,
514 * given that is contains a _mali_osk_list_t member.
516 * Each list must be of structures of one type, and must link the same members
517 * together, otherwise it will not be possible to correctly recover the
518 * sturctures that the lists link.
520 * @note no type or memory checking occurs to ensure that a structure does in
521 * fact exist for the list entry, and that it is being recovered with respect
522 * to the correct list member.
524 * @param ptr the pointer to the _mali_osk_list_t member in this structure
525 * @param type the type of the structure that contains the member
526 * @param member the member of the structure that ptr points to.
527 * @return a pointer to a \a type object which contains the _mali_osk_list_t
528 * \a member, as pointed to by the _mali_osk_list_t \a *ptr.
530 #define _MALI_OSK_LIST_ENTRY(ptr, type, member) \
531 _MALI_OSK_CONTAINER_OF(ptr, type, member)
533 /** @brief Enumerate a list safely
535 * With this macro, lists can be enumerated in a 'safe' manner. That is,
536 * entries can be deleted from the list without causing an error during
537 * enumeration. To achieve this, a 'temporary' pointer is required, which must
538 * be provided to the macro.
540 * Use it like a 'for()', 'while()' or 'do()' construct, and so it must be
541 * followed by a statement or compound-statement which will be executed for
544 * Upon loop completion, providing that an early out was not taken in the
545 * loop body, then it is guaranteed that ptr->member == list, even if the loop
546 * body never executed.
548 * @param ptr a pointer to an object of type 'type', which points to the
549 * structure that contains the currently enumerated list entry.
550 * @param tmp a pointer to an object of type 'type', which must not be used
551 * inside the list-execution statement.
552 * @param list a pointer to a _mali_osk_list_t, from which enumeration will
554 * @param type the type of the structure that contains the _mali_osk_list_t
555 * member that is part of the list to be enumerated.
556 * @param member the _mali_osk_list_t member of the structure that is part of
557 * the list to be enumerated.
559 #define _MALI_OSK_LIST_FOREACHENTRY(ptr, tmp, list, type, member) \
560 for (ptr = _MALI_OSK_LIST_ENTRY((list)->next, type, member), \
561 tmp = _MALI_OSK_LIST_ENTRY(ptr->member.next, type, member); \
562 &ptr->member != (list); \
563 ptr = tmp, tmp = _MALI_OSK_LIST_ENTRY(tmp->member.next, type, member))
564 /** @} */ /* end group _mali_osk_list */
567 /** @addtogroup _mali_osk_miscellaneous
570 /** @brief resource description struct
572 * Platform independent representation of a Mali HW resource
574 typedef struct _mali_osk_resource
576 const char * description; /**< short description of the resource */
577 u32 base; /**< Physical base address of the resource, as seen by Mali resources. */
578 u32 irq; /**< IRQ number delivered to the CPU, or -1 to tell the driver to probe for it (if possible) */
579 } _mali_osk_resource_t;
580 /** @} */ /* end group _mali_osk_miscellaneous */
583 #include "mali_kernel_memory_engine.h" /* include for mali_memory_allocation and mali_physical_memory_allocation type */
585 /** @addtogroup _mali_osk_wq
588 /** @brief Initialize work queues (for deferred work)
590 * @return _MALI_OSK_ERR_OK on success, otherwise failure.
592 _mali_osk_errcode_t _mali_osk_wq_init(void);
594 /** @brief Terminate work queues (for deferred work)
596 void _mali_osk_wq_term(void);
598 /** @brief Create work in the work queue
600 * Creates a work object which can be scheduled in the work queue. When
601 * scheduled, \a handler will be called with \a data as the argument.
603 * Refer to \ref _mali_osk_wq_schedule_work() for details on how work
604 * is scheduled in the queue.
606 * The returned pointer must be freed with \ref _mali_osk_wq_delete_work()
607 * when no longer needed.
609 _mali_osk_wq_work_t *_mali_osk_wq_create_work( _mali_osk_wq_work_handler_t handler, void *data );
611 /** @brief Delete a work object
613 * This will flush the work queue to ensure that the work handler will not
614 * be called after deletion.
616 void _mali_osk_wq_delete_work( _mali_osk_wq_work_t *work );
618 /** @brief Cause a queued, deferred call of the work handler
620 * _mali_osk_wq_schedule_work provides a mechanism for enqueuing deferred calls
621 * to the work handler. After calling \ref _mali_osk_wq_schedule_work(), the
622 * work handler will be scheduled to run at some point in the future.
624 * Typically this is called by the IRQ upper-half to defer further processing of
625 * IRQ-related work to the IRQ bottom-half handler. This is necessary for work
626 * that cannot be done in an IRQ context by the IRQ upper-half handler. Timer
627 * callbacks also use this mechanism, because they are treated as though they
628 * operate in an IRQ context. Refer to \ref _mali_osk_timer_t for more
631 * Code that operates in a kernel-process context (with no IRQ context
632 * restrictions) may also enqueue deferred calls to the IRQ bottom-half. The
633 * advantage over direct calling is that deferred calling allows the caller and
634 * IRQ bottom half to hold the same mutex, with a guarantee that they will not
635 * deadlock just by using this mechanism.
637 * _mali_osk_wq_schedule_work() places deferred call requests on a queue, to
638 * allow for more than one thread to make a deferred call. Therfore, if it is
639 * called 'K' times, then the IRQ bottom-half will be scheduled 'K' times too.
640 * 'K' is a number that is implementation-specific.
642 * _mali_osk_wq_schedule_work() is guaranteed to not block on:
643 * - enqueuing a deferred call request.
644 * - the completion of the work handler.
646 * This is to prevent deadlock. For example, if _mali_osk_wq_schedule_work()
647 * blocked, then it would cause a deadlock when the following two conditions
649 * - The work handler callback (of type _mali_osk_wq_work_handler_t) locks
651 * - And, at the same time, the caller of _mali_osk_wq_schedule_work() also
652 * holds the same mutex
654 * @note care must be taken to not overflow the queue that
655 * _mali_osk_wq_schedule_work() operates on. Code must be structured to
656 * ensure that the number of requests made to the queue is bounded. Otherwise,
659 * The queue that _mali_osk_wq_schedule_work implements is a FIFO of N-writer,
660 * 1-reader type. The writers are the callers of _mali_osk_wq_schedule_work
661 * (all OSK-registered IRQ upper-half handlers in the system, watchdog timers,
662 * callers from a Kernel-process context). The reader is a single thread that
663 * handles all OSK-registered work.
665 * @param work a pointer to the _mali_osk_wq_work_t object corresponding to the
666 * work to begin processing.
668 void _mali_osk_wq_schedule_work( _mali_osk_wq_work_t *work );
670 /** @brief Flush the work queue
672 * This will flush the OSK work queue, ensuring all work in the queue has
673 * completed before returning.
675 * Since this blocks on the completion of work in the work-queue, the
676 * caller of this function \b must \b not hold any mutexes that are taken by
677 * any registered work handler. To do so may cause a deadlock.
680 void _mali_osk_wq_flush(void);
683 /** @} */ /* end group _mali_osk_wq */
685 /** @addtogroup _mali_osk_irq
688 /** @brief Initialize IRQ handling for a resource
690 * Registers an interrupt handler \a uhandler for the given IRQ number \a irqnum.
691 * \a data will be passed as argument to the handler when an interrupt occurs.
693 * If \a irqnum is -1, _mali_osk_irq_init will probe for the IRQ number using
694 * the supplied \a trigger_func and \a ack_func. These functions will also
695 * receive \a data as their argument.
697 * @param irqnum The IRQ number that the resource uses, as seen by the CPU.
698 * The value -1 has a special meaning which indicates the use of probing, and
699 * trigger_func and ack_func must be non-NULL.
700 * @param uhandler The interrupt handler, corresponding to a ISR handler for
702 * @param int_data resource specific data, which will be passed to uhandler
703 * @param trigger_func Optional: a function to trigger the resource's irq, to
704 * probe for the interrupt. Use NULL if irqnum != -1.
705 * @param ack_func Optional: a function to acknowledge the resource's irq, to
706 * probe for the interrupt. Use NULL if irqnum != -1.
707 * @param probe_data resource-specific data, which will be passed to
708 * (if present) trigger_func and ack_func
709 * @param description textual description of the IRQ resource.
710 * @return on success, a pointer to a _mali_osk_irq_t object, which represents
711 * the IRQ handling on this resource. NULL on failure.
713 _mali_osk_irq_t *_mali_osk_irq_init( u32 irqnum, _mali_osk_irq_uhandler_t uhandler, void *int_data, _mali_osk_irq_trigger_t trigger_func, _mali_osk_irq_ack_t ack_func, void *probe_data, const char *description );
715 /** @brief Terminate IRQ handling on a resource.
717 * This will disable the interrupt from the device, and then waits for any
718 * currently executing IRQ handlers to complete.
720 * @note If work is deferred to an IRQ bottom-half handler through
721 * \ref _mali_osk_wq_schedule_work(), be sure to flush any remaining work
722 * with \ref _mali_osk_wq_flush() or (implicitly) with \ref _mali_osk_wq_delete_work()
724 * @param irq a pointer to the _mali_osk_irq_t object corresponding to the
725 * resource whose IRQ handling is to be terminated.
727 void _mali_osk_irq_term( _mali_osk_irq_t *irq );
729 /** @} */ /* end group _mali_osk_irq */
732 /** @addtogroup _mali_osk_atomic
735 /** @brief Decrement an atomic counter
737 * @note It is an error to decrement the counter beyond -(1<<23)
739 * @param atom pointer to an atomic counter */
740 void _mali_osk_atomic_dec( _mali_osk_atomic_t *atom );
742 /** @brief Decrement an atomic counter, return new value
744 * @param atom pointer to an atomic counter
745 * @return The new value, after decrement */
746 u32 _mali_osk_atomic_dec_return( _mali_osk_atomic_t *atom );
748 /** @brief Increment an atomic counter
750 * @note It is an error to increment the counter beyond (1<<23)-1
752 * @param atom pointer to an atomic counter */
753 void _mali_osk_atomic_inc( _mali_osk_atomic_t *atom );
755 /** @brief Increment an atomic counter, return new value
757 * @param atom pointer to an atomic counter */
758 u32 _mali_osk_atomic_inc_return( _mali_osk_atomic_t *atom );
760 /** @brief Initialize an atomic counter
762 * @note the parameter required is a u32, and so signed integers should be
765 * @param atom pointer to an atomic counter
766 * @param val the value to initialize the atomic counter.
767 * @return _MALI_OSK_ERR_OK on success, otherwise, a suitable
768 * _mali_osk_errcode_t on failure.
770 _mali_osk_errcode_t _mali_osk_atomic_init( _mali_osk_atomic_t *atom, u32 val );
772 /** @brief Read a value from an atomic counter
774 * This can only be safely used to determine the value of the counter when it
775 * is guaranteed that other threads will not be modifying the counter. This
776 * makes its usefulness limited.
778 * @param atom pointer to an atomic counter
780 u32 _mali_osk_atomic_read( _mali_osk_atomic_t *atom );
782 /** @brief Terminate an atomic counter
784 * @param atom pointer to an atomic counter
786 void _mali_osk_atomic_term( _mali_osk_atomic_t *atom );
787 /** @} */ /* end group _mali_osk_atomic */
790 /** @defgroup _mali_osk_memory OSK Memory Allocation
793 /** @brief Allocate zero-initialized memory.
795 * Returns a buffer capable of containing at least \a n elements of \a size
796 * bytes each. The buffer is initialized to zero.
798 * If there is a need for a bigger block of memory (16KB or bigger), then
799 * consider to use _mali_osk_vmalloc() instead, as this function might
800 * map down to a OS function with size limitations.
802 * The buffer is suitably aligned for storage and subsequent access of every
803 * type that the compiler supports. Therefore, the pointer to the start of the
804 * buffer may be cast into any pointer type, and be subsequently accessed from
805 * such a pointer, without loss of information.
807 * When the buffer is no longer in use, it must be freed with _mali_osk_free().
808 * Failure to do so will cause a memory leak.
810 * @note Most toolchains supply memory allocation functions that meet the
811 * compiler's alignment requirements.
813 * @param n Number of elements to allocate
814 * @param size Size of each element
815 * @return On success, the zero-initialized buffer allocated. NULL on failure
817 void *_mali_osk_calloc( u32 n, u32 size );
819 /** @brief Allocate memory.
821 * Returns a buffer capable of containing at least \a size bytes. The
822 * contents of the buffer are undefined.
824 * If there is a need for a bigger block of memory (16KB or bigger), then
825 * consider to use _mali_osk_vmalloc() instead, as this function might
826 * map down to a OS function with size limitations.
828 * The buffer is suitably aligned for storage and subsequent access of every
829 * type that the compiler supports. Therefore, the pointer to the start of the
830 * buffer may be cast into any pointer type, and be subsequently accessed from
831 * such a pointer, without loss of information.
833 * When the buffer is no longer in use, it must be freed with _mali_osk_free().
834 * Failure to do so will cause a memory leak.
836 * @note Most toolchains supply memory allocation functions that meet the
837 * compiler's alignment requirements.
839 * Remember to free memory using _mali_osk_free().
840 * @param size Number of bytes to allocate
841 * @return On success, the buffer allocated. NULL on failure.
843 void *_mali_osk_malloc( u32 size );
845 /** @brief Free memory.
847 * Reclaims the buffer pointed to by the parameter \a ptr for the system.
848 * All memory returned from _mali_osk_malloc() and _mali_osk_calloc()
849 * must be freed before the application exits. Otherwise,
850 * a memory leak will occur.
852 * Memory must be freed once. It is an error to free the same non-NULL pointer
855 * It is legal to free the NULL pointer.
857 * @param ptr Pointer to buffer to free
859 void _mali_osk_free( void *ptr );
861 /** @brief Allocate memory.
863 * Returns a buffer capable of containing at least \a size bytes. The
864 * contents of the buffer are undefined.
866 * This function is potentially slower than _mali_osk_malloc() and _mali_osk_calloc(),
867 * but do support bigger sizes.
869 * The buffer is suitably aligned for storage and subsequent access of every
870 * type that the compiler supports. Therefore, the pointer to the start of the
871 * buffer may be cast into any pointer type, and be subsequently accessed from
872 * such a pointer, without loss of information.
874 * When the buffer is no longer in use, it must be freed with _mali_osk_free().
875 * Failure to do so will cause a memory leak.
877 * @note Most toolchains supply memory allocation functions that meet the
878 * compiler's alignment requirements.
880 * Remember to free memory using _mali_osk_free().
881 * @param size Number of bytes to allocate
882 * @return On success, the buffer allocated. NULL on failure.
884 void *_mali_osk_valloc( u32 size );
886 /** @brief Free memory.
888 * Reclaims the buffer pointed to by the parameter \a ptr for the system.
889 * All memory returned from _mali_osk_valloc() must be freed before the
890 * application exits. Otherwise a memory leak will occur.
892 * Memory must be freed once. It is an error to free the same non-NULL pointer
895 * It is legal to free the NULL pointer.
897 * @param ptr Pointer to buffer to free
899 void _mali_osk_vfree( void *ptr );
901 /** @brief Copies memory.
903 * Copies the \a len bytes from the buffer pointed by the parameter \a src
904 * directly to the buffer pointed by \a dst.
906 * It is an error for \a src to overlap \a dst anywhere in \a len bytes.
908 * @param dst Pointer to the destination array where the content is to be
910 * @param src Pointer to the source of data to be copied.
911 * @param len Number of bytes to copy.
912 * @return \a dst is always passed through unmodified.
914 void *_mali_osk_memcpy( void *dst, const void *src, u32 len );
916 /** @brief Fills memory.
918 * Sets the first \a n bytes of the block of memory pointed to by \a s to
919 * the specified value
920 * @param s Pointer to the block of memory to fill.
921 * @param c Value to be set, passed as u32. Only the 8 Least Significant Bits (LSB)
923 * @param n Number of bytes to be set to the value.
924 * @return \a s is always passed through unmodified
926 void *_mali_osk_memset( void *s, u32 c, u32 n );
927 /** @} */ /* end group _mali_osk_memory */
930 /** @brief Checks the amount of memory allocated
932 * Checks that not more than \a max_allocated bytes are allocated.
934 * Some OS bring up an interactive out of memory dialogue when the
935 * system runs out of memory. This can stall non-interactive
936 * apps (e.g. automated test runs). This function can be used to
937 * not trigger the OOM dialogue by keeping allocations
938 * within a certain limit.
940 * @return MALI_TRUE when \a max_allocated bytes are not in use yet. MALI_FALSE
941 * when at least \a max_allocated bytes are in use.
943 mali_bool _mali_osk_mem_check_allocated( u32 max_allocated );
945 /** @addtogroup _mali_osk_lock
948 /** @brief Initialize a Mutual Exclusion Lock
950 * Locks are created in the signalled (unlocked) state.
952 * initial must be zero, since there is currently no means of expressing
953 * whether a reader/writer lock should be initially locked as a reader or
954 * writer. This would require some encoding to be used.
956 * 'Automatic' ordering means that locks must be obtained in the order that
957 * they were created. For all locks that can be held at the same time, they must
958 * either all provide the order parameter, or they all must use 'automatic'
959 * ordering - because there is no way of mixing 'automatic' and 'manual'
962 * @param flags flags combined with bitwise OR ('|'), or zero. There are
963 * restrictions on which flags can be combined, @see _mali_osk_lock_flags_t.
964 * @param initial For future expansion into semaphores. SBZ.
965 * @param order The locking order of the mutex. That is, locks obtained by the
966 * same thread must have been created with an increasing order parameter, for
967 * deadlock prevention. Setting to zero causes 'automatic' ordering to be used.
968 * @return On success, a pointer to a _mali_osk_lock_t object. NULL on failure.
970 _mali_osk_lock_t *_mali_osk_lock_init( _mali_osk_lock_flags_t flags, u32 initial, u32 order );
972 /** @brief Wait for a lock to be signalled (obtained)
974 * After a thread has successfully waited on the lock, the lock is obtained by
975 * the thread, and is marked as unsignalled. The thread releases the lock by
978 * In the case of Reader/Writer locks, multiple readers can obtain a lock in
979 * the absence of writers, which is a performance optimization (providing that
980 * the readers never write to the protected resource).
982 * To prevent deadlock, locks must always be obtained in the same order.
984 * For locks marked as _MALI_OSK_LOCKFLAG_NONINTERRUPTABLE, it is a
985 * programming error for the function to exit without obtaining the lock. This
986 * means that the error code must only be checked for interruptible locks.
988 * @param lock the lock to wait upon (obtain).
989 * @param mode the mode in which the lock should be obtained. Unless the lock
990 * was created with _MALI_OSK_LOCKFLAG_READERWRITER, this must be
991 * _MALI_OSK_LOCKMODE_RW.
992 * @return On success, _MALI_OSK_ERR_OK. For interruptible locks, a suitable
993 * _mali_osk_errcode_t will be returned on failure, and the lock will not be
994 * obtained. In this case, the error code must be propagated up to the U/K
997 _mali_osk_errcode_t _mali_osk_lock_wait( _mali_osk_lock_t *lock, _mali_osk_lock_mode_t mode);
1000 /** @brief Signal (release) a lock
1002 * Locks may only be signalled by the thread that originally waited upon the
1005 * @note In the OSU, a flag exists to allow any thread to signal a
1006 * lock. Such functionality is not present in the OSK.
1008 * @param lock the lock to signal (release).
1009 * @param mode the mode in which the lock should be obtained. This must match
1010 * the mode in which the lock was waited upon.
1012 void _mali_osk_lock_signal( _mali_osk_lock_t *lock, _mali_osk_lock_mode_t mode );
1014 /** @brief Terminate a lock
1016 * This terminates a lock and frees all associated resources.
1018 * It is a programming error to terminate the lock when it is held (unsignalled)
1021 * @param lock the lock to terminate.
1023 void _mali_osk_lock_term( _mali_osk_lock_t *lock );
1024 /** @} */ /* end group _mali_osk_lock */
1027 /** @addtogroup _mali_osk_low_level_memory
1030 /** @brief Issue a memory barrier
1032 * This defines an arbitrary memory barrier operation, which forces an ordering constraint
1033 * on memory read and write operations.
1035 void _mali_osk_mem_barrier( void );
1037 /** @brief Issue a write memory barrier
1039 * This defines an write memory barrier operation which forces an ordering constraint
1040 * on memory write operations.
1042 void _mali_osk_write_mem_barrier( void );
1044 /** @brief Map a physically contiguous region into kernel space
1046 * This is primarily used for mapping in registers from resources, and Mali-MMU
1047 * page tables. The mapping is only visable from kernel-space.
1049 * Access has to go through _mali_osk_mem_ioread32 and _mali_osk_mem_iowrite32
1051 * @param phys CPU-physical base address of the memory to map in. This must
1052 * be aligned to the system's page size, which is assumed to be 4K.
1053 * @param size the number of bytes of physically contiguous address space to
1055 * @param description A textual description of the memory being mapped in.
1056 * @return On success, a Mali IO address through which the mapped-in
1057 * memory/registers can be accessed. NULL on failure.
1059 mali_io_address _mali_osk_mem_mapioregion( u32 phys, u32 size, const char *description );
1061 /** @brief Unmap a physically contiguous address range from kernel space.
1063 * The address range should be one previously mapped in through
1064 * _mali_osk_mem_mapioregion.
1066 * It is a programming error to do (but not limited to) the following:
1067 * - attempt an unmap twice
1068 * - unmap only part of a range obtained through _mali_osk_mem_mapioregion
1069 * - unmap more than the range obtained through _mali_osk_mem_mapioregion
1070 * - unmap an address range that was not successfully mapped using
1071 * _mali_osk_mem_mapioregion
1072 * - provide a mapping that does not map to phys.
1074 * @param phys CPU-physical base address of the memory that was originally
1075 * mapped in. This must be aligned to the system's page size, which is assumed
1077 * @param size The number of bytes that were originally mapped in.
1078 * @param mapping The Mali IO address through which the mapping is
1081 void _mali_osk_mem_unmapioregion( u32 phys, u32 size, mali_io_address mapping );
1083 /** @brief Allocate and Map a physically contiguous region into kernel space
1085 * This is used for allocating physically contiguous regions (such as Mali-MMU
1086 * page tables) and mapping them into kernel space. The mapping is only
1087 * visible from kernel-space.
1089 * The alignment of the returned memory is guaranteed to be at least
1090 * _MALI_OSK_CPU_PAGE_SIZE.
1092 * Access must go through _mali_osk_mem_ioread32 and _mali_osk_mem_iowrite32
1094 * @note This function is primarily to provide support for OSs that are
1095 * incapable of separating the tasks 'allocate physically contiguous memory'
1096 * and 'map it into kernel space'
1098 * @param[out] phys CPU-physical base address of memory that was allocated.
1099 * (*phys) will be guaranteed to be aligned to at least
1100 * _MALI_OSK_CPU_PAGE_SIZE on success.
1102 * @param[in] size the number of bytes of physically contiguous memory to
1103 * allocate. This must be a multiple of _MALI_OSK_CPU_PAGE_SIZE.
1105 * @return On success, a Mali IO address through which the mapped-in
1106 * memory/registers can be accessed. NULL on failure, and (*phys) is unmodified.
1108 mali_io_address _mali_osk_mem_allocioregion( u32 *phys, u32 size );
1110 /** @brief Free a physically contiguous address range from kernel space.
1112 * The address range should be one previously mapped in through
1113 * _mali_osk_mem_allocioregion.
1115 * It is a programming error to do (but not limited to) the following:
1116 * - attempt a free twice on the same ioregion
1117 * - free only part of a range obtained through _mali_osk_mem_allocioregion
1118 * - free more than the range obtained through _mali_osk_mem_allocioregion
1119 * - free an address range that was not successfully mapped using
1120 * _mali_osk_mem_allocioregion
1121 * - provide a mapping that does not map to phys.
1123 * @param phys CPU-physical base address of the memory that was originally
1124 * mapped in, which was aligned to _MALI_OSK_CPU_PAGE_SIZE.
1125 * @param size The number of bytes that were originally mapped in, which was
1126 * a multiple of _MALI_OSK_CPU_PAGE_SIZE.
1127 * @param mapping The Mali IO address through which the mapping is
1130 void _mali_osk_mem_freeioregion( u32 phys, u32 size, mali_io_address mapping );
1132 /** @brief Request a region of physically contiguous memory
1134 * This is used to ensure exclusive access to a region of physically contigous
1137 * It is acceptable to implement this as a stub. However, it is then the job
1138 * of the System Integrator to ensure that no other device driver will be using
1139 * the physical address ranges used by Mali, while the Mali device driver is
1142 * @param phys CPU-physical base address of the memory to request. This must
1143 * be aligned to the system's page size, which is assumed to be 4K.
1144 * @param size the number of bytes of physically contiguous address space to
1146 * @param description A textual description of the memory being requested.
1147 * @return _MALI_OSK_ERR_OK on success. Otherwise, a suitable
1148 * _mali_osk_errcode_t on failure.
1150 _mali_osk_errcode_t _mali_osk_mem_reqregion( u32 phys, u32 size, const char *description );
1152 /** @brief Un-request a region of physically contiguous memory
1154 * This is used to release a regious of physically contiguous memory previously
1155 * requested through _mali_osk_mem_reqregion, so that other device drivers may
1156 * use it. This will be called at time of Mali device driver termination.
1158 * It is a programming error to attempt to:
1159 * - unrequest a region twice
1160 * - unrequest only part of a range obtained through _mali_osk_mem_reqregion
1161 * - unrequest more than the range obtained through _mali_osk_mem_reqregion
1162 * - unrequest an address range that was not successfully requested using
1163 * _mali_osk_mem_reqregion
1165 * @param phys CPU-physical base address of the memory to un-request. This must
1166 * be aligned to the system's page size, which is assumed to be 4K
1167 * @param size the number of bytes of physically contiguous address space to
1170 void _mali_osk_mem_unreqregion( u32 phys, u32 size );
1172 /** @brief Read from a location currently mapped in through
1173 * _mali_osk_mem_mapioregion
1175 * This reads a 32-bit word from a 32-bit aligned location. It is a programming
1176 * error to provide unaligned locations, or to read from memory that is not
1177 * mapped in, or not mapped through either _mali_osk_mem_mapioregion() or
1178 * _mali_osk_mem_allocioregion().
1180 * @param mapping Mali IO address to read from
1181 * @param offset Byte offset from the given IO address to operate on, must be a multiple of 4
1182 * @return the 32-bit word from the specified location.
1184 u32 _mali_osk_mem_ioread32( volatile mali_io_address mapping, u32 offset );
1185 #ifdef CONFIG_SLP_MALI_DBG
1186 u32 _mali_osk_mem_ioread32_cpu( volatile mali_io_address mapping, u32 offset );
1189 /** @brief Write to a location currently mapped in through
1190 * _mali_osk_mem_mapioregion without memory barriers
1192 * This write a 32-bit word to a 32-bit aligned location without using memory barrier.
1193 * It is a programming error to provide unaligned locations, or to write to memory that is not
1194 * mapped in, or not mapped through either _mali_osk_mem_mapioregion() or
1195 * _mali_osk_mem_allocioregion().
1197 * @param mapping Mali IO address to write to
1198 * @param offset Byte offset from the given IO address to operate on, must be a multiple of 4
1199 * @param val the 32-bit word to write.
1201 void _mali_osk_mem_iowrite32_relaxed( volatile mali_io_address addr, u32 offset, u32 val );
1202 #ifdef CONFIG_SLP_MALI_DBG
1203 void _mali_osk_mem_iowrite32_relaxed_cpu( volatile mali_io_address addr, u32 offset, u32 val );
1206 /** @brief Write to a location currently mapped in through
1207 * _mali_osk_mem_mapioregion with write memory barrier
1209 * This write a 32-bit word to a 32-bit aligned location. It is a programming
1210 * error to provide unaligned locations, or to write to memory that is not
1211 * mapped in, or not mapped through either _mali_osk_mem_mapioregion() or
1212 * _mali_osk_mem_allocioregion().
1214 * @param mapping Mali IO address to write to
1215 * @param offset Byte offset from the given IO address to operate on, must be a multiple of 4
1216 * @param val the 32-bit word to write.
1218 void _mali_osk_mem_iowrite32( volatile mali_io_address mapping, u32 offset, u32 val );
1220 /** @brief Flush all CPU caches
1222 * This should only be implemented if flushing of the cache is required for
1223 * memory mapped in through _mali_osk_mem_mapregion.
1225 void _mali_osk_cache_flushall( void );
1227 /** @brief Flush any caches necessary for the CPU and MALI to have the same view of a range of uncached mapped memory
1229 * This should only be implemented if your OS doesn't do a full cache flush (inner & outer)
1230 * after allocating uncached mapped memory.
1232 * Some OS do not perform a full cache flush (including all outer caches) for uncached mapped memory.
1233 * They zero the memory through a cached mapping, then flush the inner caches but not the outer caches.
1234 * This is required for MALI to have the correct view of the memory.
1236 void _mali_osk_cache_ensure_uncached_range_flushed( void *uncached_mapping, u32 offset, u32 size );
1238 /** @} */ /* end group _mali_osk_low_level_memory */
1241 /** @addtogroup _mali_osk_notification
1243 * User space notification framework
1245 * Communication with user space of asynchronous events is performed through a
1246 * synchronous call to the \ref u_k_api.
1248 * Since the events are asynchronous, the events have to be queued until a
1249 * synchronous U/K API call can be made by user-space. A U/K API call might also
1250 * be received before any event has happened. Therefore the notifications the
1251 * different subsystems wants to send to user space has to be queued for later
1252 * reception, or a U/K API call has to be blocked until an event has occured.
1254 * Typical uses of notifications are after running of jobs on the hardware or
1255 * when changes to the system is detected that needs to be relayed to user
1258 * After an event has occured user space has to be notified using some kind of
1259 * message. The notification framework supports sending messages to waiting
1260 * threads or queueing of messages until a U/K API call is made.
1262 * The notification queue is a FIFO. There are no restrictions on the numbers
1263 * of readers or writers in the queue.
1265 * A message contains what user space needs to identifiy how to handle an
1266 * event. This includes a type field and a possible type specific payload.
1268 * A notification to user space is represented by a
1269 * \ref _mali_osk_notification_t object. A sender gets hold of such an object
1270 * using _mali_osk_notification_create(). The buffer given by the
1271 * _mali_osk_notification_t::result_buffer field in the object is used to store
1272 * any type specific data. The other fields are internal to the queue system
1273 * and should not be touched.
1277 /** @brief Create a notification object
1279 * Returns a notification object which can be added to the queue of
1280 * notifications pending for user space transfer.
1282 * The implementation will initialize all members of the
1283 * \ref _mali_osk_notification_t object. In particular, the
1284 * _mali_osk_notification_t::result_buffer member will be initialized to point
1285 * to \a size bytes of storage, and that storage will be suitably aligned for
1286 * storage of any structure. That is, the created buffer meets the same
1287 * requirements as _mali_osk_malloc().
1289 * The notification object must be deleted when not in use. Use
1290 * _mali_osk_notification_delete() for deleting it.
1292 * @note You \b must \b not call _mali_osk_free() on a \ref _mali_osk_notification_t,
1293 * object, or on a _mali_osk_notification_t::result_buffer. You must only use
1294 * _mali_osk_notification_delete() to free the resources assocaited with a
1295 * \ref _mali_osk_notification_t object.
1297 * @param type The notification type
1298 * @param size The size of the type specific buffer to send
1299 * @return Pointer to a notification object with a suitable buffer, or NULL on error.
1301 _mali_osk_notification_t *_mali_osk_notification_create( u32 type, u32 size );
1303 /** @brief Delete a notification object
1305 * This must be called to reclaim the resources of a notification object. This
1307 * - The _mali_osk_notification_t::result_buffer
1308 * - The \ref _mali_osk_notification_t itself.
1310 * A notification object \b must \b not be used after it has been deleted by
1311 * _mali_osk_notification_delete().
1313 * In addition, the notification object may not be deleted while it is in a
1314 * queue. That is, if it has been placed on a queue with
1315 * _mali_osk_notification_queue_send(), then it must not be deleted until
1316 * it has been received by a call to _mali_osk_notification_queue_receive().
1317 * Otherwise, the queue may be corrupted.
1319 * @param object the notification object to delete.
1321 void _mali_osk_notification_delete( _mali_osk_notification_t *object );
1323 /** @brief Create a notification queue
1325 * Creates a notification queue which can be used to queue messages for user
1326 * delivery and get queued messages from
1328 * The queue is a FIFO, and has no restrictions on the numbers of readers or
1331 * When the queue is no longer in use, it must be terminated with
1332 * \ref _mali_osk_notification_queue_term(). Failure to do so will result in a
1335 * @return Pointer to a new notification queue or NULL on error.
1337 _mali_osk_notification_queue_t *_mali_osk_notification_queue_init( void );
1339 /** @brief Destroy a notification queue
1341 * Destroys a notification queue and frees associated resources from the queue.
1343 * A notification queue \b must \b not be destroyed in the following cases:
1344 * - while there are \ref _mali_osk_notification_t objects in the queue.
1345 * - while there are writers currently acting upon the queue. That is, while
1346 * a thread is currently calling \ref _mali_osk_notification_queue_send() on
1347 * the queue, or while a thread may call
1348 * \ref _mali_osk_notification_queue_send() on the queue in the future.
1349 * - while there are readers currently waiting upon the queue. That is, while
1350 * a thread is currently calling \ref _mali_osk_notification_queue_receive() on
1351 * the queue, or while a thread may call
1352 * \ref _mali_osk_notification_queue_receive() on the queue in the future.
1354 * Therefore, all \ref _mali_osk_notification_t objects must be flushed and
1355 * deleted by the code that makes use of the notification queues, since only
1356 * they know the structure of the _mali_osk_notification_t::result_buffer
1357 * (even if it may only be a flat sturcture).
1359 * @note Since the queue is a FIFO, the code using notification queues may
1360 * create its own 'flush' type of notification, to assist in flushing the
1363 * Once the queue has been destroyed, it must not be used again.
1365 * @param queue The queue to destroy
1367 void _mali_osk_notification_queue_term( _mali_osk_notification_queue_t *queue );
1369 /** @brief Schedule notification for delivery
1371 * When a \ref _mali_osk_notification_t object has been created successfully
1372 * and set up, it may be added to the queue of objects waiting for user space
1375 * The sending will not block if the queue is full.
1377 * A \ref _mali_osk_notification_t object \b must \b not be put on two different
1378 * queues at the same time, or enqueued twice onto a single queue before
1379 * reception. However, it is acceptable for it to be requeued \em after reception
1380 * from a call to _mali_osk_notification_queue_receive(), even onto the same queue.
1382 * Again, requeuing must also not enqueue onto two different queues at the same
1383 * time, or enqueue onto the same queue twice before reception.
1385 * @param queue The notification queue to add this notification to
1386 * @param object The entry to add
1388 void _mali_osk_notification_queue_send( _mali_osk_notification_queue_t *queue, _mali_osk_notification_t *object );
1390 /** @brief Receive a notification from a queue
1392 * Receives a single notification from the given queue.
1394 * If no notifciations are ready the thread will sleep until one becomes ready.
1395 * Therefore, notifications may not be received into an
1396 * IRQ or 'atomic' context (that is, a context where sleeping is disallowed).
1398 * @param queue The queue to receive from
1399 * @param result Pointer to storage of a pointer of type
1400 * \ref _mali_osk_notification_t*. \a result will be written to such that the
1401 * expression \a (*result) will evaluate to a pointer to a valid
1402 * \ref _mali_osk_notification_t object, or NULL if none were received.
1403 * @return _MALI_OSK_ERR_OK on success. _MALI_OSK_ERR_RESTARTSYSCALL if the sleep was interrupted.
1405 _mali_osk_errcode_t _mali_osk_notification_queue_receive( _mali_osk_notification_queue_t *queue, _mali_osk_notification_t **result );
1407 /** @brief Dequeues a notification from a queue
1409 * Receives a single notification from the given queue.
1411 * If no notifciations are ready the function call will return an error code.
1413 * @param queue The queue to receive from
1414 * @param result Pointer to storage of a pointer of type
1415 * \ref _mali_osk_notification_t*. \a result will be written to such that the
1416 * expression \a (*result) will evaluate to a pointer to a valid
1417 * \ref _mali_osk_notification_t object, or NULL if none were received.
1418 * @return _MALI_OSK_ERR_OK on success, _MALI_OSK_ERR_ITEM_NOT_FOUND if queue was empty.
1420 _mali_osk_errcode_t _mali_osk_notification_queue_dequeue( _mali_osk_notification_queue_t *queue, _mali_osk_notification_t **result );
1422 /** @} */ /* end group _mali_osk_notification */
1425 /** @addtogroup _mali_osk_timer
1427 * Timers use the OS's representation of time, which are 'ticks'. This is to
1428 * prevent aliasing problems between the internal timer time, and the time
1433 /** @brief Initialize a timer
1435 * Allocates resources for a new timer, and initializes them. This does not
1438 * @return a pointer to the allocated timer object, or NULL on failure.
1440 _mali_osk_timer_t *_mali_osk_timer_init(void);
1442 /** @brief Start a timer
1444 * It is an error to start a timer without setting the callback via
1445 * _mali_osk_timer_setcallback().
1447 * It is an error to use this to start an already started timer.
1449 * The timer will expire in \a ticks_to_expire ticks, at which point, the
1450 * callback function will be invoked with the callback-specific data,
1451 * as registered by _mali_osk_timer_setcallback().
1453 * @param tim the timer to start
1454 * @param ticks_to_expire the amount of time in ticks for the timer to run
1455 * before triggering.
1457 void _mali_osk_timer_add( _mali_osk_timer_t *tim, u32 ticks_to_expire );
1459 /** @brief Modify a timer
1461 * Set the relative time at which a timer will expire, and start it if it is
1462 * stopped. If \a ticks_to_expire 0 the timer fires immediately.
1464 * It is an error to modify a timer without setting the callback via
1465 * _mali_osk_timer_setcallback().
1467 * The timer will expire at \a ticks_to_expire from the time of the call, at
1468 * which point, the callback function will be invoked with the
1469 * callback-specific data, as set by _mali_osk_timer_setcallback().
1471 * @param tim the timer to modify, and start if necessary
1472 * @param ticks_to_expire the \em absolute time in ticks at which this timer
1476 void _mali_osk_timer_mod( _mali_osk_timer_t *tim, u32 ticks_to_expire);
1478 /** @brief Stop a timer, and block on its completion.
1480 * Stop the timer. When the function returns, it is guaranteed that the timer's
1481 * callback will not be running on any CPU core.
1483 * Since stoping the timer blocks on compeletion of the callback, the callback
1484 * may not obtain any mutexes that the caller holds. Otherwise, a deadlock will
1487 * @note While the callback itself is guaranteed to not be running, work
1488 * enqueued on the work-queue by the timer (with
1489 * \ref _mali_osk_wq_schedule_work()) may still run. The timer callback and
1490 * work handler must take this into account.
1492 * It is legal to stop an already stopped timer.
1494 * @param tim the timer to stop.
1497 void _mali_osk_timer_del( _mali_osk_timer_t *tim );
1499 /** @brief Stop a timer.
1501 * Stop the timer. When the function returns, the timer's callback may still be
1502 * running on any CPU core.
1504 * It is legal to stop an already stopped timer.
1506 * @param tim the timer to stop.
1508 void _mali_osk_timer_del_async( _mali_osk_timer_t *tim );
1510 /** @brief Check if timer is pending.
1512 * Check if timer is active.
1514 * @param tim the timer to check
1515 * @return MALI_TRUE if time is active, MALI_FALSE if it is not active
1517 mali_bool _mali_osk_timer_pending( _mali_osk_timer_t *tim);
1519 /** @brief Set a timer's callback parameters.
1521 * This must be called at least once before a timer is started/modified.
1523 * After a timer has been stopped or expires, the callback remains set. This
1524 * means that restarting the timer will call the same function with the same
1525 * parameters on expiry.
1527 * @param tim the timer to set callback on.
1528 * @param callback Function to call when timer expires
1529 * @param data Function-specific data to supply to the function on expiry.
1531 void _mali_osk_timer_setcallback( _mali_osk_timer_t *tim, _mali_osk_timer_callback_t callback, void *data );
1533 /** @brief Terminate a timer, and deallocate resources.
1535 * The timer must first be stopped by calling _mali_osk_timer_del().
1537 * It is a programming error for _mali_osk_timer_term() to be called on:
1538 * - timer that is currently running
1539 * - a timer that is currently executing its callback.
1541 * @param tim the timer to deallocate.
1543 void _mali_osk_timer_term( _mali_osk_timer_t *tim );
1544 /** @} */ /* end group _mali_osk_timer */
1547 /** @defgroup _mali_osk_time OSK Time functions
1549 * \ref _mali_osk_time use the OS's representation of time, which are
1550 * 'ticks'. This is to prevent aliasing problems between the internal timer
1551 * time, and the time asked for.
1553 * OS tick time is measured as a u32. The time stored in a u32 may either be
1554 * an absolute time, or a time delta between two events. Whilst it is valid to
1555 * use math opeartors to \em change the tick value represented as a u32, it
1556 * is often only meaningful to do such operations on time deltas, rather than
1557 * on absolute time. However, it is meaningful to add/subtract time deltas to
1560 * Conversion between tick time and milliseconds (ms) may not be loss-less,
1561 * and are \em implementation \em depenedant.
1563 * Code use OS time must take this into account, since:
1564 * - a small OS time may (or may not) be rounded
1565 * - a large time may (or may not) overflow
1569 /** @brief Return whether ticka occurs after tickb
1571 * Some OSs handle tick 'rollover' specially, and so can be more robust against
1572 * tick counters rolling-over. This function must therefore be called to
1573 * determine if a time (in ticks) really occurs after another time (in ticks).
1575 * @param ticka ticka
1576 * @param tickb tickb
1577 * @return non-zero if ticka represents a time that occurs after tickb.
1580 int _mali_osk_time_after( u32 ticka, u32 tickb );
1582 /** @brief Convert milliseconds to OS 'ticks'
1584 * @param ms time interval in milliseconds
1585 * @return the corresponding time interval in OS ticks.
1587 u32 _mali_osk_time_mstoticks( u32 ms );
1589 /** @brief Convert OS 'ticks' to milliseconds
1591 * @param ticks time interval in OS ticks.
1592 * @return the corresponding time interval in milliseconds
1594 u32 _mali_osk_time_tickstoms( u32 ticks );
1597 /** @brief Get the current time in OS 'ticks'.
1598 * @return the current time in OS 'ticks'.
1600 u32 _mali_osk_time_tickcount( void );
1602 /** @brief Cause a microsecond delay
1604 * The delay will have microsecond resolution, and is necessary for correct
1605 * operation of the driver. At worst, the delay will be \b at least \a usecs
1606 * microseconds, and so may be (significantly) more.
1608 * This function may be implemented as a busy-wait, which is the most sensible
1609 * implementation. On OSs where there are situations in which a thread must not
1610 * sleep, this is definitely implemented as a busy-wait.
1612 * @param usecs the number of microseconds to wait for.
1614 void _mali_osk_time_ubusydelay( u32 usecs );
1616 /** @brief Return time in nano seconds, since any given reference.
1618 * @return Time in nano seconds
1620 u64 _mali_osk_time_get_ns( void );
1623 /** @} */ /* end group _mali_osk_time */
1625 /** @defgroup _mali_osk_math OSK Math
1628 /** @brief Count Leading Zeros (Little-endian)
1630 * @note This function must be implemented to support the reference
1631 * implementation of _mali_osk_find_first_zero_bit, as defined in
1632 * mali_osk_bitops.h.
1634 * @param val 32-bit words to count leading zeros on
1635 * @return the number of leading zeros.
1637 u32 _mali_osk_clz( u32 val );
1638 /** @} */ /* end group _mali_osk_math */
1640 /** @defgroup _mali_osk_wait_queue OSK Wait Queue functionality
1642 /** @brief Private type for wait queue objects */
1643 typedef struct _mali_osk_wait_queue_t_struct _mali_osk_wait_queue_t;
1645 /** @brief Initialize an empty Wait Queue */
1646 _mali_osk_wait_queue_t* _mali_osk_wait_queue_init( void );
1648 /** @brief Sleep if condition is false
1650 * @param queue the queue to use
1651 * @param condition function pointer to a boolean function
1653 * Put thread to sleep if the given \a codition function returns false. When
1654 * being asked to wake up again, the condition will be re-checked and the
1655 * thread only woken up if the condition is now true.
1657 void _mali_osk_wait_queue_wait_event( _mali_osk_wait_queue_t *queue, mali_bool (*condition)(void) );
1659 /** @brief Wake up all threads in wait queue if their respective conditions are
1662 * @param queue the queue whose threads should be woken up
1664 * Wake up all threads in wait queue \a queue whose condition is now true.
1666 void _mali_osk_wait_queue_wake_up( _mali_osk_wait_queue_t *queue );
1668 /** @brief terminate a wait queue
1670 * @param queue the queue to terminate.
1672 void _mali_osk_wait_queue_term( _mali_osk_wait_queue_t *queue );
1673 /** @} */ /* end group _mali_osk_wait_queue */
1676 /** @addtogroup _mali_osk_miscellaneous
1679 /** @brief Output a device driver debug message.
1681 * The interpretation of \a fmt is the same as the \c format parameter in
1682 * _mali_osu_vsnprintf().
1684 * @param fmt a _mali_osu_vsnprintf() style format string
1685 * @param ... a variable-number of parameters suitable for \a fmt
1687 void _mali_osk_dbgmsg( const char *fmt, ... );
1689 /** @brief Print fmt into buf.
1691 * The interpretation of \a fmt is the same as the \c format parameter in
1692 * _mali_osu_vsnprintf().
1694 * @param buf a pointer to the result buffer
1695 * @param size the total number of bytes allowed to write to \a buf
1696 * @param fmt a _mali_osu_vsnprintf() style format string
1697 * @param ... a variable-number of parameters suitable for \a fmt
1698 * @return The number of bytes written to \a buf
1700 u32 _mali_osk_snprintf( char *buf, u32 size, const char *fmt, ... );
1702 /** @brief Abnormal process abort.
1704 * Terminates the caller-process if this function is called.
1706 * This function will be called from Debug assert-macros in mali_kernel_common.h.
1708 * This function will never return - because to continue from a Debug assert
1709 * could cause even more problems, and hinder debugging of the initial problem.
1711 * This function is only used in Debug builds, and is not used in Release builds.
1713 void _mali_osk_abort(void);
1715 /** @brief Sets breakpoint at point where function is called.
1717 * This function will be called from Debug assert-macros in mali_kernel_common.h,
1718 * to assist in debugging. If debugging at this level is not required, then this
1719 * function may be implemented as a stub.
1721 * This function is only used in Debug builds, and is not used in Release builds.
1723 void _mali_osk_break(void);
1725 /** @brief Return an identificator for calling process.
1727 * @return Identificator for calling process.
1729 u32 _mali_osk_get_pid(void);
1731 /** @brief Return an identificator for calling thread.
1733 * @return Identificator for calling thread.
1735 u32 _mali_osk_get_tid(void);
1737 /** @brief Enable OS controlled runtime power management
1739 void _mali_osk_pm_dev_enable(void);
1741 /** @brief Disable OS controlled runtime power management
1743 void _mali_osk_pm_dev_disable(void);
1746 /** @brief Take a reference to the power manager system for the Mali device.
1748 * When function returns successfully, Mali is ON.
1750 * @note Call \a _mali_osk_pm_dev_ref_dec() to release this reference.
1752 _mali_osk_errcode_t _mali_osk_pm_dev_ref_add(void);
1755 /** @brief Release the reference to the power manger system for the Mali device.
1757 * When reference count reach zero, the cores can be off.
1759 * @note This must be used to release references taken with \a _mali_osk_pm_dev_ref_add().
1761 void _mali_osk_pm_dev_ref_dec(void);
1764 /** @brief Take a reference to the power manager system for the Mali device.
1766 * Will leave the cores powered off if they are already powered off.
1768 * @note Call \a _mali_osk_pm_dev_ref_dec() to release this reference.
1770 * @return MALI_TRUE if the Mali GPU is powered on, otherwise MALI_FALSE.
1772 mali_bool _mali_osk_pm_dev_ref_add_no_power_on(void);
1775 /** @brief Releasing the reference to the power manger system for the Mali device.
1777 * When reference count reach zero, the cores can be off.
1779 * @note This must be used to release references taken with \a _mali_osk_pm_dev_ref_add_no_power_on().
1781 void _mali_osk_pm_dev_ref_dec_no_power_on(void);
1783 /** @} */ /* end group _mali_osk_miscellaneous */
1785 /** @} */ /* end group osuapi */
1787 /** @} */ /* end group uddapi */
1793 #include "mali_osk_specific.h" /* include any per-os specifics */
1795 /* Check standard inlines */
1796 #ifndef MALI_STATIC_INLINE
1797 #error MALI_STATIC_INLINE not defined on your OS
1800 #ifndef MALI_NON_STATIC_INLINE
1801 #error MALI_NON_STATIC_INLINE not defined on your OS
1804 #endif /* __MALI_OSK_H__ */