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=-1.4 required=5.0 tests=DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM,FSL_HELO_FAKE, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI, T_DKIM_INVALID autolearn=ham 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 2485E7D072 for ; Mon, 28 May 2018 07:43:29 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753656AbeE1Hn1 (ORCPT ); Mon, 28 May 2018 03:43:27 -0400 Received: from mail-wm0-f66.google.com ([74.125.82.66]:38305 "EHLO mail-wm0-f66.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753612AbeE1HnZ (ORCPT ); Mon, 28 May 2018 03:43:25 -0400 Received: by mail-wm0-f66.google.com with SMTP id m129-v6so29442644wmb.3; Mon, 28 May 2018 00:43:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to:user-agent; bh=uwa2u8Xvz3KKzbGKINR6/pq7h9BnWHdDXPkUiTB9Z3U=; b=izfXzdqDdpiiEGRsdpigzckAVkedFKc/iCINRsQPd1JSLDRI+elWTwydQ6CvaKhPAe GuBdUNT0JNOZhVt60hgXzbTOQ38fAwgT6JXhV4Gja7wfIxqJnI5nfBtNMRuGoJwANzF8 5bmw7FkGbLTNIJRgzemS1eume/Sy3OcEN7wOBX5XMbFSgMbKVDQE1+VXg2RDPn2GHF7R c+0jAkhvXSOInqFjqKSgxu4pg5wv1DNgLHsGCimK97wvxTH9qZg1dbinPx+o2J4GoOLy PTSwamw1Ua7GIz9dDJlHVjaqtaxMrIm4Zp+RSydU7aW+fUQDzwwpo3wDkiyOhRcX7NzQ QiAA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to:user-agent; bh=uwa2u8Xvz3KKzbGKINR6/pq7h9BnWHdDXPkUiTB9Z3U=; b=SVtybAQs935L1YofmfB0TWwOexWonoZy4PuUC1ytV7zdi6F6DDjyeq8J53oqDmJPQx oRBigLwfr9uar3ulym+1/l0ptMPoY3W2QQgosuCV8O8Stv6J4SAqp1kftS3xCl03ydNG jWYBSTHdn/vgi112mWH/lHcFg3u0VulH2sJf4V1SBijbU4hFUDa9g9J8fWlQ/etjyyh8 l0uxx1yKt1uqbQXVsoCfdqDs+QkXkFLvlK5SnbXq2jOB2kakf6XeBxgPmoVr19v9slUH K4rVrGN93uaHW2jwsUPIh9OtUAKHJXYEW7kP/zwB3RE+RG9CP+0vxCjejQ5PO2izqpG6 4/cw== X-Gm-Message-State: ALKqPwegIpYSV60V7uqwn2aB5BeT2oIn9eM1RdAqI93tL1+nBGxj6wE8 OkHAZjJ66TE5FwVhba5fGeUm1X8M+jM= X-Google-Smtp-Source: AB8JxZqiM1MKldCxZZg9jAYfxqK4qrDBayHr3HmpQCEDiZiuZOF4ACKRVcEYfix7FcNJa709WX6UNQ== X-Received: by 2002:a2e:804c:: with SMTP id p12-v6mr7548066ljg.129.1527493404238; Mon, 28 May 2018 00:43:24 -0700 (PDT) Received: from gmail.com (c-5eea3441-74736162.cust.telenor.se. [94.234.52.65]) by smtp.gmail.com with ESMTPSA id t19-v6sm5742192ljj.46.2018.05.28.00.43.21 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Mon, 28 May 2018 00:43:23 -0700 (PDT) Date: Mon, 28 May 2018 09:42:58 +0200 From: Marcus Folkesson To: Randy Dunlap Cc: Greg Kroah-Hartman , Jonathan Corbet , Felipe Balbi , davem@davemloft.net, Mauro Carvalho Chehab , Andrew Morton , Ruslan Bilovol , Thomas Gleixner , Kate Stewart , linux-usb@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: Re: [PATCH v2 2/3] Documentation: usb: add documentation for USB CCID Gadget Device Message-ID: <20180528074258.GA4651@gmail.com> References: <20180526211940.25474-1-marcus.folkesson@gmail.com> <20180526211940.25474-2-marcus.folkesson@gmail.com> <2225254e-a8f1-570e-8b1c-f68168376784@infradead.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <2225254e-a8f1-570e-8b1c-f68168376784@infradead.org> User-Agent: Mutt/1.9.3 (2018-01-21) Sender: linux-doc-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-doc@vger.kernel.org Hi Randy, On Sun, May 27, 2018 at 04:36:24PM -0700, Randy Dunlap wrote: > 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 Thank you for your comments, I will take it with me for v3. Best regards Marcus Folkesson -- 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 From mboxrd@z Thu Jan 1 00:00:00 1970 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: base64 Subject: [v2,2/3] Documentation: usb: add documentation for USB CCID Gadget Device From: Marcus Folkesson Message-Id: <20180528074258.GA4651@gmail.com> Date: Mon, 28 May 2018 09:42:58 +0200 To: Randy Dunlap Cc: Greg Kroah-Hartman , Jonathan Corbet , Felipe Balbi , davem@davemloft.net, Mauro Carvalho Chehab , Andrew Morton , Ruslan Bilovol , Thomas Gleixner , Kate Stewart , linux-usb@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org List-ID: SGkgUmFuZHksCgpPbiBTdW4sIE1heSAyNywgMjAxOCBhdCAwNDozNjoyNFBNIC0wNzAwLCBSYW5k eSBEdW5sYXAgd3JvdGU6Cj4gSGksCj4gCj4gSSBoYXZlIGEgZmV3IGRvY3VtZW50YXRpb24gY29t bWVudHMgYmVsb3cuLi4KPiAKPiBPbiAwNS8yNi8yMDE4IDAyOjE5IFBNLCBNYXJjdXMgRm9sa2Vz c29uIHdyb3RlOgo+ID4gQWRkIGRvY3VtZW50YXRpb24gdG8gZ2l2ZSBhIGJyaWVmIGRlc2NyaXB0 aW9uIG9uIGhvdyB0byB1c2UgdGhlCj4gPiBDQ0lEIEdhZGdldCBEZXZpY2UuCj4gPiBUaGlzIGlu Y2x1ZGVzIGEgZGVzY3JpcHRpb24gZm9yIGFsbCBhdHRyaWJ1dGVzIGZvbGxvd2VkIGJ5IGFuIGV4 YW1wbGUgb24KPiA+IGhvdyB0byBzZXR1cCB0aGUgZGV2aWNlIHdpdGggQ29uZmlnRlMuCj4gPiAK PiA+IFNpZ25lZC1vZmYtYnk6IE1hcmN1cyBGb2xrZXNzb24gPG1hcmN1cy5mb2xrZXNzb25AZ21h aWwuY29tPgo+ID4gLS0tCj4gPiAgRG9jdW1lbnRhdGlvbi91c2IvZ2FkZ2V0X2NjaWQucnN0IHwg MjY3ICsrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrCj4gPiAgMSBmaWxlIGNo YW5nZWQsIDI2NyBpbnNlcnRpb25zKCspCj4gPiAgY3JlYXRlIG1vZGUgMTAwNjQ0IERvY3VtZW50 YXRpb24vdXNiL2dhZGdldF9jY2lkLnJzdAo+ID4gCj4gPiBkaWZmIC0tZ2l0IGEvRG9jdW1lbnRh dGlvbi91c2IvZ2FkZ2V0X2NjaWQucnN0IGIvRG9jdW1lbnRhdGlvbi91c2IvZ2FkZ2V0X2NjaWQu cnN0Cj4gPiBuZXcgZmlsZSBtb2RlIDEwMDY0NAo+ID4gaW5kZXggMDAwMDAwMDAwMDAwLi41YWM4 MDZiMTQ2MDQKPiA+IC0tLSAvZGV2L251bGwKPiA+ICsrKyBiL0RvY3VtZW50YXRpb24vdXNiL2dh ZGdldF9jY2lkLnJzdAo+ID4gQEAgLTAsMCArMSwyNjcgQEAKPiA+ICsuLiBTUERYLUxpY2Vuc2Ut SWRlbnRpZmllcjogR1BMLTIuMAo+ID4gKwo+ID4gKz09PT09PT09PT09PQo+ID4gK0NDSUQgR2Fk Z2V0Cj4gPiArPT09PT09PT09PT09Cj4gPiArCj4gPiArOkF1dGhvcjogTWFyY3VzIEZvbGtlc3Nv biA8bWFyY3VzLmZvbGtlc3NvbkBnbWFpbC5jb20+Cj4gPiArCj4gPiArSW50cm9kdWN0aW9uCj4g PiArPT09PT09PT09PT09Cj4gPiArCj4gPiArVGhlIENDSUQgR2FkZ2V0IHdpbGwgcHJlc2VudCBp dHNlbGYgYXMgYSBDQ0lEIGRldmljZSB0byB0aGUgaG9zdCBzeXN0ZW0uCj4gPiArVGhlIGRldmlj ZSBzdXBwb3J0cyB0d28gZW5kcG9pbnRzIGZvciBub3c7IEJVTEsgSU4gYW5kIEJVTEsgT1VULgo+ ID4gK1RoZXNlIGVuZHBvaW50cyBpcyBleHBvc2VkIHRvIHVzZXJzcGFjZSB2aWEgL2Rldi9jY2lk ZyouCj4gCj4gICAgICAgICAgICAgICAgICAgIGFyZSBleHBvc2VkCj4gCj4gPiArCj4gPiArQWxs IENDSUQgY29tbWFuZHMgYXJlIHNlbnQgb24gdGhlIEJVTEstT1VUIGVuZHBvaW50LiBFYWNoIGNv bW1hbmQgc2VudCB0byB0aGUgQ0NJRAo+ID4gK2hhcyBhbiBhc3NvY2lhdGVkIGVuZGluZyByZXNw b25zZS4gU29tZSBjb21tYW5kcyBjYW4gYWxzbyBoYXZlIGludGVybWVkaWF0ZQo+ID4gK3Jlc3Bv bnNlcy4gVGhlIHJlc3BvbnNlIGlzIHNlbnQgb24gdGhlIEJVTEstSU4gZW5kcG9pbnQuCj4gPiAr U2VlIEZpZ3VyZSAzLTMgaW4gdGhlIENDSUQgU3BlY2lmaWNhdGlvbiBbMV1fIGZvciBtb3JlIGRl dGFpbHMuCj4gPiArCj4gPiArVGhlIENDSUQgY29tbWFuZHMgbXVzdCBiZSBoYW5kbGVkIGluIHVz ZXJzcGFjZSBzaW5jZSB0aGUgZHJpdmVyIGlzIG9ubHkgd29ya2luZwo+ID4gK2FzIGEgdHJhbnNw b3J0IGxheWVyIGZvciB0aGUgVFBEVXMuCj4gPiArCj4gPiArCj4gPiArQ0NJRCBDb21tYW5kcwo+ ID4gKy0tLS0tLS0tLS0tLS0tCj4gPiArCj4gPiArQWxsIENDSUQgY29tbWFuZHMgYmVnaW5zIHdp dGggYSAxMCBieXRlcyBoZWFkZXIgZm9sbG93ZWQgYnkgYW4gb3B0aW9uYWwKPiAKPiAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgd2l0aCBhIDEwLWJ5dGUgaGVhZGVyCj4gKG9yIG1heWJlIHRo YXQncyBhIGxvY2FsZSBkaWZmZXJlbmNlKQo+IAo+ID4gK2RhdGEgZmllbGQgZGVwZW5kaW5nIG9u IG1lc3NhZ2UgdHlwZS4KPiA+ICsKPiA+ICsrLS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0rLS0tLS0t LSstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tKwo+ID4gK3wgT2Zmc2V0IHwgRmll bGQgICAgICAgIHwgU2l6ZSAgfCBEZXNjcmlwdGlvbiAgICAgICAgICAgICAgICAgICAgICB8Cj4g PiArKz09PT09PT09Kz09PT09PT09PT09PT09Kz09PT09PT0rPT09PT09PT09PT09PT09PT09PT09 PT09PT09PT09PT09PSsKPiA+ICt8IDAgICAgICB8IGJNZXNzYWdlVHlwZSB8IDEgICAgIHwgVHlw ZSBvZiBtZXNzYWdlICAgICAgICAgICAgICAgICAgfAo+ID4gKystLS0tLS0tLSstLS0tLS0tLS0t LS0tLSstLS0tLS0tKy0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0rCj4gPiArfCAx ICAgICAgfCBkd0xlbmd0aCAgICAgfCA0ICAgICB8IE1lc3NhZ2Ugc3BlY2lmaWMgZGF0YSBsZW5n dGggICAgIHwKPiA+ICt8ICAgICAgICB8ICAgICAgICAgICAgICB8ICAgICAgIHwgICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgfAo+ID4gKystLS0tLS0tLSstLS0tLS0tLS0tLS0tLSst LS0tLS0tKy0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0rCj4gPiArfCA1ICAgICAg fCBiU2xvdCAgICAgICAgfCAxICAgICB8IElkZW50aWZpZXMgdGhlIHNsb3QgbnVtYmVyICAgICAg IHwKPiA+ICt8ICAgICAgICB8ICAgICAgICAgICAgICB8ICAgICAgIHwgZm9yIHRoaXMgY29tbWFu ZCAgICAgICAgICAgICAgICAgfAo+ID4gKystLS0tLS0tLSstLS0tLS0tLS0tLS0tLSstLS0tLS0t Ky0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0rCj4gPiArfCA2ICAgICAgfCBiU2Vx ICAgICAgICAgfCAxICAgICB8IFNlcXVlbmNlIG51bWJlciBmb3IgY29tbWFuZCAgICAgIHwKPiA+ ICsrLS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0rLS0tLS0tLSstLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tKwo+ID4gK3wgNyAgICAgIHwgLi4uICAgICAgICAgIHwgMyAgICAgfCBGaWVs ZHMgZGVwZW5kcyBvbiBtZXNzYWdlIHR5cGUgICB8Cj4gPiArKy0tLS0tLS0tKy0tLS0tLS0tLS0t LS0tKy0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKPiA+ICt8IDEw ICAgICB8IGFiRGF0YSAgICAgICB8IGFycmF5IHwgTWVzc2FnZSBzcGVjaWZpYyBkYXRhIChPUFRJ T05BTCkgfAo+ID4gKystLS0tLS0tLSstLS0tLS0tLS0tLS0tLSstLS0tLS0tKy0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0rCj4gPiArCj4gPiArCj4gPiArTXVsdGlwbGUgQ0NJRCBn YWRnZXRzCj4gPiArLS0tLS0tLS0tLS0tLS0tLS0tLS0tLQo+ID4gKwo+ID4gK0l0IGlzIHBvc3Np YmxlIHRvIGNyZWF0ZSBtdWx0aXBsZSBpbnN0YW5jZXMgb2YgdGhlIENDSUQgZ2FkZ2V0LCBob3dl dmVyLAo+ID4gK2EgbXVjaCBtb3JlIGZsZXhpYmxlIHdheSBpcyB0byBjcmVhdGUgb25lIGdhZGdl dCBhbmQgc2V0IHRoZSBgbnNsb3RzYCBhdHRyaWJ1dGUKPiA+ICt0byB0aGUgbnVtYmVyIG9mIGRl c2lyZWQgQ0NJRCBkZXZpY2VzLgo+ID4gKwo+ID4gK0FsbCBDQ0lEIGNvbW1hbmRzIHNwZWNpZmll cyB3aGljaCBzbG90IHRoYXQgaXMgdGhlIHJlY2VpdmVyIGluIHRoZSBgYlNsb3RgIGZpZWxkCj4g Cj4gICAgICAgICAgICAgICAgICAgICAgc3BlY2lmeSB3aGljaCBzbG90IGlzIHRoZSByZWNlaXZl cgo+IAo+ID4gK29mIHRoZSBDQ0lEIGhlYWRlci4KPiA+ICsKPiA+ICtVc2FnZQo+ID4gKz09PT09 Cj4gPiArCj4gPiArQWNjZXNzIGZyb20gdXNlcnNwYWNlCj4gPiArLS0tLS0tLS0tLS0tLS0tLS0t LS0tLQo+ID4gK0FsbCBjb21tdW5pY2F0aW9uIGlzIGJ5IHJlYWQoMikgYW5kIHdyaXRlKDIpIHRv IHRoZSBjb3JyZXNwb25kaW5nIC9kZXYvY2NpZGcqIGRldmljZS4KPiA+ICtPbmx5IG9uZSBmaWxl ZGVzY3JpcHRvciBpcyBhbGxvd2VkIHRvIGJlIG9wZW4gdG8gdGhlIGRldmljZSBhdCBhIHRpbWUu Cj4gCj4gICAgICAgICAgICAgZmlsZSBkZXNjcmlwdG9yCj4gCj4gPiArCj4gPiArVGhlIGJ1ZmZl ciBzaXplIHByb3ZpZGVkIHRvIHJlYWQoMikgKiptdXN0IGJlIGF0IGxlYXN0KiogNTIyICgxMCBi eXRlcyBoZWFkZXIgKyA1MTIgYnl0ZXMgcGF5bG9hZCkKPiA+ICtieXRlcyBhcyB3ZSBhcmUgd29y a2luZyB3aXRoIHdob2xlIGNvbW1hbmRzLgo+ID4gKwo+ID4gK1RoZSBidWZmZXIgc2l6ZSBwcm92 aWRlZCB0byB3cml0ZSgyKSAqKm1heSBub3QgZXhjZWVkKiogNTIyICgxMCBieXRlcyBoZWFkZXIg KyA1MTIgYnl0ZXMgcGF5bG9hZCkKPiA+ICtieXRlcyBhcyB3ZSBhcmUgd29ya2luZyB3aXRoIHdo b2xlIGNvbW1hbmRzLgo+ID4gKwo+ID4gKwo+ID4gK0NvbmZpZ3VyYXRpb24gd2l0aCBjb25maWdm cwo+ID4gKy0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0KPiA+ICsKPiA+ICtDb25maWdGUyBp cyB1c2VkIHRvIGNyZWF0ZSBhbmQgY29uZmlndXJlIHRoZSBDQ0lEIGdhZGdldC4KPiA+ICtJbiBv cmRlciB0byBnZXQgYSBkZXZpY2UgdG8gd29yayBhcyBpbnRlbmRlZCwgYSBmZXcgYXR0cmlidXRl cyBtdXN0Cj4gPiArYmUgY29uc2lkZXJlZC4KPiA+ICsKPiA+ICtUaGUgYXR0cmlidXRlcyBpcyBk ZXNjcmliZWQgYmVsb3cgZm9sbG93ZWQgYnkgYW4gZXhhbXBsZS4KPiAKPiAgICAgICAgICAgICAg ICAgICBhcmUKPiAKPiA+ICsKPiA+ICtmZWF0dXJlcwo+ID4gK35+fn5+fn5+fgo+ID4gKwo+ID4g K1RoZSBgZmVhdHVyZWAgYXR0cmlidXRlIHdyaXRlcyB0byB0aGUgZHdGZWF0dXJlcyBmaWVsZCBp biB0aGUgY2xhc3MgZGVzY3JpcHRvci4KPiA+ICtTZWUgVGFibGUgNS4xLTEgU21hcnQgQ2FyZCBE ZXZpY2UgRGVzY3JpcHRvcnMgaW4gdGhlIENDSUQgU3BlY2lmaWNhdGlvbiBbMV1fLgo+ID4gKwo+ ID4gK1RoZSB2YWx1ZSBpbmRpY2F0ZXMgd2hhdCBpbnRlbGxpZ2VudCBmZWF0dXJlcyB0aGUgQ0NJ RCBoYXMuCj4gPiArVGhlc2UgdmFsdWVzIGFyZSBhdmFpbGFibGUgdG8gdXNlciBhcHBsaWNhdGlv biBhcyBkZWZpbmVzIGluIGNjaWQuaCBbMl1fLgo+IAo+ICAgICAgICAgICAgICAgICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgICAgYXMgZGVmaW5lZAo+IAo+ID4gK1RoZSBkZWZhdWx0 IHZhbHVlIGlzIDB4MDAwMDAwMDAuCj4gCj4gCj4gW3NuaXBdCj4gCj4gSFRILgo+IC0tIAo+IH5S YW5keQoKVGhhbmsgeW91IGZvciB5b3VyIGNvbW1lbnRzLCBJIHdpbGwgdGFrZSBpdCB3aXRoIG1l IGZvciB2My4KCkJlc3QgcmVnYXJkcwpNYXJjdXMgRm9sa2Vzc29uCi0tLQpUbyB1bnN1YnNjcmli ZSBmcm9tIHRoaXMgbGlzdDogc2VuZCB0aGUgbGluZSAidW5zdWJzY3JpYmUgbGludXgtdXNiIiBp bgp0aGUgYm9keSBvZiBhIG1lc3NhZ2UgdG8gbWFqb3Jkb21vQHZnZXIua2VybmVsLm9yZwpNb3Jl IG1ham9yZG9tbyBpbmZvIGF0ICBodHRwOi8vdmdlci5rZXJuZWwub3JnL21ham9yZG9tby1pbmZv Lmh0bWwK From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753879AbeE1Hna (ORCPT ); Mon, 28 May 2018 03:43:30 -0400 Received: from mail-wm0-f66.google.com ([74.125.82.66]:38305 "EHLO mail-wm0-f66.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753612AbeE1HnZ (ORCPT ); Mon, 28 May 2018 03:43:25 -0400 X-Google-Smtp-Source: AB8JxZqiM1MKldCxZZg9jAYfxqK4qrDBayHr3HmpQCEDiZiuZOF4ACKRVcEYfix7FcNJa709WX6UNQ== Date: Mon, 28 May 2018 09:42:58 +0200 From: Marcus Folkesson To: Randy Dunlap Cc: Greg Kroah-Hartman , Jonathan Corbet , Felipe Balbi , davem@davemloft.net, Mauro Carvalho Chehab , Andrew Morton , Ruslan Bilovol , Thomas Gleixner , Kate Stewart , linux-usb@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: Re: [PATCH v2 2/3] Documentation: usb: add documentation for USB CCID Gadget Device Message-ID: <20180528074258.GA4651@gmail.com> References: <20180526211940.25474-1-marcus.folkesson@gmail.com> <20180526211940.25474-2-marcus.folkesson@gmail.com> <2225254e-a8f1-570e-8b1c-f68168376784@infradead.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <2225254e-a8f1-570e-8b1c-f68168376784@infradead.org> User-Agent: Mutt/1.9.3 (2018-01-21) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Hi Randy, On Sun, May 27, 2018 at 04:36:24PM -0700, Randy Dunlap wrote: > 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 Thank you for your comments, I will take it with me for v3. Best regards Marcus Folkesson