mali_osk.h 50 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334
  1. /*
  2. * This confidential and proprietary software may be used only as
  3. * authorised by a licensing agreement from ARM Limited
  4. * (C) COPYRIGHT 2008-2013 ARM Limited
  5. * ALL RIGHTS RESERVED
  6. * The entire notice above must be reproduced on all authorised
  7. * copies and copies may only be made to the extent permitted
  8. * by a licensing agreement from ARM Limited.
  9. */
  10. /**
  11. * @file mali_osk.h
  12. * Defines the OS abstraction layer for the kernel device driver (OSK)
  13. */
  14. #ifndef __MALI_OSK_H__
  15. #define __MALI_OSK_H__
  16. #include "mali_osk_types.h"
  17. #include "mali_osk_specific.h" /* include any per-os specifics */
  18. #include "mali_osk_locks.h"
  19. #ifdef __cplusplus
  20. extern "C" {
  21. #endif
  22. /**
  23. * @addtogroup uddapi Unified Device Driver (UDD) APIs
  24. *
  25. * @{
  26. */
  27. /**
  28. * @addtogroup oskapi UDD OS Abstraction for Kernel-side (OSK) APIs
  29. *
  30. * @{
  31. */
  32. /** @addtogroup _mali_osk_lock OSK Mutual Exclusion Locks
  33. * @{ */
  34. #ifdef DEBUG
  35. /** @brief Macro for asserting that the current thread holds a given lock
  36. */
  37. #define MALI_DEBUG_ASSERT_LOCK_HELD(l) MALI_DEBUG_ASSERT(_mali_osk_lock_get_owner((_mali_osk_lock_debug_t *)l) == _mali_osk_get_tid());
  38. /** @brief returns a lock's owner (thread id) if debugging is enabled
  39. */
  40. #else
  41. #define MALI_DEBUG_ASSERT_LOCK_HELD(l) do {} while(0)
  42. #endif
  43. /** @} */ /* end group _mali_osk_lock */
  44. /** @addtogroup _mali_osk_miscellaneous
  45. * @{ */
  46. /** @brief Find the containing structure of another structure
  47. *
  48. * This is the reverse of the operation 'offsetof'. This means that the
  49. * following condition is satisfied:
  50. *
  51. * ptr == _MALI_OSK_CONTAINER_OF( &ptr->member, type, member )
  52. *
  53. * When ptr is of type 'type'.
  54. *
  55. * Its purpose it to recover a larger structure that has wrapped a smaller one.
  56. *
  57. * @note no type or memory checking occurs to ensure that a wrapper structure
  58. * does in fact exist, and that it is being recovered with respect to the
  59. * correct member.
  60. *
  61. * @param ptr the pointer to the member that is contained within the larger
  62. * structure
  63. * @param type the type of the structure that contains the member
  64. * @param member the name of the member in the structure that ptr points to.
  65. * @return a pointer to a \a type object which contains \a member, as pointed
  66. * to by \a ptr.
  67. */
  68. #define _MALI_OSK_CONTAINER_OF(ptr, type, member) \
  69. ((type *)( ((char *)ptr) - offsetof(type,member) ))
  70. /** @addtogroup _mali_osk_wq
  71. * @{ */
  72. /** @brief Initialize work queues (for deferred work)
  73. *
  74. * @return _MALI_OSK_ERR_OK on success, otherwise failure.
  75. */
  76. _mali_osk_errcode_t _mali_osk_wq_init(void);
  77. /** @brief Terminate work queues (for deferred work)
  78. */
  79. void _mali_osk_wq_term(void);
  80. /** @brief Create work in the work queue
  81. *
  82. * Creates a work object which can be scheduled in the work queue. When
  83. * scheduled, \a handler will be called with \a data as the argument.
  84. *
  85. * Refer to \ref _mali_osk_wq_schedule_work() for details on how work
  86. * is scheduled in the queue.
  87. *
  88. * The returned pointer must be freed with \ref _mali_osk_wq_delete_work()
  89. * when no longer needed.
  90. */
  91. _mali_osk_wq_work_t *_mali_osk_wq_create_work( _mali_osk_wq_work_handler_t handler, void *data );
  92. /** @brief A high priority version of \a _mali_osk_wq_create_work()
  93. *
  94. * Creates a work object which can be scheduled in the high priority work queue.
  95. *
  96. * This is unfortunately needed to get low latency scheduling of the Mali cores. Normally we would
  97. * schedule the next job in hw_irq or tasklet, but often we can't since we need to synchronously map
  98. * and unmap shared memory when a job is connected to external fences (timelines). And this requires
  99. * taking a mutex.
  100. *
  101. * We do signal a lot of other (low priority) work also as part of the job being finished, and if we
  102. * don't set this Mali scheduling thread as high priority, we see that the CPU scheduler often runs
  103. * random things instead of starting the next GPU job when the GPU is idle. So setting the gpu
  104. * scheduler to high priority does give a visually more responsive system.
  105. *
  106. * Start the high priority work with: \a _mali_osk_wq_schedule_work_high_pri()
  107. */
  108. _mali_osk_wq_work_t *_mali_osk_wq_create_work_high_pri( _mali_osk_wq_work_handler_t handler, void *data );
  109. /** @brief Delete a work object
  110. *
  111. * This will flush the work queue to ensure that the work handler will not
  112. * be called after deletion.
  113. */
  114. void _mali_osk_wq_delete_work( _mali_osk_wq_work_t *work );
  115. /** @brief Delete a work object
  116. *
  117. * This will NOT flush the work queue, so only call this if you are sure that the work handler will
  118. * not be called after deletion.
  119. */
  120. void _mali_osk_wq_delete_work_nonflush( _mali_osk_wq_work_t *work );
  121. /** @brief Cause a queued, deferred call of the work handler
  122. *
  123. * _mali_osk_wq_schedule_work provides a mechanism for enqueuing deferred calls
  124. * to the work handler. After calling \ref _mali_osk_wq_schedule_work(), the
  125. * work handler will be scheduled to run at some point in the future.
  126. *
  127. * Typically this is called by the IRQ upper-half to defer further processing of
  128. * IRQ-related work to the IRQ bottom-half handler. This is necessary for work
  129. * that cannot be done in an IRQ context by the IRQ upper-half handler. Timer
  130. * callbacks also use this mechanism, because they are treated as though they
  131. * operate in an IRQ context. Refer to \ref _mali_osk_timer_t for more
  132. * information.
  133. *
  134. * Code that operates in a kernel-process context (with no IRQ context
  135. * restrictions) may also enqueue deferred calls to the IRQ bottom-half. The
  136. * advantage over direct calling is that deferred calling allows the caller and
  137. * IRQ bottom half to hold the same mutex, with a guarantee that they will not
  138. * deadlock just by using this mechanism.
  139. *
  140. * _mali_osk_wq_schedule_work() places deferred call requests on a queue, to
  141. * allow for more than one thread to make a deferred call. Therfore, if it is
  142. * called 'K' times, then the IRQ bottom-half will be scheduled 'K' times too.
  143. * 'K' is a number that is implementation-specific.
  144. *
  145. * _mali_osk_wq_schedule_work() is guaranteed to not block on:
  146. * - enqueuing a deferred call request.
  147. * - the completion of the work handler.
  148. *
  149. * This is to prevent deadlock. For example, if _mali_osk_wq_schedule_work()
  150. * blocked, then it would cause a deadlock when the following two conditions
  151. * hold:
  152. * - The work handler callback (of type _mali_osk_wq_work_handler_t) locks
  153. * a mutex
  154. * - And, at the same time, the caller of _mali_osk_wq_schedule_work() also
  155. * holds the same mutex
  156. *
  157. * @note care must be taken to not overflow the queue that
  158. * _mali_osk_wq_schedule_work() operates on. Code must be structured to
  159. * ensure that the number of requests made to the queue is bounded. Otherwise,
  160. * work will be lost.
  161. *
  162. * The queue that _mali_osk_wq_schedule_work implements is a FIFO of N-writer,
  163. * 1-reader type. The writers are the callers of _mali_osk_wq_schedule_work
  164. * (all OSK-registered IRQ upper-half handlers in the system, watchdog timers,
  165. * callers from a Kernel-process context). The reader is a single thread that
  166. * handles all OSK-registered work.
  167. *
  168. * @param work a pointer to the _mali_osk_wq_work_t object corresponding to the
  169. * work to begin processing.
  170. */
  171. void _mali_osk_wq_schedule_work( _mali_osk_wq_work_t *work );
  172. /** @brief Cause a queued, deferred call of the high priority work handler
  173. *
  174. * Function is the same as \a _mali_osk_wq_schedule_work() with the only
  175. * difference that it runs in a high (real time) priority on the system.
  176. *
  177. * Should only be used as a substitue for doing the same work in interrupts.
  178. *
  179. * This is allowed to sleep, but the work should be small since it will block
  180. * all other applications.
  181. */
  182. void _mali_osk_wq_schedule_work_high_pri( _mali_osk_wq_work_t *work );
  183. /** @brief Flush the work queue
  184. *
  185. * This will flush the OSK work queue, ensuring all work in the queue has
  186. * completed before returning.
  187. *
  188. * Since this blocks on the completion of work in the work-queue, the
  189. * caller of this function \b must \b not hold any mutexes that are taken by
  190. * any registered work handler. To do so may cause a deadlock.
  191. *
  192. */
  193. void _mali_osk_wq_flush(void);
  194. /** @brief Create work in the delayed work queue
  195. *
  196. * Creates a work object which can be scheduled in the work queue. When
  197. * scheduled, a timer will be start and the \a handler will be called with
  198. * \a data as the argument when timer out
  199. *
  200. * Refer to \ref _mali_osk_wq_delayed_schedule_work() for details on how work
  201. * is scheduled in the queue.
  202. *
  203. * The returned pointer must be freed with \ref _mali_osk_wq_delayed_delete_work_nonflush()
  204. * when no longer needed.
  205. */
  206. _mali_osk_wq_delayed_work_t *_mali_osk_wq_delayed_create_work(_mali_osk_wq_work_handler_t handler, void *data);
  207. /** @brief Delete a work object
  208. *
  209. * This will NOT flush the work queue, so only call this if you are sure that the work handler will
  210. * not be called after deletion.
  211. */
  212. void _mali_osk_wq_delayed_delete_work_nonflush(_mali_osk_wq_delayed_work_t *work);
  213. /** @brief Cancel a delayed work without waiting for it to finish
  214. *
  215. * Note that the \a work callback function may still be running on return from
  216. * _mali_osk_wq_delayed_cancel_work_async().
  217. *
  218. * @param work The delayed work to be cancelled
  219. */
  220. void _mali_osk_wq_delayed_cancel_work_async(_mali_osk_wq_delayed_work_t *work);
  221. /** @brief Cancel a delayed work and wait for it to finish
  222. *
  223. * When this function returns, the \a work was either cancelled or it finished running.
  224. *
  225. * @param work The delayed work to be cancelled
  226. */
  227. void _mali_osk_wq_delayed_cancel_work_sync(_mali_osk_wq_delayed_work_t *work);
  228. /** @brief Put \a work task in global workqueue after delay
  229. *
  230. * After waiting for a given time this puts a job in the kernel-global
  231. * workqueue.
  232. *
  233. * If \a work was already on a queue, this function will return without doing anything
  234. *
  235. * @param work job to be done
  236. * @param delay number of jiffies to wait or 0 for immediate execution
  237. */
  238. void _mali_osk_wq_delayed_schedule_work(_mali_osk_wq_delayed_work_t *work, u32 delay);
  239. /** @} */ /* end group _mali_osk_wq */
  240. /** @addtogroup _mali_osk_irq
  241. * @{ */
  242. /** @brief Initialize IRQ handling for a resource
  243. *
  244. * Registers an interrupt handler \a uhandler for the given IRQ number \a irqnum.
  245. * \a data will be passed as argument to the handler when an interrupt occurs.
  246. *
  247. * If \a irqnum is -1, _mali_osk_irq_init will probe for the IRQ number using
  248. * the supplied \a trigger_func and \a ack_func. These functions will also
  249. * receive \a data as their argument.
  250. *
  251. * @param irqnum The IRQ number that the resource uses, as seen by the CPU.
  252. * The value -1 has a special meaning which indicates the use of probing, and
  253. * trigger_func and ack_func must be non-NULL.
  254. * @param uhandler The interrupt handler, corresponding to a ISR handler for
  255. * the resource
  256. * @param int_data resource specific data, which will be passed to uhandler
  257. * @param trigger_func Optional: a function to trigger the resource's irq, to
  258. * probe for the interrupt. Use NULL if irqnum != -1.
  259. * @param ack_func Optional: a function to acknowledge the resource's irq, to
  260. * probe for the interrupt. Use NULL if irqnum != -1.
  261. * @param probe_data resource-specific data, which will be passed to
  262. * (if present) trigger_func and ack_func
  263. * @param description textual description of the IRQ resource.
  264. * @return on success, a pointer to a _mali_osk_irq_t object, which represents
  265. * the IRQ handling on this resource. NULL on failure.
  266. */
  267. _mali_osk_irq_t *_mali_osk_irq_init( u32 irqnum, _mali_osk_irq_uhandler_t uhandler, void *int_data, _mali_osk_irq_trigger_t trigger_func, _mali_osk_irq_ack_t ack_func, void *probe_data, const char *description );
  268. /** @brief Terminate IRQ handling on a resource.
  269. *
  270. * This will disable the interrupt from the device, and then waits for any
  271. * currently executing IRQ handlers to complete.
  272. *
  273. * @note If work is deferred to an IRQ bottom-half handler through
  274. * \ref _mali_osk_wq_schedule_work(), be sure to flush any remaining work
  275. * with \ref _mali_osk_wq_flush() or (implicitly) with \ref _mali_osk_wq_delete_work()
  276. *
  277. * @param irq a pointer to the _mali_osk_irq_t object corresponding to the
  278. * resource whose IRQ handling is to be terminated.
  279. */
  280. void _mali_osk_irq_term( _mali_osk_irq_t *irq );
  281. /** @} */ /* end group _mali_osk_irq */
  282. /** @addtogroup _mali_osk_atomic
  283. * @{ */
  284. /** @brief Decrement an atomic counter
  285. *
  286. * @note It is an error to decrement the counter beyond -(1<<23)
  287. *
  288. * @param atom pointer to an atomic counter */
  289. void _mali_osk_atomic_dec( _mali_osk_atomic_t *atom );
  290. /** @brief Decrement an atomic counter, return new value
  291. *
  292. * @param atom pointer to an atomic counter
  293. * @return The new value, after decrement */
  294. u32 _mali_osk_atomic_dec_return( _mali_osk_atomic_t *atom );
  295. /** @brief Increment an atomic counter
  296. *
  297. * @note It is an error to increment the counter beyond (1<<23)-1
  298. *
  299. * @param atom pointer to an atomic counter */
  300. void _mali_osk_atomic_inc( _mali_osk_atomic_t *atom );
  301. /** @brief Increment an atomic counter, return new value
  302. *
  303. * @param atom pointer to an atomic counter */
  304. u32 _mali_osk_atomic_inc_return( _mali_osk_atomic_t *atom );
  305. /** @brief Initialize an atomic counter
  306. *
  307. * @note the parameter required is a u32, and so signed integers should be
  308. * cast to u32.
  309. *
  310. * @param atom pointer to an atomic counter
  311. * @param val the value to initialize the atomic counter.
  312. * @return _MALI_OSK_ERR_OK on success, otherwise, a suitable
  313. * _mali_osk_errcode_t on failure.
  314. */
  315. _mali_osk_errcode_t _mali_osk_atomic_init( _mali_osk_atomic_t *atom, u32 val );
  316. /** @brief Read a value from an atomic counter
  317. *
  318. * This can only be safely used to determine the value of the counter when it
  319. * is guaranteed that other threads will not be modifying the counter. This
  320. * makes its usefulness limited.
  321. *
  322. * @param atom pointer to an atomic counter
  323. */
  324. u32 _mali_osk_atomic_read( _mali_osk_atomic_t *atom );
  325. /** @brief Terminate an atomic counter
  326. *
  327. * @param atom pointer to an atomic counter
  328. */
  329. void _mali_osk_atomic_term( _mali_osk_atomic_t *atom );
  330. /** @brief Assign a new val to atomic counter, and return the old atomic counter
  331. *
  332. * @param atom pointer to an atomic counter
  333. * @param val the new value assign to the atomic counter
  334. * @return the old value of the atomic counter
  335. */
  336. u32 _mali_osk_atomic_xchg( _mali_osk_atomic_t *atom, u32 val );
  337. /** @} */ /* end group _mali_osk_atomic */
  338. /** @defgroup _mali_osk_memory OSK Memory Allocation
  339. * @{ */
  340. /** @brief Allocate zero-initialized memory.
  341. *
  342. * Returns a buffer capable of containing at least \a n elements of \a size
  343. * bytes each. The buffer is initialized to zero.
  344. *
  345. * If there is a need for a bigger block of memory (16KB or bigger), then
  346. * consider to use _mali_osk_vmalloc() instead, as this function might
  347. * map down to a OS function with size limitations.
  348. *
  349. * The buffer is suitably aligned for storage and subsequent access of every
  350. * type that the compiler supports. Therefore, the pointer to the start of the
  351. * buffer may be cast into any pointer type, and be subsequently accessed from
  352. * such a pointer, without loss of information.
  353. *
  354. * When the buffer is no longer in use, it must be freed with _mali_osk_free().
  355. * Failure to do so will cause a memory leak.
  356. *
  357. * @note Most toolchains supply memory allocation functions that meet the
  358. * compiler's alignment requirements.
  359. *
  360. * @param n Number of elements to allocate
  361. * @param size Size of each element
  362. * @return On success, the zero-initialized buffer allocated. NULL on failure
  363. */
  364. void *_mali_osk_calloc( u32 n, u32 size );
  365. /** @brief Allocate memory.
  366. *
  367. * Returns a buffer capable of containing at least \a size bytes. The
  368. * contents of the buffer are undefined.
  369. *
  370. * If there is a need for a bigger block of memory (16KB or bigger), then
  371. * consider to use _mali_osk_vmalloc() instead, as this function might
  372. * map down to a OS function with size limitations.
  373. *
  374. * The buffer is suitably aligned for storage and subsequent access of every
  375. * type that the compiler supports. Therefore, the pointer to the start of the
  376. * buffer may be cast into any pointer type, and be subsequently accessed from
  377. * such a pointer, without loss of information.
  378. *
  379. * When the buffer is no longer in use, it must be freed with _mali_osk_free().
  380. * Failure to do so will cause a memory leak.
  381. *
  382. * @note Most toolchains supply memory allocation functions that meet the
  383. * compiler's alignment requirements.
  384. *
  385. * Remember to free memory using _mali_osk_free().
  386. * @param size Number of bytes to allocate
  387. * @return On success, the buffer allocated. NULL on failure.
  388. */
  389. void *_mali_osk_malloc( u32 size );
  390. /** @brief Free memory.
  391. *
  392. * Reclaims the buffer pointed to by the parameter \a ptr for the system.
  393. * All memory returned from _mali_osk_malloc() and _mali_osk_calloc()
  394. * must be freed before the application exits. Otherwise,
  395. * a memory leak will occur.
  396. *
  397. * Memory must be freed once. It is an error to free the same non-NULL pointer
  398. * more than once.
  399. *
  400. * It is legal to free the NULL pointer.
  401. *
  402. * @param ptr Pointer to buffer to free
  403. */
  404. void _mali_osk_free( void *ptr );
  405. /** @brief Allocate memory.
  406. *
  407. * Returns a buffer capable of containing at least \a size bytes. The
  408. * contents of the buffer are undefined.
  409. *
  410. * This function is potentially slower than _mali_osk_malloc() and _mali_osk_calloc(),
  411. * but do support bigger sizes.
  412. *
  413. * The buffer is suitably aligned for storage and subsequent access of every
  414. * type that the compiler supports. Therefore, the pointer to the start of the
  415. * buffer may be cast into any pointer type, and be subsequently accessed from
  416. * such a pointer, without loss of information.
  417. *
  418. * When the buffer is no longer in use, it must be freed with _mali_osk_free().
  419. * Failure to do so will cause a memory leak.
  420. *
  421. * @note Most toolchains supply memory allocation functions that meet the
  422. * compiler's alignment requirements.
  423. *
  424. * Remember to free memory using _mali_osk_free().
  425. * @param size Number of bytes to allocate
  426. * @return On success, the buffer allocated. NULL on failure.
  427. */
  428. void *_mali_osk_valloc( u32 size );
  429. /** @brief Free memory.
  430. *
  431. * Reclaims the buffer pointed to by the parameter \a ptr for the system.
  432. * All memory returned from _mali_osk_valloc() must be freed before the
  433. * application exits. Otherwise a memory leak will occur.
  434. *
  435. * Memory must be freed once. It is an error to free the same non-NULL pointer
  436. * more than once.
  437. *
  438. * It is legal to free the NULL pointer.
  439. *
  440. * @param ptr Pointer to buffer to free
  441. */
  442. void _mali_osk_vfree( void *ptr );
  443. /** @brief Copies memory.
  444. *
  445. * Copies the \a len bytes from the buffer pointed by the parameter \a src
  446. * directly to the buffer pointed by \a dst.
  447. *
  448. * It is an error for \a src to overlap \a dst anywhere in \a len bytes.
  449. *
  450. * @param dst Pointer to the destination array where the content is to be
  451. * copied.
  452. * @param src Pointer to the source of data to be copied.
  453. * @param len Number of bytes to copy.
  454. * @return \a dst is always passed through unmodified.
  455. */
  456. void *_mali_osk_memcpy( void *dst, const void *src, u32 len );
  457. /** @brief Fills memory.
  458. *
  459. * Sets the first \a n bytes of the block of memory pointed to by \a s to
  460. * the specified value
  461. * @param s Pointer to the block of memory to fill.
  462. * @param c Value to be set, passed as u32. Only the 8 Least Significant Bits (LSB)
  463. * are used.
  464. * @param n Number of bytes to be set to the value.
  465. * @return \a s is always passed through unmodified
  466. */
  467. void *_mali_osk_memset( void *s, u32 c, u32 n );
  468. /** @} */ /* end group _mali_osk_memory */
  469. /** @brief Checks the amount of memory allocated
  470. *
  471. * Checks that not more than \a max_allocated bytes are allocated.
  472. *
  473. * Some OS bring up an interactive out of memory dialogue when the
  474. * system runs out of memory. This can stall non-interactive
  475. * apps (e.g. automated test runs). This function can be used to
  476. * not trigger the OOM dialogue by keeping allocations
  477. * within a certain limit.
  478. *
  479. * @return MALI_TRUE when \a max_allocated bytes are not in use yet. MALI_FALSE
  480. * when at least \a max_allocated bytes are in use.
  481. */
  482. mali_bool _mali_osk_mem_check_allocated( u32 max_allocated );
  483. /** @addtogroup _mali_osk_low_level_memory
  484. * @{ */
  485. /** @brief Issue a memory barrier
  486. *
  487. * This defines an arbitrary memory barrier operation, which forces an ordering constraint
  488. * on memory read and write operations.
  489. */
  490. void _mali_osk_mem_barrier( void );
  491. /** @brief Issue a write memory barrier
  492. *
  493. * This defines an write memory barrier operation which forces an ordering constraint
  494. * on memory write operations.
  495. */
  496. void _mali_osk_write_mem_barrier( void );
  497. /** @brief Map a physically contiguous region into kernel space
  498. *
  499. * This is primarily used for mapping in registers from resources, and Mali-MMU
  500. * page tables. The mapping is only visable from kernel-space.
  501. *
  502. * Access has to go through _mali_osk_mem_ioread32 and _mali_osk_mem_iowrite32
  503. *
  504. * @param phys CPU-physical base address of the memory to map in. This must
  505. * be aligned to the system's page size, which is assumed to be 4K.
  506. * @param size the number of bytes of physically contiguous address space to
  507. * map in
  508. * @param description A textual description of the memory being mapped in.
  509. * @return On success, a Mali IO address through which the mapped-in
  510. * memory/registers can be accessed. NULL on failure.
  511. */
  512. mali_io_address _mali_osk_mem_mapioregion( u32 phys, u32 size, const char *description );
  513. /** @brief Unmap a physically contiguous address range from kernel space.
  514. *
  515. * The address range should be one previously mapped in through
  516. * _mali_osk_mem_mapioregion.
  517. *
  518. * It is a programming error to do (but not limited to) the following:
  519. * - attempt an unmap twice
  520. * - unmap only part of a range obtained through _mali_osk_mem_mapioregion
  521. * - unmap more than the range obtained through _mali_osk_mem_mapioregion
  522. * - unmap an address range that was not successfully mapped using
  523. * _mali_osk_mem_mapioregion
  524. * - provide a mapping that does not map to phys.
  525. *
  526. * @param phys CPU-physical base address of the memory that was originally
  527. * mapped in. This must be aligned to the system's page size, which is assumed
  528. * to be 4K
  529. * @param size The number of bytes that were originally mapped in.
  530. * @param mapping The Mali IO address through which the mapping is
  531. * accessed.
  532. */
  533. void _mali_osk_mem_unmapioregion( u32 phys, u32 size, mali_io_address mapping );
  534. /** @brief Allocate and Map a physically contiguous region into kernel space
  535. *
  536. * This is used for allocating physically contiguous regions (such as Mali-MMU
  537. * page tables) and mapping them into kernel space. The mapping is only
  538. * visible from kernel-space.
  539. *
  540. * The alignment of the returned memory is guaranteed to be at least
  541. * _MALI_OSK_CPU_PAGE_SIZE.
  542. *
  543. * Access must go through _mali_osk_mem_ioread32 and _mali_osk_mem_iowrite32
  544. *
  545. * @note This function is primarily to provide support for OSs that are
  546. * incapable of separating the tasks 'allocate physically contiguous memory'
  547. * and 'map it into kernel space'
  548. *
  549. * @param[out] phys CPU-physical base address of memory that was allocated.
  550. * (*phys) will be guaranteed to be aligned to at least
  551. * _MALI_OSK_CPU_PAGE_SIZE on success.
  552. *
  553. * @param[in] size the number of bytes of physically contiguous memory to
  554. * allocate. This must be a multiple of _MALI_OSK_CPU_PAGE_SIZE.
  555. *
  556. * @return On success, a Mali IO address through which the mapped-in
  557. * memory/registers can be accessed. NULL on failure, and (*phys) is unmodified.
  558. */
  559. mali_io_address _mali_osk_mem_allocioregion( u32 *phys, u32 size );
  560. /** @brief Free a physically contiguous address range from kernel space.
  561. *
  562. * The address range should be one previously mapped in through
  563. * _mali_osk_mem_allocioregion.
  564. *
  565. * It is a programming error to do (but not limited to) the following:
  566. * - attempt a free twice on the same ioregion
  567. * - free only part of a range obtained through _mali_osk_mem_allocioregion
  568. * - free more than the range obtained through _mali_osk_mem_allocioregion
  569. * - free an address range that was not successfully mapped using
  570. * _mali_osk_mem_allocioregion
  571. * - provide a mapping that does not map to phys.
  572. *
  573. * @param phys CPU-physical base address of the memory that was originally
  574. * mapped in, which was aligned to _MALI_OSK_CPU_PAGE_SIZE.
  575. * @param size The number of bytes that were originally mapped in, which was
  576. * a multiple of _MALI_OSK_CPU_PAGE_SIZE.
  577. * @param mapping The Mali IO address through which the mapping is
  578. * accessed.
  579. */
  580. void _mali_osk_mem_freeioregion( u32 phys, u32 size, mali_io_address mapping );
  581. /** @brief Request a region of physically contiguous memory
  582. *
  583. * This is used to ensure exclusive access to a region of physically contigous
  584. * memory.
  585. *
  586. * It is acceptable to implement this as a stub. However, it is then the job
  587. * of the System Integrator to ensure that no other device driver will be using
  588. * the physical address ranges used by Mali, while the Mali device driver is
  589. * loaded.
  590. *
  591. * @param phys CPU-physical base address of the memory to request. This must
  592. * be aligned to the system's page size, which is assumed to be 4K.
  593. * @param size the number of bytes of physically contiguous address space to
  594. * request.
  595. * @param description A textual description of the memory being requested.
  596. * @return _MALI_OSK_ERR_OK on success. Otherwise, a suitable
  597. * _mali_osk_errcode_t on failure.
  598. */
  599. _mali_osk_errcode_t _mali_osk_mem_reqregion( u32 phys, u32 size, const char *description );
  600. /** @brief Un-request a region of physically contiguous memory
  601. *
  602. * This is used to release a regious of physically contiguous memory previously
  603. * requested through _mali_osk_mem_reqregion, so that other device drivers may
  604. * use it. This will be called at time of Mali device driver termination.
  605. *
  606. * It is a programming error to attempt to:
  607. * - unrequest a region twice
  608. * - unrequest only part of a range obtained through _mali_osk_mem_reqregion
  609. * - unrequest more than the range obtained through _mali_osk_mem_reqregion
  610. * - unrequest an address range that was not successfully requested using
  611. * _mali_osk_mem_reqregion
  612. *
  613. * @param phys CPU-physical base address of the memory to un-request. This must
  614. * be aligned to the system's page size, which is assumed to be 4K
  615. * @param size the number of bytes of physically contiguous address space to
  616. * un-request.
  617. */
  618. void _mali_osk_mem_unreqregion( u32 phys, u32 size );
  619. /** @brief Read from a location currently mapped in through
  620. * _mali_osk_mem_mapioregion
  621. *
  622. * This reads a 32-bit word from a 32-bit aligned location. It is a programming
  623. * error to provide unaligned locations, or to read from memory that is not
  624. * mapped in, or not mapped through either _mali_osk_mem_mapioregion() or
  625. * _mali_osk_mem_allocioregion().
  626. *
  627. * @param mapping Mali IO address to read from
  628. * @param offset Byte offset from the given IO address to operate on, must be a multiple of 4
  629. * @return the 32-bit word from the specified location.
  630. */
  631. u32 _mali_osk_mem_ioread32( volatile mali_io_address mapping, u32 offset );
  632. /** @brief Write to a location currently mapped in through
  633. * _mali_osk_mem_mapioregion without memory barriers
  634. *
  635. * This write a 32-bit word to a 32-bit aligned location without using memory barrier.
  636. * It is a programming error to provide unaligned locations, or to write to memory that is not
  637. * mapped in, or not mapped through either _mali_osk_mem_mapioregion() or
  638. * _mali_osk_mem_allocioregion().
  639. *
  640. * @param mapping Mali IO address to write to
  641. * @param offset Byte offset from the given IO address to operate on, must be a multiple of 4
  642. * @param val the 32-bit word to write.
  643. */
  644. void _mali_osk_mem_iowrite32_relaxed( volatile mali_io_address addr, u32 offset, u32 val );
  645. /** @brief Write to a location currently mapped in through
  646. * _mali_osk_mem_mapioregion with write memory barrier
  647. *
  648. * This write a 32-bit word to a 32-bit aligned location. It is a programming
  649. * error to provide unaligned locations, or to write to memory that is not
  650. * mapped in, or not mapped through either _mali_osk_mem_mapioregion() or
  651. * _mali_osk_mem_allocioregion().
  652. *
  653. * @param mapping Mali IO address to write to
  654. * @param offset Byte offset from the given IO address to operate on, must be a multiple of 4
  655. * @param val the 32-bit word to write.
  656. */
  657. void _mali_osk_mem_iowrite32( volatile mali_io_address mapping, u32 offset, u32 val );
  658. /** @brief Flush all CPU caches
  659. *
  660. * This should only be implemented if flushing of the cache is required for
  661. * memory mapped in through _mali_osk_mem_mapregion.
  662. */
  663. void _mali_osk_cache_flushall( void );
  664. /** @brief Flush any caches necessary for the CPU and MALI to have the same view of a range of uncached mapped memory
  665. *
  666. * This should only be implemented if your OS doesn't do a full cache flush (inner & outer)
  667. * after allocating uncached mapped memory.
  668. *
  669. * Some OS do not perform a full cache flush (including all outer caches) for uncached mapped memory.
  670. * They zero the memory through a cached mapping, then flush the inner caches but not the outer caches.
  671. * This is required for MALI to have the correct view of the memory.
  672. */
  673. void _mali_osk_cache_ensure_uncached_range_flushed( void *uncached_mapping, u32 offset, u32 size );
  674. /** @} */ /* end group _mali_osk_low_level_memory */
  675. /** @addtogroup _mali_osk_notification
  676. *
  677. * User space notification framework
  678. *
  679. * Communication with user space of asynchronous events is performed through a
  680. * synchronous call to the \ref u_k_api.
  681. *
  682. * Since the events are asynchronous, the events have to be queued until a
  683. * synchronous U/K API call can be made by user-space. A U/K API call might also
  684. * be received before any event has happened. Therefore the notifications the
  685. * different subsystems wants to send to user space has to be queued for later
  686. * reception, or a U/K API call has to be blocked until an event has occured.
  687. *
  688. * Typical uses of notifications are after running of jobs on the hardware or
  689. * when changes to the system is detected that needs to be relayed to user
  690. * space.
  691. *
  692. * After an event has occured user space has to be notified using some kind of
  693. * message. The notification framework supports sending messages to waiting
  694. * threads or queueing of messages until a U/K API call is made.
  695. *
  696. * The notification queue is a FIFO. There are no restrictions on the numbers
  697. * of readers or writers in the queue.
  698. *
  699. * A message contains what user space needs to identifiy how to handle an
  700. * event. This includes a type field and a possible type specific payload.
  701. *
  702. * A notification to user space is represented by a
  703. * \ref _mali_osk_notification_t object. A sender gets hold of such an object
  704. * using _mali_osk_notification_create(). The buffer given by the
  705. * _mali_osk_notification_t::result_buffer field in the object is used to store
  706. * any type specific data. The other fields are internal to the queue system
  707. * and should not be touched.
  708. *
  709. * @{ */
  710. /** @brief Create a notification object
  711. *
  712. * Returns a notification object which can be added to the queue of
  713. * notifications pending for user space transfer.
  714. *
  715. * The implementation will initialize all members of the
  716. * \ref _mali_osk_notification_t object. In particular, the
  717. * _mali_osk_notification_t::result_buffer member will be initialized to point
  718. * to \a size bytes of storage, and that storage will be suitably aligned for
  719. * storage of any structure. That is, the created buffer meets the same
  720. * requirements as _mali_osk_malloc().
  721. *
  722. * The notification object must be deleted when not in use. Use
  723. * _mali_osk_notification_delete() for deleting it.
  724. *
  725. * @note You \b must \b not call _mali_osk_free() on a \ref _mali_osk_notification_t,
  726. * object, or on a _mali_osk_notification_t::result_buffer. You must only use
  727. * _mali_osk_notification_delete() to free the resources assocaited with a
  728. * \ref _mali_osk_notification_t object.
  729. *
  730. * @param type The notification type
  731. * @param size The size of the type specific buffer to send
  732. * @return Pointer to a notification object with a suitable buffer, or NULL on error.
  733. */
  734. _mali_osk_notification_t *_mali_osk_notification_create( u32 type, u32 size );
  735. /** @brief Delete a notification object
  736. *
  737. * This must be called to reclaim the resources of a notification object. This
  738. * includes:
  739. * - The _mali_osk_notification_t::result_buffer
  740. * - The \ref _mali_osk_notification_t itself.
  741. *
  742. * A notification object \b must \b not be used after it has been deleted by
  743. * _mali_osk_notification_delete().
  744. *
  745. * In addition, the notification object may not be deleted while it is in a
  746. * queue. That is, if it has been placed on a queue with
  747. * _mali_osk_notification_queue_send(), then it must not be deleted until
  748. * it has been received by a call to _mali_osk_notification_queue_receive().
  749. * Otherwise, the queue may be corrupted.
  750. *
  751. * @param object the notification object to delete.
  752. */
  753. void _mali_osk_notification_delete( _mali_osk_notification_t *object );
  754. /** @brief Create a notification queue
  755. *
  756. * Creates a notification queue which can be used to queue messages for user
  757. * delivery and get queued messages from
  758. *
  759. * The queue is a FIFO, and has no restrictions on the numbers of readers or
  760. * writers.
  761. *
  762. * When the queue is no longer in use, it must be terminated with
  763. * \ref _mali_osk_notification_queue_term(). Failure to do so will result in a
  764. * memory leak.
  765. *
  766. * @return Pointer to a new notification queue or NULL on error.
  767. */
  768. _mali_osk_notification_queue_t *_mali_osk_notification_queue_init( void );
  769. /** @brief Destroy a notification queue
  770. *
  771. * Destroys a notification queue and frees associated resources from the queue.
  772. *
  773. * A notification queue \b must \b not be destroyed in the following cases:
  774. * - while there are \ref _mali_osk_notification_t objects in the queue.
  775. * - while there are writers currently acting upon the queue. That is, while
  776. * a thread is currently calling \ref _mali_osk_notification_queue_send() on
  777. * the queue, or while a thread may call
  778. * \ref _mali_osk_notification_queue_send() on the queue in the future.
  779. * - while there are readers currently waiting upon the queue. That is, while
  780. * a thread is currently calling \ref _mali_osk_notification_queue_receive() on
  781. * the queue, or while a thread may call
  782. * \ref _mali_osk_notification_queue_receive() on the queue in the future.
  783. *
  784. * Therefore, all \ref _mali_osk_notification_t objects must be flushed and
  785. * deleted by the code that makes use of the notification queues, since only
  786. * they know the structure of the _mali_osk_notification_t::result_buffer
  787. * (even if it may only be a flat sturcture).
  788. *
  789. * @note Since the queue is a FIFO, the code using notification queues may
  790. * create its own 'flush' type of notification, to assist in flushing the
  791. * queue.
  792. *
  793. * Once the queue has been destroyed, it must not be used again.
  794. *
  795. * @param queue The queue to destroy
  796. */
  797. void _mali_osk_notification_queue_term( _mali_osk_notification_queue_t *queue );
  798. /** @brief Schedule notification for delivery
  799. *
  800. * When a \ref _mali_osk_notification_t object has been created successfully
  801. * and set up, it may be added to the queue of objects waiting for user space
  802. * transfer.
  803. *
  804. * The sending will not block if the queue is full.
  805. *
  806. * A \ref _mali_osk_notification_t object \b must \b not be put on two different
  807. * queues at the same time, or enqueued twice onto a single queue before
  808. * reception. However, it is acceptable for it to be requeued \em after reception
  809. * from a call to _mali_osk_notification_queue_receive(), even onto the same queue.
  810. *
  811. * Again, requeuing must also not enqueue onto two different queues at the same
  812. * time, or enqueue onto the same queue twice before reception.
  813. *
  814. * @param queue The notification queue to add this notification to
  815. * @param object The entry to add
  816. */
  817. void _mali_osk_notification_queue_send( _mali_osk_notification_queue_t *queue, _mali_osk_notification_t *object );
  818. /** @brief Receive a notification from a queue
  819. *
  820. * Receives a single notification from the given queue.
  821. *
  822. * If no notifciations are ready the thread will sleep until one becomes ready.
  823. * Therefore, notifications may not be received into an
  824. * IRQ or 'atomic' context (that is, a context where sleeping is disallowed).
  825. *
  826. * @param queue The queue to receive from
  827. * @param result Pointer to storage of a pointer of type
  828. * \ref _mali_osk_notification_t*. \a result will be written to such that the
  829. * expression \a (*result) will evaluate to a pointer to a valid
  830. * \ref _mali_osk_notification_t object, or NULL if none were received.
  831. * @return _MALI_OSK_ERR_OK on success. _MALI_OSK_ERR_RESTARTSYSCALL if the sleep was interrupted.
  832. */
  833. _mali_osk_errcode_t _mali_osk_notification_queue_receive( _mali_osk_notification_queue_t *queue, _mali_osk_notification_t **result );
  834. /** @brief Dequeues a notification from a queue
  835. *
  836. * Receives a single notification from the given queue.
  837. *
  838. * If no notifciations are ready the function call will return an error code.
  839. *
  840. * @param queue The queue to receive from
  841. * @param result Pointer to storage of a pointer of type
  842. * \ref _mali_osk_notification_t*. \a result will be written to such that the
  843. * expression \a (*result) will evaluate to a pointer to a valid
  844. * \ref _mali_osk_notification_t object, or NULL if none were received.
  845. * @return _MALI_OSK_ERR_OK on success, _MALI_OSK_ERR_ITEM_NOT_FOUND if queue was empty.
  846. */
  847. _mali_osk_errcode_t _mali_osk_notification_queue_dequeue( _mali_osk_notification_queue_t *queue, _mali_osk_notification_t **result );
  848. /** @} */ /* end group _mali_osk_notification */
  849. /** @addtogroup _mali_osk_timer
  850. *
  851. * Timers use the OS's representation of time, which are 'ticks'. This is to
  852. * prevent aliasing problems between the internal timer time, and the time
  853. * asked for.
  854. *
  855. * @{ */
  856. /** @brief Initialize a timer
  857. *
  858. * Allocates resources for a new timer, and initializes them. This does not
  859. * start the timer.
  860. *
  861. * @return a pointer to the allocated timer object, or NULL on failure.
  862. */
  863. _mali_osk_timer_t *_mali_osk_timer_init(void);
  864. /** @brief Start a timer
  865. *
  866. * It is an error to start a timer without setting the callback via
  867. * _mali_osk_timer_setcallback().
  868. *
  869. * It is an error to use this to start an already started timer.
  870. *
  871. * The timer will expire in \a ticks_to_expire ticks, at which point, the
  872. * callback function will be invoked with the callback-specific data,
  873. * as registered by _mali_osk_timer_setcallback().
  874. *
  875. * @param tim the timer to start
  876. * @param ticks_to_expire the amount of time in ticks for the timer to run
  877. * before triggering.
  878. */
  879. void _mali_osk_timer_add( _mali_osk_timer_t *tim, u32 ticks_to_expire );
  880. /** @brief Modify a timer
  881. *
  882. * Set the relative time at which a timer will expire, and start it if it is
  883. * stopped. If \a ticks_to_expire 0 the timer fires immediately.
  884. *
  885. * It is an error to modify a timer without setting the callback via
  886. * _mali_osk_timer_setcallback().
  887. *
  888. * The timer will expire at \a ticks_to_expire from the time of the call, at
  889. * which point, the callback function will be invoked with the
  890. * callback-specific data, as set by _mali_osk_timer_setcallback().
  891. *
  892. * @param tim the timer to modify, and start if necessary
  893. * @param ticks_to_expire the \em absolute time in ticks at which this timer
  894. * should trigger.
  895. *
  896. */
  897. void _mali_osk_timer_mod( _mali_osk_timer_t *tim, u32 ticks_to_expire);
  898. /** @brief Stop a timer, and block on its completion.
  899. *
  900. * Stop the timer. When the function returns, it is guaranteed that the timer's
  901. * callback will not be running on any CPU core.
  902. *
  903. * Since stoping the timer blocks on compeletion of the callback, the callback
  904. * may not obtain any mutexes that the caller holds. Otherwise, a deadlock will
  905. * occur.
  906. *
  907. * @note While the callback itself is guaranteed to not be running, work
  908. * enqueued on the work-queue by the timer (with
  909. * \ref _mali_osk_wq_schedule_work()) may still run. The timer callback and
  910. * work handler must take this into account.
  911. *
  912. * It is legal to stop an already stopped timer.
  913. *
  914. * @param tim the timer to stop.
  915. *
  916. */
  917. void _mali_osk_timer_del( _mali_osk_timer_t *tim );
  918. /** @brief Stop a timer.
  919. *
  920. * Stop the timer. When the function returns, the timer's callback may still be
  921. * running on any CPU core.
  922. *
  923. * It is legal to stop an already stopped timer.
  924. *
  925. * @param tim the timer to stop.
  926. */
  927. void _mali_osk_timer_del_async( _mali_osk_timer_t *tim );
  928. /** @brief Check if timer is pending.
  929. *
  930. * Check if timer is active.
  931. *
  932. * @param tim the timer to check
  933. * @return MALI_TRUE if time is active, MALI_FALSE if it is not active
  934. */
  935. mali_bool _mali_osk_timer_pending( _mali_osk_timer_t *tim);
  936. /** @brief Set a timer's callback parameters.
  937. *
  938. * This must be called at least once before a timer is started/modified.
  939. *
  940. * After a timer has been stopped or expires, the callback remains set. This
  941. * means that restarting the timer will call the same function with the same
  942. * parameters on expiry.
  943. *
  944. * @param tim the timer to set callback on.
  945. * @param callback Function to call when timer expires
  946. * @param data Function-specific data to supply to the function on expiry.
  947. */
  948. void _mali_osk_timer_setcallback( _mali_osk_timer_t *tim, void *callback, void *data );
  949. /** @brief Terminate a timer, and deallocate resources.
  950. *
  951. * The timer must first be stopped by calling _mali_osk_timer_del().
  952. *
  953. * It is a programming error for _mali_osk_timer_term() to be called on:
  954. * - timer that is currently running
  955. * - a timer that is currently executing its callback.
  956. *
  957. * @param tim the timer to deallocate.
  958. */
  959. void _mali_osk_timer_term( _mali_osk_timer_t *tim );
  960. /** @} */ /* end group _mali_osk_timer */
  961. /** @defgroup _mali_osk_time OSK Time functions
  962. *
  963. * \ref _mali_osk_time use the OS's representation of time, which are
  964. * 'ticks'. This is to prevent aliasing problems between the internal timer
  965. * time, and the time asked for.
  966. *
  967. * OS tick time is measured as a u32. The time stored in a u32 may either be
  968. * an absolute time, or a time delta between two events. Whilst it is valid to
  969. * use math opeartors to \em change the tick value represented as a u32, it
  970. * is often only meaningful to do such operations on time deltas, rather than
  971. * on absolute time. However, it is meaningful to add/subtract time deltas to
  972. * absolute times.
  973. *
  974. * Conversion between tick time and milliseconds (ms) may not be loss-less,
  975. * and are \em implementation \em depenedant.
  976. *
  977. * Code use OS time must take this into account, since:
  978. * - a small OS time may (or may not) be rounded
  979. * - a large time may (or may not) overflow
  980. *
  981. * @{ */
  982. /** @brief Return whether ticka occurs after tickb
  983. *
  984. * Some OSs handle tick 'rollover' specially, and so can be more robust against
  985. * tick counters rolling-over. This function must therefore be called to
  986. * determine if a time (in ticks) really occurs after another time (in ticks).
  987. *
  988. * @param ticka ticka
  989. * @param tickb tickb
  990. * @return non-zero if ticka represents a time that occurs after tickb.
  991. * Zero otherwise.
  992. */
  993. int _mali_osk_time_after( u32 ticka, u32 tickb );
  994. /** @brief Convert milliseconds to OS 'ticks'
  995. *
  996. * @param ms time interval in milliseconds
  997. * @return the corresponding time interval in OS ticks.
  998. */
  999. u32 _mali_osk_time_mstoticks( u32 ms );
  1000. /** @brief Convert OS 'ticks' to milliseconds
  1001. *
  1002. * @param ticks time interval in OS ticks.
  1003. * @return the corresponding time interval in milliseconds
  1004. */
  1005. u32 _mali_osk_time_tickstoms( u32 ticks );
  1006. /** @brief Get the current time in OS 'ticks'.
  1007. * @return the current time in OS 'ticks'.
  1008. */
  1009. u32 _mali_osk_time_tickcount( void );
  1010. /** @brief Cause a microsecond delay
  1011. *
  1012. * The delay will have microsecond resolution, and is necessary for correct
  1013. * operation of the driver. At worst, the delay will be \b at least \a usecs
  1014. * microseconds, and so may be (significantly) more.
  1015. *
  1016. * This function may be implemented as a busy-wait, which is the most sensible
  1017. * implementation. On OSs where there are situations in which a thread must not
  1018. * sleep, this is definitely implemented as a busy-wait.
  1019. *
  1020. * @param usecs the number of microseconds to wait for.
  1021. */
  1022. void _mali_osk_time_ubusydelay( u32 usecs );
  1023. /** @brief Return time in nano seconds, since any given reference.
  1024. *
  1025. * @return Time in nano seconds
  1026. */
  1027. u64 _mali_osk_time_get_ns( void );
  1028. /** @} */ /* end group _mali_osk_time */
  1029. /** @defgroup _mali_osk_math OSK Math
  1030. * @{ */
  1031. /** @brief Count Leading Zeros (Little-endian)
  1032. *
  1033. * @note This function must be implemented to support the reference
  1034. * implementation of _mali_osk_find_first_zero_bit, as defined in
  1035. * mali_osk_bitops.h.
  1036. *
  1037. * @param val 32-bit words to count leading zeros on
  1038. * @return the number of leading zeros.
  1039. */
  1040. u32 _mali_osk_clz( u32 val );
  1041. /** @brief find last (most-significant) bit set
  1042. *
  1043. * @param val 32-bit words to count last bit set on
  1044. * @return last bit set.
  1045. */
  1046. u32 _mali_osk_fls( u32 val );
  1047. /** @} */ /* end group _mali_osk_math */
  1048. /** @addtogroup _mali_osk_wait_queue OSK Wait Queue functionality
  1049. * @{ */
  1050. /** @brief Initialize an empty Wait Queue */
  1051. _mali_osk_wait_queue_t* _mali_osk_wait_queue_init( void );
  1052. /** @brief Sleep if condition is false
  1053. *
  1054. * @param queue the queue to use
  1055. * @param condition function pointer to a boolean function
  1056. * @param data data parameter for condition function
  1057. *
  1058. * Put thread to sleep if the given \a condition function returns false. When
  1059. * being asked to wake up again, the condition will be re-checked and the
  1060. * thread only woken up if the condition is now true.
  1061. */
  1062. void _mali_osk_wait_queue_wait_event( _mali_osk_wait_queue_t *queue, mali_bool (*condition)(void *), void *data );
  1063. /** @brief Sleep if condition is false
  1064. *
  1065. * @param queue the queue to use
  1066. * @param condition function pointer to a boolean function
  1067. * @param data data parameter for condition function
  1068. * @param timeout timeout in ms
  1069. *
  1070. * Put thread to sleep if the given \a condition function returns false. When
  1071. * being asked to wake up again, the condition will be re-checked and the
  1072. * thread only woken up if the condition is now true. Will return if time
  1073. * exceeds timeout.
  1074. */
  1075. void _mali_osk_wait_queue_wait_event_timeout( _mali_osk_wait_queue_t *queue, mali_bool (*condition)(void *), void *data, u32 timeout );
  1076. /** @brief Wake up all threads in wait queue if their respective conditions are
  1077. * true
  1078. *
  1079. * @param queue the queue whose threads should be woken up
  1080. *
  1081. * Wake up all threads in wait queue \a queue whose condition is now true.
  1082. */
  1083. void _mali_osk_wait_queue_wake_up( _mali_osk_wait_queue_t *queue );
  1084. /** @brief terminate a wait queue
  1085. *
  1086. * @param queue the queue to terminate.
  1087. */
  1088. void _mali_osk_wait_queue_term( _mali_osk_wait_queue_t *queue );
  1089. /** @} */ /* end group _mali_osk_wait_queue */
  1090. /** @addtogroup _mali_osk_miscellaneous
  1091. * @{ */
  1092. /** @brief Output a device driver debug message.
  1093. *
  1094. * The interpretation of \a fmt is the same as the \c format parameter in
  1095. * _mali_osu_vsnprintf().
  1096. *
  1097. * @param fmt a _mali_osu_vsnprintf() style format string
  1098. * @param ... a variable-number of parameters suitable for \a fmt
  1099. */
  1100. void _mali_osk_dbgmsg( const char *fmt, ... );
  1101. /** @brief Print fmt into buf.
  1102. *
  1103. * The interpretation of \a fmt is the same as the \c format parameter in
  1104. * _mali_osu_vsnprintf().
  1105. *
  1106. * @param buf a pointer to the result buffer
  1107. * @param size the total number of bytes allowed to write to \a buf
  1108. * @param fmt a _mali_osu_vsnprintf() style format string
  1109. * @param ... a variable-number of parameters suitable for \a fmt
  1110. * @return The number of bytes written to \a buf
  1111. */
  1112. u32 _mali_osk_snprintf( char *buf, u32 size, const char *fmt, ... );
  1113. /** @brief Abnormal process abort.
  1114. *
  1115. * Terminates the caller-process if this function is called.
  1116. *
  1117. * This function will be called from Debug assert-macros in mali_kernel_common.h.
  1118. *
  1119. * This function will never return - because to continue from a Debug assert
  1120. * could cause even more problems, and hinder debugging of the initial problem.
  1121. *
  1122. * This function is only used in Debug builds, and is not used in Release builds.
  1123. */
  1124. void _mali_osk_abort(void);
  1125. /** @brief Sets breakpoint at point where function is called.
  1126. *
  1127. * This function will be called from Debug assert-macros in mali_kernel_common.h,
  1128. * to assist in debugging. If debugging at this level is not required, then this
  1129. * function may be implemented as a stub.
  1130. *
  1131. * This function is only used in Debug builds, and is not used in Release builds.
  1132. */
  1133. void _mali_osk_break(void);
  1134. /** @brief Return an identificator for calling process.
  1135. *
  1136. * @return Identificator for calling process.
  1137. */
  1138. u32 _mali_osk_get_pid(void);
  1139. /** @brief Return an identificator for calling thread.
  1140. *
  1141. * @return Identificator for calling thread.
  1142. */
  1143. u32 _mali_osk_get_tid(void);
  1144. /** @brief Enable OS controlled runtime power management
  1145. */
  1146. void _mali_osk_pm_dev_enable(void);
  1147. /** @brief Disable OS controlled runtime power management
  1148. */
  1149. void _mali_osk_pm_dev_disable(void);
  1150. /** @brief Take a reference to the power manager system for the Mali device.
  1151. *
  1152. * When function returns successfully, Mali is ON.
  1153. *
  1154. * @note Call \a _mali_osk_pm_dev_ref_dec() to release this reference.
  1155. */
  1156. _mali_osk_errcode_t _mali_osk_pm_dev_ref_add(void);
  1157. /** @brief Release the reference to the power manger system for the Mali device.
  1158. *
  1159. * When reference count reach zero, the cores can be off.
  1160. *
  1161. * @note This must be used to release references taken with \a _mali_osk_pm_dev_ref_add().
  1162. */
  1163. void _mali_osk_pm_dev_ref_dec(void);
  1164. /** @brief Take a reference to the power manager system for the Mali device.
  1165. *
  1166. * Will leave the cores powered off if they are already powered off.
  1167. *
  1168. * @note Call \a _mali_osk_pm_dev_ref_dec() to release this reference.
  1169. *
  1170. * @return MALI_TRUE if the Mali GPU is powered on, otherwise MALI_FALSE.
  1171. */
  1172. mali_bool _mali_osk_pm_dev_ref_add_no_power_on(void);
  1173. /** @brief Releasing the reference to the power manger system for the Mali device.
  1174. *
  1175. * When reference count reach zero, the cores can be off.
  1176. *
  1177. * @note This must be used to release references taken with \a _mali_osk_pm_dev_ref_add_no_power_on().
  1178. */
  1179. void _mali_osk_pm_dev_ref_dec_no_power_on(void);
  1180. /** @brief Block untill pending PM operations are done
  1181. */
  1182. void _mali_osk_pm_dev_barrier(void);
  1183. /** @} */ /* end group _mali_osk_miscellaneous */
  1184. /** @} */ /* end group osuapi */
  1185. /** @} */ /* end group uddapi */
  1186. #ifdef __cplusplus
  1187. }
  1188. #endif
  1189. /* Check standard inlines */
  1190. #ifndef MALI_STATIC_INLINE
  1191. #error MALI_STATIC_INLINE not defined on your OS
  1192. #endif
  1193. #ifndef MALI_NON_STATIC_INLINE
  1194. #error MALI_NON_STATIC_INLINE not defined on your OS
  1195. #endif
  1196. #endif /* __MALI_OSK_H__ */