From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.1 (2015-04-28) on archive.lwn.net X-Spam-Level: X-Spam-Status: No, score=-5.6 required=5.0 tests=DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI, T_DKIM_INVALID autolearn=unavailable autolearn_force=no version=3.4.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by archive.lwn.net (Postfix) with ESMTP id C30767D043 for ; Sun, 27 May 2018 23:38:15 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752665AbeE0Xgn (ORCPT ); Sun, 27 May 2018 19:36:43 -0400 Received: from merlin.infradead.org ([205.233.59.134]:35400 "EHLO merlin.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752466AbeE0Xgm (ORCPT ); Sun, 27 May 2018 19:36:42 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=merlin.20170209; h=Content-Transfer-Encoding:Content-Type: In-Reply-To:MIME-Version:Date:Message-ID:From:References:Cc:To:Subject:Sender :Reply-To:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=v9ZBS005NHgOXT2HwBtFQbF8218/v7mPSXJ6zGyvY5E=; b=2VJUB8Y7R9ii+9hKEKxen1pWuH nhNY1vpd1CsuXH8ylaWJ009DGTeEyMXgFRV8aStGTcutA9Ww1un79/XA6kQVd5Ndlnatj3/VCI1Bv MU71AVuvaiWBpM6DXEr1SwboO0cKV8ZrKLO7YZhE0zF+9stdGiBjqNN+Rkq9W6YZibIclDY05pvQ2 LwquHoL3f1OHUc7DFroEEqDo0H6isUOlfvQ8Qe3arcscVmxLOE8QmmkC9XCRqEMMNGR1bCBsv9YfS LDQqIJSi5bPvc0t6cnFnqWOYFyXKJgs3C6IdB/WFDfP/Zd76Itmstrk68+TFOnZ/qxFn/AXU9OFRy eBKalGLQ==; Received: from static-50-53-52-16.bvtn.or.frontiernet.net ([50.53.52.16] helo=midway.dunlab) by merlin.infradead.org with esmtpsa (Exim 4.90_1 #2 (Red Hat Linux)) id 1fN5DH-0003pa-3s; Sun, 27 May 2018 23:36:35 +0000 Subject: Re: [PATCH v2 2/3] Documentation: usb: add documentation for USB CCID Gadget Device To: Marcus Folkesson , Greg Kroah-Hartman , Jonathan Corbet , Felipe Balbi , davem@davemloft.net, Mauro Carvalho Chehab , Andrew Morton , Ruslan Bilovol , Thomas Gleixner , Kate Stewart Cc: linux-usb@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org References: <20180526211940.25474-1-marcus.folkesson@gmail.com> <20180526211940.25474-2-marcus.folkesson@gmail.com> From: Randy Dunlap Message-ID: <2225254e-a8f1-570e-8b1c-f68168376784@infradead.org> Date: Sun, 27 May 2018 16:36:24 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.8.0 MIME-Version: 1.0 In-Reply-To: <20180526211940.25474-2-marcus.folkesson@gmail.com> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit Sender: linux-doc-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-doc@vger.kernel.org Hi, I have a few documentation comments below... On 05/26/2018 02:19 PM, Marcus Folkesson wrote: > Add documentation to give a brief description on how to use the > CCID Gadget Device. > This includes a description for all attributes followed by an example on > how to setup the device with ConfigFS. > > Signed-off-by: Marcus Folkesson > --- > Documentation/usb/gadget_ccid.rst | 267 ++++++++++++++++++++++++++++++++++++++ > 1 file changed, 267 insertions(+) > create mode 100644 Documentation/usb/gadget_ccid.rst > > diff --git a/Documentation/usb/gadget_ccid.rst b/Documentation/usb/gadget_ccid.rst > new file mode 100644 > index 000000000000..5ac806b14604 > --- /dev/null > +++ b/Documentation/usb/gadget_ccid.rst > @@ -0,0 +1,267 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +============ > +CCID Gadget > +============ > + > +:Author: Marcus Folkesson > + > +Introduction > +============ > + > +The CCID Gadget will present itself as a CCID device to the host system. > +The device supports two endpoints for now; BULK IN and BULK OUT. > +These endpoints is exposed to userspace via /dev/ccidg*. are exposed > + > +All CCID commands are sent on the BULK-OUT endpoint. Each command sent to the CCID > +has an associated ending response. Some commands can also have intermediate > +responses. The response is sent on the BULK-IN endpoint. > +See Figure 3-3 in the CCID Specification [1]_ for more details. > + > +The CCID commands must be handled in userspace since the driver is only working > +as a transport layer for the TPDUs. > + > + > +CCID Commands > +-------------- > + > +All CCID commands begins with a 10 bytes header followed by an optional with a 10-byte header (or maybe that's a locale difference) > +data field depending on message type. > + > ++--------+--------------+-------+----------------------------------+ > +| Offset | Field | Size | Description | > ++========+==============+=======+==================================+ > +| 0 | bMessageType | 1 | Type of message | > ++--------+--------------+-------+----------------------------------+ > +| 1 | dwLength | 4 | Message specific data length | > +| | | | | > ++--------+--------------+-------+----------------------------------+ > +| 5 | bSlot | 1 | Identifies the slot number | > +| | | | for this command | > ++--------+--------------+-------+----------------------------------+ > +| 6 | bSeq | 1 | Sequence number for command | > ++--------+--------------+-------+----------------------------------+ > +| 7 | ... | 3 | Fields depends on message type | > ++--------+--------------+-------+----------------------------------+ > +| 10 | abData | array | Message specific data (OPTIONAL) | > ++--------+--------------+-------+----------------------------------+ > + > + > +Multiple CCID gadgets > +---------------------- > + > +It is possible to create multiple instances of the CCID gadget, however, > +a much more flexible way is to create one gadget and set the `nslots` attribute > +to the number of desired CCID devices. > + > +All CCID commands specifies which slot that is the receiver in the `bSlot` field specify which slot is the receiver > +of the CCID header. > + > +Usage > +===== > + > +Access from userspace > +---------------------- > +All communication is by read(2) and write(2) to the corresponding /dev/ccidg* device. > +Only one filedescriptor is allowed to be open to the device at a time. file descriptor > + > +The buffer size provided to read(2) **must be at least** 522 (10 bytes header + 512 bytes payload) > +bytes as we are working with whole commands. > + > +The buffer size provided to write(2) **may not exceed** 522 (10 bytes header + 512 bytes payload) > +bytes as we are working with whole commands. > + > + > +Configuration with configfs > +---------------------------- > + > +ConfigFS is used to create and configure the CCID gadget. > +In order to get a device to work as intended, a few attributes must > +be considered. > + > +The attributes is described below followed by an example. are > + > +features > +~~~~~~~~~ > + > +The `feature` attribute writes to the dwFeatures field in the class descriptor. > +See Table 5.1-1 Smart Card Device Descriptors in the CCID Specification [1]_. > + > +The value indicates what intelligent features the CCID has. > +These values are available to user application as defines in ccid.h [2]_. as defined > +The default value is 0x00000000. [snip] HTH. -- ~Randy -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html