drivers/gpu/arm/mali400/r4p0_rel0/common/mali_soft_job.h

   1 /*
   2  * Copyright (C) 2010-2012 ARM Limited. All rights reserved.
   3  *
   4  * This program is free software and is provided to you under the terms of the GNU General Public License version 2
   5  * as published by the Free Software Foundation, and any use by you of this program is subject to the terms of such GNU licence.
   6  *
   7  * A copy of the licence is included with the program, and can also be obtained from Free Software
   8  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
   9  */
  10
  11 #ifndef __MALI_SOFT_JOB_H__
  12 #define __MALI_SOFT_JOB_H__
  13
  14 #include "mali_osk.h"
  15
  16 #include "mali_timeline.h"
  17
  18 struct mali_timeline_fence;
  19 struct mali_session_data;
  20 struct mali_soft_job;
  21 struct mali_soft_job_system;
  22
  23 /**
  24  * Soft job types.
  25  *
  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.
  29  */
  30 typedef enum mali_soft_job_type {
  31         MALI_SOFT_JOB_TYPE_USER_SIGNALED,
  32 } mali_soft_job_type;
  33
  34 /**
  35  * Soft job state.
  36  *
  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.
  41  *
  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.
  45  *
  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.
  49  *
  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.
  52  */
  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;
  60
  61 #define MALI_SOFT_JOB_INVALID_ID ((u32) -1)
  62
  63 /* Maximum number of soft jobs per soft system. */
  64 #define MALI_MAX_NUM_SOFT_JOBS 20
  65
  66 /**
  67  * Soft job struct.
  68  *
  69  * Soft job can be used to represent any kind of CPU work done in kernel-space.
  70  */
  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. */
  78
  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. */
  84 } mali_soft_job;
  85
  86 /**
  87  * Per-session soft job system.
  88  *
  89  * The soft job system is used to manage all soft jobs that belongs to a session.
  90  */
  91 typedef struct mali_soft_job_system {
  92         struct mali_session_data *session;                    /**< The session this soft job system belongs to. */
  93
  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. */
  97
  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;
 101
 102 /**
 103  * Create a soft job system.
 104  *
 105  * @param session The session this soft job system will belong to.
 106  * @return The new soft job system, or NULL if unsuccessful.
 107  */
 108 struct mali_soft_job_system *mali_soft_job_system_create(struct mali_session_data *session);
 109
 110 /**
 111  * Destroy a soft job system.
 112  *
 113  * @note The soft job must not have any started or activated jobs.  Call @ref
 114  * mali_soft_job_system_abort first.
 115  *
 116  * @param system The soft job system we are destroying.
 117  */
 118 void mali_soft_job_system_destroy(struct mali_soft_job_system *system);
 119
 120 /**
 121  * Create a soft job.
 122  *
 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.
 127  */
 128 struct mali_soft_job *mali_soft_job_create(struct mali_soft_job_system *system, mali_soft_job_type type, u32 user_job);
 129
 130 /**
 131  * Destroy soft job.
 132  *
 133  * @param job Soft job to destroy.
 134  */
 135 void mali_soft_job_destroy(struct mali_soft_job *job);
 136
 137 /**
 138  * Start a soft job.
 139  *
 140  * The soft job will be added to the Timeline system which will then activate it after all
 141  * dependencies have been resolved.
 142  *
 143  * Create soft jobs with @ref mali_soft_job_create before starting them.
 144  *
 145  * @param job Soft job to start.
 146  * @param fence Fence representing dependencies for this soft job.
 147  * @return Point on soft job timeline.
 148  */
 149 mali_timeline_point mali_soft_job_start(struct mali_soft_job *job, struct mali_timeline_fence *fence);
 150
 151 /**
 152  * Use by user-space to signal that a soft job has completed.
 153  *
 154  * @note Only valid for soft jobs with type MALI_SOFT_JOB_TYPE_USER_SIGNALED.
 155  *
 156  * @note The soft job must be in state MALI_SOFT_JOB_STATE_STARTED for the signal to be successful.
 157  *
 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.
 160  *
 161  * @note This function will block until the soft job has been activated.
 162  *
 163  * @param system The soft job system the job was started in.
 164  * @param job_id ID of soft job we are signaling.
 165  *
 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.
 168  */
 169 _mali_osk_errcode_t mali_soft_job_system_signal_job(struct mali_soft_job_system *system, u32 job_id);
 170
 171 /**
 172  * Used by the Timeline system to activate a soft job.
 173  *
 174  * @param job The soft job that is being activated.
 175  */
 176 void mali_soft_job_system_activate_job(struct mali_soft_job *job);
 177
 178 /**
 179  * Used by the Timeline system to timeout a soft job.
 180  *
 181  * A soft job is timed out if it completes or is signaled later than MALI_TIMELINE_TIMEOUT_HZ after
 182  * activation.
 183  *
 184  * @param job The soft job that is being timed out.
 185  * @return A scheduling bitmask.
 186  */
 187 mali_scheduler_mask mali_soft_job_system_timeout_job(struct mali_soft_job *job);
 188
 189 /**
 190  * Used to cleanup activated soft jobs in the soft job system on session abort.
 191  *
 192  * @param system The soft job system that is being aborted.
 193  */
 194 void mali_soft_job_system_abort(struct mali_soft_job_system *system);
 195
 196 #endif /* __MALI_SOFT_JOB_H__ */