// SPDX-License-Identifier: GPL-2.0
/*
 * Media device request objects
 *
 * Copyright 2018 Cisco Systems, Inc. and/or its affiliates. All rights reserved.
 * Copyright (C) 2018 Intel Corporation
 *
 * Author: Hans Verkuil <hverkuil@kernel.org>
 * Author: Sakari Ailus <sakari.ailus@linux.intel.com>
 */

#ifndef MEDIA_REQUEST_H
#define MEDIA_REQUEST_H

#include <linux/list.h>
#include <linux/slab.h>
#include <linux/spinlock.h>
#include <linux/refcount.h>

#include <media/media-device.h>

/**
 * enum media_request_state - media request state
 *
 * @MEDIA_REQUEST_STATE_IDLE:           Idle
 * @MEDIA_REQUEST_STATE_VALIDATING:     Validating the request, no state changes
 *                                      allowed
 * @MEDIA_REQUEST_STATE_QUEUED:         Queued
 * @MEDIA_REQUEST_STATE_COMPLETE:       Completed, the request is done
 * @MEDIA_REQUEST_STATE_CLEANING:       Cleaning, the request is being re-inited
 * @MEDIA_REQUEST_STATE_UPDATING:       The request is being updated, i.e.
 *                                      request objects are being added,
 *                                      modified or removed
 * @NR_OF_MEDIA_REQUEST_STATE:          The number of media request states, used
 *                                      internally for sanity check purposes
 */
enum media_request_state {
        MEDIA_REQUEST_STATE_IDLE,
        MEDIA_REQUEST_STATE_VALIDATING,
        MEDIA_REQUEST_STATE_QUEUED,
        MEDIA_REQUEST_STATE_COMPLETE,
        MEDIA_REQUEST_STATE_CLEANING,
        MEDIA_REQUEST_STATE_UPDATING,
        NR_OF_MEDIA_REQUEST_STATE,
};

struct media_request_object;

/**
 * struct media_request - Media device request
 * @mdev: Media device this request belongs to
 * @kref: Reference count
 * @debug_str: Prefix for debug messages (process name:fd)
 * @state: The state of the request
 * @updating_count: count the number of request updates that are in progress
 * @access_count: count the number of request accesses that are in progress
 * @objects: List of @struct media_request_object request objects
 * @num_incomplete_objects: The number of incomplete objects in the request
 * @manual_completion: if true, then the request won't be marked as completed
 * when @num_incomplete_objects reaches 0. Call media_request_manual_complete()
 * to complete the request after @num_incomplete_objects == 0.
 * @poll_wait: Wait queue for poll
 * @lock: Serializes access to this struct
 */
struct media_request {
        struct media_device *mdev;
        struct kref kref;
        char debug_str[TASK_COMM_LEN + 11];
        enum media_request_state state;
        unsigned int updating_count;
        unsigned int access_count;
        struct list_head objects;
        unsigned int num_incomplete_objects;
        bool manual_completion;
        wait_queue_head_t poll_wait;
        spinlock_t lock;
};

#ifdef CONFIG_MEDIA_CONTROLLER

/**
 * media_request_lock_for_access - Lock the request to access its objects
 *
 * @req: The media request
 *
 * Use before accessing a completed request. A reference to the request must
 * be held during the access. This usually takes place automatically through
 * a file handle. Use @media_request_unlock_for_access when done.
 */
static inline int __must_check
media_request_lock_for_access(struct media_request *req)
{
        unsigned long flags;
        int ret = -EBUSY;

        spin_lock_irqsave(&req->lock, flags);
        if (req->state == MEDIA_REQUEST_STATE_COMPLETE) {
                req->access_count++;
                ret = 0;
        }
        spin_unlock_irqrestore(&req->lock, flags);

        return ret;
}

/**
 * media_request_unlock_for_access - Unlock a request previously locked for
 *                                   access
 *
 * @req: The media request
 *
 * Unlock a request that has previously been locked using
 * @media_request_lock_for_access.
 */
static inline void media_request_unlock_for_access(struct media_request *req)
{
        unsigned long flags;

        spin_lock_irqsave(&req->lock, flags);
        if (!WARN_ON(!req->access_count))
                req->access_count--;
        spin_unlock_irqrestore(&req->lock, flags);
}

/**
 * media_request_lock_for_update - Lock the request for updating its objects
 *
 * @req: The media request
 *
 * Use before updating a request, i.e. adding, modifying or removing a request
 * object in it. A reference to the request must be held during the update. This
 * usually takes place automatically through a file handle. Use
 * @media_request_unlock_for_update when done.
 */
