/drivers/gpu/mali/mali/common/mali_osk.h
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