1 /* 2 * Copyright (C) 2010-2017 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_types.h 13 * Defines types of the OS abstraction layer for the kernel device driver (OSK) 14 */ 15 16 #ifndef __MALI_OSK_TYPES_H__ 17 #define __MALI_OSK_TYPES_H__ 18 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 23 /** 24 * @addtogroup uddapi Unified Device Driver (UDD) APIs 25 * 26 * @{ 27 */ 28 29 /** 30 * @addtogroup oskapi UDD OS Abstraction for Kernel-side (OSK) APIs 31 * 32 * @{ 33 */ 34 35 /** @defgroup _mali_osk_miscellaneous OSK Miscellaneous functions, constants and types 36 * @{ */ 37 38 /* Define integer types used by OSK. Note: these currently clash with Linux so we only define them if not defined already */ 39 #ifndef __KERNEL__ 40 typedef unsigned char u8; 41 typedef signed char s8; 42 typedef unsigned short u16; 43 typedef signed short s16; 44 typedef unsigned int u32; 45 typedef signed int s32; 46 typedef unsigned long long u64; 47 #define BITS_PER_LONG (sizeof(long)*8) 48 #else 49 /* Ensure Linux types u32, etc. are defined */ 50 #include <linux/types.h> 51 #endif 52 53 /** @brief Mali Boolean type which uses MALI_TRUE and MALI_FALSE 54 */ 55 typedef unsigned long mali_bool; 56 57 #ifndef MALI_TRUE 58 #define MALI_TRUE ((mali_bool)1) 59 #endif 60 61 #ifndef MALI_FALSE 62 #define MALI_FALSE ((mali_bool)0) 63 #endif 64 65 #define MALI_HW_CORE_NO_COUNTER ((u32)-1) 66 67 68 #define MALI_S32_MAX 0x7fffffff 69 70 /** 71 * @brief OSK Error codes 72 * 73 * Each OS may use its own set of error codes, and may require that the 74 * User/Kernel interface take certain error code. This means that the common 75 * error codes need to be sufficiently rich to pass the correct error code 76 * thorugh from the OSK to U/K layer, across all OSs. 77 * 78 * The result is that some error codes will appear redundant on some OSs. 79 * Under all OSs, the OSK layer must translate native OS error codes to 80 * _mali_osk_errcode_t codes. Similarly, the U/K layer must translate from 81 * _mali_osk_errcode_t codes to native OS error codes. 82 */ 83 typedef enum { 84 _MALI_OSK_ERR_OK = 0, /**< Success. */ 85 _MALI_OSK_ERR_FAULT = -1, /**< General non-success */ 86 _MALI_OSK_ERR_INVALID_FUNC = -2, /**< Invalid function requested through User/Kernel interface (e.g. bad IOCTL number) */ 87 _MALI_OSK_ERR_INVALID_ARGS = -3, /**< Invalid arguments passed through User/Kernel interface */ 88 _MALI_OSK_ERR_NOMEM = -4, /**< Insufficient memory */ 89 _MALI_OSK_ERR_TIMEOUT = -5, /**< Timeout occurred */ 90 _MALI_OSK_ERR_RESTARTSYSCALL = -6, /**< Special: On certain OSs, must report when an interruptable mutex is interrupted. Ignore otherwise. */ 91 _MALI_OSK_ERR_ITEM_NOT_FOUND = -7, /**< Table Lookup failed */ 92 _MALI_OSK_ERR_BUSY = -8, /**< Device/operation is busy. Try again later */ 93 _MALI_OSK_ERR_UNSUPPORTED = -9, /**< Optional part of the interface used, and is unsupported */ 94 } _mali_osk_errcode_t; 95 96 /** @} */ /* end group _mali_osk_miscellaneous */ 97 98 /** @defgroup _mali_osk_wq OSK work queues 99 * @{ */ 100 101 /** @brief Private type for work objects */ 102 typedef struct _mali_osk_wq_work_s _mali_osk_wq_work_t; 103 typedef struct _mali_osk_wq_delayed_work_s _mali_osk_wq_delayed_work_t; 104 105 /** @brief Work queue handler function 106 * 107 * This function type is called when the work is scheduled by the work queue, 108 * e.g. as an IRQ bottom-half handler. 109 * 110 * Refer to \ref _mali_osk_wq_schedule_work() for more information on the 111 * work-queue and work handlers. 112 * 113 * @param arg resource-specific data 114 */ 115 typedef void (*_mali_osk_wq_work_handler_t)(void *arg); 116 117 /* @} */ /* end group _mali_osk_wq */ 118 119 /** @defgroup _mali_osk_irq OSK IRQ handling 120 * @{ */ 121 122 /** @brief Private type for IRQ handling objects */ 123 typedef struct _mali_osk_irq_t_struct _mali_osk_irq_t; 124 125 /** @brief Optional function to trigger an irq from a resource 126 * 127 * This function is implemented by the common layer to allow probing of a resource's IRQ. 128 * @param arg resource-specific data */ 129 typedef void (*_mali_osk_irq_trigger_t)(void *arg); 130 131 /** @brief Optional function to acknowledge an irq from a resource 132 * 133 * This function is implemented by the common layer to allow probing of a resource's IRQ. 134 * @param arg resource-specific data 135 * @return _MALI_OSK_ERR_OK if the IRQ was successful, or a suitable _mali_osk_errcode_t on failure. */ 136 typedef _mali_osk_errcode_t (*_mali_osk_irq_ack_t)(void *arg); 137 138 /** @brief IRQ 'upper-half' handler callback. 139 * 140 * This function is implemented by the common layer to do the initial handling of a 141 * resource's IRQ. This maps on to the concept of an ISR that does the minimum 142 * work necessary before handing off to an IST. 143 * 144 * The communication of the resource-specific data from the ISR to the IST is 145 * handled by the OSK implementation. 146 * 147 * On most systems, the IRQ upper-half handler executes in IRQ context. 148 * Therefore, the system may have restrictions about what can be done in this 149 * context 150 * 151 * If an IRQ upper-half handler requires more work to be done than can be 152 * acheived in an IRQ context, then it may defer the work with 153 * _mali_osk_wq_schedule_work(). Refer to \ref _mali_osk_wq_create_work() for 154 * more information. 155 * 156 * @param arg resource-specific data 157 * @return _MALI_OSK_ERR_OK if the IRQ was correctly handled, or a suitable 158 * _mali_osk_errcode_t otherwise. 159 */ 160 typedef _mali_osk_errcode_t (*_mali_osk_irq_uhandler_t)(void *arg); 161 162 163 /** @} */ /* end group _mali_osk_irq */ 164 165 166 /** @defgroup _mali_osk_atomic OSK Atomic counters 167 * @{ */ 168 169 /** @brief Public type of atomic counters 170 * 171 * This is public for allocation on stack. On systems that support it, this is just a single 32-bit value. 172 * On others, it could be encapsulating an object stored elsewhere. 173 * 174 * Regardless of implementation, the \ref _mali_osk_atomic functions \b must be used 175 * for all accesses to the variable's value, even if atomicity is not required. 176 * Do not access u.val or u.obj directly. 177 */ 178 typedef struct { 179 union { 180 u32 val; 181 void *obj; 182 } u; 183 } _mali_osk_atomic_t; 184 /** @} */ /* end group _mali_osk_atomic */ 185 186 187 /** @defgroup _mali_osk_lock OSK Mutual Exclusion Locks 188 * @{ */ 189 190 191 /** @brief OSK Mutual Exclusion Lock ordered list 192 * 193 * This lists the various types of locks in the system and is used to check 194 * that locks are taken in the correct order. 195 * 196 * - Holding more than one lock of the same order at the same time is not 197 * allowed. 198 * - Taking a lock of a lower order than the highest-order lock currently held 199 * is not allowed. 200 * 201 */ 202 typedef enum { 203 /* || Locks || */ 204 /* || must be || */ 205 /* _||_ taken in _||_ */ 206 /* \ / this \ / */ 207 /* \/ order! \/ */ 208 209 _MALI_OSK_LOCK_ORDER_FIRST = 0, 210 211 _MALI_OSK_LOCK_ORDER_SESSIONS, 212 _MALI_OSK_LOCK_ORDER_MEM_SESSION, 213 _MALI_OSK_LOCK_ORDER_MEM_INFO, 214 _MALI_OSK_LOCK_ORDER_MEM_PT_CACHE, 215 _MALI_OSK_LOCK_ORDER_DESCRIPTOR_MAP, 216 _MALI_OSK_LOCK_ORDER_PM_EXECUTION, 217 _MALI_OSK_LOCK_ORDER_EXECUTOR, 218 _MALI_OSK_LOCK_ORDER_TIMELINE_SYSTEM, 219 _MALI_OSK_LOCK_ORDER_SCHEDULER, 220 _MALI_OSK_LOCK_ORDER_SCHEDULER_DEFERRED, 221 _MALI_OSK_LOCK_ORDER_PROFILING, 222 _MALI_OSK_LOCK_ORDER_L2, 223 _MALI_OSK_LOCK_ORDER_L2_COMMAND, 224 _MALI_OSK_LOCK_ORDER_UTILIZATION, 225 _MALI_OSK_LOCK_ORDER_SESSION_PENDING_JOBS, 226 _MALI_OSK_LOCK_ORDER_PM_STATE, 227 228 _MALI_OSK_LOCK_ORDER_LAST, 229 } _mali_osk_lock_order_t; 230 231 232 /** @brief OSK Mutual Exclusion Lock flags type 233 * 234 * - Any lock can use the order parameter. 235 */ 236 typedef enum { 237 _MALI_OSK_LOCKFLAG_UNORDERED = 0x1, /**< Indicate that the order of this lock should not be checked */ 238 _MALI_OSK_LOCKFLAG_ORDERED = 0x2, 239 /** @enum _mali_osk_lock_flags_t 240 * 241 * Flags from 0x10000--0x80000000 are RESERVED for User-mode */ 242 243 } _mali_osk_lock_flags_t; 244 245 /** @brief Mutual Exclusion Lock Mode Optimization hint 246 * 247 * The lock mode is used to implement the read/write locking of locks when we call 248 * functions _mali_osk_mutex_rw_init/wait/signal/term/. In this case, the RO mode can 249 * be used to allow multiple concurrent readers, but no writers. The RW mode is used for 250 * writers, and so will wait for all readers to release the lock (if any present). 251 * Further readers and writers will wait until the writer releases the lock. 252 * 253 * The mode is purely an optimization hint: for example, it is permissible for 254 * all locks to behave in RW mode, regardless of that supplied. 255 * 256 * It is an error to attempt to use locks in anything other that RW mode when 257 * call functions _mali_osk_mutex_rw_wait/signal(). 258 * 259 */ 260 typedef enum { 261 _MALI_OSK_LOCKMODE_UNDEF = -1, /**< Undefined lock mode. For internal use only */ 262 _MALI_OSK_LOCKMODE_RW = 0x0, /**< Read-write mode, default. All readers and writers are mutually-exclusive */ 263 _MALI_OSK_LOCKMODE_RO, /**< Read-only mode, to support multiple concurrent readers, but mutual exclusion in the presence of writers. */ 264 /** @enum _mali_osk_lock_mode_t 265 * 266 * Lock modes 0x40--0x7F are RESERVED for User-mode */ 267 } _mali_osk_lock_mode_t; 268 269 /** @brief Private types for Mutual Exclusion lock objects */ 270 typedef struct _mali_osk_lock_debug_s _mali_osk_lock_debug_t; 271 typedef struct _mali_osk_spinlock_s _mali_osk_spinlock_t; 272 typedef struct _mali_osk_spinlock_irq_s _mali_osk_spinlock_irq_t; 273 typedef struct _mali_osk_mutex_s _mali_osk_mutex_t; 274 typedef struct _mali_osk_mutex_rw_s _mali_osk_mutex_rw_t; 275 276 /** @} */ /* end group _mali_osk_lock */ 277 278 /** @defgroup _mali_osk_low_level_memory OSK Low-level Memory Operations 279 * @{ */ 280 281 /** 282 * @brief Private data type for use in IO accesses to/from devices. 283 * 284 * This represents some range that is accessible from the device. Examples 285 * include: 286 * - Device Registers, which could be readable and/or writeable. 287 * - Memory that the device has access to, for storing configuration structures. 288 * 289 * Access to this range must be made through the _mali_osk_mem_ioread32() and 290 * _mali_osk_mem_iowrite32() functions. 291 */ 292 typedef struct _mali_io_address *mali_io_address; 293 294 /** @defgroup _MALI_OSK_CPU_PAGE CPU Physical page size macros. 295 * 296 * The order of the page size is supplied for 297 * ease of use by algorithms that might require it, since it is easier to know 298 * it ahead of time rather than calculating it. 299 * 300 * The Mali Page Mask macro masks off the lower bits of a physical address to 301 * give the start address of the page for that physical address. 302 * 303 * @note The Mali device driver code is designed for systems with 4KB page size. 304 * Changing these macros will not make the entire Mali device driver work with 305 * page sizes other than 4KB. 306 * 307 * @note The CPU Physical Page Size has been assumed to be the same as the Mali 308 * Physical Page Size. 309 * 310 * @{ 311 */ 312 313 /** CPU Page Order, as log to base 2 of the Page size. @see _MALI_OSK_CPU_PAGE_SIZE */ 314 #define _MALI_OSK_CPU_PAGE_ORDER ((u32)12) 315 /** CPU Page Size, in bytes. */ 316 #define _MALI_OSK_CPU_PAGE_SIZE (((u32)1) << (_MALI_OSK_CPU_PAGE_ORDER)) 317 /** CPU Page Mask, which masks off the offset within a page */ 318 #define _MALI_OSK_CPU_PAGE_MASK (~((((u32)1) << (_MALI_OSK_CPU_PAGE_ORDER)) - ((u32)1))) 319 /** @} */ /* end of group _MALI_OSK_CPU_PAGE */ 320 321 /** @defgroup _MALI_OSK_MALI_PAGE Mali Physical Page size macros 322 * 323 * Mali Physical page size macros. The order of the page size is supplied for 324 * ease of use by algorithms that might require it, since it is easier to know 325 * it ahead of time rather than calculating it. 326 * 327 * The Mali Page Mask macro masks off the lower bits of a physical address to 328 * give the start address of the page for that physical address. 329 * 330 * @note The Mali device driver code is designed for systems with 4KB page size. 331 * Changing these macros will not make the entire Mali device driver work with 332 * page sizes other than 4KB. 333 * 334 * @note The Mali Physical Page Size has been assumed to be the same as the CPU 335 * Physical Page Size. 336 * 337 * @{ 338 */ 339 340 /** Mali Page Order, as log to base 2 of the Page size. @see _MALI_OSK_MALI_PAGE_SIZE */ 341 #define _MALI_OSK_MALI_PAGE_ORDER PAGE_SHIFT 342 /** Mali Page Size, in bytes. */ 343 #define _MALI_OSK_MALI_PAGE_SIZE PAGE_SIZE 344 /** Mali Page Mask, which masks off the offset within a page */ 345 #define _MALI_OSK_MALI_PAGE_MASK PAGE_MASK 346 /** @} */ /* end of group _MALI_OSK_MALI_PAGE*/ 347 348 /** @brief flags for mapping a user-accessible memory range 349 * 350 * Where a function with prefix '_mali_osk_mem_mapregion' accepts flags as one 351 * of the function parameters, it will use one of these. These allow per-page 352 * control over mappings. Compare with the mali_memory_allocation_flag type, 353 * which acts over an entire range 354 * 355 * These may be OR'd together with bitwise OR (|), but must be cast back into 356 * the type after OR'ing. 357 */ 358 typedef enum { 359 _MALI_OSK_MEM_MAPREGION_FLAG_OS_ALLOCATED_PHYSADDR = 0x1, /**< Physical address is OS Allocated */ 360 } _mali_osk_mem_mapregion_flags_t; 361 /** @} */ /* end group _mali_osk_low_level_memory */ 362 363 /** @defgroup _mali_osk_notification OSK Notification Queues 364 * @{ */ 365 366 /** @brief Private type for notification queue objects */ 367 typedef struct _mali_osk_notification_queue_t_struct _mali_osk_notification_queue_t; 368 369 /** @brief Public notification data object type */ 370 typedef struct _mali_osk_notification_t_struct { 371 u32 notification_type; /**< The notification type */ 372 u32 result_buffer_size; /**< Size of the result buffer to copy to user space */ 373 void *result_buffer; /**< Buffer containing any type specific data */ 374 } _mali_osk_notification_t; 375 376 /** @} */ /* end group _mali_osk_notification */ 377 378 379 /** @defgroup _mali_osk_timer OSK Timer Callbacks 380 * @{ */ 381 382 /** @brief Function to call when a timer expires 383 * 384 * When a timer expires, this function is called. Note that on many systems, 385 * a timer callback will be executed in IRQ context. Therefore, restrictions 386 * may apply on what can be done inside the timer callback. 387 * 388 * If a timer requires more work to be done than can be acheived in an IRQ 389 * context, then it may defer the work with a work-queue. For example, it may 390 * use \ref _mali_osk_wq_schedule_work() to make use of a bottom-half handler 391 * to carry out the remaining work. 392 * 393 * Stopping the timer with \ref _mali_osk_timer_del() blocks on compeletion of 394 * the callback. Therefore, the callback may not obtain any mutexes also held 395 * by any callers of _mali_osk_timer_del(). Otherwise, a deadlock may occur. 396 * 397 * @param arg Function-specific data */ 398 typedef void (*_mali_osk_timer_callback_t)(void *arg); 399 400 /** @brief Private type for Timer Callback Objects */ 401 typedef struct _mali_osk_timer_t_struct _mali_osk_timer_t; 402 /** @} */ /* end group _mali_osk_timer */ 403 404 405 /** @addtogroup _mali_osk_list OSK Doubly-Linked Circular Lists 406 * @{ */ 407 408 /** @brief Public List objects. 409 * 410 * To use, add a _mali_osk_list_t member to the structure that may become part 411 * of a list. When traversing the _mali_osk_list_t objects, use the 412 * _MALI_OSK_CONTAINER_OF() macro to recover the structure from its 413 *_mali_osk_list_t member 414 * 415 * Each structure may have multiple _mali_osk_list_t members, so that the 416 * structure is part of multiple lists. When traversing lists, ensure that the 417 * correct _mali_osk_list_t member is used, because type-checking will be 418 * lost by the compiler. 419 */ 420 typedef struct _mali_osk_list_s { 421 struct _mali_osk_list_s *next; 422 struct _mali_osk_list_s *prev; 423 } _mali_osk_list_t; 424 /** @} */ /* end group _mali_osk_list */ 425 426 /** @addtogroup _mali_osk_miscellaneous 427 * @{ */ 428 429 /** @brief resource description struct 430 * 431 * Platform independent representation of a Mali HW resource 432 */ 433 typedef struct _mali_osk_resource { 434 const char *description; /**< short description of the resource */ 435 uintptr_t base; /**< Physical base address of the resource, as seen by Mali resources. */ 436 const char *irq_name; /**< Name of irq belong to this resource */ 437 u32 irq; /**< IRQ number delivered to the CPU, or -1 to tell the driver to probe for it (if possible) */ 438 } _mali_osk_resource_t; 439 /** @} */ /* end group _mali_osk_miscellaneous */ 440 441 /** @defgroup _mali_osk_wait_queue OSK Wait Queue functionality 442 * @{ */ 443 /** @brief Private type for wait queue objects */ 444 typedef struct _mali_osk_wait_queue_t_struct _mali_osk_wait_queue_t; 445 /** @} */ /* end group _mali_osk_wait_queue */ 446 447 /** @} */ /* end group osuapi */ 448 449 /** @} */ /* end group uddapi */ 450 451 /** @brief Mali print ctx type which uses seq_file 452 */ 453 typedef struct seq_file _mali_osk_print_ctx; 454 455 #define _MALI_OSK_BITMAP_INVALIDATE_INDEX -1 456 457 typedef struct _mali_osk_bitmap { 458 u32 reserve; 459 u32 last; 460 u32 max; 461 u32 avail; 462 _mali_osk_spinlock_t *lock; 463 unsigned long *table; 464 } _mali_osk_bitmap_t; 465 466 467 #ifdef __cplusplus 468 } 469 #endif 470 471 #endif /* __MALI_OSK_TYPES_H__ */ 472