static inline int __must_check
media_request_lock_for_update(struct media_request *req)
{
        unsigned long flags;
        int ret = 0;

        spin_lock_irqsave(&req->lock, flags);
        if (req->state == MEDIA_REQUEST_STATE_IDLE ||
            req->state == MEDIA_REQUEST_STATE_UPDATING) {
                req->state = MEDIA_REQUEST_STATE_UPDATING;
                req->updating_count++;
        } else {
                ret = -EBUSY;
        }
        spin_unlock_irqrestore(&req->lock, flags);

        return ret;
}

/**
 * media_request_unlock_for_update - Unlock a request previously locked for
 *                                   update
 *
 * @req: The media request
 *
 * Unlock a request that has previously been locked using
 * @media_request_lock_for_update.
 */
static inline void media_request_unlock_for_update(struct media_request *req)
{
        unsigned long flags;

        spin_lock_irqsave(&req->lock, flags);
        WARN_ON(req->updating_count <= 0);
        if (!--req->updating_count)
                req->state = MEDIA_REQUEST_STATE_IDLE;
        spin_unlock_irqrestore(&req->lock, flags);
}

/**
 * media_request_get - Get the media request
 *
 * @req: The media request
 *
 * Get the media request.
 */
static inline void media_request_get(struct media_request *req)
{
        kref_get(&req->kref);
}

/**
 * media_request_put - Put the media request
 *
 * @req: The media request
 *
 * Put the media request. The media request will be released
 * when the refcount reaches 0.
 */
void media_request_put(struct media_request *req);

/**
 * media_request_get_by_fd - Get a media request by fd
 *
 * @mdev: Media device this request belongs to
 * @request_fd: The file descriptor of the request
 *
 * Get the request represented by @request_fd that is owned
 * by the media device.
 *
 * Return a -EBADR error pointer if requests are not supported
 * by this driver. Return -EINVAL if the request was not found.
 * Return the pointer to the request if found: the caller will
 * have to call @media_request_put when it finished using the
 * request.
 */
struct media_request *
media_request_get_by_fd(struct media_device *mdev, int request_fd);

/**
 * media_request_alloc - Allocate the media request
 *
 * @mdev: Media device this request belongs to
 * @alloc_fd: Store the request's file descriptor in this int
 *
 * Allocated the media request and put the fd in @alloc_fd.
 */
int media_request_alloc(struct media_device *mdev,
                        int *alloc_fd);

/**
 * media_request_mark_manual_completion - Enable manual completion
 *
 * @req: The request
 *
 * Mark that the request has to be manually completed by calling
 * media_request_manual_complete().
 *
 * This function shall be called in the req_queue callback.
 */
static inline void
media_request_mark_manual_completion(struct media_request *req)
{
        req->manual_completion = true;
}

/**
 * media_request_manual_complete - Mark the request as completed
 *
 * @req: The request
 *
 * This function completes a request that was marked for manual completion by an
 * earlier call to media_request_mark_manual_completion(). The request's
 * @manual_completion field is reset to false.
 *
 * All objects contained in the request must have been completed previously. It
 * is an error to call this function otherwise. If such an error occurred, the
 * function will WARN and the object completion will be delayed until
 * @num_incomplete_objects is 0.
 */
void media_request_manual_complete(struct media_request *req);

#else

static inline void media_request_get(struct media_request *req)
{
}

static inline void media_request_put(struct media_request *req)
{
}

static inline struct media_request *
media_request_get_by_fd(struct media_device *mdev, int request_fd)
{
        return ERR_PTR(-EBADR);
}

#endif

/**
 * struct media_request_object_ops - Media request object operations
 * @prepare: Validate and prepare the request object, optional.
 * @unprepare: Unprepare the request object, optional.
 * @queue: Queue the request object, optional.
 * @unbind: Unbind the request object, optional.
 * @release: Release the request object, required.
 */
struct media_request_object_ops {
        int (*prepare)(struct media_request_object *object);
        void (*unprepare)(struct media_request_object *object);
        void (*queue)(struct media_request_object *object);
        void (*unbind)(struct media_request_object *object);
        void (*release)(struct media_request_object *object);
};

