PageRenderTime 34ms CodeModel.GetById 18ms app.highlight 10ms RepoModel.GetById 0ms app.codeStats 0ms

/drivers/gpu/mali/mali/common/mali_osk.h

https://bitbucket.org/ndreys/linux-sunxi
C++ Header | 1798 lines | 249 code | 185 blank | 1364 comment | 3 complexity | 139486b4bafa7eb97ee81909e2759f94 MD5 | raw file
Possible License(s): GPL-2.0, LGPL-2.0, AGPL-1.0

Large files files are truncated, but you can click here to view the full file

   1/*
   2 * Copyright (C) 2010-2012 ARM Limited. All rights reserved.
   3 * 
   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.
   6 * 
   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.
   9 */
  10
  11/**
  12 * @file mali_osk.h
  13 * Defines the OS abstraction layer for the kernel device driver (OSK)
  14 */
  15
  16#ifndef __MALI_OSK_H__
  17#define __MALI_OSK_H__
  18
  19#ifdef __cplusplus
  20extern "C"
  21{
  22#endif
  23
  24/**
  25 * @addtogroup uddapi Unified Device Driver (UDD) APIs
  26 *
  27 * @{
  28 */
  29
  30/**
  31 * @addtogroup oskapi UDD OS Abstraction for Kernel-side (OSK) APIs
  32 *
  33 * @{
  34 */
  35
  36/** @defgroup _mali_osk_miscellaneous OSK Miscellaneous functions, constants and types
  37 * @{ */
  38
  39/* Define integer types used by OSK. Note: these currently clash with Linux so we only define them if not defined already */
  40#ifndef __KERNEL__
  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)
  49#else
  50	/* Ensure Linux types u32, etc. are defined */
  51	#include <linux/types.h>
  52#endif
  53
  54/** @brief Mali Boolean type which uses MALI_TRUE and MALI_FALSE
  55  */
  56	typedef unsigned long mali_bool;
  57
  58#ifndef MALI_TRUE
  59	#define MALI_TRUE ((mali_bool)1)
  60#endif
  61
  62#ifndef MALI_FALSE
  63	#define MALI_FALSE ((mali_bool)0)
  64#endif
  65
  66/**
  67 * @brief OSK Error codes
  68 *
  69 * Each OS may use its own set of error codes, and may require that the
  70 * User/Kernel interface take certain error code. This means that the common
  71 * error codes need to be sufficiently rich to pass the correct error code
  72 * thorugh from the OSK to U/K layer, across all OSs.
  73 *
  74 * The result is that some error codes will appear redundant on some OSs.
  75 * Under all OSs, the OSK layer must translate native OS error codes to
  76 * _mali_osk_errcode_t codes. Similarly, the U/K layer must translate from
  77 * _mali_osk_errcode_t codes to native OS error codes.
  78 */
  79typedef enum
  80{
  81    _MALI_OSK_ERR_OK = 0, /**< Success. */
  82    _MALI_OSK_ERR_FAULT = -1, /**< General non-success */
  83    _MALI_OSK_ERR_INVALID_FUNC = -2, /**< Invalid function requested through User/Kernel interface (e.g. bad IOCTL number) */
  84    _MALI_OSK_ERR_INVALID_ARGS = -3, /**< Invalid arguments passed through User/Kernel interface */
  85    _MALI_OSK_ERR_NOMEM = -4, /**< Insufficient memory */
  86    _MALI_OSK_ERR_TIMEOUT = -5, /**< Timeout occurred */
  87    _MALI_OSK_ERR_RESTARTSYSCALL = -6, /**< Special: On certain OSs, must report when an interruptable mutex is interrupted. Ignore otherwise. */
  88    _MALI_OSK_ERR_ITEM_NOT_FOUND = -7, /**< Table Lookup failed */
  89    _MALI_OSK_ERR_BUSY = -8, /**< Device/operation is busy. Try again later */
  90	_MALI_OSK_ERR_UNSUPPORTED = -9, /**< Optional part of the interface used, and is unsupported */
  91} _mali_osk_errcode_t;
  92
  93/** @} */ /* end group _mali_osk_miscellaneous */
  94
  95
  96/** @defgroup _mali_osk_irq OSK IRQ handling
  97 * @{ */
  98
  99/** @brief Private type for IRQ handling objects */
 100typedef struct _mali_osk_irq_t_struct _mali_osk_irq_t;
 101
 102/** @brief Optional function to trigger an irq from a resource
 103 *
 104 * This function is implemented by the common layer to allow probing of a resource's IRQ.
 105 * @param arg resource-specific data */
 106typedef void  (*_mali_osk_irq_trigger_t)( void * arg );
 107
 108/** @brief Optional function to acknowledge an irq from a resource
 109 *
 110 * This function is implemented by the common layer to allow probing of a resource's IRQ.
 111 * @param arg resource-specific data
 112 * @return _MALI_OSK_ERR_OK if the IRQ was successful, or a suitable _mali_osk_errcode_t on failure. */
 113typedef _mali_osk_errcode_t (*_mali_osk_irq_ack_t)( void * arg );
 114
 115/** @brief IRQ 'upper-half' handler callback.
 116 *
 117 * This function is implemented by the common layer to do the initial handling of a
 118 * resource's IRQ. This maps on to the concept of an ISR that does the minimum
 119 * work necessary before handing off to an IST.
 120 *
 121 * The communication of the resource-specific data from the ISR to the IST is
 122 * handled by the OSK implementation.
 123 *
 124 * On most systems, the IRQ upper-half handler executes in IRQ context.
 125 * Therefore, the system may have restrictions about what can be done in this
 126 * context
 127 *
 128 * If an IRQ upper-half handler requires more work to be done than can be
 129 * acheived in an IRQ context, then it may defer the work with
 130 * _mali_osk_irq_schedulework(). Refer to \ref _mali_osk_irq_schedulework() for
 131 * more information.
 132 *
 133 * @param arg resource-specific data
 134 * @return _MALI_OSK_ERR_OK if the IRQ was correctly handled, or a suitable
 135 * _mali_osk_errcode_t otherwise.
 136 */
 137typedef _mali_osk_errcode_t  (*_mali_osk_irq_uhandler_t)( void * arg );
 138
 139/** @brief IRQ 'bottom-half' handler callback.
 140 *
 141 * This function is implemented by the common layer to do the deferred handling
 142 * of a resource's IRQ. Usually, this work cannot be carried out in IRQ context
 143 * by the IRQ upper-half handler.
 144 *
 145 * The IRQ bottom-half handler maps on to the concept of an IST that may
 146 * execute some time after the actual IRQ has fired.
 147 *
 148 * All OSK-registered IRQ bottom-half handlers will be serialized, across all
 149 * CPU-cores in the system.
 150 *
 151 * Refer to \ref _mali_osk_irq_schedulework() for more information on the
 152 * IRQ work-queue, and the calling of the IRQ bottom-half handler.
 153 *
 154 * @param arg resource-specific data
 155 */
 156typedef void (*_mali_osk_irq_bhandler_t)( void * arg );
 157/** @} */ /* end group _mali_osk_irq */
 158
 159
 160/** @defgroup _mali_osk_atomic OSK Atomic counters
 161 * @{ */
 162
 163/** @brief Public type of atomic counters
 164 *
 165 * This is public for allocation on stack. On systems that support it, this is just a single 32-bit value.
 166 * On others, it could be encapsulating an object stored elsewhere.
 167 *
 168 * Regardless of implementation, the \ref _mali_osk_atomic functions \b must be used
 169 * for all accesses to the variable's value, even if atomicity is not required.
 170 * Do not access u.val or u.obj directly.
 171 */
 172typedef struct
 173{
 174    union
 175    {
 176        u32 val;
 177        void *obj;
 178    } u;
 179} _mali_osk_atomic_t;
 180/** @} */ /* end group _mali_osk_atomic */
 181
 182
 183/** @defgroup _mali_osk_lock OSK Mutual Exclusion Locks
 184 * @{ */
 185
 186
 187/** @brief OSK Mutual Exclusion Lock ordered list
 188 *
 189 * This lists the various types of locks in the system and is used to check
 190 * that locks are taken in the correct order.
 191 *
 192 * Holding more than one lock of the same order at the same time is not
 193 * allowed.
 194 *
 195 */
 196typedef enum
 197{
 198	_MALI_OSK_LOCK_ORDER_LAST = 0,
 199
 200	_MALI_OSK_LOCK_ORDER_PM_EXECUTE,
 201	_MALI_OSK_LOCK_ORDER_UTILIZATION,
 202	_MALI_OSK_LOCK_ORDER_L2_COUNTER,
 203	_MALI_OSK_LOCK_ORDER_PROFILING,
 204	_MALI_OSK_LOCK_ORDER_L2_COMMAND,
 205	_MALI_OSK_LOCK_ORDER_PM_CORE_STATE,
 206	_MALI_OSK_LOCK_ORDER_GROUP,
 207	_MALI_OSK_LOCK_ORDER_SCHEDULER,
 208
 209	_MALI_OSK_LOCK_ORDER_DESCRIPTOR_MAP,
 210	_MALI_OSK_LOCK_ORDER_MEM_PT_CACHE,
 211	_MALI_OSK_LOCK_ORDER_MEM_INFO,
 212	_MALI_OSK_LOCK_ORDER_MEM_SESSION,
 213
 214	_MALI_OSK_LOCK_ORDER_SESSIONS,
 215
 216	_MALI_OSK_LOCK_ORDER_FIRST
 217} _mali_osk_lock_order_t;
 218
 219
 220/** @brief OSK Mutual Exclusion Lock flags type
 221 *
 222 * Flags are supplied at the point where the Lock is initialized. Each flag can
 223 * be combined with others using bitwise OR, '|'.
 224 *
 225 * The flags must be sufficiently rich to cope with all our OSs. This means
 226 * that on some OSs, certain flags can be completely ignored. We define a
 227 * number of terms that are significant across all OSs:
 228 *
 229 * - Sleeping/non-sleeping mutexs. Sleeping mutexs can block on waiting, and so
 230 * schedule out the current thread. This is significant on OSs where there are
 231 * situations in which the current thread must not be put to sleep. On OSs
 232 * without this restriction, sleeping and non-sleeping mutexes can be treated
 233 * as the same (if that is required).
 234 * - Interruptable/non-interruptable mutexes. For sleeping mutexes, it may be
 235 * possible for the sleep to be interrupted for a reason other than the thread
 236 * being able to obtain the lock. OSs behaving in this way may provide a
 237 * mechanism to control whether sleeping mutexes can be interrupted. On OSs
 238 * that do not support the concept of interruption, \b or they do not support
 239 * control of mutex interruption, then interruptable mutexes may be treated
 240 * as non-interruptable.
 241 *
 242 * Some constrains apply to the lock type flags:
 243 *
 244 * - Spinlocks are by nature, non-interruptable. Hence, they must always be
 245 * combined with the NONINTERRUPTABLE flag, because it is meaningless to ask
 246 * for a spinlock that is interruptable (and this highlights its
 247 * non-interruptable-ness). For example, on certain OSs they should be used when
 248 * you must not sleep.
 249 * - Reader/writer is an optimization hint, and any type of lock can be
 250 * reader/writer. Since this is an optimization hint, the implementation need
 251 * not respect this for any/all types of lock. For example, on certain OSs,
 252 * there's no interruptable reader/writer mutex. If such a thing were requested
 253 * on that OS, the fact that interruptable was requested takes priority over the
 254 * reader/writer-ness, because reader/writer-ness is not necessary for correct
 255 * operation.
 256 * - Any lock can use the order parameter.
 257 * - A onelock is an optimization hint specific to certain OSs. It can be
 258 * specified when it is known that only one lock will be held by the thread,
 259 * and so can provide faster mutual exclusion. This can be safely ignored if
 260 * such optimization is not required/present.
 261 *
 262 * The absence of any flags (the value 0) results in a sleeping-mutex, which is interruptable.
 263 */
 264typedef enum
 265{
 266	_MALI_OSK_LOCKFLAG_SPINLOCK = 0x1,          /**< Specifically, don't sleep on those architectures that require it */
 267	_MALI_OSK_LOCKFLAG_NONINTERRUPTABLE = 0x2,  /**< The mutex cannot be interrupted, e.g. delivery of signals on those architectures where this is required */
 268	_MALI_OSK_LOCKFLAG_READERWRITER = 0x4,      /**< Optimise for readers/writers */
 269	_MALI_OSK_LOCKFLAG_ORDERED = 0x8,           /**< Use the order parameter; otherwise use automatic ordering */
 270	_MALI_OSK_LOCKFLAG_ONELOCK = 0x10,          /**< Each thread can only hold one lock at a time */
 271	_MALI_OSK_LOCKFLAG_SPINLOCK_IRQ = 0x20,    /**<  IRQ version of spinlock */
 272	/** @enum _mali_osk_lock_flags_t
 273	 *
 274	 * Flags from 0x10000--0x80000000 are RESERVED for User-mode */
 275
 276} _mali_osk_lock_flags_t;
 277
 278/** @brief Mutual Exclusion Lock Mode Optimization hint
 279 *
 280 * The lock mode is used to implement the read/write locking of locks specified
 281 * as _MALI_OSK_LOCKFLAG_READERWRITER. In this case, the RO mode can be used
 282 * to allow multiple concurrent readers, but no writers. The RW mode is used for
 283 * writers, and so will wait for all readers to release the lock (if any present).
 284 * Further readers and writers will wait until the writer releases the lock.
 285 *
 286 * The mode is purely an optimization hint: for example, it is permissible for
 287 * all locks to behave in RW mode, regardless of that supplied.
 288 *
 289 * It is an error to attempt to use locks in anything other that RW mode when
 290 * _MALI_OSK_LOCKFLAG_READERWRITER is not supplied.
 291 *
 292 */
 293typedef enum
 294{
 295	_MALI_OSK_LOCKMODE_UNDEF = -1,  /**< Undefined lock mode. For internal use only */
 296	_MALI_OSK_LOCKMODE_RW    = 0x0, /**< Read-write mode, default. All readers and writers are mutually-exclusive */
 297	_MALI_OSK_LOCKMODE_RO,          /**< Read-only mode, to support multiple concurrent readers, but mutual exclusion in the presence of writers. */
 298	/** @enum _mali_osk_lock_mode_t
 299	 *
 300	 * Lock modes 0x40--0x7F are RESERVED for User-mode */
 301} _mali_osk_lock_mode_t;
 302
 303/** @brief Private type for Mutual Exclusion lock objects */
 304typedef struct _mali_osk_lock_t_struct _mali_osk_lock_t;
 305
 306#ifdef DEBUG
 307/** @brief Macro for asserting that the current thread holds a given lock
 308 */
 309#define MALI_DEBUG_ASSERT_LOCK_HELD(l) MALI_DEBUG_ASSERT(_mali_osk_lock_get_owner(l) == _mali_osk_get_tid());
 310
 311/** @brief returns a lock's owner (thread id) if debugging is enabled
 312 */
 313u32 _mali_osk_lock_get_owner( _mali_osk_lock_t *lock );
 314#endif
 315
 316/** @} */ /* end group _mali_osk_lock */
 317
 318/** @defgroup _mali_osk_low_level_memory OSK Low-level Memory Operations
 319 * @{ */
 320
 321/**
 322 * @brief Private data type for use in IO accesses to/from devices.
 323 *
 324 * This represents some range that is accessible from the device. Examples
 325 * include:
 326 * - Device Registers, which could be readable and/or writeable.
 327 * - Memory that the device has access to, for storing configuration structures.
 328 *
 329 * Access to this range must be made through the _mali_osk_mem_ioread32() and
 330 * _mali_osk_mem_iowrite32() functions.
 331 */
 332typedef struct _mali_io_address * mali_io_address;
 333
 334/** @defgroup _MALI_OSK_CPU_PAGE CPU Physical page size macros.
 335 *
 336 * The order of the page size is supplied for
 337 * ease of use by algorithms that might require it, since it is easier to know
 338 * it ahead of time rather than calculating it.
 339 *
 340 * The Mali Page Mask macro masks off the lower bits of a physical address to
 341 * give the start address of the page for that physical address.
 342 *
 343 * @note The Mali device driver code is designed for systems with 4KB page size.
 344 * Changing these macros will not make the entire Mali device driver work with
 345 * page sizes other than 4KB.
 346 *
 347 * @note The CPU Physical Page Size has been assumed to be the same as the Mali
 348 * Physical Page Size.
 349 *
 350 * @{
 351 */
 352
 353/** CPU Page Order, as log to base 2 of the Page size. @see _MALI_OSK_CPU_PAGE_SIZE */
 354#define _MALI_OSK_CPU_PAGE_ORDER ((u32)12)
 355/** CPU Page Size, in bytes.               */
 356#define _MALI_OSK_CPU_PAGE_SIZE (((u32)1) << (_MALI_OSK_CPU_PAGE_ORDER))
 357/** CPU Page Mask, which masks off the offset within a page */
 358#define _MALI_OSK_CPU_PAGE_MASK (~((((u32)1) << (_MALI_OSK_CPU_PAGE_ORDER)) - ((u32)1)))
 359/** @} */ /* end of group _MALI_OSK_CPU_PAGE */
 360
 361/** @defgroup _MALI_OSK_MALI_PAGE Mali Physical Page size macros
 362 *
 363 * Mali Physical page size macros. The order of the page size is supplied for
 364 * ease of use by algorithms that might require it, since it is easier to know
 365 * it ahead of time rather than calculating it.
 366 *
 367 * The Mali Page Mask macro masks off the lower bits of a physical address to
 368 * give the start address of the page for that physical address.
 369 *
 370 * @note The Mali device driver code is designed for systems with 4KB page size.
 371 * Changing these macros will not make the entire Mali device driver work with
 372 * page sizes other than 4KB.
 373 *
 374 * @note The Mali Physical Page Size has been assumed to be the same as the CPU
 375 * Physical Page Size.
 376 *
 377 * @{
 378 */
 379
 380/** Mali Page Order, as log to base 2 of the Page size. @see _MALI_OSK_MALI_PAGE_SIZE */
 381#define _MALI_OSK_MALI_PAGE_ORDER ((u32)12)
 382/** Mali Page Size, in bytes.               */
 383#define _MALI_OSK_MALI_PAGE_SIZE (((u32)1) << (_MALI_OSK_MALI_PAGE_ORDER))
 384/** Mali Page Mask, which masks off the offset within a page */
 385#define _MALI_OSK_MALI_PAGE_MASK (~((((u32)1) << (_MALI_OSK_MALI_PAGE_ORDER)) - ((u32)1)))
 386/** @} */ /* end of group _MALI_OSK_MALI_PAGE*/
 387
 388/** @brief flags for mapping a user-accessible memory range
 389 *
 390 * Where a function with prefix '_mali_osk_mem_mapregion' accepts flags as one
 391 * of the function parameters, it will use one of these. These allow per-page
 392 * control over mappings. Compare with the mali_memory_allocation_flag type,
 393 * which acts over an entire range
 394 *
 395 * These may be OR'd together with bitwise OR (|), but must be cast back into
 396 * the type after OR'ing.
 397 */
 398typedef enum
 399{
 400	_MALI_OSK_MEM_MAPREGION_FLAG_OS_ALLOCATED_PHYSADDR = 0x1, /**< Physical address is OS Allocated */
 401} _mali_osk_mem_mapregion_flags_t;
 402/** @} */ /* end group _mali_osk_low_level_memory */
 403
 404/** @defgroup _mali_osk_notification OSK Notification Queues
 405 * @{ */
 406
 407/** @brief Private type for notification queue objects */
 408typedef struct _mali_osk_notification_queue_t_struct _mali_osk_notification_queue_t;
 409
 410/** @brief Public notification data object type */
 411typedef struct _mali_osk_notification_t_struct
 412{
 413	u32 notification_type;   /**< The notification type */
 414	u32 result_buffer_size; /**< Size of the result buffer to copy to user space */
 415	void * result_buffer;   /**< Buffer containing any type specific data */
 416} _mali_osk_notification_t;
 417
 418/** @} */ /* end group _mali_osk_notification */
 419
 420
 421/** @defgroup _mali_osk_timer OSK Timer Callbacks
 422 * @{ */
 423
 424/** @brief Function to call when a timer expires
 425 *
 426 * When a timer expires, this function is called. Note that on many systems,
 427 * a timer callback will be executed in IRQ context. Therefore, restrictions
 428 * may apply on what can be done inside the timer callback.
 429 *
 430 * If a timer requires more work to be done than can be acheived in an IRQ
 431 * context, then it may defer the work with a work-queue. For example, it may
 432 * use \ref _mali_osk_irq_schedulework() to make use of the IRQ bottom-half handler
 433 * to carry out the remaining work.
 434 *
 435 * Stopping the timer with \ref _mali_osk_timer_del() blocks on compeletion of
 436 * the callback. Therefore, the callback may not obtain any mutexes also held
 437 * by any callers of _mali_osk_timer_del(). Otherwise, a deadlock may occur.
 438 *
 439 * @param arg Function-specific data */
 440typedef void (*_mali_osk_timer_callback_t)(void * arg );
 441
 442/** @brief Private type for Timer Callback Objects */
 443typedef struct _mali_osk_timer_t_struct _mali_osk_timer_t;
 444/** @} */ /* end group _mali_osk_timer */
 445
 446
 447/** @addtogroup _mali_osk_list OSK Doubly-Linked Circular Lists
 448 * @{ */
 449
 450/** @brief Public List objects.
 451 *
 452 * To use, add a _mali_osk_list_t member to the structure that may become part
 453 * of a list. When traversing the _mali_osk_list_t objects, use the
 454 * _MALI_OSK_CONTAINER_OF() macro to recover the structure from its
 455 *_mali_osk_list_t member
 456 *
 457 * Each structure may have multiple _mali_osk_list_t members, so that the
 458 * structure is part of multiple lists. When traversing lists, ensure that the
 459 * correct _mali_osk_list_t member is used, because type-checking will be
 460 * lost by the compiler.
 461 */
 462typedef struct _mali_osk_list_s
 463{
 464	struct _mali_osk_list_s *next;
 465	struct _mali_osk_list_s *prev;
 466} _mali_osk_list_t;
 467
 468/** @brief Initialize a list to be a head of an empty list
 469 * @param exp the list to initialize. */
 470#define _MALI_OSK_INIT_LIST_HEAD(exp) _mali_osk_list_init(exp)
 471
 472/** @brief Define a list variable, which is uninitialized.
 473 * @param exp the name of the variable that the list will be defined as. */
 474#define _MALI_OSK_LIST_HEAD(exp)      _mali_osk_list_t exp
 475
 476/** @brief Find the containing structure of another structure
 477 *
 478 * This is the reverse of the operation 'offsetof'. This means that the
 479 * following condition is satisfied:
 480 *
 481 *   ptr == _MALI_OSK_CONTAINER_OF( &ptr->member, type, member )
 482 *
 483 * When ptr is of type 'type'.
 484 *
 485 * Its purpose it to recover a larger structure that has wrapped a smaller one.
 486 *
 487 * @note no type or memory checking occurs to ensure that a wrapper structure
 488 * does in fact exist, and that it is being recovered with respect to the
 489 * correct member.
 490 *
 491 * @param ptr the pointer to the member that is contained within the larger
 492 * structure
 493 * @param type the type of the structure that contains the member
 494 * @param member the name of the member in the structure that ptr points to.
 495 * @return a pointer to a \a type object which contains \a member, as pointed
 496 * to by \a ptr.
 497 */
 498#define _MALI_OSK_CONTAINER_OF(ptr, type, member) \
 499             ((type *)( ((char *)ptr) - offsetof(type,member) ))
 500
 501/** @brief Find the containing structure of a list
 502 *
 503 * When traversing a list, this is used to recover the containing structure,
 504 * given that is contains a _mali_osk_list_t member.
 505 *
 506 * Each list must be of structures of one type, and must link the same members
 507 * together, otherwise it will not be possible to correctly recover the
 508 * sturctures that the lists link.
 509 *
 510 * @note no type or memory checking occurs to ensure that a structure does in
 511 * fact exist for the list entry, and that it is being recovered with respect
 512 * to the correct list member.
 513 *
 514 * @param ptr the pointer to the _mali_osk_list_t member in this structure
 515 * @param type the type of the structure that contains the member
 516 * @param member the member of the structure that ptr points to.
 517 * @return a pointer to a \a type object which contains the _mali_osk_list_t
 518 * \a member, as pointed to by the _mali_osk_list_t \a *ptr.
 519 */
 520#define _MALI_OSK_LIST_ENTRY(ptr, type, member) \
 521            _MALI_OSK_CONTAINER_OF(ptr, type, member)
 522
 523/** @brief Enumerate a list safely
 524 *
 525 * With this macro, lists can be enumerated in a 'safe' manner. That is,
 526 * entries can be deleted from the list without causing an error during
 527 * enumeration. To achieve this, a 'temporary' pointer is required, which must
 528 * be provided to the macro.
 529 *
 530 * Use it like a 'for()', 'while()' or 'do()' construct, and so it must be
 531 * followed by a statement or compound-statement which will be executed for
 532 * each list entry.
 533 *
 534 * Upon loop completion, providing that an early out was not taken in the
 535 * loop body, then it is guaranteed that ptr->member == list, even if the loop
 536 * body never executed.
 537 *
 538 * @param ptr a pointer to an object of type 'type', which points to the
 539 * structure that contains the currently enumerated list entry.
 540 * @param tmp a pointer to an object of type 'type', which must not be used
 541 * inside the list-execution statement.
 542 * @param list a pointer to a _mali_osk_list_t, from which enumeration will
 543 * begin
 544 * @param type the type of the structure that contains the _mali_osk_list_t
 545 * member that is part of the list to be enumerated.
 546 * @param member the _mali_osk_list_t member of the structure that is part of
 547 * the list to be enumerated.
 548 */
 549#define _MALI_OSK_LIST_FOREACHENTRY(ptr, tmp, list, type, member)         \
 550        for (ptr = _MALI_OSK_LIST_ENTRY((list)->next, type, member),      \
 551             tmp = _MALI_OSK_LIST_ENTRY(ptr->member.next, type, member); \
 552             &ptr->member != (list);                                    \
 553             ptr = tmp, tmp = _MALI_OSK_LIST_ENTRY(tmp->member.next, type, member))
 554/** @} */ /* end group _mali_osk_list */
 555
 556
 557/** @addtogroup _mali_osk_miscellaneous
 558 * @{ */
 559
 560/** @brief The known resource types
 561 *
 562 * @note \b IMPORTANT: these must remain fixed, and only be extended. This is
 563 * because not all systems use a header file for reading in their resources.
 564 * The resources may instead come from a data file where these resources are
 565 * 'hard-coded' in, because there's no easy way of transferring the enum values
 566 * into such data files. E.g. the C-Pre-processor does \em not process enums.
 567 */
 568typedef enum _mali_osk_resource_type
 569{
 570	RESOURCE_TYPE_FIRST =0,  /**< Duplicate resource marker for the first resource*/
 571
 572	MEMORY              =0,  /**< Physically contiguous memory block, not managed by the OS */
 573	OS_MEMORY           =1,  /**< Memory managed by and shared with the OS */
 574
 575	MALI_PP             =2,  /**< Mali Pixel Processor core */
 576	MALI450PP           =2,  /**< Compatibility option */
 577	MALI400PP           =2,  /**< Compatibility option */
 578	MALI300PP           =2,  /**< Compatibility option */
 579	MALI200             =2,  /**< Compatibility option */
 580	
 581	MALI_GP             =3,  /**< Mali Geometry Processor core */
 582	MALI450GP           =3,  /**< Compatibility option */
 583	MALI400GP           =3,  /**< Compatibility option */
 584	MALI300GP           =3,  /**< Compatibility option */
 585	MALIGP2             =3,  /**< Compatibility option */
 586
 587	MMU                 =4,  /**< Mali MMU (Memory Management Unit) */
 588
 589	FPGA_FRAMEWORK      =5,  /**< Mali registers specific to FPGA implementations */
 590
 591	MALI_L2             =6,  /**< Mali Level 2 cache core */
 592	MALI450L2           =6,  /**< Compatibility option */
 593	MALI400L2           =6,  /**< Compatibility option */
 594	MALI300L2           =6,  /**< Compatibility option */
 595
 596	MEM_VALIDATION      =7, /**< External Memory Validator */
 597
 598	PMU                 =8, /**< Power Manangement Unit */
 599
 600	RESOURCE_TYPE_COUNT      /**< The total number of known resources */
 601} _mali_osk_resource_type_t;
 602
 603/** @brief resource description struct
 604 *
 605 * _mali_osk_resources_init() will enumerate objects of this type. Not all
 606 * members have a valid meaning across all types.
 607 *
 608 * The mmu_id is used to group resources to a certain MMU, since there may be
 609 * more than one MMU in the system, and each resource may be using a different
 610 * MMU:
 611 * - For MMU resources, the setting of mmu_id is a uniquely identifying number.
 612 * - For Other resources, the setting of mmu_id determines which MMU the
 613 * resource uses.
 614 */
 615typedef struct _mali_osk_resource
 616{
 617	_mali_osk_resource_type_t type; /**< type of the resource */
 618	const char * description;       /**< short description of the resource */
 619	u32 base;                       /**< Physical base address of the resource, as seen by Mali resources. */
 620	s32 cpu_usage_adjust;           /**< Offset added to the base address of the resource to arrive at the CPU physical address of the resource (if different from the Mali physical address) */
 621	u32 size;                       /**< Size in bytes of the resource - either the size of its register range, or the size of the memory block. */
 622	u32 irq;                        /**< IRQ number delivered to the CPU, or -1 to tell the driver to probe for it (if possible) */
 623	u32 flags;                      /**< Resources-specific flags. */
 624	u32 mmu_id;                     /**< Identifier for Mali MMU resources. */
 625	u32 alloc_order;                /**< Order in which MEMORY/OS_MEMORY resources are used */
 626} _mali_osk_resource_t;
 627/** @} */ /* end group _mali_osk_miscellaneous */
 628
 629
 630#include "mali_kernel_memory_engine.h"   /* include for mali_memory_allocation and mali_physical_memory_allocation type */
 631
 632/** @addtogroup _mali_osk_irq
 633 * @{ */
 634
 635/** @brief Fake IRQ number for testing purposes
 636 */
 637#define _MALI_OSK_IRQ_NUMBER_FAKE ((u32)0xFFFFFFF1)
 638
 639/** @addtogroup _mali_osk_irq
 640 * @{ */
 641
 642/** @brief PMM Virtual IRQ number
 643 */
 644#define _MALI_OSK_IRQ_NUMBER_PMM ((u32)0xFFFFFFF2)
 645
 646
 647/** @brief Initialize IRQ handling for a resource
 648 *
 649 * The _mali_osk_irq_t returned must be written into the resource-specific data
 650 * pointed to by data. This is so that the upper and lower handlers can call
 651 * _mali_osk_irq_schedulework().
 652 *
 653 * @note The caller must ensure that the resource does not generate an
 654 * interrupt after _mali_osk_irq_init() finishes, and before the
 655 * _mali_osk_irq_t is written into the resource-specific data. Otherwise,
 656 * the upper-half handler will fail to call _mali_osk_irq_schedulework().
 657 *
 658 * @param irqnum The IRQ number that the resource uses, as seen by the CPU.
 659 * The value -1 has a special meaning which indicates the use of probing, and trigger_func and ack_func must be
 660 * non-NULL.
 661 * @param uhandler The upper-half handler, corresponding to a ISR handler for
 662 * the resource
 663 * @param bhandler The lower-half handler, corresponding to an IST handler for
 664 * the resource
 665 * @param trigger_func Optional: a function to trigger the resource's irq, to
 666 * probe for the interrupt. Use NULL if irqnum != -1.
 667 * @param ack_func Optional: a function to acknowledge the resource's irq, to
 668 * probe for the interrupt. Use NULL if irqnum != -1.
 669 * @param data resource-specific data, which will be passed to uhandler,
 670 * bhandler and (if present) trigger_func and ack_funnc
 671 * @param description textual description of the IRQ resource.
 672 * @return on success, a pointer to a _mali_osk_irq_t object, which represents
 673 * the IRQ handling on this resource. NULL on failure.
 674 */
 675_mali_osk_irq_t *_mali_osk_irq_init( u32 irqnum, _mali_osk_irq_uhandler_t uhandler,	_mali_osk_irq_bhandler_t bhandler, _mali_osk_irq_trigger_t trigger_func, _mali_osk_irq_ack_t ack_func, void *data, const char *description );
 676
 677/** @brief Cause a queued, deferred call of the IRQ bottom-half.
 678 *
 679 * _mali_osk_irq_schedulework provides a mechanism for enqueuing deferred calls
 680 * to the IRQ bottom-half handler. The queue is known as the IRQ work-queue.
 681 * After calling _mali_osk_irq_schedulework(), the IRQ bottom-half handler will
 682 * be scheduled to run at some point in the future.
 683 *
 684 * This is called by the IRQ upper-half to defer further processing of
 685 * IRQ-related work to the IRQ bottom-half handler. This is necessary for work
 686 * that cannot be done in an IRQ context by the IRQ upper-half handler. Timer
 687 * callbacks also use this mechanism, because they are treated as though they
 688 * operate in an IRQ context. Refer to \ref _mali_osk_timer_t for more
 689 * information.
 690 *
 691 * Code that operates in a kernel-process context (with no IRQ context
 692 * restrictions) may also enqueue deferred calls to the IRQ bottom-half. The
 693 * advantage over direct calling is that deferred calling allows the caller and
 694 * IRQ bottom half to hold the same mutex, with a guarantee that they will not
 695 * deadlock just by using this mechanism.
 696 *
 697 * _mali_osk_irq_schedulework() places deferred call requests on a queue, to
 698 * allow for more than one thread to make a deferred call. Therfore, if it is
 699 * called 'K' times, then the IRQ bottom-half will be scheduled 'K' times too.
 700 * 'K' is a number that is implementation-specific.
 701 *
 702 * _mali_osk_irq_schedulework() is guaranteed to not block on:
 703 * - enqueuing a deferred call request.
 704 * - the completion of the IRQ bottom-half handler.
 705 *
 706 * This is to prevent deadlock. For example, if _mali_osk_irq_schedulework()
 707 * blocked, then it would cause a deadlock when the following two conditions
 708 * hold:
 709 * - The IRQ bottom-half callback (of type _mali_osk_irq_bhandler_t) locks
 710 * a mutex
 711 * - And, at the same time, the caller of _mali_osk_irq_schedulework() also
 712 * holds the same mutex
 713 *
 714 * @note care must be taken to not overflow the queue that
 715 * _mali_osk_irq_schedulework() operates on. Code must be structured to
 716 * ensure that the number of requests made to the queue is bounded. Otherwise,
 717 * IRQs will be lost.
 718 *
 719 * The queue that _mali_osk_irq_schedulework implements is a FIFO of N-writer,
 720 * 1-reader type. The writers are the callers of _mali_osk_irq_schedulework
 721 * (all OSK-registered IRQ upper-half handlers in the system, watchdog timers,
 722 * callers from a Kernel-process context). The reader is a single thread that
 723 * handles all OSK-registered IRQs.
 724 *
 725 * The consequence of the queue being a 1-reader type is that calling
 726 * _mali_osk_irq_schedulework() on different _mali_osk_irq_t objects causes
 727 * their IRQ bottom-halves to be serialized, across all CPU-cores in the
 728 * system.
 729 *
 730 * @param irq a pointer to the _mali_osk_irq_t object corresponding to the
 731 * resource whose IRQ bottom-half must begin processing.
 732 */
 733void _mali_osk_irq_schedulework( _mali_osk_irq_t *irq );
 734
 735/** @brief Terminate IRQ handling on a resource.
 736 *
 737 * This will disable the interrupt from the device, and then waits for the
 738 * IRQ work-queue to finish the work that is currently in the queue. That is,
 739 * for every deferred call currently in the IRQ work-queue, it waits for each
 740 * of those to be processed by their respective IRQ bottom-half handler.
 741 *
 742 * This function is used to ensure that the bottom-half handler of the supplied
 743 * IRQ object will not be running at the completion of this function call.
 744 * However, the caller must ensure that no other sources could call the
 745 * _mali_osk_irq_schedulework() on the same IRQ object. For example, the
 746 * relevant timers must be stopped.
 747 *
 748 * @note While this function is being called, other OSK-registered IRQs in the
 749 * system may enqueue work for their respective bottom-half handlers. This
 750 * function will not wait for those entries in the work-queue to be flushed.
 751 *
 752 * Since this blocks on the completion of work in the IRQ work-queue, the
 753 * caller of this function \b must \b not hold any mutexes that are taken by
 754 * any OSK-registered IRQ bottom-half handler. To do so may cause a deadlock.
 755 *
 756 * @param irq a pointer to the _mali_osk_irq_t object corresponding to the
 757 * resource whose IRQ handling is to be terminated.
 758 */
 759void _mali_osk_irq_term( _mali_osk_irq_t *irq );
 760
 761/** @brief flushing workqueue.
 762 *
 763 * This will flush the workqueue.
 764 *
 765 * @param irq a pointer to the _mali_osk_irq_t object corresponding to the
 766 * resource whose IRQ handling is to be terminated.
 767 */
 768void _mali_osk_flush_workqueue( _mali_osk_irq_t *irq );
 769
 770/** @} */ /* end group _mali_osk_irq */
 771
 772
 773/** @addtogroup _mali_osk_atomic
 774 * @{ */
 775
 776/** @brief Decrement an atomic counter
 777 *
 778 * @note It is an error to decrement the counter beyond -(1<<23)
 779 *
 780 * @param atom pointer to an atomic counter */
 781void _mali_osk_atomic_dec( _mali_osk_atomic_t *atom );
 782
 783/** @brief Decrement an atomic counter, return new value
 784 *
 785 * @param atom pointer to an atomic counter
 786 * @return The new value, after decrement */
 787u32 _mali_osk_atomic_dec_return( _mali_osk_atomic_t *atom );
 788
 789/** @brief Increment an atomic counter
 790 *
 791 * @note It is an error to increment the counter beyond (1<<23)-1
 792 *
 793 * @param atom pointer to an atomic counter */
 794void _mali_osk_atomic_inc( _mali_osk_atomic_t *atom );
 795
 796/** @brief Increment an atomic counter, return new value
 797 *
 798 * @param atom pointer to an atomic counter */
 799u32 _mali_osk_atomic_inc_return( _mali_osk_atomic_t *atom );
 800
 801/** @brief Initialize an atomic counter
 802 *
 803 * @note the parameter required is a u32, and so signed integers should be
 804 * cast to u32.
 805 *
 806 * @param atom pointer to an atomic counter
 807 * @param val the value to initialize the atomic counter.
 808 * @return _MALI_OSK_ERR_OK on success, otherwise, a suitable
 809 * _mali_osk_errcode_t on failure.
 810 */
 811_mali_osk_errcode_t _mali_osk_atomic_init( _mali_osk_atomic_t *atom, u32 val );
 812
 813/** @brief Read a value from an atomic counter
 814 *
 815 * This can only be safely used to determine the value of the counter when it
 816 * is guaranteed that other threads will not be modifying the counter. This
 817 * makes its usefulness limited.
 818 *
 819 * @param atom pointer to an atomic counter
 820 */
 821u32 _mali_osk_atomic_read( _mali_osk_atomic_t *atom );
 822
 823/** @brief Terminate an atomic counter
 824 *
 825 * @param atom pointer to an atomic counter
 826 */
 827void _mali_osk_atomic_term( _mali_osk_atomic_t *atom );
 828/** @} */  /* end group _mali_osk_atomic */
 829
 830
 831/** @defgroup _mali_osk_memory OSK Memory Allocation
 832 * @{ */
 833
 834/** @brief Allocate zero-initialized memory.
 835 *
 836 * Returns a buffer capable of containing at least \a n elements of \a size
 837 * bytes each. The buffer is initialized to zero.
 838 *
 839 * If there is a need for a bigger block of memory (16KB or bigger), then
 840 * consider to use _mali_osk_vmalloc() instead, as this function might
 841 * map down to a OS function with size limitations.
 842 *
 843 * The buffer is suitably aligned for storage and subsequent access of every
 844 * type that the compiler supports. Therefore, the pointer to the start of the
 845 * buffer may be cast into any pointer type, and be subsequently accessed from
 846 * such a pointer, without loss of information.
 847 *
 848 * When the buffer is no longer in use, it must be freed with _mali_osk_free().
 849 * Failure to do so will cause a memory leak.
 850 *
 851 * @note Most toolchains supply memory allocation functions that meet the
 852 * compiler's alignment requirements.
 853 *
 854 * @param n Number of elements to allocate
 855 * @param size Size of each element
 856 * @return On success, the zero-initialized buffer allocated. NULL on failure
 857 */
 858void *_mali_osk_calloc( u32 n, u32 size );
 859
 860/** @brief Allocate memory.
 861 *
 862 * Returns a buffer capable of containing at least \a size bytes. The
 863 * contents of the buffer are undefined.
 864 *
 865 * If there is a need for a bigger block of memory (16KB or bigger), then
 866 * consider to use _mali_osk_vmalloc() instead, as this function might
 867 * map down to a OS function with size limitations.
 868 *
 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.
 873 *
 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.
 876 *
 877 * @note Most toolchains supply memory allocation functions that meet the
 878 * compiler's alignment requirements.
 879 *
 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.
 883 */
 884void *_mali_osk_malloc( u32 size );
 885
 886/** @brief Free memory.
 887 *
 888 * Reclaims the buffer pointed to by the parameter \a ptr for the system.
 889 * All memory returned from _mali_osk_malloc() and _mali_osk_calloc()
 890 * must be freed before the application exits. Otherwise,
 891 * a memory leak will occur.
 892 *
 893 * Memory must be freed once. It is an error to free the same non-NULL pointer
 894 * more than once.
 895 *
 896 * It is legal to free the NULL pointer.
 897 *
 898 * @param ptr Pointer to buffer to free
 899 */
 900void _mali_osk_free( void *ptr );
 901
 902/** @brief Allocate memory.
 903 *
 904 * Returns a buffer capable of containing at least \a size bytes. The
 905 * contents of the buffer are undefined.
 906 *
 907 * This function is potentially slower than _mali_osk_malloc() and _mali_osk_calloc(),
 908 * but do support bigger sizes.
 909 *
 910 * The buffer is suitably aligned for storage and subsequent access of every
 911 * type that the compiler supports. Therefore, the pointer to the start of the
 912 * buffer may be cast into any pointer type, and be subsequently accessed from
 913 * such a pointer, without loss of information.
 914 *
 915 * When the buffer is no longer in use, it must be freed with _mali_osk_free().
 916 * Failure to do so will cause a memory leak.
 917 *
 918 * @note Most toolchains supply memory allocation functions that meet the
 919 * compiler's alignment requirements.
 920 *
 921 * Remember to free memory using _mali_osk_free().
 922 * @param size Number of bytes to allocate
 923 * @return On success, the buffer allocated. NULL on failure.
 924 */
 925void *_mali_osk_valloc( u32 size );
 926
 927/** @brief Free memory.
 928 *
 929 * Reclaims the buffer pointed to by the parameter \a ptr for the system.
 930 * All memory returned from _mali_osk_valloc() must be freed before the
 931 * application exits. Otherwise a memory leak will occur.
 932 *
 933 * Memory must be freed once. It is an error to free the same non-NULL pointer
 934 * more than once.
 935 *
 936 * It is legal to free the NULL pointer.
 937 *
 938 * @param ptr Pointer to buffer to free
 939 */
 940void _mali_osk_vfree( void *ptr );
 941
 942/** @brief Copies memory.
 943 *
 944 * Copies the \a len bytes from the buffer pointed by the parameter \a src
 945 * directly to the buffer pointed by \a dst.
 946 *
 947 * It is an error for \a src to overlap \a dst anywhere in \a len bytes.
 948 *
 949 * @param dst Pointer to the destination array where the content is to be
 950 * copied.
 951 * @param src Pointer to the source of data to be copied.
 952 * @param len Number of bytes to copy.
 953 * @return \a dst is always passed through unmodified.
 954 */
 955void *_mali_osk_memcpy( void *dst, const void *src, u32 len );
 956
 957/** @brief Fills memory.
 958 *
 959 * Sets the first \a n bytes of the block of memory pointed to by \a s to
 960 * the specified value
 961 * @param s Pointer to the block of memory to fill.
 962 * @param c Value to be set, passed as u32. Only the 8 Least Significant Bits (LSB)
 963 * are used.
 964 * @param n Number of bytes to be set to the value.
 965 * @return \a s is always passed through unmodified
 966 */
 967void *_mali_osk_memset( void *s, u32 c, u32 n );
 968/** @} */ /* end group _mali_osk_memory */
 969
 970
 971/** @brief Checks the amount of memory allocated
 972 *
 973 * Checks that not more than \a max_allocated bytes are allocated.
 974 *
 975 * Some OS bring up an interactive out of memory dialogue when the
 976 * system runs out of memory. This can stall non-interactive
 977 * apps (e.g. automated test runs). This function can be used to
 978 * not trigger the OOM dialogue by keeping allocations
 979 * within a certain limit.
 980 *
 981 * @return MALI_TRUE when \a max_allocated bytes are not in use yet. MALI_FALSE
 982 * when at least \a max_allocated bytes are in use.
 983 */
 984mali_bool _mali_osk_mem_check_allocated( u32 max_allocated );
 985
 986/** @addtogroup _mali_osk_lock
 987 * @{ */
 988
 989/** @brief Initialize a Mutual Exclusion Lock
 990 *
 991 * Locks are created in the signalled (unlocked) state.
 992 *
 993 * initial must be zero, since there is currently no means of expressing
 994 * whether a reader/writer lock should be initially locked as a reader or
 995 * writer. This would require some encoding to be used.
 996 *
 997 * 'Automatic' ordering means that locks must be obtained in the order that
 998 * they were created. For all locks that can be held at the same time, they must
 999 * either all provide the order parameter, or they all must use 'automatic'
1000 * ordering - because there is no way of mixing 'automatic' and 'manual'
1001 * ordering.
1002 *
1003 * @param flags flags combined with bitwise OR ('|'), or zero. There are
1004 * restrictions on which flags can be combined, @see _mali_osk_lock_flags_t.
1005 * @param initial For future expansion into semaphores. SBZ.
1006 * @param order The locking order of the mutex. That is, locks obtained by the
1007 * same thread must have been created with an increasing order parameter, for
1008 * deadlock prevention. Setting to zero causes 'automatic' ordering to be used.
1009 * @return On success, a pointer to a _mali_osk_lock_t object. NULL on failure.
1010 */
1011_mali_osk_lock_t *_mali_osk_lock_init( _mali_osk_lock_flags_t flags, u32 initial, u32 order );
1012
1013/** @brief Wait for a lock to be signalled (obtained)
1014
1015 * After a thread has successfully waited on the lock, the lock is obtained by
1016 * the thread, and is marked as unsignalled. The thread releases the lock by
1017 * signalling it.
1018 *
1019 * In the case of Reader/Writer locks, multiple readers can obtain a lock in
1020 * the absence of writers, which is a performance optimization (providing that
1021 * the readers never write to the protected resource).
1022 *
1023 * To prevent deadlock, locks must always be obtained in the same order.
1024 *
1025 * For locks marked as _MALI_OSK_LOCKFLAG_NONINTERRUPTABLE, it is a
1026 * programming error for the function to exit without obtaining the lock. This
1027 * means that the error code must only be checked for interruptible locks.
1028 *
1029 * @param lock the lock to wait upon (obtain).
1030 * @param mode the mode in which the lock should be obtained. Unless the lock
1031 * was created with _MALI_OSK_LOCKFLAG_READERWRITER, this must be
1032 * _MALI_OSK_LOCKMODE_RW.
1033 * @return On success, _MALI_OSK_ERR_OK. For interruptible locks, a suitable
1034 * _mali_osk_errcode_t will be returned on failure, and the lock will not be
1035 * obtained. In this case, the error code must be propagated up to the U/K
1036 * interface.
1037 */
1038_mali_osk_errcode_t _mali_osk_lock_wait( _mali_osk_lock_t *lock, _mali_osk_lock_mode_t mode);
1039
1040
1041/** @brief Signal (release) a lock
1042 *
1043 * Locks may only be signalled by the thread that originally waited upon the
1044 * lock.
1045 *
1046 * @note In the OSU, a flag exists to allow any thread to signal a
1047 * lock. Such functionality is not present in the OSK.
1048 *
1049 * @param lock the lock to signal (release).
1050 * @param mode the mode in which the lock should be obtained. This must match
1051 * the mode in which the lock was waited upon.
1052 */
1053void _mali_osk_lock_signal( _mali_osk_lock_t *lock, _mali_osk_lock_mode_t mode );
1054
1055/** @brief Terminate a lock
1056 *
1057 * This terminates a lock and frees all associated resources.
1058 *
1059 * It is a programming error to terminate the lock when it is held (unsignalled)
1060 * by a thread.
1061 *
1062 * @param lock the lock to terminate.
1063 */
1064void _mali_osk_lock_term( _mali_osk_lock_t *lock );
1065/** @} */ /* end group _mali_osk_lock */
1066
1067
1068/** @addtogroup _mali_osk_low_level_memory
1069 * @{ */
1070
1071/** @brief Issue a memory barrier
1072 *
1073 * This defines an arbitrary memory barrier operation, which forces an ordering constraint
1074 * on memory read and write operations.
1075 */
1076void _mali_osk_mem_barrier( void );
1077
1078/** @brief Issue a write memory barrier
1079 *
1080 * This defines an write memory barrier operation which forces an ordering constraint
1081 * on memory write operations.
1082 */
1083void _mali_osk_write_mem_barrier( void );
1084
1085/** @brief Map a physically contiguous region into kernel space
1086 *
1087 * This is primarily used for mapping in registers from resources, and Mali-MMU
1088 * page tables. The mapping is only visable from kernel-space.
1089 *
1090 * Access has to go through _mali_osk_mem_ioread32 and _mali_osk_mem_iowrite32
1091 *
1092 * @param phys CPU-physical base address of the memory to map in. This must
1093 * be aligned to the system's page size, which is assumed to be 4K.
1094 * @param size the number of bytes of physically contiguous address space to
1095 * map in
1096 * @param description A textual description of the memory being mapped in.
1097 * @return On success, a Mali IO address through which the mapped-in
1098 * memory/registers can be accessed. NULL on failure.
1099 */
1100mali_io_address _mali_osk_mem_mapioregion( u32 phys, u32 size, const char *description );
1101
1102/** @brief Unmap a physically contiguous address range from kernel space.
1103 *
1104 * The address range should be one previously mapped in through
1105 * _mali_osk_mem_mapioregion.
1106 *
1107 * It is a programming error to do (but not limited to) the following:
1108 * - attempt an unmap twice
1109 * - unmap only part of a range obtained through _mali_osk_mem_mapioregion
1110 * - unmap more than the range obtained through  _mali_osk_mem_mapioregion
1111 * - unmap an address range that was not successfully mapped using
1112 * _mali_osk_mem_mapioregion
1113 * - provide a mapping that does not map to phys.
1114 *
1115 * @param phys CPU-physical base address of the memory that was originally
1116 * mapped in. This must be aligned to the system's page size, which is assumed
1117 * to be 4K
1118 * @param size The number of bytes that were originally mapped in.
1119 * @param mapping The Mali IO address through which the mapping is
1120 * accessed.
1121 */
1122void _mali_osk_mem_unmapioregion( u32 phys, u32 size, mali_io_address mapping );
1123
1124/** @brief Allocate and Map a physically contiguous region into kernel space
1125 *
1126 * This is used for allocating physically contiguous regions (such as Mali-MMU
1127 * page tables) and mapping them into kernel space. The mapping is only
1128 * visible from kernel-space.
1129 *
1130 * The alignment of the returned memory is guaranteed to be at least
1131 * _MALI_OSK_CPU_PAGE_SIZE.
1132 *
1133 * Access must go through _mali_osk_mem_ioread32 and _mali_osk_mem_iowrite32
1134 *
1135 * @note This function is primarily to provide support for OSs that are
1136 * incapable of separating the tasks 'allocate physically contiguous memory'
1137 * and 'map it into kernel space'
1138 *
1139 * @param[out] phys CPU-physical base address of memory that was allocated.
1140 * (*phys) will be guaranteed to be aligned to at least
1141 * _MALI_OSK_CPU_PAGE_SIZE on success.
1142 *
1143 * @param[in] size the number of bytes of physically contiguous memory to
1144 * allocate. This must be a multiple of _MALI_OSK_CPU_PAGE_SIZE.
1145 *
1146 * @return On success, a Mali IO address through which the mapped-in
1147 * memory/registers can be accessed. NULL on failure, and (*phys) is unmodified.
1148 */
1149mali_io_address _mali_osk_mem_allocioregion( u32 *phys, u32 size );
1150
1151/** @brief Free a physically contiguous address range from kernel space.
1152 *
1153 * The address range should be one previously mapped in through
1154 * _mali_osk_mem_allocioregion.
1155 *
1156 * It is a programming error to do (but not limited to) the following:
1157 * - attempt a free twice on the same ioregion
1158 * - free only part of a range obtained through _mali_osk_mem_allocioregion
1159 * - free more than the range obtained through  _mali_osk_mem_allocioregion
1160 * - free an address range that was not successfully mapped using
1161 * _mali_osk_mem_allocioregion
1162 * - provide a mapping that does not map to phys.
1163 *
1164 * @param phys CPU-physical base address of the memory that was originally
1165 * mapped in, which was aligned to _MALI_OSK_CPU_PAGE_SIZE.
1166 * @param size The number of bytes that were originally mapped in, which was
1167 * a multiple of _MALI_OSK_CPU_PAGE_SIZE.
1168 * @param mapping The Mali IO address through which the mapping is
1169 * accessed.
1170 */
1171void _mali_osk_mem_freeioregion( u32 phys, u32 size, mali_io_address mapping );
1172
1173/** @brief Request a region of physically contiguous memory
1174 *
1175 * This is used to ensure exclusive access to a region of physically contigous
1176 * memory.
1177 *
1178 * It is acceptable to implement this as a stub. However, it is then the job
1179 * of the System Integrator to ensure that no other device driver will be using
1180 * the physical address ranges used by Mali, while the Mali device driver is
1181 * loaded.
1182 *
1183 * @param phys CPU-physical base address of the memory to request. This must
1184 * be aligned to the system's page size, which is assumed to be 4K.
1185 * @param size the number of bytes of physically contiguous address space to
1186 * request.
1187 * @param description A textual description of the memory being requested.
1188 * @return _MALI_OSK_ERR_OK on success. Otherwise, a suitable
1189 * _mali_osk_errcode_t on failure.
1190 */
1191_mali_osk_errcode_t _mali_osk_mem_reqregion( u32 phys, u32 size, const char *description );
1192
1193/** @brief Un-request a region of physically contiguous memory
1194 *
1195 * This is used to release a regious of physically contiguous memory previously
1196 * requested through _mali_osk_mem_reqregion, so that other device drivers may
1197 * use it. This will be called at time of Mali device driver termination.
1198 *
1199 * It is a programming error to attempt to:
1200 * - unrequest a region twice
1201 * - unrequest only part of a range obtained through _mali_osk_mem_reqregion
1202 * - unrequest more than the range obtained through  _mali_osk_mem_reqregion
1203 * - unrequest an address range that was not successfully requested using
1204 * _mali_osk_mem_reqregion
1205 *
1206 * @param phys CPU-physical base address of the memory to un-request. This must
1207 * be aligned to the system's page size, which is assumed to be 4K
1208 * @param size the number of bytes of physically contiguous address space to
1209 * un-request.
1210 */
1211void _mali_osk_mem_unreqregion( u32 phys, u32 size );
1212
1213/** @brief Read from a location currently mapped in through
1214 * _mali_osk_mem_mapioregion
1215 *
1216 * This reads a 32-bit word from a 32-bit aligned location. It is a …

Large files files are truncated, but you can click here to view the full file