From patchwork Thu Dec 17 08:40:13 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 7870771 X-Patchwork-Delegate: geert@linux-m68k.org Return-Path: X-Original-To: patchwork-linux-sh@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 86E80BEEE5 for ; Thu, 17 Dec 2015 08:42:11 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 65C7720396 for ; Thu, 17 Dec 2015 08:42:10 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 2EA6F203E9 for ; Thu, 17 Dec 2015 08:42:05 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751501AbbLQIlV (ORCPT ); Thu, 17 Dec 2015 03:41:21 -0500 Received: from galahad.ideasonboard.com ([185.26.127.97]:44652 "EHLO galahad.ideasonboard.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S934270AbbLQIlQ (ORCPT ); Thu, 17 Dec 2015 03:41:16 -0500 Received: from avalon.ideasonboard.com (unknown [207.140.26.138]) by galahad.ideasonboard.com (Postfix) with ESMTPSA id 845C120398; Thu, 17 Dec 2015 09:41:12 +0100 (CET) From: Laurent Pinchart To: linux-media@vger.kernel.org Cc: linux-sh@vger.kernel.org Subject: [PATCH/RFC 35/48] DocBook: media: Document the media request API Date: Thu, 17 Dec 2015 10:40:13 +0200 Message-Id: <1450341626-6695-36-git-send-email-laurent.pinchart+renesas@ideasonboard.com> X-Mailer: git-send-email 2.4.10 In-Reply-To: <1450341626-6695-1-git-send-email-laurent.pinchart+renesas@ideasonboard.com> References: <1450341626-6695-1-git-send-email-laurent.pinchart+renesas@ideasonboard.com> Sender: linux-sh-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-sh@vger.kernel.org X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, T_RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP The media request API is made of a new ioctl to implement request management. Document it. Signed-off-by: Laurent Pinchart --- .../DocBook/media/v4l/media-controller.xml | 1 + .../DocBook/media/v4l/media-ioc-request-cmd.xml | 194 +++++++++++++++++++++ 2 files changed, 195 insertions(+) create mode 100644 Documentation/DocBook/media/v4l/media-ioc-request-cmd.xml diff --git a/Documentation/DocBook/media/v4l/media-controller.xml b/Documentation/DocBook/media/v4l/media-controller.xml index 873ac3a621f0..09be5231fd88 100644 --- a/Documentation/DocBook/media/v4l/media-controller.xml +++ b/Documentation/DocBook/media/v4l/media-controller.xml @@ -85,5 +85,6 @@ &sub-media-ioc-device-info; &sub-media-ioc-enum-entities; &sub-media-ioc-enum-links; + &sub-media-ioc-request-cmd; &sub-media-ioc-setup-link; diff --git a/Documentation/DocBook/media/v4l/media-ioc-request-cmd.xml b/Documentation/DocBook/media/v4l/media-ioc-request-cmd.xml new file mode 100644 index 000000000000..202b248c872c --- /dev/null +++ b/Documentation/DocBook/media/v4l/media-ioc-request-cmd.xml @@ -0,0 +1,194 @@ + + + ioctl MEDIA_IOC_REQUEST_CMD + &manvol; + + + + MEDIA_IOC_REQUEST_CMD + Manage media device requests + + + + + + int ioctl + int fd + int request + struct media_request_cmd *argp + + + + + + Arguments + + + + fd + + File descriptor returned by + open(). + + + + request + + MEDIA_IOC_REQUEST_CMD + + + + argp + + + + + + + + + Description + + The MEDIA_IOC_REQUEST_CMD ioctl allow applications to manage media + device requests. A request is an object that can group media device + configuration parameters, including subsystem-specific parameters, in order + to apply all the parameters atomically. Applications are responsible for + allocating and deleting requests, filling them with configuration parameters + and (synchronously) applying or (asynchronously) queuing them. + + Request operations are performed by calling the MEDIA_IOC_REQUEST_CMD + ioctl with a pointer to a &media-request-cmd; with the + cmd set to the appropriate command. + lists the commands supported by + the ioctl. + + The &media-request-cmd; request field + contains the ID of the request on which the command operates. For the + MEDIA_REQ_CMD_ALLOC command the field is set to zero + by applications and filled by the driver. For all other commands the field + is set by applications and left untouched by the driver. + + To allocate a new request applications use the + MEDIA_REQ_CMD_ALLOC. The driver will allocate a new + request and return its ID in the request field. + + + Requests are reference-counted. A newly allocate request is referenced + by the media device file handled on which it has been created, and can be + later referenced by subsystem-specific operations using the request ID. + Requests will thus be automatically deleted when they're not longer used + after the media device file handle is closed. + + If a request isn't needed applications can delete it using the + MEDIA_REQ_CMD_DELETE command. The driver will drop the + reference to the request stored in the media device file handle. The request + will not be usable through the MEDIA_IOC_REQUEST_CMD ioctl anymore, but will + only be deleted when the last reference is released. If no other reference + exists when the delete command is invoked the request will be deleted + immediately. + + After creating a request applications should fill it with + configuration parameters. This is performed through subsystem-specific + request APIs outside the scope of the media controller API. See the + appropriate subsystem APIs for more information, including how they interact + with the MEDIA_IOC_REQUEST_CMD ioctl. + + Once a request contains all the desired configuration parameters it + can be applied synchronously or queued asynchronously. To apply a request + applications use the MEDIA_REQ_CMD_APPLY command. The + driver will apply all configuration parameters stored in the request to the + device atomically. The ioctl will return once all parameters have been + applied, but it should be noted that they might not have fully taken effect + yet. + + To queue a request applications use the + MEDIA_REQ_CMD_QUEUE command. The driver will queue the + request for processing and return immediately. The request will then be + processed and applied after all previously queued requests. + + Once a request has been queued applications are not allowed to modify + its configuration parameters until the request has been fully processed. + Any attempt to do so will result in the related subsystem API returning + an error. The media device request API doesn't notify applications of + request processing completion, this is left to the other subsystems APIs to + implement. + + + struct <structname>media_request_cmd</structname> + + &cs-str; + + + __u32 + cmd + Command, set by the application. See + for the list of supported + commands. + + + __u32 + request + Request ID, set by the driver for the + MEDIA_REQ_CMD_ALLOC and by the application + for all other commands. + + + __u32 + reserved[10] + Reserved for future extensions. Drivers and applications must + set this array to zero. + + + +
+ + + Media request commands + + + + + + MEDIA_REQ_CMD_ALLOC + Allocate a new request. + + + MEDIA_REQ_CMD_DELETE + Delete a request. + + + MEDIA_REQ_CMD_APPLY + Apply all settings from a request. + + + MEDIA_REQ_CMD_QUEUE + Queue a request for processing. + + + +
+ + + + &return-value; + + + + EINVAL + + The &media-request-cmd; specifies an invalid command or + references a non-existing request. + + + ENOSYS + + The &media-request-cmd; specifies the + MEDIA_REQ_CMD_QUEUE or + MEDIA_REQ_CMD_APPLY and that command isn't + implemented by the device. + + + + + +