From patchwork Fri May 6 10:53: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: 9031811 Return-Path: X-Original-To: patchwork-linux-media@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id 50D599F30C for ; Fri, 6 May 2016 10:57:08 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 2853F2037F for ; Fri, 6 May 2016 10:57:07 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 9CB3720381 for ; Fri, 6 May 2016 10:57:05 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1758352AbcEFK44 (ORCPT ); Fri, 6 May 2016 06:56:56 -0400 Received: from mga02.intel.com ([134.134.136.20]:57272 "EHLO mga02.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1758138AbcEFK4z (ORCPT ); Fri, 6 May 2016 06:56:55 -0400 Received: from fmsmga002.fm.intel.com ([10.253.24.26]) by orsmga101.jf.intel.com with ESMTP; 06 May 2016 03:56:41 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.24,586,1455004800"; d="scan'208";a="973958956" Received: from paasikivi.fi.intel.com ([10.237.72.42]) by fmsmga002.fm.intel.com with ESMTP; 06 May 2016 03:56:40 -0700 Received: from nauris.fi.intel.com (nauris.localdomain [192.168.240.2]) by paasikivi.fi.intel.com (Postfix) with ESMTP id 709A8210B2; Fri, 6 May 2016 13:56:36 +0300 (EEST) Received: by nauris.fi.intel.com (Postfix, from userid 1000) id A628D20168; Fri, 6 May 2016 13:53:37 +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 17/22] DocBook: media: Document the media request API Date: Fri, 6 May 2016 13:53:26 +0300 Message-Id: <1462532011-15527-18-git-send-email-sakari.ailus@linux.intel.com> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1462532011-15527-1-git-send-email-sakari.ailus@linux.intel.com> References: <1462532011-15527-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-Spam-Status: No, score=-9.0 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, 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 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. + + + + + +