/**
 * struct media_request_object - An opaque object that belongs to a media
 *                               request
 *
 * @mdev: Media device this object belongs to
 * @ops: object's operations
 * @priv: object's priv pointer
 * @req: the request this object belongs to (can be NULL)
 * @list: List entry of the object for @struct media_request
 * @kref: Reference count of the object, acquire before releasing req->lock
 * @completed: If true, then this object was completed.
 *
 * An object related to the request. This struct is always embedded in
 * another struct that contains the actual data for this request object.
 */
struct media_request_object {
        struct media_device *mdev;
        const struct media_request_object_ops *ops;
        void *priv;
        struct media_request *req;
        struct list_head list;
        struct kref kref;
        bool completed;
};

#ifdef CONFIG_MEDIA_CONTROLLER

/**
 * media_request_object_get - Get a media request object
 *
 * @obj: The object
 *
 * Get a media request object.
 */
static inline void media_request_object_get(struct media_request_object *obj)
{
        kref_get(&obj->kref);
}

/**
 * media_request_object_put - Put a media request object
 *
 * @obj: The object
 *
 * Put a media request object. Once all references are gone, the
 * object's memory is released.
 */
void media_request_object_put(struct media_request_object *obj);

/**
 * media_request_object_find - Find an object in a request
 *
 * @req: The media request
 * @ops: Find an object with this ops value
 * @priv: Find an object with this priv value
 *
 * Both @ops and @priv must be non-NULL.
 *
 * Returns the object pointer or NULL if not found. The caller must
 * call media_request_object_put() once it finished using the object.
 *
 * Since this function needs to walk the list of objects it takes
 * the @req->lock spin lock to make this safe.
 */
struct media_request_object *
media_request_object_find(struct media_request *req,
                          const struct media_request_object_ops *ops,
                          void *priv);

/**
 * media_request_object_init - Initialise a media request object
 *
 * @obj: The object
 *
 * Initialise a media request object. The object will be released using the
 * release callback of the ops once it has no references (this function
 * initialises references to one).
 */
void media_request_object_init(struct media_request_object *obj);

/**
 * media_request_object_bind - Bind a media request object to a request
 *
 * @req: The media request
 * @ops: The object ops for this object
 * @priv: A driver-specific priv pointer associated with this object
 * @is_buffer: Set to true if the object is a buffer object.
 * @obj: The object
 *
 * Bind this object to the request and set the ops and priv values of
 * the object so it can be found later with media_request_object_find().
 *
 * Every bound object must be unbound or completed by the kernel at some
 * point in time, otherwise the request will never complete. When the
 * request is released all completed objects will be unbound by the
 * request core code.
 *
 * Buffer objects will be added to the end of the request's object
 * list, non-buffer objects will be added to the front of the list.
 * This ensures that all buffer objects are at the end of the list
 * and that all non-buffer objects that they depend on are processed
 * first.
 */
int media_request_object_bind(struct media_request *req,
                              const struct media_request_object_ops *ops,
                              void *priv, bool is_buffer,
                              struct media_request_object *obj);

/**
 * media_request_object_unbind - Unbind a media request object
 *
 * @obj: The object
 *
 * Unbind the media request object from the request.
 */
void media_request_object_unbind(struct media_request_object *obj);

/**
 * media_request_object_complete - Mark the media request object as complete
 *
 * @obj: The object
 *
 * Mark the media request object as complete. Only bound objects can
 * be completed.
 */
void media_request_object_complete(struct media_request_object *obj);

#else

static inline int __must_check
media_request_lock_for_access(struct media_request *req)
{
        return -EINVAL;
}

static inline void media_request_unlock_for_access(struct media_request *req)
{
}

static inline int __must_check
media_request_lock_for_update(struct media_request *req)
{
        return -EINVAL;
}

static inline void media_request_unlock_for_update(struct media_request *req)
{
}

static inline void media_request_object_get(struct media_request_object *obj)
{
}

static inline void media_request_object_put(struct media_request_object *obj)
{
}

static inline struct media_request_object *
media_request_object_find(struct media_request *req,
                          const struct media_request_object_ops *ops,
                          void *priv)
{
        return NULL;
}

static inline void media_request_object_init(struct media_request_object *obj)
{
        obj->ops = NULL;
        obj->req = NULL;
}

static inline int media_request_object_bind(struct media_request *req,
                               const struct media_request_object_ops *ops,
                               void *priv, bool is_buffer,
                               struct media_request_object *obj)
{
        return 0;
}

static inline void media_request_object_unbind(struct media_request_object *obj)
{
}

static inline void media_request_object_complete(struct media_request_object *obj)
{
}

#endif

#endif