From patchwork Tue May 24 16:47:26 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sakari Ailus X-Patchwork-Id: 9133923 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 68D84607D5 for ; Tue, 24 May 2016 16:51:19 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 5B7D02823B for ; Tue, 24 May 2016 16:51:19 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 509D82825C; Tue, 24 May 2016 16:51:19 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 9C46A2823B for ; Tue, 24 May 2016 16:51:18 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932267AbcEXQvL (ORCPT ); Tue, 24 May 2016 12:51:11 -0400 Received: from mga09.intel.com ([134.134.136.24]:64592 "EHLO mga09.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1756472AbcEXQvC (ORCPT ); Tue, 24 May 2016 12:51:02 -0400 Received: from orsmga001.jf.intel.com ([10.7.209.18]) by orsmga102.jf.intel.com with ESMTP; 24 May 2016 09:51:02 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.26,360,1459839600"; d="scan'208";a="961399508" Received: from paasikivi.fi.intel.com ([10.237.72.42]) by orsmga001.jf.intel.com with ESMTP; 24 May 2016 09:50:59 -0700 Received: from nauris.fi.intel.com (nauris.localdomain [192.168.240.2]) by paasikivi.fi.intel.com (Postfix) with ESMTP id 8915321126; Tue, 24 May 2016 19:50:55 +0300 (EEST) Received: by nauris.fi.intel.com (Postfix, from userid 1000) id 777CA2020D; Tue, 24 May 2016 19:47:42 +0300 (EEST) From: Sakari Ailus To: linux-media@vger.kernel.org Cc: laurent.pinchart@ideasonboard.com, hverkuil@xs4all.nl, mchehab@osg.samsung.com, Laurent Pinchart Subject: [RFC v2 16/21] DocBook: media: Document the media request API Date: Tue, 24 May 2016 19:47:26 +0300 Message-Id: <1464108451-28142-17-git-send-email-sakari.ailus@linux.intel.com> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1464108451-28142-1-git-send-email-sakari.ailus@linux.intel.com> References: <1464108451-28142-1-git-send-email-sakari.ailus@linux.intel.com> Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Laurent Pinchart The media request API is made of a new ioctl to implement request management. Document it. Signed-off-by: Laurent Pinchart Strip off the reserved fields. Signed-off-by: Sakari Ailus --- .../DocBook/media/v4l/media-controller.xml | 1 + .../DocBook/media/v4l/media-ioc-request-cmd.xml | 188 +++++++++++++++++++++ 2 files changed, 189 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 5f2fc07..2a5a5d0 100644 --- a/Documentation/DocBook/media/v4l/media-controller.xml +++ b/Documentation/DocBook/media/v4l/media-controller.xml @@ -101,5 +101,6 @@ &sub-media-ioc-g-topology; &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 0000000..4f4acea --- /dev/null +++ b/Documentation/DocBook/media/v4l/media-ioc-request-cmd.xml @@ -0,0 +1,188 @@ + + + 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. + + + +
+ + + 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. + + + + + +