2 * This confidential and proprietary software may be used only as
3 * authorised by a licensing agreement from ARM Limited
4 * (C) COPYRIGHT 2013 ARM Limited
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.
11 #ifndef __MALI_SOFT_JOB_H__
12 #define __MALI_SOFT_JOB_H__
16 #include "mali_timeline.h"
18 struct mali_timeline_fence
;
19 struct mali_session_data
;
21 struct mali_soft_job_system
;
26 * Soft jobs of type MALI_SOFT_JOB_TYPE_USER_SIGNALED will only complete after activation if either
27 * they are signaled by user-space (@ref mali_soft_job_system_signaled_job) or if they are timed out
28 * by the Timeline system.
30 typedef enum mali_soft_job_type
{
31 MALI_SOFT_JOB_TYPE_USER_SIGNALED
,
37 * All soft jobs in a soft job system will initially be in state MALI_SOFT_JOB_STATE_FREE. On @ref
38 * mali_soft_job_system_start_job a job will first be allocated. A job in state
39 * MALI_SOFT_JOB_STATE_FREE will be picked and the state changed to MALI_SOFT_JOB_STATE_ALLOCATED.
40 * Once the job is added to the timeline system, the state changes to MALI_SOFT_JOB_STATE_STARTED.
42 * For soft jobs of type MALI_SOFT_JOB_TYPE_USER_SIGNALED the state is changed to
43 * MALI_SOFT_JOB_STATE_SIGNALED when @ref mali_soft_job_system_signal_job is called and the soft
44 * job's state is MALI_SOFT_JOB_STATE_STARTED or MALI_SOFT_JOB_STATE_TIMED_OUT.
46 * If a soft job of type MALI_SOFT_JOB_TYPE_USER_SIGNALED is timed out before being signaled, the
47 * state is changed to MALI_SOFT_JOB_STATE_TIMED_OUT. This can only happen to soft jobs in state
48 * MALI_SOFT_JOB_STATE_STARTED.
50 * When a soft job's reference count reaches zero, it will be freed and the state returns to
51 * MALI_SOFT_JOB_STATE_FREE.
53 typedef enum mali_soft_job_state
{
54 MALI_SOFT_JOB_STATE_FREE
,
55 MALI_SOFT_JOB_STATE_ALLOCATED
,
56 MALI_SOFT_JOB_STATE_STARTED
,
57 MALI_SOFT_JOB_STATE_SIGNALED
,
58 MALI_SOFT_JOB_STATE_TIMED_OUT
,
59 } mali_soft_job_state
;
61 #define MALI_SOFT_JOB_INVALID_ID ((u32) -1)
63 /* Maximum number of soft jobs per soft system. */
64 #define MALI_MAX_NUM_SOFT_JOBS 20
69 * Soft job can be used to represent any kind of CPU work done in kernel-space.
71 typedef struct mali_soft_job
{
72 mali_soft_job_type type
; /**< Soft job type. Must be one of MALI_SOFT_JOB_TYPE_*. */
73 u32 user_job
; /**< Identifier for soft job in user space. */
74 _mali_osk_atomic_t refcount
; /**< Soft jobs are reference counted to prevent premature deletion. */
75 struct mali_timeline_tracker tracker
; /**< Timeline tracker for soft job. */
76 mali_bool activated
; /**< MALI_TRUE if the job has been activated, MALI_FALSE if not. */
77 _mali_osk_notification_t
*activated_notification
; /**< Pre-allocated notification object for ACTIVATED_NOTIFICATION. */
79 /* Protected by soft job system lock. */
80 u32 id
; /**< Used by user-space to find corresponding soft job in kernel-space. */
81 mali_soft_job_state state
; /**< State of soft job, must be one of MALI_SOFT_JOB_STATE_*. */
82 struct mali_soft_job_system
*system
; /**< The soft job system this job is in. */
83 _mali_osk_list_t system_list
; /**< List element used by soft job system. */
87 * Per-session soft job system.
89 * The soft job system is used to manage all soft jobs that belongs to a session.
91 typedef struct mali_soft_job_system
{
92 struct mali_session_data
*session
; /**< The session this soft job system belongs to. */
94 struct mali_soft_job jobs
[MALI_MAX_NUM_SOFT_JOBS
]; /**< Array of all soft jobs in this system. */
95 _MALI_OSK_LIST_HEAD(jobs_free
); /**< List of all free soft jobs. */
96 _MALI_OSK_LIST_HEAD(jobs_used
); /**< List of all allocated soft jobs. */
98 _mali_osk_spinlock_irq_t
*lock
; /**< Lock used to protect soft job system and its soft jobs. */
99 u32 lock_owner
; /**< Contains tid of thread that locked the system or 0, if not locked. */
100 } mali_soft_job_system
;
103 * Create a soft job system.
105 * @param session The session this soft job system will belong to.
106 * @return The new soft job system, or NULL if unsuccessful.
108 struct mali_soft_job_system
*mali_soft_job_system_create(struct mali_session_data
*session
);
111 * Destroy a soft job system.
113 * @note The soft job must not have any started or activated jobs. Call @ref
114 * mali_soft_job_system_abort first.
116 * @param system The soft job system we are destroying.
118 void mali_soft_job_system_destroy(struct mali_soft_job_system
*system
);
123 * @param system Soft job system to create soft job from.
124 * @param type Type of the soft job.
125 * @param user_job Identifier for soft job in user space.
126 * @return New soft job if successful, NULL if not.
128 struct mali_soft_job
*mali_soft_job_create(struct mali_soft_job_system
*system
, mali_soft_job_type type
, u32 user_job
);
133 * @param job Soft job to destroy.
135 void mali_soft_job_destroy(struct mali_soft_job
*job
);
140 * The soft job will be added to the Timeline system which will then activate it after all
141 * dependencies have been resolved.
143 * Create soft jobs with @ref mali_soft_job_create before starting them.
145 * @param job Soft job to start.
146 * @param fence Fence representing dependencies for this soft job.
147 * @return Point on soft job timeline.
149 mali_timeline_point
mali_soft_job_start(struct mali_soft_job
*job
, struct mali_timeline_fence
*fence
);
152 * Use by user-space to signal that a soft job has completed.
154 * @note Only valid for soft jobs with type MALI_SOFT_JOB_TYPE_USER_SIGNALED.
156 * @note The soft job must be in state MALI_SOFT_JOB_STATE_STARTED for the signal to be successful.
158 * @note If the soft job was signaled successfully, or it received a time out, the soft job will be
159 * destroyed after this call and should no longer be used.
161 * @note This function will block until the soft job has been activated.
163 * @param system The soft job system the job was started in.
164 * @param job_id ID of soft job we are signaling.
166 * @return _MALI_OSK_ERR_ITEM_NOT_FOUND if the soft job ID was invalid, _MALI_OSK_ERR_TIMEOUT if the
167 * soft job was timed out or _MALI_OSK_ERR_OK if we successfully signaled the soft job.
169 _mali_osk_errcode_t
mali_soft_job_system_signal_job(struct mali_soft_job_system
*system
, u32 job_id
);
172 * Used by the Timeline system to activate a soft job.
174 * @param job The soft job that is being activated.
176 void mali_soft_job_system_activate_job(struct mali_soft_job
*job
);
179 * Used by the Timeline system to timeout a soft job.
181 * A soft job is timed out if it completes or is signaled later than MALI_TIMELINE_TIMEOUT_HZ after
184 * @param job The soft job that is being timed out.
185 * @return A scheduling bitmask.
187 mali_scheduler_mask
mali_soft_job_system_timeout_job(struct mali_soft_job
*job
);
190 * Used to cleanup activated soft jobs in the soft job system on session abort.
192 * @param system The soft job system that is being aborted.
194 void mali_soft_job_system_abort(struct mali_soft_job_system
*system
);
196 #endif /* __MALI_SOFT_JOB_H__ */