Branch data     Line data    Source code

       1                 :            : // SPDX-License-Identifier: GPL-2.0
       2                 :            : /*
       3                 :            :  * Media device request objects
       4                 :            :  *
       5                 :            :  * Copyright 2018 Cisco Systems, Inc. and/or its affiliates. All rights reserved.
       6                 :            :  * Copyright (C) 2018 Intel Corporation
       7                 :            :  *
       8                 :            :  * Author: Hans Verkuil <hans.verkuil@cisco.com>
       9                 :            :  * Author: Sakari Ailus <sakari.ailus@linux.intel.com>
      10                 :            :  */
      11                 :            : 
      12                 :            : #ifndef MEDIA_REQUEST_H
      13                 :            : #define MEDIA_REQUEST_H
      14                 :            : 
      15                 :            : #include <linux/list.h>
      16                 :            : #include <linux/slab.h>
      17                 :            : #include <linux/spinlock.h>
      18                 :            : #include <linux/refcount.h>
      19                 :            : 
      20                 :            : #include <media/media-device.h>
      21                 :            : 
      22                 :            : /**
      23                 :            :  * enum media_request_state - media request state
      24                 :            :  *
      25                 :            :  * @MEDIA_REQUEST_STATE_IDLE:           Idle
      26                 :            :  * @MEDIA_REQUEST_STATE_VALIDATING:     Validating the request, no state changes
      27                 :            :  *                                      allowed
      28                 :            :  * @MEDIA_REQUEST_STATE_QUEUED:         Queued
      29                 :            :  * @MEDIA_REQUEST_STATE_COMPLETE:       Completed, the request is done
      30                 :            :  * @MEDIA_REQUEST_STATE_CLEANING:       Cleaning, the request is being re-inited
      31                 :            :  * @MEDIA_REQUEST_STATE_UPDATING:       The request is being updated, i.e.
      32                 :            :  *                                      request objects are being added,
      33                 :            :  *                                      modified or removed
      34                 :            :  * @NR_OF_MEDIA_REQUEST_STATE:          The number of media request states, used
      35                 :            :  *                                      internally for sanity check purposes
      36                 :            :  */
      37                 :            : enum media_request_state {
      38                 :            :         MEDIA_REQUEST_STATE_IDLE,
      39                 :            :         MEDIA_REQUEST_STATE_VALIDATING,
      40                 :            :         MEDIA_REQUEST_STATE_QUEUED,
      41                 :            :         MEDIA_REQUEST_STATE_COMPLETE,
      42                 :            :         MEDIA_REQUEST_STATE_CLEANING,
      43                 :            :         MEDIA_REQUEST_STATE_UPDATING,
      44                 :            :         NR_OF_MEDIA_REQUEST_STATE,
      45                 :            : };
      46                 :            : 
      47                 :            : struct media_request_object;
      48                 :            : 
      49                 :            : /**
      50                 :            :  * struct media_request - Media device request
      51                 :            :  * @mdev: Media device this request belongs to
      52                 :            :  * @kref: Reference count
      53                 :            :  * @debug_str: Prefix for debug messages (process name:fd)
      54                 :            :  * @state: The state of the request
      55                 :            :  * @updating_count: count the number of request updates that are in progress
      56                 :            :  * @access_count: count the number of request accesses that are in progress
      57                 :            :  * @objects: List of @struct media_request_object request objects
      58                 :            :  * @num_incomplete_objects: The number of incomplete objects in the request
      59                 :            :  * @poll_wait: Wait queue for poll
      60                 :            :  * @lock: Serializes access to this struct
      61                 :            :  */
      62                 :            : struct media_request {
      63                 :            :         struct media_device *mdev;
      64                 :            :         struct kref kref;
      65                 :            :         char debug_str[TASK_COMM_LEN + 11];
      66                 :            :         enum media_request_state state;
      67                 :            :         unsigned int updating_count;
      68                 :            :         unsigned int access_count;
      69                 :            :         struct list_head objects;
      70                 :            :         unsigned int num_incomplete_objects;
      71                 :            :         wait_queue_head_t poll_wait;
      72                 :            :         spinlock_t lock;
      73                 :            : };
      74                 :            : 
      75                 :            : #ifdef CONFIG_MEDIA_CONTROLLER
      76                 :            : 
      77                 :            : /**
      78                 :            :  * media_request_lock_for_access - Lock the request to access its objects
      79                 :            :  *
      80                 :            :  * @req: The media request
      81                 :            :  *
      82                 :            :  * Use before accessing a completed request. A reference to the request must
      83                 :            :  * be held during the access. This usually takes place automatically through
      84                 :            :  * a file handle. Use @media_request_unlock_for_access when done.
      85                 :            :  */
      86                 :            : static inline int __must_check
      87                 :          0 : media_request_lock_for_access(struct media_request *req)
      88                 :            : {
      89                 :            :         unsigned long flags;
      90                 :            :         int ret = -EBUSY;
      91                 :            : 
      92                 :          0 :         spin_lock_irqsave(&req->lock, flags);
      93                 :          0 :         if (req->state == MEDIA_REQUEST_STATE_COMPLETE) {
      94                 :          0 :                 req->access_count++;
      95                 :            :                 ret = 0;
      96                 :            :         }
      97                 :            :         spin_unlock_irqrestore(&req->lock, flags);
      98                 :            : 
      99                 :          0 :         return ret;
     100                 :            : }
     101                 :            : 
     102                 :            : /**
     103                 :            :  * media_request_unlock_for_access - Unlock a request previously locked for
     104                 :            :  *                                   access
     105                 :            :  *
     106                 :            :  * @req: The media request
     107                 :            :  *
     108                 :            :  * Unlock a request that has previously been locked using
     109                 :            :  * @media_request_lock_for_access.
     110                 :            :  */
     111                 :          0 : static inline void media_request_unlock_for_access(struct media_request *req)
     112                 :            : {
     113                 :            :         unsigned long flags;
     114                 :            : 
     115                 :          0 :         spin_lock_irqsave(&req->lock, flags);
     116                 :          0 :         if (!WARN_ON(!req->access_count))
     117                 :          0 :                 req->access_count--;
     118                 :            :         spin_unlock_irqrestore(&req->lock, flags);
     119                 :          0 : }
     120                 :            : 
     121                 :            : /**
     122                 :            :  * media_request_lock_for_update - Lock the request for updating its objects
     123                 :            :  *
     124                 :            :  * @req: The media request
     125                 :            :  *
     126                 :            :  * Use before updating a request, i.e. adding, modifying or removing a request
     127                 :            :  * object in it. A reference to the request must be held during the update. This
     128                 :            :  * usually takes place automatically through a file handle. Use
     129                 :            :  * @media_request_unlock_for_update when done.
     130                 :            :  */
     131                 :            : static inline int __must_check
     132                 :          0 : media_request_lock_for_update(struct media_request *req)
     133                 :            : {
     134                 :            :         unsigned long flags;
     135                 :            :         int ret = 0;
     136                 :            : 
     137                 :          0 :         spin_lock_irqsave(&req->lock, flags);
     138                 :          0 :         if (req->state == MEDIA_REQUEST_STATE_IDLE ||
     139                 :            :             req->state == MEDIA_REQUEST_STATE_UPDATING) {
     140                 :          0 :                 req->state = MEDIA_REQUEST_STATE_UPDATING;
     141                 :          0 :                 req->updating_count++;
     142                 :            :         } else {
     143                 :            :                 ret = -EBUSY;
     144                 :            :         }
     145                 :            :         spin_unlock_irqrestore(&req->lock, flags);
     146                 :            : 
     147                 :          0 :         return ret;
     148                 :            : }
     149                 :            : 
     150                 :            : /**
     151                 :            :  * media_request_unlock_for_update - Unlock a request previously locked for
     152                 :            :  *                                   update
     153                 :            :  *
     154                 :            :  * @req: The media request
     155                 :            :  *
     156                 :            :  * Unlock a request that has previously been locked using
     157                 :            :  * @media_request_lock_for_update.
     158                 :            :  */
     159                 :          0 : static inline void media_request_unlock_for_update(struct media_request *req)
     160                 :            : {
     161                 :            :         unsigned long flags;
     162                 :            : 
     163                 :          0 :         spin_lock_irqsave(&req->lock, flags);
     164                 :          0 :         WARN_ON(req->updating_count <= 0);
     165                 :          0 :         if (!--req->updating_count)
     166                 :          0 :                 req->state = MEDIA_REQUEST_STATE_IDLE;
     167                 :            :         spin_unlock_irqrestore(&req->lock, flags);
     168                 :          0 : }
     169                 :            : 
     170                 :            : /**
     171                 :            :  * media_request_get - Get the media request
     172                 :            :  *
     173                 :            :  * @req: The media request
     174                 :            :  *
     175                 :            :  * Get the media request.
     176                 :            :  */
     177                 :            : static inline void media_request_get(struct media_request *req)
     178                 :            : {
     179                 :            :         kref_get(&req->kref);
     180                 :            : }
     181                 :            : 
     182                 :            : /**
     183                 :            :  * media_request_put - Put the media request
     184                 :            :  *
     185                 :            :  * @req: The media request
     186                 :            :  *
     187                 :            :  * Put the media request. The media request will be released
     188                 :            :  * when the refcount reaches 0.
     189                 :            :  */
     190                 :            : void media_request_put(struct media_request *req);
     191                 :            : 
     192                 :            : /**
     193                 :            :  * media_request_get_by_fd - Get a media request by fd
     194                 :            :  *
     195                 :            :  * @mdev: Media device this request belongs to
     196                 :            :  * @request_fd: The file descriptor of the request
     197                 :            :  *
     198                 :            :  * Get the request represented by @request_fd that is owned
     199                 :            :  * by the media device.
     200                 :            :  *
     201                 :            :  * Return a -EBADR error pointer if requests are not supported
     202                 :            :  * by this driver. Return -EINVAL if the request was not found.
     203                 :            :  * Return the pointer to the request if found: the caller will
     204                 :            :  * have to call @media_request_put when it finished using the
     205                 :            :  * request.
     206                 :            :  */
     207                 :            : struct media_request *
     208                 :            : media_request_get_by_fd(struct media_device *mdev, int request_fd);
     209                 :            : 
     210                 :            : /**
     211                 :            :  * media_request_alloc - Allocate the media request
     212                 :            :  *
     213                 :            :  * @mdev: Media device this request belongs to
     214                 :            :  * @alloc_fd: Store the request's file descriptor in this int
     215                 :            :  *
     216                 :            :  * Allocated the media request and put the fd in @alloc_fd.
     217                 :            :  */
     218                 :            : int media_request_alloc(struct media_device *mdev,
     219                 :            :                         int *alloc_fd);
     220                 :            : 
     221                 :            : #else
     222                 :            : 
     223                 :            : static inline void media_request_get(struct media_request *req)
     224                 :            : {
     225                 :            : }
     226                 :            : 
     227                 :            : static inline void media_request_put(struct media_request *req)
     228                 :            : {
     229                 :            : }
     230                 :            : 
     231                 :            : static inline struct media_request *
     232                 :            : media_request_get_by_fd(struct media_device *mdev, int request_fd)
     233                 :            : {
     234                 :            :         return ERR_PTR(-EBADR);
     235                 :            : }
     236                 :            : 
     237                 :            : #endif
     238                 :            : 
     239                 :            : /**
     240                 :            :  * struct media_request_object_ops - Media request object operations
     241                 :            :  * @prepare: Validate and prepare the request object, optional.
     242                 :            :  * @unprepare: Unprepare the request object, optional.
     243                 :            :  * @queue: Queue the request object, optional.
     244                 :            :  * @unbind: Unbind the request object, optional.
     245                 :            :  * @release: Release the request object, required.
     246                 :            :  */
     247                 :            : struct media_request_object_ops {
     248                 :            :         int (*prepare)(struct media_request_object *object);
     249                 :            :         void (*unprepare)(struct media_request_object *object);
     250                 :            :         void (*queue)(struct media_request_object *object);
     251                 :            :         void (*unbind)(struct media_request_object *object);
     252                 :            :         void (*release)(struct media_request_object *object);
     253                 :            : };
     254                 :            : 
     255                 :            : /**
     256                 :            :  * struct media_request_object - An opaque object that belongs to a media
     257                 :            :  *                               request
     258                 :            :  *
     259                 :            :  * @ops: object's operations
     260                 :            :  * @priv: object's priv pointer
     261                 :            :  * @req: the request this object belongs to (can be NULL)
     262                 :            :  * @list: List entry of the object for @struct media_request
     263                 :            :  * @kref: Reference count of the object, acquire before releasing req->lock
     264                 :            :  * @completed: If true, then this object was completed.
     265                 :            :  *
     266                 :            :  * An object related to the request. This struct is always embedded in
     267                 :            :  * another struct that contains the actual data for this request object.
     268                 :            :  */
     269                 :            : struct media_request_object {
     270                 :            :         const struct media_request_object_ops *ops;
     271                 :            :         void *priv;
     272                 :            :         struct media_request *req;
     273                 :            :         struct list_head list;
     274                 :            :         struct kref kref;
     275                 :            :         bool completed;
     276                 :            : };
     277                 :            : 
     278                 :            : #ifdef CONFIG_MEDIA_CONTROLLER
     279                 :            : 
     280                 :            : /**
     281                 :            :  * media_request_object_get - Get a media request object
     282                 :            :  *
     283                 :            :  * @obj: The object
     284                 :            :  *
     285                 :            :  * Get a media request object.
     286                 :            :  */
     287                 :            : static inline void media_request_object_get(struct media_request_object *obj)
     288                 :            : {
     289                 :            :         kref_get(&obj->kref);
     290                 :            : }
     291                 :            : 
     292                 :            : /**
     293                 :            :  * media_request_object_put - Put a media request object
     294                 :            :  *
     295                 :            :  * @obj: The object
     296                 :            :  *
     297                 :            :  * Put a media request object. Once all references are gone, the
     298                 :            :  * object's memory is released.
     299                 :            :  */
     300                 :            : void media_request_object_put(struct media_request_object *obj);
     301                 :            : 
     302                 :            : /**
     303                 :            :  * media_request_object_find - Find an object in a request
     304                 :            :  *
     305                 :            :  * @req: The media request
     306                 :            :  * @ops: Find an object with this ops value
     307                 :            :  * @priv: Find an object with this priv value
     308                 :            :  *
     309                 :            :  * Both @ops and @priv must be non-NULL.
     310                 :            :  *
     311                 :            :  * Returns the object pointer or NULL if not found. The caller must
     312                 :            :  * call media_request_object_put() once it finished using the object.
     313                 :            :  *
     314                 :            :  * Since this function needs to walk the list of objects it takes
     315                 :            :  * the @req->lock spin lock to make this safe.
     316                 :            :  */
     317                 :            : struct media_request_object *
     318                 :            : media_request_object_find(struct media_request *req,
     319                 :            :                           const struct media_request_object_ops *ops,
     320                 :            :                           void *priv);
     321                 :            : 
     322                 :            : /**
     323                 :            :  * media_request_object_init - Initialise a media request object
     324                 :            :  *
     325                 :            :  * @obj: The object
     326                 :            :  *
     327                 :            :  * Initialise a media request object. The object will be released using the
     328                 :            :  * release callback of the ops once it has no references (this function
     329                 :            :  * initialises references to one).
     330                 :            :  */
     331                 :            : void media_request_object_init(struct media_request_object *obj);
     332                 :            : 
     333                 :            : /**
     334                 :            :  * media_request_object_bind - Bind a media request object to a request
     335                 :            :  *
     336                 :            :  * @req: The media request
     337                 :            :  * @ops: The object ops for this object
     338                 :            :  * @priv: A driver-specific priv pointer associated with this object
     339                 :            :  * @is_buffer: Set to true if the object a buffer object.
     340                 :            :  * @obj: The object
     341                 :            :  *
     342                 :            :  * Bind this object to the request and set the ops and priv values of
     343                 :            :  * the object so it can be found later with media_request_object_find().
     344                 :            :  *
     345                 :            :  * Every bound object must be unbound or completed by the kernel at some
     346                 :            :  * point in time, otherwise the request will never complete. When the
     347                 :            :  * request is released all completed objects will be unbound by the
     348                 :            :  * request core code.
     349                 :            :  *
     350                 :            :  * Buffer objects will be added to the end of the request's object
     351                 :            :  * list, non-buffer objects will be added to the front of the list.
     352                 :            :  * This ensures that all buffer objects are at the end of the list
     353                 :            :  * and that all non-buffer objects that they depend on are processed
     354                 :            :  * first.
     355                 :            :  */
     356                 :            : int media_request_object_bind(struct media_request *req,
     357                 :            :                               const struct media_request_object_ops *ops,
     358                 :            :                               void *priv, bool is_buffer,
     359                 :            :                               struct media_request_object *obj);
     360                 :            : 
     361                 :            : /**
     362                 :            :  * media_request_object_unbind - Unbind a media request object
     363                 :            :  *
     364                 :            :  * @obj: The object
     365                 :            :  *
     366                 :            :  * Unbind the media request object from the request.
     367                 :            :  */
     368                 :            : void media_request_object_unbind(struct media_request_object *obj);
     369                 :            : 
     370                 :            : /**
     371                 :            :  * media_request_object_complete - Mark the media request object as complete
     372                 :            :  *
     373                 :            :  * @obj: The object
     374                 :            :  *
     375                 :            :  * Mark the media request object as complete. Only bound objects can
     376                 :            :  * be completed.
     377                 :            :  */
     378                 :            : void media_request_object_complete(struct media_request_object *obj);
     379                 :            : 
     380                 :            : #else
     381                 :            : 
     382                 :            : static inline int __must_check
     383                 :            : media_request_lock_for_access(struct media_request *req)
     384                 :            : {
     385                 :            :         return -EINVAL;
     386                 :            : }
     387                 :            : 
     388                 :            : static inline void media_request_unlock_for_access(struct media_request *req)
     389                 :            : {
     390                 :            : }
     391                 :            : 
     392                 :            : static inline int __must_check
     393                 :            : media_request_lock_for_update(struct media_request *req)
     394                 :            : {
     395                 :            :         return -EINVAL;
     396                 :            : }
     397                 :            : 
     398                 :            : static inline void media_request_unlock_for_update(struct media_request *req)
     399                 :            : {
     400                 :            : }
     401                 :            : 
     402                 :            : static inline void media_request_object_get(struct media_request_object *obj)
     403                 :            : {
     404                 :            : }
     405                 :            : 
     406                 :            : static inline void media_request_object_put(struct media_request_object *obj)
     407                 :            : {
     408                 :            : }
     409                 :            : 
     410                 :            : static inline struct media_request_object *
     411                 :            : media_request_object_find(struct media_request *req,
     412                 :            :                           const struct media_request_object_ops *ops,
     413                 :            :                           void *priv)
     414                 :            : {
     415                 :            :         return NULL;
     416                 :            : }
     417                 :            : 
     418                 :            : static inline void media_request_object_init(struct media_request_object *obj)
     419                 :            : {
     420                 :            :         obj->ops = NULL;
     421                 :            :         obj->req = NULL;
     422                 :            : }
     423                 :            : 
     424                 :            : static inline int media_request_object_bind(struct media_request *req,
     425                 :            :                                const struct media_request_object_ops *ops,
     426                 :            :                                void *priv, bool is_buffer,
     427                 :            :                                struct media_request_object *obj)
     428                 :            : {
     429                 :            :         return 0;
     430                 :            : }
     431                 :            : 
     432                 :            : static inline void media_request_object_unbind(struct media_request_object *obj)
     433                 :            : {
     434                 :            : }
     435                 :            : 
     436                 :            : static inline void media_request_object_complete(struct media_request_object *obj)
     437                 :            : {
     438                 :            : }
     439                 :            : 
     440                 :            : #endif
     441                 :            : 
     442                 :            : #endif