2 * Copyright (C) 2010-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__
19 #include "mali_osk_types.h"
20 #include "mali_osk_specific.h" /* include any per-os specifics */
21 #include "mali_osk_locks.h"
28 * @addtogroup uddapi Unified Device Driver (UDD) APIs
34 * @addtogroup oskapi UDD OS Abstraction for Kernel-side (OSK) APIs
39 /** @addtogroup _mali_osk_lock OSK Mutual Exclusion Locks
43 /** @brief Macro for asserting that the current thread holds a given lock
45 #define MALI_DEBUG_ASSERT_LOCK_HELD(l) MALI_DEBUG_ASSERT(_mali_osk_lock_get_owner((_mali_osk_lock_debug_t *)l) == _mali_osk_get_tid());
47 /** @brief returns a lock's owner (thread id) if debugging is enabled
50 #define MALI_DEBUG_ASSERT_LOCK_HELD(l) do {} while(0)
53 /** @} */ /* end group _mali_osk_lock */
55 /** @addtogroup _mali_osk_miscellaneous
58 /** @brief Find the containing structure of another structure
60 * This is the reverse of the operation 'offsetof'. This means that the
61 * following condition is satisfied:
63 * ptr == _MALI_OSK_CONTAINER_OF( &ptr->member, type, member )
65 * When ptr is of type 'type'.
67 * Its purpose it to recover a larger structure that has wrapped a smaller one.
69 * @note no type or memory checking occurs to ensure that a wrapper structure
70 * does in fact exist, and that it is being recovered with respect to the
73 * @param ptr the pointer to the member that is contained within the larger
75 * @param type the type of the structure that contains the member
76 * @param member the name of the member in the structure that ptr points to.
77 * @return a pointer to a \a type object which contains \a member, as pointed
80 #define _MALI_OSK_CONTAINER_OF(ptr, type, member) \
81 ((type *)( ((char *)ptr) - offsetof(type,member) ))
83 /** @addtogroup _mali_osk_wq
86 /** @brief Initialize work queues (for deferred work)
88 * @return _MALI_OSK_ERR_OK on success, otherwise failure.
90 _mali_osk_errcode_t _mali_osk_wq_init(void);
92 /** @brief Terminate work queues (for deferred work)
94 void _mali_osk_wq_term(void);
96 /** @brief Create work in the work queue
98 * Creates a work object which can be scheduled in the work queue. When
99 * scheduled, \a handler will be called with \a data as the argument.
101 * Refer to \ref _mali_osk_wq_schedule_work() for details on how work
102 * is scheduled in the queue.
104 * The returned pointer must be freed with \ref _mali_osk_wq_delete_work()
105 * when no longer needed.
107 _mali_osk_wq_work_t *_mali_osk_wq_create_work( _mali_osk_wq_work_handler_t handler, void *data );
109 /** @brief A high priority version of \a _mali_osk_wq_create_work()
111 * Creates a work object which can be scheduled in the high priority work queue.
113 * This is unfortunately needed to get low latency scheduling of the Mali cores. Normally we would
114 * schedule the next job in hw_irq or tasklet, but often we can't since we need to synchronously map
115 * and unmap shared memory when a job is connected to external fences (timelines). And this requires
118 * We do signal a lot of other (low priority) work also as part of the job being finished, and if we
119 * don't set this Mali scheduling thread as high priority, we see that the CPU scheduler often runs
120 * random things instead of starting the next GPU job when the GPU is idle. So setting the gpu
121 * scheduler to high priority does give a visually more responsive system.
123 * Start the high priority work with: \a _mali_osk_wq_schedule_work_high_pri()
125 _mali_osk_wq_work_t *_mali_osk_wq_create_work_high_pri( _mali_osk_wq_work_handler_t handler, void *data );
127 /** @brief Delete a work object
129 * This will flush the work queue to ensure that the work handler will not
130 * be called after deletion.
132 void _mali_osk_wq_delete_work( _mali_osk_wq_work_t *work );
134 /** @brief Delete a work object
136 * This will NOT flush the work queue, so only call this if you are sure that the work handler will
137 * not be called after deletion.
139 void _mali_osk_wq_delete_work_nonflush( _mali_osk_wq_work_t *work );
141 /** @brief Cause a queued, deferred call of the work handler
143 * _mali_osk_wq_schedule_work provides a mechanism for enqueuing deferred calls
144 * to the work handler. After calling \ref _mali_osk_wq_schedule_work(), the
145 * work handler will be scheduled to run at some point in the future.
147 * Typically this is called by the IRQ upper-half to defer further processing of
148 * IRQ-related work to the IRQ bottom-half handler. This is necessary for work
149 * that cannot be done in an IRQ context by the IRQ upper-half handler. Timer
150 * callbacks also use this mechanism, because they are treated as though they
151 * operate in an IRQ context. Refer to \ref _mali_osk_timer_t for more
154 * Code that operates in a kernel-process context (with no IRQ context
155 * restrictions) may also enqueue deferred calls to the IRQ bottom-half. The
156 * advantage over direct calling is that deferred calling allows the caller and
157 * IRQ bottom half to hold the same mutex, with a guarantee that they will not
158 * deadlock just by using this mechanism.
160 * _mali_osk_wq_schedule_work() places deferred call requests on a queue, to
161 * allow for more than one thread to make a deferred call. Therfore, if it is
162 * called 'K' times, then the IRQ bottom-half will be scheduled 'K' times too.
163 * 'K' is a number that is implementation-specific.
165 * _mali_osk_wq_schedule_work() is guaranteed to not block on:
166 * - enqueuing a deferred call request.
167 * - the completion of the work handler.
169 * This is to prevent deadlock. For example, if _mali_osk_wq_schedule_work()
170 * blocked, then it would cause a deadlock when the following two conditions
172 * - The work handler callback (of type _mali_osk_wq_work_handler_t) locks
174 * - And, at the same time, the caller of _mali_osk_wq_schedule_work() also
175 * holds the same mutex
177 * @note care must be taken to not overflow the queue that
178 * _mali_osk_wq_schedule_work() operates on. Code must be structured to
179 * ensure that the number of requests made to the queue is bounded. Otherwise,
182 * The queue that _mali_osk_wq_schedule_work implements is a FIFO of N-writer,
183 * 1-reader type. The writers are the callers of _mali_osk_wq_schedule_work
184 * (all OSK-registered IRQ upper-half handlers in the system, watchdog timers,
185 * callers from a Kernel-process context). The reader is a single thread that
186 * handles all OSK-registered work.
188 * @param work a pointer to the _mali_osk_wq_work_t object corresponding to the
189 * work to begin processing.
191 void _mali_osk_wq_schedule_work( _mali_osk_wq_work_t *work );
193 /** @brief Cause a queued, deferred call of the high priority work handler
195 * Function is the same as \a _mali_osk_wq_schedule_work() with the only
196 * difference that it runs in a high (real time) priority on the system.
198 * Should only be used as a substitue for doing the same work in interrupts.
200 * This is allowed to sleep, but the work should be small since it will block
201 * all other applications.
203 void _mali_osk_wq_schedule_work_high_pri( _mali_osk_wq_work_t *work );
205 /** @brief Flush the work queue
207 * This will flush the OSK work queue, ensuring all work in the queue has
208 * completed before returning.
210 * Since this blocks on the completion of work in the work-queue, the
211 * caller of this function \b must \b not hold any mutexes that are taken by
212 * any registered work handler. To do so may cause a deadlock.
215 void _mali_osk_wq_flush(void);
217 /** @brief Create work in the delayed work queue
219 * Creates a work object which can be scheduled in the work queue. When
220 * scheduled, a timer will be start and the \a handler will be called with
221 * \a data as the argument when timer out
223 * Refer to \ref _mali_osk_wq_delayed_schedule_work() for details on how work
224 * is scheduled in the queue.
226 * The returned pointer must be freed with \ref _mali_osk_wq_delayed_delete_work_nonflush()
227 * when no longer needed.
229 _mali_osk_wq_delayed_work_t *_mali_osk_wq_delayed_create_work(_mali_osk_wq_work_handler_t handler, void *data);
231 /** @brief Delete a work object
233 * This will NOT flush the work queue, so only call this if you are sure that the work handler will
234 * not be called after deletion.
236 void _mali_osk_wq_delayed_delete_work_nonflush(_mali_osk_wq_delayed_work_t *work);
238 /** @brief Cancel a delayed work without waiting for it to finish
240 * Note that the \a work callback function may still be running on return from
241 * _mali_osk_wq_delayed_cancel_work_async().
243 * @param work The delayed work to be cancelled
245 void _mali_osk_wq_delayed_cancel_work_async(_mali_osk_wq_delayed_work_t *work);
247 /** @brief Cancel a delayed work and wait for it to finish
249 * When this function returns, the \a work was either cancelled or it finished running.
251 * @param work The delayed work to be cancelled
253 void _mali_osk_wq_delayed_cancel_work_sync(_mali_osk_wq_delayed_work_t *work);
255 /** @brief Put \a work task in global workqueue after delay
257 * After waiting for a given time this puts a job in the kernel-global
260 * If \a work was already on a queue, this function will return without doing anything
262 * @param work job to be done
263 * @param delay number of jiffies to wait or 0 for immediate execution
265 void _mali_osk_wq_delayed_schedule_work(_mali_osk_wq_delayed_work_t *work, u32 delay);
267 /** @} */ /* end group _mali_osk_wq */
270 /** @addtogroup _mali_osk_irq
273 /** @brief Initialize IRQ handling for a resource
275 * Registers an interrupt handler \a uhandler for the given IRQ number \a irqnum.
276 * \a data will be passed as argument to the handler when an interrupt occurs.
278 * If \a irqnum is -1, _mali_osk_irq_init will probe for the IRQ number using
279 * the supplied \a trigger_func and \a ack_func. These functions will also
280 * receive \a data as their argument.
282 * @param irqnum The IRQ number that the resource uses, as seen by the CPU.
283 * The value -1 has a special meaning which indicates the use of probing, and
284 * trigger_func and ack_func must be non-NULL.
285 * @param uhandler The interrupt handler, corresponding to a ISR handler for
287 * @param int_data resource specific data, which will be passed to uhandler
288 * @param trigger_func Optional: a function to trigger the resource's irq, to
289 * probe for the interrupt. Use NULL if irqnum != -1.
290 * @param ack_func Optional: a function to acknowledge the resource's irq, to
291 * probe for the interrupt. Use NULL if irqnum != -1.
292 * @param probe_data resource-specific data, which will be passed to
293 * (if present) trigger_func and ack_func
294 * @param description textual description of the IRQ resource.
295 * @return on success, a pointer to a _mali_osk_irq_t object, which represents
296 * the IRQ handling on this resource. NULL on failure.
298 _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 );
300 /** @brief Terminate IRQ handling on a resource.
302 * This will disable the interrupt from the device, and then waits for any
303 * currently executing IRQ handlers to complete.
305 * @note If work is deferred to an IRQ bottom-half handler through
306 * \ref _mali_osk_wq_schedule_work(), be sure to flush any remaining work
307 * with \ref _mali_osk_wq_flush() or (implicitly) with \ref _mali_osk_wq_delete_work()
309 * @param irq a pointer to the _mali_osk_irq_t object corresponding to the
310 * resource whose IRQ handling is to be terminated.
312 void _mali_osk_irq_term( _mali_osk_irq_t *irq );
314 /** @} */ /* end group _mali_osk_irq */
317 /** @addtogroup _mali_osk_atomic
320 /** @brief Decrement an atomic counter
322 * @note It is an error to decrement the counter beyond -(1<<23)
324 * @param atom pointer to an atomic counter */
325 void _mali_osk_atomic_dec( _mali_osk_atomic_t *atom );
327 /** @brief Decrement an atomic counter, return new value
329 * @param atom pointer to an atomic counter
330 * @return The new value, after decrement */
331 u32 _mali_osk_atomic_dec_return( _mali_osk_atomic_t *atom );
333 /** @brief Increment an atomic counter
335 * @note It is an error to increment the counter beyond (1<<23)-1
337 * @param atom pointer to an atomic counter */
338 void _mali_osk_atomic_inc( _mali_osk_atomic_t *atom );
340 /** @brief Increment an atomic counter, return new value
342 * @param atom pointer to an atomic counter */
343 u32 _mali_osk_atomic_inc_return( _mali_osk_atomic_t *atom );
345 /** @brief Initialize an atomic counter
347 * @note the parameter required is a u32, and so signed integers should be
350 * @param atom pointer to an atomic counter
351 * @param val the value to initialize the atomic counter.
352 * @return _MALI_OSK_ERR_OK on success, otherwise, a suitable
353 * _mali_osk_errcode_t on failure.
355 _mali_osk_errcode_t _mali_osk_atomic_init( _mali_osk_atomic_t *atom, u32 val );
357 /** @brief Read a value from an atomic counter
359 * This can only be safely used to determine the value of the counter when it
360 * is guaranteed that other threads will not be modifying the counter. This
361 * makes its usefulness limited.
363 * @param atom pointer to an atomic counter
365 u32 _mali_osk_atomic_read( _mali_osk_atomic_t *atom );
367 /** @brief Terminate an atomic counter
369 * @param atom pointer to an atomic counter
371 void _mali_osk_atomic_term( _mali_osk_atomic_t *atom );
373 /** @brief Assign a new val to atomic counter, and return the old atomic counter
375 * @param atom pointer to an atomic counter
376 * @param val the new value assign to the atomic counter
377 * @return the old value of the atomic counter
379 u32 _mali_osk_atomic_xchg( _mali_osk_atomic_t *atom, u32 val );
380 /** @} */ /* end group _mali_osk_atomic */
383 /** @defgroup _mali_osk_memory OSK Memory Allocation
386 /** @brief Allocate zero-initialized memory.
388 * Returns a buffer capable of containing at least \a n elements of \a size
389 * bytes each. The buffer is initialized to zero.
391 * If there is a need for a bigger block of memory (16KB or bigger), then
392 * consider to use _mali_osk_vmalloc() instead, as this function might
393 * map down to a OS function with size limitations.
395 * The buffer is suitably aligned for storage and subsequent access of every
396 * type that the compiler supports. Therefore, the pointer to the start of the
397 * buffer may be cast into any pointer type, and be subsequently accessed from
398 * such a pointer, without loss of information.
400 * When the buffer is no longer in use, it must be freed with _mali_osk_free().
401 * Failure to do so will cause a memory leak.
403 * @note Most toolchains supply memory allocation functions that meet the
404 * compiler's alignment requirements.
406 * @param n Number of elements to allocate
407 * @param size Size of each element
408 * @return On success, the zero-initialized buffer allocated. NULL on failure
410 void *_mali_osk_calloc( u32 n, u32 size );
412 /** @brief Allocate memory.
414 * Returns a buffer capable of containing at least \a size bytes. The
415 * contents of the buffer are undefined.
417 * If there is a need for a bigger block of memory (16KB or bigger), then
418 * consider to use _mali_osk_vmalloc() instead, as this function might
419 * map down to a OS function with size limitations.
421 * The buffer is suitably aligned for storage and subsequent access of every
422 * type that the compiler supports. Therefore, the pointer to the start of the
423 * buffer may be cast into any pointer type, and be subsequently accessed from
424 * such a pointer, without loss of information.
426 * When the buffer is no longer in use, it must be freed with _mali_osk_free().
427 * Failure to do so will cause a memory leak.
429 * @note Most toolchains supply memory allocation functions that meet the
430 * compiler's alignment requirements.
432 * Remember to free memory using _mali_osk_free().
433 * @param size Number of bytes to allocate
434 * @return On success, the buffer allocated. NULL on failure.
436 void *_mali_osk_malloc( u32 size );
438 /** @brief Free memory.
440 * Reclaims the buffer pointed to by the parameter \a ptr for the system.
441 * All memory returned from _mali_osk_malloc() and _mali_osk_calloc()
442 * must be freed before the application exits. Otherwise,
443 * a memory leak will occur.
445 * Memory must be freed once. It is an error to free the same non-NULL pointer
448 * It is legal to free the NULL pointer.
450 * @param ptr Pointer to buffer to free
452 void _mali_osk_free( void *ptr );
454 /** @brief Allocate memory.
456 * Returns a buffer capable of containing at least \a size bytes. The
457 * contents of the buffer are undefined.
459 * This function is potentially slower than _mali_osk_malloc() and _mali_osk_calloc(),
460 * but do support bigger sizes.
462 * The buffer is suitably aligned for storage and subsequent access of every
463 * type that the compiler supports. Therefore, the pointer to the start of the
464 * buffer may be cast into any pointer type, and be subsequently accessed from
465 * such a pointer, without loss of information.
467 * When the buffer is no longer in use, it must be freed with _mali_osk_free().
468 * Failure to do so will cause a memory leak.
470 * @note Most toolchains supply memory allocation functions that meet the
471 * compiler's alignment requirements.
473 * Remember to free memory using _mali_osk_free().
474 * @param size Number of bytes to allocate
475 * @return On success, the buffer allocated. NULL on failure.
477 void *_mali_osk_valloc( u32 size );
479 /** @brief Free memory.
481 * Reclaims the buffer pointed to by the parameter \a ptr for the system.
482 * All memory returned from _mali_osk_valloc() must be freed before the
483 * application exits. Otherwise a memory leak will occur.
485 * Memory must be freed once. It is an error to free the same non-NULL pointer
488 * It is legal to free the NULL pointer.
490 * @param ptr Pointer to buffer to free
492 void _mali_osk_vfree( void *ptr );
494 /** @brief Copies memory.
496 * Copies the \a len bytes from the buffer pointed by the parameter \a src
497 * directly to the buffer pointed by \a dst.
499 * It is an error for \a src to overlap \a dst anywhere in \a len bytes.
501 * @param dst Pointer to the destination array where the content is to be
503 * @param src Pointer to the source of data to be copied.
504 * @param len Number of bytes to copy.
505 * @return \a dst is always passed through unmodified.
507 void *_mali_osk_memcpy( void *dst, const void *src, u32 len );
509 /** @brief Fills memory.
511 * Sets the first \a n bytes of the block of memory pointed to by \a s to
512 * the specified value
513 * @param s Pointer to the block of memory to fill.
514 * @param c Value to be set, passed as u32. Only the 8 Least Significant Bits (LSB)
516 * @param n Number of bytes to be set to the value.
517 * @return \a s is always passed through unmodified
519 void *_mali_osk_memset( void *s, u32 c, u32 n );
520 /** @} */ /* end group _mali_osk_memory */
523 /** @brief Checks the amount of memory allocated
525 * Checks that not more than \a max_allocated bytes are allocated.
527 * Some OS bring up an interactive out of memory dialogue when the
528 * system runs out of memory. This can stall non-interactive
529 * apps (e.g. automated test runs). This function can be used to
530 * not trigger the OOM dialogue by keeping allocations
531 * within a certain limit.
533 * @return MALI_TRUE when \a max_allocated bytes are not in use yet. MALI_FALSE
534 * when at least \a max_allocated bytes are in use.
536 mali_bool _mali_osk_mem_check_allocated( u32 max_allocated );
539 /** @addtogroup _mali_osk_low_level_memory
542 /** @brief Issue a memory barrier
544 * This defines an arbitrary memory barrier operation, which forces an ordering constraint
545 * on memory read and write operations.
547 void _mali_osk_mem_barrier( void );
549 /** @brief Issue a write memory barrier
551 * This defines an write memory barrier operation which forces an ordering constraint
552 * on memory write operations.
554 void _mali_osk_write_mem_barrier( void );
556 /** @brief Map a physically contiguous region into kernel space
558 * This is primarily used for mapping in registers from resources, and Mali-MMU
559 * page tables. The mapping is only visable from kernel-space.
561 * Access has to go through _mali_osk_mem_ioread32 and _mali_osk_mem_iowrite32
563 * @param phys CPU-physical base address of the memory to map in. This must
564 * be aligned to the system's page size, which is assumed to be 4K.
565 * @param size the number of bytes of physically contiguous address space to
567 * @param description A textual description of the memory being mapped in.
568 * @return On success, a Mali IO address through which the mapped-in
569 * memory/registers can be accessed. NULL on failure.
571 mali_io_address _mali_osk_mem_mapioregion( u32 phys, u32 size, const char *description );
573 /** @brief Unmap a physically contiguous address range from kernel space.
575 * The address range should be one previously mapped in through
576 * _mali_osk_mem_mapioregion.
578 * It is a programming error to do (but not limited to) the following:
579 * - attempt an unmap twice
580 * - unmap only part of a range obtained through _mali_osk_mem_mapioregion
581 * - unmap more than the range obtained through _mali_osk_mem_mapioregion
582 * - unmap an address range that was not successfully mapped using
583 * _mali_osk_mem_mapioregion
584 * - provide a mapping that does not map to phys.
586 * @param phys CPU-physical base address of the memory that was originally
587 * mapped in. This must be aligned to the system's page size, which is assumed
589 * @param size The number of bytes that were originally mapped in.
590 * @param mapping The Mali IO address through which the mapping is
593 void _mali_osk_mem_unmapioregion( u32 phys, u32 size, mali_io_address mapping );
595 /** @brief Allocate and Map a physically contiguous region into kernel space
597 * This is used for allocating physically contiguous regions (such as Mali-MMU
598 * page tables) and mapping them into kernel space. The mapping is only
599 * visible from kernel-space.
601 * The alignment of the returned memory is guaranteed to be at least
602 * _MALI_OSK_CPU_PAGE_SIZE.
604 * Access must go through _mali_osk_mem_ioread32 and _mali_osk_mem_iowrite32
606 * @note This function is primarily to provide support for OSs that are
607 * incapable of separating the tasks 'allocate physically contiguous memory'
608 * and 'map it into kernel space'
610 * @param[out] phys CPU-physical base address of memory that was allocated.
611 * (*phys) will be guaranteed to be aligned to at least
612 * _MALI_OSK_CPU_PAGE_SIZE on success.
614 * @param[in] size the number of bytes of physically contiguous memory to
615 * allocate. This must be a multiple of _MALI_OSK_CPU_PAGE_SIZE.
617 * @return On success, a Mali IO address through which the mapped-in
618 * memory/registers can be accessed. NULL on failure, and (*phys) is unmodified.
620 mali_io_address _mali_osk_mem_allocioregion( u32 *phys, u32 size );
622 /** @brief Free a physically contiguous address range from kernel space.
624 * The address range should be one previously mapped in through
625 * _mali_osk_mem_allocioregion.
627 * It is a programming error to do (but not limited to) the following:
628 * - attempt a free twice on the same ioregion
629 * - free only part of a range obtained through _mali_osk_mem_allocioregion
630 * - free more than the range obtained through _mali_osk_mem_allocioregion
631 * - free an address range that was not successfully mapped using
632 * _mali_osk_mem_allocioregion
633 * - provide a mapping that does not map to phys.
635 * @param phys CPU-physical base address of the memory that was originally
636 * mapped in, which was aligned to _MALI_OSK_CPU_PAGE_SIZE.
637 * @param size The number of bytes that were originally mapped in, which was
638 * a multiple of _MALI_OSK_CPU_PAGE_SIZE.
639 * @param mapping The Mali IO address through which the mapping is
642 void _mali_osk_mem_freeioregion( u32 phys, u32 size, mali_io_address mapping );
644 /** @brief Request a region of physically contiguous memory
646 * This is used to ensure exclusive access to a region of physically contigous
649 * It is acceptable to implement this as a stub. However, it is then the job
650 * of the System Integrator to ensure that no other device driver will be using
651 * the physical address ranges used by Mali, while the Mali device driver is
654 * @param phys CPU-physical base address of the memory to request. This must
655 * be aligned to the system's page size, which is assumed to be 4K.
656 * @param size the number of bytes of physically contiguous address space to
658 * @param description A textual description of the memory being requested.
659 * @return _MALI_OSK_ERR_OK on success. Otherwise, a suitable
660 * _mali_osk_errcode_t on failure.
662 _mali_osk_errcode_t _mali_osk_mem_reqregion( u32 phys, u32 size, const char *description );
664 /** @brief Un-request a region of physically contiguous memory
666 * This is used to release a regious of physically contiguous memory previously
667 * requested through _mali_osk_mem_reqregion, so that other device drivers may
668 * use it. This will be called at time of Mali device driver termination.
670 * It is a programming error to attempt to:
671 * - unrequest a region twice
672 * - unrequest only part of a range obtained through _mali_osk_mem_reqregion
673 * - unrequest more than the range obtained through _mali_osk_mem_reqregion
674 * - unrequest an address range that was not successfully requested using
675 * _mali_osk_mem_reqregion
677 * @param phys CPU-physical base address of the memory to un-request. This must
678 * be aligned to the system's page size, which is assumed to be 4K
679 * @param size the number of bytes of physically contiguous address space to
682 void _mali_osk_mem_unreqregion( u32 phys, u32 size );
684 /** @brief Read from a location currently mapped in through
685 * _mali_osk_mem_mapioregion
687 * This reads a 32-bit word from a 32-bit aligned location. It is a programming
688 * error to provide unaligned locations, or to read from memory that is not
689 * mapped in, or not mapped through either _mali_osk_mem_mapioregion() or
690 * _mali_osk_mem_allocioregion().
692 * @param mapping Mali IO address to read from
693 * @param offset Byte offset from the given IO address to operate on, must be a multiple of 4
694 * @return the 32-bit word from the specified location.
696 u32 _mali_osk_mem_ioread32( volatile mali_io_address mapping, u32 offset );
698 /** @brief Write to a location currently mapped in through
699 * _mali_osk_mem_mapioregion without memory barriers
701 * This write a 32-bit word to a 32-bit aligned location without using memory barrier.
702 * It is a programming error to provide unaligned locations, or to write to memory that is not
703 * mapped in, or not mapped through either _mali_osk_mem_mapioregion() or
704 * _mali_osk_mem_allocioregion().
706 * @param mapping Mali IO address to write to
707 * @param offset Byte offset from the given IO address to operate on, must be a multiple of 4
708 * @param val the 32-bit word to write.
710 void _mali_osk_mem_iowrite32_relaxed( volatile mali_io_address addr, u32 offset, u32 val );
712 /** @brief Write to a location currently mapped in through
713 * _mali_osk_mem_mapioregion with write memory barrier
715 * This write a 32-bit word to a 32-bit aligned location. It is a programming
716 * error to provide unaligned locations, or to write to memory that is not
717 * mapped in, or not mapped through either _mali_osk_mem_mapioregion() or
718 * _mali_osk_mem_allocioregion().
720 * @param mapping Mali IO address to write to
721 * @param offset Byte offset from the given IO address to operate on, must be a multiple of 4
722 * @param val the 32-bit word to write.
724 void _mali_osk_mem_iowrite32( volatile mali_io_address mapping, u32 offset, u32 val );
726 /** @brief Flush all CPU caches
728 * This should only be implemented if flushing of the cache is required for
729 * memory mapped in through _mali_osk_mem_mapregion.
731 void _mali_osk_cache_flushall( void );
733 /** @brief Flush any caches necessary for the CPU and MALI to have the same view of a range of uncached mapped memory
735 * This should only be implemented if your OS doesn't do a full cache flush (inner & outer)
736 * after allocating uncached mapped memory.
738 * Some OS do not perform a full cache flush (including all outer caches) for uncached mapped memory.
739 * They zero the memory through a cached mapping, then flush the inner caches but not the outer caches.
740 * This is required for MALI to have the correct view of the memory.
742 void _mali_osk_cache_ensure_uncached_range_flushed( void *uncached_mapping, u32 offset, u32 size );
744 /** @} */ /* end group _mali_osk_low_level_memory */
747 /** @addtogroup _mali_osk_notification
749 * User space notification framework
751 * Communication with user space of asynchronous events is performed through a
752 * synchronous call to the \ref u_k_api.
754 * Since the events are asynchronous, the events have to be queued until a
755 * synchronous U/K API call can be made by user-space. A U/K API call might also
756 * be received before any event has happened. Therefore the notifications the
757 * different subsystems wants to send to user space has to be queued for later
758 * reception, or a U/K API call has to be blocked until an event has occured.
760 * Typical uses of notifications are after running of jobs on the hardware or
761 * when changes to the system is detected that needs to be relayed to user
764 * After an event has occured user space has to be notified using some kind of
765 * message. The notification framework supports sending messages to waiting
766 * threads or queueing of messages until a U/K API call is made.
768 * The notification queue is a FIFO. There are no restrictions on the numbers
769 * of readers or writers in the queue.
771 * A message contains what user space needs to identifiy how to handle an
772 * event. This includes a type field and a possible type specific payload.
774 * A notification to user space is represented by a
775 * \ref _mali_osk_notification_t object. A sender gets hold of such an object
776 * using _mali_osk_notification_create(). The buffer given by the
777 * _mali_osk_notification_t::result_buffer field in the object is used to store
778 * any type specific data. The other fields are internal to the queue system
779 * and should not be touched.
783 /** @brief Create a notification object
785 * Returns a notification object which can be added to the queue of
786 * notifications pending for user space transfer.
788 * The implementation will initialize all members of the
789 * \ref _mali_osk_notification_t object. In particular, the
790 * _mali_osk_notification_t::result_buffer member will be initialized to point
791 * to \a size bytes of storage, and that storage will be suitably aligned for
792 * storage of any structure. That is, the created buffer meets the same
793 * requirements as _mali_osk_malloc().
795 * The notification object must be deleted when not in use. Use
796 * _mali_osk_notification_delete() for deleting it.
798 * @note You \b must \b not call _mali_osk_free() on a \ref _mali_osk_notification_t,
799 * object, or on a _mali_osk_notification_t::result_buffer. You must only use
800 * _mali_osk_notification_delete() to free the resources assocaited with a
801 * \ref _mali_osk_notification_t object.
803 * @param type The notification type
804 * @param size The size of the type specific buffer to send
805 * @return Pointer to a notification object with a suitable buffer, or NULL on error.
807 _mali_osk_notification_t *_mali_osk_notification_create( u32 type, u32 size );
809 /** @brief Delete a notification object
811 * This must be called to reclaim the resources of a notification object. This
813 * - The _mali_osk_notification_t::result_buffer
814 * - The \ref _mali_osk_notification_t itself.
816 * A notification object \b must \b not be used after it has been deleted by
817 * _mali_osk_notification_delete().
819 * In addition, the notification object may not be deleted while it is in a
820 * queue. That is, if it has been placed on a queue with
821 * _mali_osk_notification_queue_send(), then it must not be deleted until
822 * it has been received by a call to _mali_osk_notification_queue_receive().
823 * Otherwise, the queue may be corrupted.
825 * @param object the notification object to delete.
827 void _mali_osk_notification_delete( _mali_osk_notification_t *object );
829 /** @brief Create a notification queue
831 * Creates a notification queue which can be used to queue messages for user
832 * delivery and get queued messages from
834 * The queue is a FIFO, and has no restrictions on the numbers of readers or
837 * When the queue is no longer in use, it must be terminated with
838 * \ref _mali_osk_notification_queue_term(). Failure to do so will result in a
841 * @return Pointer to a new notification queue or NULL on error.
843 _mali_osk_notification_queue_t *_mali_osk_notification_queue_init( void );
845 /** @brief Destroy a notification queue
847 * Destroys a notification queue and frees associated resources from the queue.
849 * A notification queue \b must \b not be destroyed in the following cases:
850 * - while there are \ref _mali_osk_notification_t objects in the queue.
851 * - while there are writers currently acting upon the queue. That is, while
852 * a thread is currently calling \ref _mali_osk_notification_queue_send() on
853 * the queue, or while a thread may call
854 * \ref _mali_osk_notification_queue_send() on the queue in the future.
855 * - while there are readers currently waiting upon the queue. That is, while
856 * a thread is currently calling \ref _mali_osk_notification_queue_receive() on
857 * the queue, or while a thread may call
858 * \ref _mali_osk_notification_queue_receive() on the queue in the future.
860 * Therefore, all \ref _mali_osk_notification_t objects must be flushed and
861 * deleted by the code that makes use of the notification queues, since only
862 * they know the structure of the _mali_osk_notification_t::result_buffer
863 * (even if it may only be a flat sturcture).
865 * @note Since the queue is a FIFO, the code using notification queues may
866 * create its own 'flush' type of notification, to assist in flushing the
869 * Once the queue has been destroyed, it must not be used again.
871 * @param queue The queue to destroy
873 void _mali_osk_notification_queue_term( _mali_osk_notification_queue_t *queue );
875 /** @brief Schedule notification for delivery
877 * When a \ref _mali_osk_notification_t object has been created successfully
878 * and set up, it may be added to the queue of objects waiting for user space
881 * The sending will not block if the queue is full.
883 * A \ref _mali_osk_notification_t object \b must \b not be put on two different
884 * queues at the same time, or enqueued twice onto a single queue before
885 * reception. However, it is acceptable for it to be requeued \em after reception
886 * from a call to _mali_osk_notification_queue_receive(), even onto the same queue.
888 * Again, requeuing must also not enqueue onto two different queues at the same
889 * time, or enqueue onto the same queue twice before reception.
891 * @param queue The notification queue to add this notification to
892 * @param object The entry to add
894 void _mali_osk_notification_queue_send( _mali_osk_notification_queue_t *queue, _mali_osk_notification_t *object );
896 /** @brief Receive a notification from a queue
898 * Receives a single notification from the given queue.
900 * If no notifciations are ready the thread will sleep until one becomes ready.
901 * Therefore, notifications may not be received into an
902 * IRQ or 'atomic' context (that is, a context where sleeping is disallowed).
904 * @param queue The queue to receive from
905 * @param result Pointer to storage of a pointer of type
906 * \ref _mali_osk_notification_t*. \a result will be written to such that the
907 * expression \a (*result) will evaluate to a pointer to a valid
908 * \ref _mali_osk_notification_t object, or NULL if none were received.
909 * @return _MALI_OSK_ERR_OK on success. _MALI_OSK_ERR_RESTARTSYSCALL if the sleep was interrupted.
911 _mali_osk_errcode_t _mali_osk_notification_queue_receive( _mali_osk_notification_queue_t *queue, _mali_osk_notification_t **result );
913 /** @brief Dequeues a notification from a queue
915 * Receives a single notification from the given queue.
917 * If no notifciations are ready the function call will return an error code.
919 * @param queue The queue to receive from
920 * @param result Pointer to storage of a pointer of type
921 * \ref _mali_osk_notification_t*. \a result will be written to such that the
922 * expression \a (*result) will evaluate to a pointer to a valid
923 * \ref _mali_osk_notification_t object, or NULL if none were received.
924 * @return _MALI_OSK_ERR_OK on success, _MALI_OSK_ERR_ITEM_NOT_FOUND if queue was empty.
926 _mali_osk_errcode_t _mali_osk_notification_queue_dequeue( _mali_osk_notification_queue_t *queue, _mali_osk_notification_t **result );
928 /** @} */ /* end group _mali_osk_notification */
931 /** @addtogroup _mali_osk_timer
933 * Timers use the OS's representation of time, which are 'ticks'. This is to
934 * prevent aliasing problems between the internal timer time, and the time
939 /** @brief Initialize a timer
941 * Allocates resources for a new timer, and initializes them. This does not
944 * @return a pointer to the allocated timer object, or NULL on failure.
946 _mali_osk_timer_t *_mali_osk_timer_init(void);
948 /** @brief Start a timer
950 * It is an error to start a timer without setting the callback via
951 * _mali_osk_timer_setcallback().
953 * It is an error to use this to start an already started timer.
955 * The timer will expire in \a ticks_to_expire ticks, at which point, the
956 * callback function will be invoked with the callback-specific data,
957 * as registered by _mali_osk_timer_setcallback().
959 * @param tim the timer to start
960 * @param ticks_to_expire the amount of time in ticks for the timer to run
963 void _mali_osk_timer_add( _mali_osk_timer_t *tim, u32 ticks_to_expire );
965 /** @brief Modify a timer
967 * Set the relative time at which a timer will expire, and start it if it is
968 * stopped. If \a ticks_to_expire 0 the timer fires immediately.
970 * It is an error to modify a timer without setting the callback via
971 * _mali_osk_timer_setcallback().
973 * The timer will expire at \a ticks_to_expire from the time of the call, at
974 * which point, the callback function will be invoked with the
975 * callback-specific data, as set by _mali_osk_timer_setcallback().
977 * @param tim the timer to modify, and start if necessary
978 * @param ticks_to_expire the \em absolute time in ticks at which this timer
982 void _mali_osk_timer_mod( _mali_osk_timer_t *tim, u32 ticks_to_expire);
984 /** @brief Stop a timer, and block on its completion.
986 * Stop the timer. When the function returns, it is guaranteed that the timer's
987 * callback will not be running on any CPU core.
989 * Since stoping the timer blocks on compeletion of the callback, the callback
990 * may not obtain any mutexes that the caller holds. Otherwise, a deadlock will
993 * @note While the callback itself is guaranteed to not be running, work
994 * enqueued on the work-queue by the timer (with
995 * \ref _mali_osk_wq_schedule_work()) may still run. The timer callback and
996 * work handler must take this into account.
998 * It is legal to stop an already stopped timer.
1000 * @param tim the timer to stop.
1003 void _mali_osk_timer_del( _mali_osk_timer_t *tim );
1005 /** @brief Stop a timer.
1007 * Stop the timer. When the function returns, the timer's callback may still be
1008 * running on any CPU core.
1010 * It is legal to stop an already stopped timer.
1012 * @param tim the timer to stop.
1014 void _mali_osk_timer_del_async( _mali_osk_timer_t *tim );
1016 /** @brief Check if timer is pending.
1018 * Check if timer is active.
1020 * @param tim the timer to check
1021 * @return MALI_TRUE if time is active, MALI_FALSE if it is not active
1023 mali_bool _mali_osk_timer_pending( _mali_osk_timer_t *tim);
1025 /** @brief Set a timer's callback parameters.
1027 * This must be called at least once before a timer is started/modified.
1029 * After a timer has been stopped or expires, the callback remains set. This
1030 * means that restarting the timer will call the same function with the same
1031 * parameters on expiry.
1033 * @param tim the timer to set callback on.
1034 * @param callback Function to call when timer expires
1035 * @param data Function-specific data to supply to the function on expiry.
1037 void _mali_osk_timer_setcallback( _mali_osk_timer_t *tim, _mali_osk_timer_callback_t callback, void *data );
1039 /** @brief Terminate a timer, and deallocate resources.
1041 * The timer must first be stopped by calling _mali_osk_timer_del().
1043 * It is a programming error for _mali_osk_timer_term() to be called on:
1044 * - timer that is currently running
1045 * - a timer that is currently executing its callback.
1047 * @param tim the timer to deallocate.
1049 void _mali_osk_timer_term( _mali_osk_timer_t *tim );
1050 /** @} */ /* end group _mali_osk_timer */
1053 /** @defgroup _mali_osk_time OSK Time functions
1055 * \ref _mali_osk_time use the OS's representation of time, which are
1056 * 'ticks'. This is to prevent aliasing problems between the internal timer
1057 * time, and the time asked for.
1059 * OS tick time is measured as a u32. The time stored in a u32 may either be
1060 * an absolute time, or a time delta between two events. Whilst it is valid to
1061 * use math opeartors to \em change the tick value represented as a u32, it
1062 * is often only meaningful to do such operations on time deltas, rather than
1063 * on absolute time. However, it is meaningful to add/subtract time deltas to
1066 * Conversion between tick time and milliseconds (ms) may not be loss-less,
1067 * and are \em implementation \em depenedant.
1069 * Code use OS time must take this into account, since:
1070 * - a small OS time may (or may not) be rounded
1071 * - a large time may (or may not) overflow
1075 /** @brief Return whether ticka occurs after tickb
1077 * Some OSs handle tick 'rollover' specially, and so can be more robust against
1078 * tick counters rolling-over. This function must therefore be called to
1079 * determine if a time (in ticks) really occurs after another time (in ticks).
1081 * @param ticka ticka
1082 * @param tickb tickb
1083 * @return non-zero if ticka represents a time that occurs after tickb.
1086 int _mali_osk_time_after( u32 ticka, u32 tickb );
1088 /** @brief Convert milliseconds to OS 'ticks'
1090 * @param ms time interval in milliseconds
1091 * @return the corresponding time interval in OS ticks.
1093 u32 _mali_osk_time_mstoticks( u32 ms );
1095 /** @brief Convert OS 'ticks' to milliseconds
1097 * @param ticks time interval in OS ticks.
1098 * @return the corresponding time interval in milliseconds
1100 u32 _mali_osk_time_tickstoms( u32 ticks );
1103 /** @brief Get the current time in OS 'ticks'.
1104 * @return the current time in OS 'ticks'.
1106 u32 _mali_osk_time_tickcount( void );
1108 /** @brief Cause a microsecond delay
1110 * The delay will have microsecond resolution, and is necessary for correct
1111 * operation of the driver. At worst, the delay will be \b at least \a usecs
1112 * microseconds, and so may be (significantly) more.
1114 * This function may be implemented as a busy-wait, which is the most sensible
1115 * implementation. On OSs where there are situations in which a thread must not
1116 * sleep, this is definitely implemented as a busy-wait.
1118 * @param usecs the number of microseconds to wait for.
1120 void _mali_osk_time_ubusydelay( u32 usecs );
1122 /** @brief Return time in nano seconds, since any given reference.
1124 * @return Time in nano seconds
1126 u64 _mali_osk_time_get_ns( void );
1129 /** @} */ /* end group _mali_osk_time */
1131 /** @defgroup _mali_osk_math OSK Math
1134 /** @brief Count Leading Zeros (Little-endian)
1136 * @note This function must be implemented to support the reference
1137 * implementation of _mali_osk_find_first_zero_bit, as defined in
1138 * mali_osk_bitops.h.
1140 * @param val 32-bit words to count leading zeros on
1141 * @return the number of leading zeros.
1143 u32 _mali_osk_clz( u32 val );
1145 /** @brief find last (most-significant) bit set
1147 * @param val 32-bit words to count last bit set on
1148 * @return last bit set.
1150 u32 _mali_osk_fls( u32 val );
1152 /** @} */ /* end group _mali_osk_math */
1154 /** @addtogroup _mali_osk_wait_queue OSK Wait Queue functionality
1157 /** @brief Initialize an empty Wait Queue */
1158 _mali_osk_wait_queue_t* _mali_osk_wait_queue_init( void );
1160 /** @brief Sleep if condition is false
1162 * @param queue the queue to use
1163 * @param condition function pointer to a boolean function
1164 * @param data data parameter for condition function
1166 * Put thread to sleep if the given \a condition function returns false. When
1167 * being asked to wake up again, the condition will be re-checked and the
1168 * thread only woken up if the condition is now true.
1170 void _mali_osk_wait_queue_wait_event( _mali_osk_wait_queue_t *queue, mali_bool (*condition)(void *), void *data );
1172 /** @brief Sleep if condition is false
1174 * @param queue the queue to use
1175 * @param condition function pointer to a boolean function
1176 * @param data data parameter for condition function
1177 * @param timeout timeout in ms
1179 * Put thread to sleep if the given \a condition function returns false. When
1180 * being asked to wake up again, the condition will be re-checked and the
1181 * thread only woken up if the condition is now true. Will return if time
1184 void _mali_osk_wait_queue_wait_event_timeout( _mali_osk_wait_queue_t *queue, mali_bool (*condition)(void *), void *data, u32 timeout );
1186 /** @brief Wake up all threads in wait queue if their respective conditions are
1189 * @param queue the queue whose threads should be woken up
1191 * Wake up all threads in wait queue \a queue whose condition is now true.
1193 void _mali_osk_wait_queue_wake_up( _mali_osk_wait_queue_t *queue );
1195 /** @brief terminate a wait queue
1197 * @param queue the queue to terminate.
1199 void _mali_osk_wait_queue_term( _mali_osk_wait_queue_t *queue );
1200 /** @} */ /* end group _mali_osk_wait_queue */
1203 /** @addtogroup _mali_osk_miscellaneous
1206 /** @brief Output a device driver debug message.
1208 * The interpretation of \a fmt is the same as the \c format parameter in
1209 * _mali_osu_vsnprintf().
1211 * @param fmt a _mali_osu_vsnprintf() style format string
1212 * @param ... a variable-number of parameters suitable for \a fmt
1214 void _mali_osk_dbgmsg( const char *fmt, ... );
1216 /** @brief Print fmt into buf.
1218 * The interpretation of \a fmt is the same as the \c format parameter in
1219 * _mali_osu_vsnprintf().
1221 * @param buf a pointer to the result buffer
1222 * @param size the total number of bytes allowed to write to \a buf
1223 * @param fmt a _mali_osu_vsnprintf() style format string
1224 * @param ... a variable-number of parameters suitable for \a fmt
1225 * @return The number of bytes written to \a buf
1227 u32 _mali_osk_snprintf( char *buf, u32 size, const char *fmt, ... );
1229 /** @brief Abnormal process abort.
1231 * Terminates the caller-process if this function is called.
1233 * This function will be called from Debug assert-macros in mali_kernel_common.h.
1235 * This function will never return - because to continue from a Debug assert
1236 * could cause even more problems, and hinder debugging of the initial problem.
1238 * This function is only used in Debug builds, and is not used in Release builds.
1240 void _mali_osk_abort(void);
1242 /** @brief Sets breakpoint at point where function is called.
1244 * This function will be called from Debug assert-macros in mali_kernel_common.h,
1245 * to assist in debugging. If debugging at this level is not required, then this
1246 * function may be implemented as a stub.
1248 * This function is only used in Debug builds, and is not used in Release builds.
1250 void _mali_osk_break(void);
1252 /** @brief Return an identificator for calling process.
1254 * @return Identificator for calling process.
1256 u32 _mali_osk_get_pid(void);
1258 /** @brief Return an identificator for calling thread.
1260 * @return Identificator for calling thread.
1262 u32 _mali_osk_get_tid(void);
1264 /** @brief Enable OS controlled runtime power management
1266 void _mali_osk_pm_dev_enable(void);
1268 /** @brief Disable OS controlled runtime power management
1270 void _mali_osk_pm_dev_disable(void);
1273 /** @brief Take a reference to the power manager system for the Mali device.
1275 * When function returns successfully, Mali is ON.
1277 * @note Call \a _mali_osk_pm_dev_ref_dec() to release this reference.
1279 _mali_osk_errcode_t _mali_osk_pm_dev_ref_add(void);
1282 /** @brief Release the reference to the power manger system for the Mali device.
1284 * When reference count reach zero, the cores can be off.
1286 * @note This must be used to release references taken with \a _mali_osk_pm_dev_ref_add().
1288 void _mali_osk_pm_dev_ref_dec(void);
1291 /** @brief Take a reference to the power manager system for the Mali device.
1293 * Will leave the cores powered off if they are already powered off.
1295 * @note Call \a _mali_osk_pm_dev_ref_dec() to release this reference.
1297 * @return MALI_TRUE if the Mali GPU is powered on, otherwise MALI_FALSE.
1299 mali_bool _mali_osk_pm_dev_ref_add_no_power_on(void);
1302 /** @brief Releasing the reference to the power manger system for the Mali device.
1304 * When reference count reach zero, the cores can be off.
1306 * @note This must be used to release references taken with \a _mali_osk_pm_dev_ref_add_no_power_on().
1308 void _mali_osk_pm_dev_ref_dec_no_power_on(void);
1310 /** @brief Block untill pending PM operations are done
1312 void _mali_osk_pm_dev_barrier(void);
1314 /** @} */ /* end group _mali_osk_miscellaneous */
1316 /** @} */ /* end group osuapi */
1318 /** @} */ /* end group uddapi */
1326 /* Check standard inlines */
1327 #ifndef MALI_STATIC_INLINE
1328 #error MALI_STATIC_INLINE not defined on your OS
1331 #ifndef MALI_NON_STATIC_INLINE
1332 #error MALI_NON_STATIC_INLINE not defined on your OS
1335 #endif /* __MALI_OSK_H__ */