drivers/gpu/arm/mali400/mali/common/mali_osk_types.h

   1 /*
   2  * Copyright (C) 2010-2016 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__ */