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.4 required=5.0 tests=DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, 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 6744C7DF8B for ; Sat, 26 May 2018 20:35:55 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1032409AbeEZUfO (ORCPT ); Sat, 26 May 2018 16:35:14 -0400 Received: from mail-wr0-f196.google.com ([209.85.128.196]:37665 "EHLO mail-wr0-f196.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1032375AbeEZUfM (ORCPT ); Sat, 26 May 2018 16:35:12 -0400 Received: by mail-wr0-f196.google.com with SMTP id i12-v6so14421446wrc.4; Sat, 26 May 2018 13:35:11 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=UxpLaP4sVvgvW5DWM6scbZ1+Cf42pGzYx7dVTWDzoCQ=; b=mZ/fNQmFPdM5N4Wn/KmaBqFro6qmow3d4LUPVdougNLt4c4u7QCrn0cAJehXjg85Pb vd4a9Q+BTl9TDLHTMrbRg4vjM+XQtYnBe8rOjSnajM/Su7XBrmGreURtwcypu+3Btf4u TEKu+egWp1rTEg2lWUpRjxsTtpjnZ+lECmgtfzyFDgnoPl1Lh0sHeVaWUCq/zOhtLzjW gRnM7vkyZyBrwl+HF9SbnvKw8/qWMYu+OXQCbOg/uH8ch9n0BmIw0CSQo2wTqDH+TEW+ fSmKZzA0lDFs4vARp7jKXg5hIEtchS0LJvESlyrBBJZ4WaqTiYz8POi93jvdVBlvLTb6 zkTw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=UxpLaP4sVvgvW5DWM6scbZ1+Cf42pGzYx7dVTWDzoCQ=; b=EoBo8YorkQW1GvUUUtsHZ28KHcP50zBHtxbAnOySBQQz7IqKmucQUWzsyfSeYH3Cvm AExN1w/oAnAv0aJAduAhPOqHej/H8POOUi4vyrR5F5PKyNB1BxkpKe9bPRV9LYFsvDTM GPWiD6A5JSgqDvCXDfCUuSYORj7DD01uRsojchMrX+NjwizMINLQWIjGNNXv5CZ2GNQi 8knkGuk45X0wnEPmWgh1ixf7PkPqgBjr8xiVW55+bU6b21LfI5WJa/l69QUKH5U7g6wR nrRz9vm/dXm6UYUmPOKTXO7GDLKhDaV+i6I7XoIoUQ27rGjeDWBtKXmZkSaxRttnv8J1 ElJA== X-Gm-Message-State: ALKqPwdk8DnWJxecL8fwJryLZLdheLqMVJDzRilHc9HJMA5ehbq9xhzB WnzjhXuuwFDvJuNVrx006QFe5ycD X-Google-Smtp-Source: ADUXVKJ9Iy+CDiCEKfX0EjX/PWWnTej9qoVQZ5Oh0zNoruIqEI3fBpRsyiOTxf1b+62ThVPC/9BIsg== X-Received: by 2002:a19:d7d5:: with SMTP id q82-v6mr4141161lfi.71.1527366910411; Sat, 26 May 2018 13:35:10 -0700 (PDT) Received: from localhost.localdomain (c-2ec2c701-74736162.cust.telenor.se. [46.194.199.1]) by smtp.gmail.com with ESMTPSA id d7-v6sm4953381ljc.45.2018.05.26.13.35.08 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sat, 26 May 2018 13:35:09 -0700 (PDT) From: Marcus Folkesson To: Greg Kroah-Hartman , Jonathan Corbet , Felipe Balbi , davem@davemloft.net, Mauro Carvalho Chehab , Andrew Morton , Randy Dunlap , Ruslan Bilovol , Thomas Gleixner , Kate Stewart Cc: linux-usb@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Marcus Folkesson Subject: [PATCH 2/3] Documentation: usb: add documentation for USB CCID Gadget Device Date: Sat, 26 May 2018 22:34:00 +0200 Message-Id: <20180526203401.16586-2-marcus.folkesson@gmail.com> X-Mailer: git-send-email 2.16.2 In-Reply-To: <20180526203401.16586-1-marcus.folkesson@gmail.com> References: <20180526203401.16586-1-marcus.folkesson@gmail.com> Sender: linux-doc-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-doc@vger.kernel.org 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*. + +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 +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 +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. + +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. + +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]_. +The default value is 0x00000000. + +The value is a bitwise OR operation performed on the following values: + ++------------+----------------------------------------------------------------+ +| Value | Description | ++============+================================================================+ +| 0x00000000 | No special characteristics | ++------------+----------------------------------------------------------------+ +| 0x00000002 | Automatic parameter configuration based on ATR data | ++------------+----------------------------------------------------------------+ +| 0x00000004 | Automatic activation of ICC on inserting | ++------------+----------------------------------------------------------------+ +| 0x00000008 | Automatic ICC voltage selection | ++------------+----------------------------------------------------------------+ +| 0x00000010 | Automatic ICC clock frequency change according to active | +| | parameters provided by the Host or self determined | ++------------+----------------------------------------------------------------+ +| 0x00000020 | Automatic baud rate change according to active | +| | parameters provided by the Host or self determined | ++------------+----------------------------------------------------------------+ +| 0x00000040 | Automatic parameters negotiation made by the CCID | ++------------+----------------------------------------------------------------+ +| 0x00000080 | Automatic PPS made by the CCID according to the | +| | active parameters | ++------------+----------------------------------------------------------------+ +| 0x00000100 | CCID can set ICC in clock stop mode | ++------------+----------------------------------------------------------------+ +| 0x00000200 | NAD value other than 00 accepted (T=1 protocol in use) | ++------------+----------------------------------------------------------------+ +| 0x00000400 | Automatic IFSD exchange as first exchange | ++------------+----------------------------------------------------------------+ + + +Only one of the following values may be present to select a level of exchange: + ++------------+--------------------------------------------------+ +| Value | Description | ++============+==================================================+ +| 0x00010000 | TPDU level exchanges with CCID | ++------------+--------------------------------------------------+ +| 0x00020000 | Short APDU level exchange with CCID | ++------------+--------------------------------------------------+ +| 0x00040000 | Short and Extended APDU level exchange with CCID | ++------------+--------------------------------------------------+ + +If none of those values is indicated the level of exchange is +character. + + +protocols +~~~~~~~~~~ +The `protocols` attribute writes to the dwProtocols field in the class descriptor. +See Table 5.1-1 Smart Card Device Descriptors in the CCID Specification [1]_. + +The value is a bitwise OR operation performed on the following values: + ++--------+--------------+ +| Value | Description | ++========+==============+ +| 0x0001 | Protocol T=0 | ++--------+--------------+ +| 0x0002 | Protocol T=1 | ++--------+--------------+ + +If no protocol is selected both T=0 and T=1 will be supported (`protocols` = 0x0003). + +nslots +~~~~~~ + +The `nslots` attribute writes to the bMaxSlotIndex field in the class descriptor. +See Table 5.1-1 Smart Card Device Descriptors in the CCID Specification [1]_. + +This is the index of the highest available slot on this device. All slots are consecutive starting at 00h. +i.e. 0Fh = 16 slots on this device numbered 00h to 0Fh. + +The default value is 0, which means one slot. + + +pinsupport +~~~~~~~~~~~~ + +This value indicates what PIN support features the CCID has. + +The `pinsupport` attribute writes to the dwPINSupport field in the class descriptor. +See Table 5.1-1 Smart Card Device Descriptors in the CCID Specification [1]_. + + +The value is a bitwise OR operation performed on the following values: + ++--------+----------------------------+ +| Value | Description | ++========+============================+ +| 0x00 | No PIN support | ++--------+----------------------------+ +| 0x01 | PIN Verification supported | ++--------+----------------------------+ +| 0x02 | PIN Modification supported | ++--------+----------------------------+ + +The default value is set to 0x00. + + +lcdlayout +~~~~~~~~~~ + +Number of lines and characters for the LCD display used to send messages for PIN entry. + +The `lcdLayout` attribute writes to the wLcdLayout field in the class descriptor. +See Table 5.1-1 Smart Card Device Descriptors in the CCID Specification [1]_. + + +The value is set as follows: + ++--------+------------------------------------+ +| Value | Description | ++========+====================================+ +| 0x0000 | No LCD | ++--------+------------------------------------+ +| 0xXXYY | XX: number of lines | +| | YY: number of characters per line. | ++--------+------------------------------------+ + +The default value is set to 0x0000. + + +Example +------- + +Here is an example on how to setup a CCID gadget with configfs :: + + #!/bin/sh + + CONFIGDIR=/sys/kernel/config + GADGET=$CONFIGDIR/usb_gadget/g0 + FUNCTION=$GADGET/functions/ccid.sc0 + + VID=YOUR_VENDOR_ID_HERE + PID=YOUR_PRODUCT_ID_HERE + UDC=YOUR_UDC_HERE + + #Mount filesystem + mount none -t configfs $CONFIGDIR + + #Populate ID:s + echo $VID > $GADGET/idVendor + echo $PID > $GADGET/idProduct + + #Create and configure the gadget + mkdir $FUNCTION + echo 0x000407B8 > $FUNCTION/features + echo 0x02 > $FUNCTION/protocols + + #Create our english strings + mkdir $GADGET/strings/0x409 + echo 556677 > $GADGET/strings/0x409/serialnumber + echo "Hungry Penguins" > $GADGET/strings/0x409/manufacturer + echo "Harpoon With SmartCard" > $GADGET/strings/0x409/product + + #Create configuration + mkdir $GADGET/configs/c.1 + mkdir $GADGET/configs/c.1/strings/0x409 + echo Config1 > $GADGET/configs/c.1/strings/0x409/configuration + + #Use `Config1` for our CCID gadget + ln -s $FUNCTION $GADGET/configs/c.1 + + #Execute + echo $UDC > $GADGET/UDC + + +References +========== + +.. [1] http://www.usb.org/developers/docs/devclass_docs/DWG_Smart-Card_CCID_Rev110.pdf +.. [2] include/uapi/linux/usb/ccid.h -- 2.16.2 -- 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: [2/3] Documentation: usb: add documentation for USB CCID Gadget Device From: Marcus Folkesson Message-Id: <20180526203401.16586-2-marcus.folkesson@gmail.com> Date: Sat, 26 May 2018 22:34:00 +0200 To: Greg Kroah-Hartman , Jonathan Corbet , Felipe Balbi , davem@davemloft.net, Mauro Carvalho Chehab , Andrew Morton , Randy Dunlap , Ruslan Bilovol , Thomas Gleixner , Kate Stewart Cc: linux-usb@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Marcus Folkesson List-ID: U2lnbmVkLW9mZi1ieTogTWFyY3VzIEZvbGtlc3NvbiA8bWFyY3VzLmZvbGtlc3NvbkBnbWFpbC5j b20+Ci0tLQogRG9jdW1lbnRhdGlvbi91c2IvZ2FkZ2V0X2NjaWQucnN0IHwgMjY3ICsrKysrKysr KysrKysrKysrKysrKysrKysrKysrKysrKysrKysrCiAxIGZpbGUgY2hhbmdlZCwgMjY3IGluc2Vy dGlvbnMoKykKIGNyZWF0ZSBtb2RlIDEwMDY0NCBEb2N1bWVudGF0aW9uL3VzYi9nYWRnZXRfY2Np ZC5yc3QKCmRpZmYgLS1naXQgYS9Eb2N1bWVudGF0aW9uL3VzYi9nYWRnZXRfY2NpZC5yc3QgYi9E b2N1bWVudGF0aW9uL3VzYi9nYWRnZXRfY2NpZC5yc3QKbmV3IGZpbGUgbW9kZSAxMDA2NDQKaW5k ZXggMDAwMDAwMDAwMDAwLi41YWM4MDZiMTQ2MDQKLS0tIC9kZXYvbnVsbAorKysgYi9Eb2N1bWVu dGF0aW9uL3VzYi9nYWRnZXRfY2NpZC5yc3QKQEAgLTAsMCArMSwyNjcgQEAKKy4uIFNQRFgtTGlj ZW5zZS1JZGVudGlmaWVyOiBHUEwtMi4wCisKKz09PT09PT09PT09PQorQ0NJRCBHYWRnZXQKKz09 PT09PT09PT09PQorCis6QXV0aG9yOiBNYXJjdXMgRm9sa2Vzc29uIDxtYXJjdXMuZm9sa2Vzc29u QGdtYWlsLmNvbT4KKworSW50cm9kdWN0aW9uCis9PT09PT09PT09PT0KKworVGhlIENDSUQgR2Fk Z2V0IHdpbGwgcHJlc2VudCBpdHNlbGYgYXMgYSBDQ0lEIGRldmljZSB0byB0aGUgaG9zdCBzeXN0 ZW0uCitUaGUgZGV2aWNlIHN1cHBvcnRzIHR3byBlbmRwb2ludHMgZm9yIG5vdzsgQlVMSyBJTiBh bmQgQlVMSyBPVVQuCitUaGVzZSBlbmRwb2ludHMgaXMgZXhwb3NlZCB0byB1c2Vyc3BhY2Ugdmlh IC9kZXYvY2NpZGcqLgorCitBbGwgQ0NJRCBjb21tYW5kcyBhcmUgc2VudCBvbiB0aGUgQlVMSy1P VVQgZW5kcG9pbnQuIEVhY2ggY29tbWFuZCBzZW50IHRvIHRoZSBDQ0lECitoYXMgYW4gYXNzb2Np YXRlZCBlbmRpbmcgcmVzcG9uc2UuIFNvbWUgY29tbWFuZHMgY2FuIGFsc28gaGF2ZSBpbnRlcm1l ZGlhdGUKK3Jlc3BvbnNlcy4gVGhlIHJlc3BvbnNlIGlzIHNlbnQgb24gdGhlIEJVTEstSU4gZW5k cG9pbnQuCitTZWUgRmlndXJlIDMtMyBpbiB0aGUgQ0NJRCBTcGVjaWZpY2F0aW9uIFsxXV8gZm9y IG1vcmUgZGV0YWlscy4KKworVGhlIENDSUQgY29tbWFuZHMgbXVzdCBiZSBoYW5kbGVkIGluIHVz ZXJzcGFjZSBzaW5jZSB0aGUgZHJpdmVyIGlzIG9ubHkgd29ya2luZworYXMgYSB0cmFuc3BvcnQg bGF5ZXIgZm9yIHRoZSBUUERVcy4KKworCitDQ0lEIENvbW1hbmRzCistLS0tLS0tLS0tLS0tLQor CitBbGwgQ0NJRCBjb21tYW5kcyBiZWdpbnMgd2l0aCBhIDEwIGJ5dGVzIGhlYWRlciBmb2xsb3dl ZCBieSBhbiBvcHRpb25hbAorZGF0YSBmaWVsZCBkZXBlbmRpbmcgb24gbWVzc2FnZSB0eXBlLgor CisrLS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0rLS0tLS0tLSstLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tKworfCBPZmZzZXQgfCBGaWVsZCAgICAgICAgfCBTaXplICB8IERlc2NyaXB0 aW9uICAgICAgICAgICAgICAgICAgICAgIHwKKys9PT09PT09PSs9PT09PT09PT09PT09PSs9PT09 PT09Kz09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT0rCit8IDAgICAgICB8IGJNZXNz YWdlVHlwZSB8IDEgICAgIHwgVHlwZSBvZiBtZXNzYWdlICAgICAgICAgICAgICAgICAgfAorKy0t LS0tLS0tKy0tLS0tLS0tLS0tLS0tKy0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLSsKK3wgMSAgICAgIHwgZHdMZW5ndGggICAgIHwgNCAgICAgfCBNZXNzYWdlIHNwZWNp ZmljIGRhdGEgbGVuZ3RoICAgICB8Cit8ICAgICAgICB8ICAgICAgICAgICAgICB8ICAgICAgIHwg ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgfAorKy0tLS0tLS0tKy0tLS0tLS0tLS0t LS0tKy0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKK3wgNSAgICAg IHwgYlNsb3QgICAgICAgIHwgMSAgICAgfCBJZGVudGlmaWVzIHRoZSBzbG90IG51bWJlciAgICAg ICB8Cit8ICAgICAgICB8ICAgICAgICAgICAgICB8ICAgICAgIHwgZm9yIHRoaXMgY29tbWFuZCAg ICAgICAgICAgICAgICAgfAorKy0tLS0tLS0tKy0tLS0tLS0tLS0tLS0tKy0tLS0tLS0rLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKK3wgNiAgICAgIHwgYlNlcSAgICAgICAgIHwg MSAgICAgfCBTZXF1ZW5jZSBudW1iZXIgZm9yIGNvbW1hbmQgICAgICB8CisrLS0tLS0tLS0rLS0t LS0tLS0tLS0tLS0rLS0tLS0tLSstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tKwor fCA3ICAgICAgfCAuLi4gICAgICAgICAgfCAzICAgICB8IEZpZWxkcyBkZXBlbmRzIG9uIG1lc3Nh Z2UgdHlwZSAgIHwKKystLS0tLS0tLSstLS0tLS0tLS0tLS0tLSstLS0tLS0tKy0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0rCit8IDEwICAgICB8IGFiRGF0YSAgICAgICB8IGFycmF5 IHwgTWVzc2FnZSBzcGVjaWZpYyBkYXRhIChPUFRJT05BTCkgfAorKy0tLS0tLS0tKy0tLS0tLS0t LS0tLS0tKy0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKKworCitN dWx0aXBsZSBDQ0lEIGdhZGdldHMKKy0tLS0tLS0tLS0tLS0tLS0tLS0tLS0KKworSXQgaXMgcG9z c2libGUgdG8gY3JlYXRlIG11bHRpcGxlIGluc3RhbmNlcyBvZiB0aGUgQ0NJRCBnYWRnZXQsIGhv d2V2ZXIsCithIG11Y2ggbW9yZSBmbGV4aWJsZSB3YXkgaXMgdG8gY3JlYXRlIG9uZSBnYWRnZXQg YW5kIHNldCB0aGUgYG5zbG90c2AgYXR0cmlidXRlCit0byB0aGUgbnVtYmVyIG9mIGRlc2lyZWQg Q0NJRCBkZXZpY2VzLgorCitBbGwgQ0NJRCBjb21tYW5kcyBzcGVjaWZpZXMgd2hpY2ggc2xvdCB0 aGF0IGlzIHRoZSByZWNlaXZlciBpbiB0aGUgYGJTbG90YCBmaWVsZAorb2YgdGhlIENDSUQgaGVh ZGVyLgorCitVc2FnZQorPT09PT0KKworQWNjZXNzIGZyb20gdXNlcnNwYWNlCistLS0tLS0tLS0t LS0tLS0tLS0tLS0tCitBbGwgY29tbXVuaWNhdGlvbiBpcyBieSByZWFkKDIpIGFuZCB3cml0ZSgy KSB0byB0aGUgY29ycmVzcG9uZGluZyAvZGV2L2NjaWRnKiBkZXZpY2UuCitPbmx5IG9uZSBmaWxl ZGVzY3JpcHRvciBpcyBhbGxvd2VkIHRvIGJlIG9wZW4gdG8gdGhlIGRldmljZSBhdCBhIHRpbWUu CisKK1RoZSBidWZmZXIgc2l6ZSBwcm92aWRlZCB0byByZWFkKDIpICoqbXVzdCBiZSBhdCBsZWFz dCoqIDUyMiAoMTAgYnl0ZXMgaGVhZGVyICsgNTEyIGJ5dGVzIHBheWxvYWQpCitieXRlcyBhcyB3 ZSBhcmUgd29ya2luZyB3aXRoIHdob2xlIGNvbW1hbmRzLgorCitUaGUgYnVmZmVyIHNpemUgcHJv dmlkZWQgdG8gd3JpdGUoMikgKiptYXkgbm90IGV4Y2VlZCoqIDUyMiAoMTAgYnl0ZXMgaGVhZGVy ICsgNTEyIGJ5dGVzIHBheWxvYWQpCitieXRlcyBhcyB3ZSBhcmUgd29ya2luZyB3aXRoIHdob2xl IGNvbW1hbmRzLgorCisKK0NvbmZpZ3VyYXRpb24gd2l0aCBjb25maWdmcworLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLQorCitDb25maWdGUyBpcyB1c2VkIHRvIGNyZWF0ZSBhbmQgY29uZmln dXJlIHRoZSBDQ0lEIGdhZGdldC4KK0luIG9yZGVyIHRvIGdldCBhIGRldmljZSB0byB3b3JrIGFz IGludGVuZGVkLCBhIGZldyBhdHRyaWJ1dGVzIG11c3QKK2JlIGNvbnNpZGVyZWQuCisKK1RoZSBh dHRyaWJ1dGVzIGlzIGRlc2NyaWJlZCBiZWxvdyBmb2xsb3dlZCBieSBhbiBleGFtcGxlLgorCitm ZWF0dXJlcworfn5+fn5+fn5+CisKK1RoZSBgZmVhdHVyZWAgYXR0cmlidXRlIHdyaXRlcyB0byB0 aGUgZHdGZWF0dXJlcyBmaWVsZCBpbiB0aGUgY2xhc3MgZGVzY3JpcHRvci4KK1NlZSBUYWJsZSA1 LjEtMSBTbWFydCBDYXJkIERldmljZSBEZXNjcmlwdG9ycyBpbiB0aGUgQ0NJRCBTcGVjaWZpY2F0 aW9uIFsxXV8uCisKK1RoZSB2YWx1ZSBpbmRpY2F0ZXMgd2hhdCBpbnRlbGxpZ2VudCBmZWF0dXJl cyB0aGUgQ0NJRCBoYXMuCitUaGVzZSB2YWx1ZXMgYXJlIGF2YWlsYWJsZSB0byB1c2VyIGFwcGxp Y2F0aW9uIGFzIGRlZmluZXMgaW4gY2NpZC5oIFsyXV8uCitUaGUgZGVmYXVsdCB2YWx1ZSBpcyAw eDAwMDAwMDAwLgorCitUaGUgdmFsdWUgaXMgYSBiaXR3aXNlIE9SIG9wZXJhdGlvbiBwZXJmb3Jt ZWQgb24gdGhlIGZvbGxvd2luZyB2YWx1ZXM6CisKKystLS0tLS0tLS0tLS0rLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKK3wg VmFsdWUgICAgICB8IERlc2NyaXB0aW9uICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg ICAgICAgICAgICAgICAgICAgIHwKKys9PT09PT09PT09PT0rPT09PT09PT09PT09PT09PT09PT09 PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PSsKK3wgMHgwMDAwMDAw MCB8IE5vIHNwZWNpYWwgY2hhcmFjdGVyaXN0aWNzICAgICAgICAgICAgICAgICAgICAgICAgICAg ICAgICAgICAgIHwKKystLS0tLS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKK3wgMHgwMDAwMDAwMiB8IEF1dG9t YXRpYyBwYXJhbWV0ZXIgY29uZmlndXJhdGlvbiBiYXNlZCBvbiBBVFIgZGF0YSAgICAgICAgICAg IHwKKystLS0tLS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKK3wgMHgwMDAwMDAwNCB8IEF1dG9tYXRpYyBhY3Rp dmF0aW9uIG9mIElDQyBvbiBpbnNlcnRpbmcgICAgICAgICAgICAgICAgICAgICAgIHwKKystLS0t LS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLSsKK3wgMHgwMDAwMDAwOCB8IEF1dG9tYXRpYyBJQ0Mgdm9sdGFnZSBz ZWxlY3Rpb24gICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIHwKKystLS0tLS0tLS0tLS0r LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLSsKK3wgMHgwMDAwMDAxMCB8IEF1dG9tYXRpYyBJQ0MgY2xvY2sgZnJlcXVlbmN5IGNo YW5nZSBhY2NvcmRpbmcgdG8gYWN0aXZlICAgICAgIHwKK3wgICAgICAgICAgICB8IHBhcmFtZXRl cnMgcHJvdmlkZWQgYnkgdGhlIEhvc3Qgb3Igc2VsZiBkZXRlcm1pbmVkICAgICAgICAgICAgIHwK KystLS0tLS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKK3wgMHgwMDAwMDAyMCB8IEF1dG9tYXRpYyBiYXVkIHJh dGUgY2hhbmdlIGFjY29yZGluZyB0byBhY3RpdmUgICAgICAgICAgICAgICAgIHwKK3wgICAgICAg ICAgICB8IHBhcmFtZXRlcnMgcHJvdmlkZWQgYnkgdGhlIEhvc3Qgb3Igc2VsZiBkZXRlcm1pbmVk ICAgICAgICAgICAgIHwKKystLS0tLS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKK3wgMHgwMDAwMDA0MCB8IEF1 dG9tYXRpYyBwYXJhbWV0ZXJzIG5lZ290aWF0aW9uIG1hZGUgYnkgdGhlIENDSUQgICAgICAgICAg ICAgIHwKKystLS0tLS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKK3wgMHgwMDAwMDA4MCB8IEF1dG9tYXRpYyBQ UFMgbWFkZSBieSB0aGUgQ0NJRCBhY2NvcmRpbmcgdG8gdGhlICAgICAgICAgICAgICAgIHwKK3wg ICAgICAgICAgICB8IGFjdGl2ZSBwYXJhbWV0ZXJzICAgICAgICAgICAgICAgICAgICAgICAgICAg ICAgICAgICAgICAgICAgICAgIHwKKystLS0tLS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKK3wgMHgwMDAwMDEw MCB8IENDSUQgY2FuIHNldCBJQ0MgaW4gY2xvY2sgc3RvcCBtb2RlICAgICAgICAgICAgICAgICAg ICAgICAgICAgIHwKKystLS0tLS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKK3wgMHgwMDAwMDIwMCB8IE5BRCB2 YWx1ZSBvdGhlciB0aGFuIDAwIGFjY2VwdGVkIChUPTEgcHJvdG9jb2wgaW4gdXNlKSAgICAgICAg IHwKKystLS0tLS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKK3wgMHgwMDAwMDQwMCB8IEF1dG9tYXRpYyBJRlNE IGV4Y2hhbmdlIGFzIGZpcnN0IGV4Y2hhbmdlICAgICAgICAgICAgICAgICAgICAgIHwKKystLS0t LS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLSsKKworCitPbmx5IG9uZSBvZiB0aGUgZm9sbG93aW5nIHZhbHVlcyBt YXkgYmUgcHJlc2VudCB0byBzZWxlY3QgYSBsZXZlbCBvZiBleGNoYW5nZToKKworKy0tLS0tLS0t LS0tLSstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsK K3wgVmFsdWUgICAgICB8IERlc2NyaXB0aW9uICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg ICAgICAgICB8CisrPT09PT09PT09PT09Kz09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09 PT09PT09PT09PT09PT09PT09KworfCAweDAwMDEwMDAwIHwgVFBEVSBsZXZlbCBleGNoYW5nZXMg d2l0aCBDQ0lEICAgICAgICAgICAgICAgICAgIHwKKystLS0tLS0tLS0tLS0rLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0rCit8IDB4MDAwMjAwMDAgfCBT aG9ydCBBUERVIGxldmVsIGV4Y2hhbmdlIHdpdGggQ0NJRCAgICAgICAgICAgICAgfAorKy0tLS0t LS0tLS0tLSstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LSsKK3wgMHgwMDA0MDAwMCB8IFNob3J0IGFuZCBFeHRlbmRlZCBBUERVIGxldmVsIGV4Y2hhbmdl IHdpdGggQ0NJRCB8CisrLS0tLS0tLS0tLS0tKy0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tKworCitJZiBub25lIG9mIHRob3NlIHZhbHVlcyBpcyBpbmRp Y2F0ZWQgdGhlIGxldmVsIG9mIGV4Y2hhbmdlIGlzCitjaGFyYWN0ZXIuCisKKworcHJvdG9jb2xz Cit+fn5+fn5+fn5+CitUaGUgYHByb3RvY29sc2AgYXR0cmlidXRlIHdyaXRlcyB0byB0aGUgZHdQ cm90b2NvbHMgZmllbGQgaW4gdGhlIGNsYXNzIGRlc2NyaXB0b3IuCitTZWUgVGFibGUgNS4xLTEg U21hcnQgQ2FyZCBEZXZpY2UgRGVzY3JpcHRvcnMgaW4gdGhlIENDSUQgU3BlY2lmaWNhdGlvbiBb MV1fLgorCitUaGUgdmFsdWUgaXMgYSBiaXR3aXNlIE9SIG9wZXJhdGlvbiBwZXJmb3JtZWQgb24g dGhlIGZvbGxvd2luZyB2YWx1ZXM6CisKKystLS0tLS0tLSstLS0tLS0tLS0tLS0tLSsKK3wgVmFs dWUgIHwgRGVzY3JpcHRpb24gIHwKKys9PT09PT09PSs9PT09PT09PT09PT09PSsKK3wgMHgwMDAx IHwgUHJvdG9jb2wgVD0wIHwKKystLS0tLS0tLSstLS0tLS0tLS0tLS0tLSsKK3wgMHgwMDAyIHwg UHJvdG9jb2wgVD0xIHwKKystLS0tLS0tLSstLS0tLS0tLS0tLS0tLSsKKworSWYgbm8gcHJvdG9j b2wgaXMgc2VsZWN0ZWQgYm90aCBUPTAgYW5kIFQ9MSB3aWxsIGJlIHN1cHBvcnRlZCAoYHByb3Rv Y29sc2AgPSAweDAwMDMpLgorCituc2xvdHMKK35+fn5+fgorCitUaGUgYG5zbG90c2AgYXR0cmli dXRlIHdyaXRlcyB0byB0aGUgYk1heFNsb3RJbmRleCBmaWVsZCBpbiB0aGUgY2xhc3MgZGVzY3Jp cHRvci4KK1NlZSBUYWJsZSA1LjEtMSBTbWFydCBDYXJkIERldmljZSBEZXNjcmlwdG9ycyBpbiB0 aGUgQ0NJRCBTcGVjaWZpY2F0aW9uIFsxXV8uCisKK1RoaXMgaXMgdGhlIGluZGV4IG9mIHRoZSBo aWdoZXN0IGF2YWlsYWJsZSBzbG90IG9uIHRoaXMgZGV2aWNlLiBBbGwgc2xvdHMgYXJlIGNvbnNl Y3V0aXZlIHN0YXJ0aW5nIGF0IDAwaC4KK2kuZS4gMEZoID0gMTYgc2xvdHMgb24gdGhpcyBkZXZp Y2UgbnVtYmVyZWQgMDBoIHRvIDBGaC4KKworVGhlIGRlZmF1bHQgdmFsdWUgaXMgMCwgd2hpY2gg bWVhbnMgb25lIHNsb3QuCisKKworcGluc3VwcG9ydAorfn5+fn5+fn5+fn5+CisKK1RoaXMgdmFs dWUgaW5kaWNhdGVzIHdoYXQgUElOIHN1cHBvcnQgZmVhdHVyZXMgdGhlIENDSUQgaGFzLgorCitU aGUgYHBpbnN1cHBvcnRgIGF0dHJpYnV0ZSB3cml0ZXMgdG8gdGhlIGR3UElOU3VwcG9ydCBmaWVs ZCBpbiB0aGUgY2xhc3MgZGVzY3JpcHRvci4KK1NlZSBUYWJsZSA1LjEtMSBTbWFydCBDYXJkIERl dmljZSBEZXNjcmlwdG9ycyBpbiB0aGUgQ0NJRCBTcGVjaWZpY2F0aW9uIFsxXV8uCisKKworVGhl IHZhbHVlIGlzIGEgYml0d2lzZSBPUiBvcGVyYXRpb24gcGVyZm9ybWVkIG9uIHRoZSBmb2xsb3dp bmcgdmFsdWVzOgorCisrLS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKK3wg VmFsdWUgIHwgRGVzY3JpcHRpb24gICAgICAgICAgICAgICAgfAorKz09PT09PT09Kz09PT09PT09 PT09PT09PT09PT09PT09PT09PT0rCit8IDB4MDAgICB8IE5vIFBJTiBzdXBwb3J0ICAgICAgICAg ICAgIHwKKystLS0tLS0tLSstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tKworfCAweDAxICAg fCBQSU4gVmVyaWZpY2F0aW9uIHN1cHBvcnRlZCB8CisrLS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLSsKK3wgMHgwMiAgIHwgUElOIE1vZGlmaWNhdGlvbiBzdXBwb3J0ZWQgfAor Ky0tLS0tLS0tKy0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0rCisKK1RoZSBkZWZhdWx0IHZh bHVlIGlzIHNldCB0byAweDAwLgorCisKK2xjZGxheW91dAorfn5+fn5+fn5+fgorCitOdW1iZXIg b2YgbGluZXMgYW5kIGNoYXJhY3RlcnMgZm9yIHRoZSBMQ0QgZGlzcGxheSB1c2VkIHRvIHNlbmQg bWVzc2FnZXMgZm9yIFBJTiBlbnRyeS4KKworVGhlIGBsY2RMYXlvdXRgIGF0dHJpYnV0ZSB3cml0 ZXMgdG8gdGhlIHdMY2RMYXlvdXQgZmllbGQgaW4gdGhlIGNsYXNzIGRlc2NyaXB0b3IuCitTZWUg VGFibGUgNS4xLTEgU21hcnQgQ2FyZCBEZXZpY2UgRGVzY3JpcHRvcnMgaW4gdGhlIENDSUQgU3Bl Y2lmaWNhdGlvbiBbMV1fLgorCisKK1RoZSB2YWx1ZSBpcyBzZXQgYXMgZm9sbG93czoKKworKy0t LS0tLS0tKy0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKK3wgVmFsdWUgIHwg RGVzY3JpcHRpb24gICAgICAgICAgICAgICAgICAgICAgICB8CisrPT09PT09PT0rPT09PT09PT09 PT09PT09PT09PT09PT09PT09PT09PT09PT09KworfCAweDAwMDAgfCBObyBMQ0QgICAgICAgICAg ICAgICAgICAgICAgICAgICAgIHwKKystLS0tLS0tLSstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0rCit8IDB4WFhZWSB8IFhYOiBudW1iZXIgb2YgbGluZXMgICAgICAgICAgICAg ICAgfAorfCAgICAgICAgfCBZWTogbnVtYmVyIG9mIGNoYXJhY3RlcnMgcGVyIGxpbmUuIHwKKyst LS0tLS0tLSstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0rCisKK1RoZSBkZWZh dWx0IHZhbHVlIGlzIHNldCB0byAweDAwMDAuCisKKworRXhhbXBsZQorLS0tLS0tLQorCitIZXJl IGlzIGFuIGV4YW1wbGUgb24gaG93IHRvIHNldHVwIGEgQ0NJRCBnYWRnZXQgd2l0aCBjb25maWdm cyA6OgorCisgICAgIyEvYmluL3NoCisKKyAgICBDT05GSUdESVI9L3N5cy9rZXJuZWwvY29uZmln CisgICAgR0FER0VUPSRDT05GSUdESVIvdXNiX2dhZGdldC9nMAorICAgIEZVTkNUSU9OPSRHQURH RVQvZnVuY3Rpb25zL2NjaWQuc2MwCisKKyAgICBWSUQ9WU9VUl9WRU5ET1JfSURfSEVSRQorICAg IFBJRD1ZT1VSX1BST0RVQ1RfSURfSEVSRQorICAgIFVEQz1ZT1VSX1VEQ19IRVJFCisKKyAgICAj TW91bnQgZmlsZXN5c3RlbQorICAgIG1vdW50IG5vbmUgLXQgY29uZmlnZnMgJENPTkZJR0RJUgor CisgICAgI1BvcHVsYXRlIElEOnMKKyAgICBlY2hvICRWSUQgPiAkR0FER0VUL2lkVmVuZG9yCisg ICAgZWNobyAkUElEID4gJEdBREdFVC9pZFByb2R1Y3QKKworICAgICNDcmVhdGUgYW5kIGNvbmZp Z3VyZSB0aGUgZ2FkZ2V0CisgICAgbWtkaXIgJEZVTkNUSU9OCisgICAgZWNobyAweDAwMDQwN0I4 ID4gJEZVTkNUSU9OL2ZlYXR1cmVzCisgICAgZWNobyAweDAyID4gJEZVTkNUSU9OL3Byb3RvY29s cworCisgICAgI0NyZWF0ZSBvdXIgZW5nbGlzaCBzdHJpbmdzCisgICAgbWtkaXIgICRHQURHRVQv c3RyaW5ncy8weDQwOQorICAgIGVjaG8gNTU2Njc3ID4gJEdBREdFVC9zdHJpbmdzLzB4NDA5L3Nl cmlhbG51bWJlcgorICAgIGVjaG8gIkh1bmdyeSBQZW5ndWlucyIgPiAkR0FER0VUL3N0cmluZ3Mv MHg0MDkvbWFudWZhY3R1cmVyCisgICAgZWNobyAiSGFycG9vbiBXaXRoIFNtYXJ0Q2FyZCIgID4g JEdBREdFVC9zdHJpbmdzLzB4NDA5L3Byb2R1Y3QKKworICAgICNDcmVhdGUgY29uZmlndXJhdGlv bgorICAgIG1rZGlyICAkR0FER0VUL2NvbmZpZ3MvYy4xCisgICAgbWtkaXIgICRHQURHRVQvY29u Zmlncy9jLjEvc3RyaW5ncy8weDQwOQorICAgIGVjaG8gQ29uZmlnMSA+ICRHQURHRVQvY29uZmln cy9jLjEvc3RyaW5ncy8weDQwOS9jb25maWd1cmF0aW9uCisKKyAgICAjVXNlIGBDb25maWcxYCBm b3Igb3VyIENDSUQgZ2FkZ2V0CisgICAgbG4gLXMgJEZVTkNUSU9OICRHQURHRVQvY29uZmlncy9j LjEKKworICAgICNFeGVjdXRlCisgICAgZWNobyAkVURDID4gJEdBREdFVC9VREMKKworCitSZWZl cmVuY2VzCis9PT09PT09PT09CisKKy4uIFsxXSBodHRwOi8vd3d3LnVzYi5vcmcvZGV2ZWxvcGVy cy9kb2NzL2RldmNsYXNzX2RvY3MvRFdHX1NtYXJ0LUNhcmRfQ0NJRF9SZXYxMTAucGRmCisuLiBb Ml0gaW5jbHVkZS91YXBpL2xpbnV4L3VzYi9jY2lkLmgK From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1032436AbeEZUfQ (ORCPT ); Sat, 26 May 2018 16:35:16 -0400 Received: from mail-wr0-f196.google.com ([209.85.128.196]:37665 "EHLO mail-wr0-f196.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1032375AbeEZUfM (ORCPT ); Sat, 26 May 2018 16:35:12 -0400 X-Google-Smtp-Source: ADUXVKJ9Iy+CDiCEKfX0EjX/PWWnTej9qoVQZ5Oh0zNoruIqEI3fBpRsyiOTxf1b+62ThVPC/9BIsg== From: Marcus Folkesson To: Greg Kroah-Hartman , Jonathan Corbet , Felipe Balbi , davem@davemloft.net, Mauro Carvalho Chehab , Andrew Morton , Randy Dunlap , Ruslan Bilovol , Thomas Gleixner , Kate Stewart Cc: linux-usb@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Marcus Folkesson Subject: [PATCH 2/3] Documentation: usb: add documentation for USB CCID Gadget Device Date: Sat, 26 May 2018 22:34:00 +0200 Message-Id: <20180526203401.16586-2-marcus.folkesson@gmail.com> X-Mailer: git-send-email 2.16.2 In-Reply-To: <20180526203401.16586-1-marcus.folkesson@gmail.com> References: <20180526203401.16586-1-marcus.folkesson@gmail.com> Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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*. + +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 +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 +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. + +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. + +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]_. +The default value is 0x00000000. + +The value is a bitwise OR operation performed on the following values: + ++------------+----------------------------------------------------------------+ +| Value | Description | ++============+================================================================+ +| 0x00000000 | No special characteristics | ++------------+----------------------------------------------------------------+ +| 0x00000002 | Automatic parameter configuration based on ATR data | ++------------+----------------------------------------------------------------+ +| 0x00000004 | Automatic activation of ICC on inserting | ++------------+----------------------------------------------------------------+ +| 0x00000008 | Automatic ICC voltage selection | ++------------+----------------------------------------------------------------+ +| 0x00000010 | Automatic ICC clock frequency change according to active | +| | parameters provided by the Host or self determined | ++------------+----------------------------------------------------------------+ +| 0x00000020 | Automatic baud rate change according to active | +| | parameters provided by the Host or self determined | ++------------+----------------------------------------------------------------+ +| 0x00000040 | Automatic parameters negotiation made by the CCID | ++------------+----------------------------------------------------------------+ +| 0x00000080 | Automatic PPS made by the CCID according to the | +| | active parameters | ++------------+----------------------------------------------------------------+ +| 0x00000100 | CCID can set ICC in clock stop mode | ++------------+----------------------------------------------------------------+ +| 0x00000200 | NAD value other than 00 accepted (T=1 protocol in use) | ++------------+----------------------------------------------------------------+ +| 0x00000400 | Automatic IFSD exchange as first exchange | ++------------+----------------------------------------------------------------+ + + +Only one of the following values may be present to select a level of exchange: + ++------------+--------------------------------------------------+ +| Value | Description | ++============+==================================================+ +| 0x00010000 | TPDU level exchanges with CCID | ++------------+--------------------------------------------------+ +| 0x00020000 | Short APDU level exchange with CCID | ++------------+--------------------------------------------------+ +| 0x00040000 | Short and Extended APDU level exchange with CCID | ++------------+--------------------------------------------------+ + +If none of those values is indicated the level of exchange is +character. + + +protocols +~~~~~~~~~~ +The `protocols` attribute writes to the dwProtocols field in the class descriptor. +See Table 5.1-1 Smart Card Device Descriptors in the CCID Specification [1]_. + +The value is a bitwise OR operation performed on the following values: + ++--------+--------------+ +| Value | Description | ++========+==============+ +| 0x0001 | Protocol T=0 | ++--------+--------------+ +| 0x0002 | Protocol T=1 | ++--------+--------------+ + +If no protocol is selected both T=0 and T=1 will be supported (`protocols` = 0x0003). + +nslots +~~~~~~ + +The `nslots` attribute writes to the bMaxSlotIndex field in the class descriptor. +See Table 5.1-1 Smart Card Device Descriptors in the CCID Specification [1]_. + +This is the index of the highest available slot on this device. All slots are consecutive starting at 00h. +i.e. 0Fh = 16 slots on this device numbered 00h to 0Fh. + +The default value is 0, which means one slot. + + +pinsupport +~~~~~~~~~~~~ + +This value indicates what PIN support features the CCID has. + +The `pinsupport` attribute writes to the dwPINSupport field in the class descriptor. +See Table 5.1-1 Smart Card Device Descriptors in the CCID Specification [1]_. + + +The value is a bitwise OR operation performed on the following values: + ++--------+----------------------------+ +| Value | Description | ++========+============================+ +| 0x00 | No PIN support | ++--------+----------------------------+ +| 0x01 | PIN Verification supported | ++--------+----------------------------+ +| 0x02 | PIN Modification supported | ++--------+----------------------------+ + +The default value is set to 0x00. + + +lcdlayout +~~~~~~~~~~ + +Number of lines and characters for the LCD display used to send messages for PIN entry. + +The `lcdLayout` attribute writes to the wLcdLayout field in the class descriptor. +See Table 5.1-1 Smart Card Device Descriptors in the CCID Specification [1]_. + + +The value is set as follows: + ++--------+------------------------------------+ +| Value | Description | ++========+====================================+ +| 0x0000 | No LCD | ++--------+------------------------------------+ +| 0xXXYY | XX: number of lines | +| | YY: number of characters per line. | ++--------+------------------------------------+ + +The default value is set to 0x0000. + + +Example +------- + +Here is an example on how to setup a CCID gadget with configfs :: + + #!/bin/sh + + CONFIGDIR=/sys/kernel/config + GADGET=$CONFIGDIR/usb_gadget/g0 + FUNCTION=$GADGET/functions/ccid.sc0 + + VID=YOUR_VENDOR_ID_HERE + PID=YOUR_PRODUCT_ID_HERE + UDC=YOUR_UDC_HERE + + #Mount filesystem + mount none -t configfs $CONFIGDIR + + #Populate ID:s + echo $VID > $GADGET/idVendor + echo $PID > $GADGET/idProduct + + #Create and configure the gadget + mkdir $FUNCTION + echo 0x000407B8 > $FUNCTION/features + echo 0x02 > $FUNCTION/protocols + + #Create our english strings + mkdir $GADGET/strings/0x409 + echo 556677 > $GADGET/strings/0x409/serialnumber + echo "Hungry Penguins" > $GADGET/strings/0x409/manufacturer + echo "Harpoon With SmartCard" > $GADGET/strings/0x409/product + + #Create configuration + mkdir $GADGET/configs/c.1 + mkdir $GADGET/configs/c.1/strings/0x409 + echo Config1 > $GADGET/configs/c.1/strings/0x409/configuration + + #Use `Config1` for our CCID gadget + ln -s $FUNCTION $GADGET/configs/c.1 + + #Execute + echo $UDC > $GADGET/UDC + + +References +========== + +.. [1] http://www.usb.org/developers/docs/devclass_docs/DWG_Smart-Card_CCID_Rev110.pdf +.. [2] include/uapi/linux/usb/ccid.h -- 2.16.2