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=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 8FA407DF8A for ; Tue, 26 Jun 2018 08:14:54 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752828AbeFZIOw (ORCPT ); Tue, 26 Jun 2018 04:14:52 -0400 Received: from mail-lf0-f68.google.com ([209.85.215.68]:36485 "EHLO mail-lf0-f68.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752669AbeFZIOm (ORCPT ); Tue, 26 Jun 2018 04:14:42 -0400 Received: by mail-lf0-f68.google.com with SMTP id n24-v6so16671129lfh.3; Tue, 26 Jun 2018 01:14:41 -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=sXg7Ly2hHNzrjG5wNU8iGTxdYK3Jbxx11AygjgUXt8Q=; b=WxONe6fSNL2QHiTFVxgce2YWb1QWVYEZZUH/YAoC0pjPJMicdjdm0w1cGSsbxxG7Xg KCE38hrwUSWFMs6mTf0yegrNzrdLvy2MbLDBxVNjmKbwHefIzBSkxTC56I3ycrvy6Mw9 uf7GVw7wZNuJPlnM2XjaAJtipFLRsPQg9naSy210cUt7CxRzmU8ZPLhkikHrBcKyHunb jo8ALOE5WXObqs4T7OZb20PTh0bztgdHN5+IHRSKSVm8wrWil2SHVlaC2SljObms1PdV Ffy8qDqFdct72IsLpvVLIH705dl6AGYDJBSzjgUaBxwOaqlugcC6wg+decrLh/4Zg9qn TJAw== 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=sXg7Ly2hHNzrjG5wNU8iGTxdYK3Jbxx11AygjgUXt8Q=; b=UWZxZFy8nJZy9t9vaBrPniECe4jz/eKo8+19DLNOXNCTFYai604U4ScLH0yC0g3lKW m/K3MhKsxLClVKs2IZQFzuJ1viLV37X9LEe3vrYyH0sXFk8/JlOqoDLs9GmDa+xGyaqI dDqfAXk6d0Bj5hX3/deml5tPXkmtq/0qHXRpfFT7HeLX0bGbux2I6qKPMTpiyGN52q2g dKAjCGyS713mg65M7hDkjCuwHO/y0hVUr2ZXHnfmT/2GE08LW8/KbivRC8TPw8A7FpeH R6uSjPinnDLmWOOyR1SQ2qf6tkrQ/Np+zNoTHXMlHyfdhRwrOaMATP+7IXJn9ah8F8YZ tRSw== X-Gm-Message-State: APt69E2a2vExzErV2S/QgwF8qkpxFpkk12zg1gNVe8QH2+ro2YBTiEJ6 7aat02JvWREgmD98MpYrReZS4raD X-Google-Smtp-Source: AAOMgpecrbBmmf3HU09l+jPeodNEKHWpiK4lt0na4At8d6Fltjz/vyqWDDtin6/5nErhMVa3n06l/g== X-Received: by 2002:a19:cb12:: with SMTP id b18-v6mr455907lfg.64.1530000880743; Tue, 26 Jun 2018 01:14:40 -0700 (PDT) Received: from localhost.localdomain (c-2ec26030-74736162.cust.telenor.se. [46.194.96.48]) by smtp.gmail.com with ESMTPSA id p28-v6sm149783lja.13.2018.06.26.01.14.38 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 26 Jun 2018 01:14:39 -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 v4 2/3] Documentation: usb: add documentation for USB CCID Gadget Device Date: Tue, 26 Jun 2018 10:14:21 +0200 Message-Id: <20180626081422.19237-2-marcus.folkesson@gmail.com> X-Mailer: git-send-email 2.18.0 In-Reply-To: <20180626081422.19237-1-marcus.folkesson@gmail.com> References: <20180626081422.19237-1-marcus.folkesson@gmail.com> Sender: linux-doc-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-doc@vger.kernel.org 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. Reviewed-by: Randy Dunlap Signed-off-by: Marcus Folkesson --- Notes: v4: - clarify how to use /dev/ccidg and BULK endpoind (thanks Randy) v3: - correct the grammer (thanks Randy) v2: - add the missing changelog text Documentation/usb/gadget_ccid.rst | 269 ++++++++++++++++++++++++++++++ 1 file changed, 269 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..c8f25080c9e7 --- /dev/null +++ b/Documentation/usb/gadget_ccid.rst @@ -0,0 +1,269 @@ +.. 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 are exposed to userspace via /dev/ccidgX where `X` is +the device enumeration number. +Use read(2) and write(3) to operate on BULK_IN and BULK_OUT respectively. + +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-byte 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 specify which slot 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 file descriptor 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 are 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 defined 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 Smart Card" > $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.18.0 -- 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: [v4,2/3] Documentation: usb: add documentation for USB CCID Gadget Device From: Marcus Folkesson Message-Id: <20180626081422.19237-2-marcus.folkesson@gmail.com> Date: Tue, 26 Jun 2018 10:14:21 +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: QWRkIGRvY3VtZW50YXRpb24gdG8gZ2l2ZSBhIGJyaWVmIGRlc2NyaXB0aW9uIG9uIGhvdyB0byB1 c2UgdGhlCkNDSUQgR2FkZ2V0IERldmljZS4KVGhpcyBpbmNsdWRlcyBhIGRlc2NyaXB0aW9uIGZv ciBhbGwgYXR0cmlidXRlcyBmb2xsb3dlZCBieSBhbiBleGFtcGxlIG9uCmhvdyB0byBzZXR1cCB0 aGUgZGV2aWNlIHdpdGggQ29uZmlnRlMuCgpSZXZpZXdlZC1ieTogUmFuZHkgRHVubGFwIDxyZHVu bGFwQGluZnJhZGVhZC5vcmc+ClNpZ25lZC1vZmYtYnk6IE1hcmN1cyBGb2xrZXNzb24gPG1hcmN1 cy5mb2xrZXNzb25AZ21haWwuY29tPgotLS0KCk5vdGVzOgogICAgdjQ6CiAgICAJLSBjbGFyaWZ5 IGhvdyB0byB1c2UgL2Rldi9jY2lkZyBhbmQgQlVMSyBlbmRwb2luZCAodGhhbmtzIFJhbmR5KQog ICAgdjM6CiAgICAJLSBjb3JyZWN0IHRoZSBncmFtbWVyICh0aGFua3MgUmFuZHkpCiAgICB2MjoK ICAgIAktIGFkZCB0aGUgbWlzc2luZyBjaGFuZ2Vsb2cgdGV4dAoKIERvY3VtZW50YXRpb24vdXNi L2dhZGdldF9jY2lkLnJzdCB8IDI2OSArKysrKysrKysrKysrKysrKysrKysrKysrKysrKysKIDEg ZmlsZSBjaGFuZ2VkLCAyNjkgaW5zZXJ0aW9ucygrKQogY3JlYXRlIG1vZGUgMTAwNjQ0IERvY3Vt ZW50YXRpb24vdXNiL2dhZGdldF9jY2lkLnJzdAoKZGlmZiAtLWdpdCBhL0RvY3VtZW50YXRpb24v dXNiL2dhZGdldF9jY2lkLnJzdCBiL0RvY3VtZW50YXRpb24vdXNiL2dhZGdldF9jY2lkLnJzdApu ZXcgZmlsZSBtb2RlIDEwMDY0NAppbmRleCAwMDAwMDAwMDAwMDAuLmM4ZjI1MDgwYzllNwotLS0g L2Rldi9udWxsCisrKyBiL0RvY3VtZW50YXRpb24vdXNiL2dhZGdldF9jY2lkLnJzdApAQCAtMCww ICsxLDI2OSBAQAorLi4gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEdQTC0yLjAKKworPT09PT09 PT09PT09CitDQ0lEIEdhZGdldAorPT09PT09PT09PT09CisKKzpBdXRob3I6IE1hcmN1cyBGb2xr ZXNzb24gPG1hcmN1cy5mb2xrZXNzb25AZ21haWwuY29tPgorCitJbnRyb2R1Y3Rpb24KKz09PT09 PT09PT09PQorCitUaGUgQ0NJRCBHYWRnZXQgd2lsbCBwcmVzZW50IGl0c2VsZiBhcyBhIENDSUQg ZGV2aWNlIHRvIHRoZSBob3N0IHN5c3RlbS4KK1RoZSBkZXZpY2Ugc3VwcG9ydHMgdHdvIGVuZHBv aW50cyBmb3Igbm93OyBCVUxLIElOIGFuZCBCVUxLIE9VVC4KK1RoZXNlIGVuZHBvaW50cyBhcmUg ZXhwb3NlZCB0byB1c2Vyc3BhY2UgdmlhIC9kZXYvY2NpZGdYIHdoZXJlIGBYYCBpcwordGhlIGRl dmljZSBlbnVtZXJhdGlvbiBudW1iZXIuCitVc2UgcmVhZCgyKSBhbmQgd3JpdGUoMykgdG8gb3Bl cmF0ZSBvbiBCVUxLX0lOIGFuZCBCVUxLX09VVCByZXNwZWN0aXZlbHkuCisKK0FsbCBDQ0lEIGNv bW1hbmRzIGFyZSBzZW50IG9uIHRoZSBCVUxLLU9VVCBlbmRwb2ludC4gRWFjaCBjb21tYW5kIHNl bnQgdG8gdGhlIENDSUQKK2hhcyBhbiBhc3NvY2lhdGVkIGVuZGluZyByZXNwb25zZS4gU29tZSBj b21tYW5kcyBjYW4gYWxzbyBoYXZlIGludGVybWVkaWF0ZQorcmVzcG9uc2VzLiBUaGUgcmVzcG9u c2UgaXMgc2VudCBvbiB0aGUgQlVMSy1JTiBlbmRwb2ludC4KK1NlZSBGaWd1cmUgMy0zIGluIHRo ZSBDQ0lEIFNwZWNpZmljYXRpb24gWzFdXyBmb3IgbW9yZSBkZXRhaWxzLgorCitUaGUgQ0NJRCBj b21tYW5kcyBtdXN0IGJlIGhhbmRsZWQgaW4gdXNlcnNwYWNlIHNpbmNlIHRoZSBkcml2ZXIgaXMg b25seSB3b3JraW5nCithcyBhIHRyYW5zcG9ydCBsYXllciBmb3IgdGhlIFRQRFVzLgorCisKK0ND SUQgQ29tbWFuZHMKKy0tLS0tLS0tLS0tLS0tCisKK0FsbCBDQ0lEIGNvbW1hbmRzIGJlZ2lucyB3 aXRoIGEgMTAtYnl0ZSBoZWFkZXIgZm9sbG93ZWQgYnkgYW4gb3B0aW9uYWwKK2RhdGEgZmllbGQg ZGVwZW5kaW5nIG9uIG1lc3NhZ2UgdHlwZS4KKworKy0tLS0tLS0tKy0tLS0tLS0tLS0tLS0tKy0t LS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKK3wgT2Zmc2V0IHwgRmll bGQgICAgICAgIHwgU2l6ZSAgfCBEZXNjcmlwdGlvbiAgICAgICAgICAgICAgICAgICAgICB8Cisr PT09PT09PT0rPT09PT09PT09PT09PT0rPT09PT09PSs9PT09PT09PT09PT09PT09PT09PT09PT09 PT09PT09PT09KworfCAwICAgICAgfCBiTWVzc2FnZVR5cGUgfCAxICAgICB8IFR5cGUgb2YgbWVz c2FnZSAgICAgICAgICAgICAgICAgIHwKKystLS0tLS0tLSstLS0tLS0tLS0tLS0tLSstLS0tLS0t Ky0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0rCit8IDEgICAgICB8IGR3TGVuZ3Ro ICAgICB8IDQgICAgIHwgTWVzc2FnZSBzcGVjaWZpYyBkYXRhIGxlbmd0aCAgICAgfAorfCAgICAg ICAgfCAgICAgICAgICAgICAgfCAgICAgICB8ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg ICAgIHwKKystLS0tLS0tLSstLS0tLS0tLS0tLS0tLSstLS0tLS0tKy0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0rCit8IDUgICAgICB8IGJTbG90ICAgICAgICB8IDEgICAgIHwgSWRl bnRpZmllcyB0aGUgc2xvdCBudW1iZXIgICAgICAgfAorfCAgICAgICAgfCAgICAgICAgICAgICAg fCAgICAgICB8IGZvciB0aGlzIGNvbW1hbmQgICAgICAgICAgICAgICAgIHwKKystLS0tLS0tLSst LS0tLS0tLS0tLS0tLSstLS0tLS0tKy0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0r Cit8IDYgICAgICB8IGJTZXEgICAgICAgICB8IDEgICAgIHwgU2VxdWVuY2UgbnVtYmVyIGZvciBj b21tYW5kICAgICAgfAorKy0tLS0tLS0tKy0tLS0tLS0tLS0tLS0tKy0tLS0tLS0rLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKK3wgNyAgICAgIHwgLi4uICAgICAgICAgIHwgMyAg ICAgfCBGaWVsZHMgZGVwZW5kcyBvbiBtZXNzYWdlIHR5cGUgICB8CisrLS0tLS0tLS0rLS0tLS0t LS0tLS0tLS0rLS0tLS0tLSstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tKworfCAx MCAgICAgfCBhYkRhdGEgICAgICAgfCBhcnJheSB8IE1lc3NhZ2Ugc3BlY2lmaWMgZGF0YSAoT1BU SU9OQUwpIHwKKystLS0tLS0tLSstLS0tLS0tLS0tLS0tLSstLS0tLS0tKy0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0rCisKKworTXVsdGlwbGUgQ0NJRCBnYWRnZXRzCistLS0tLS0t LS0tLS0tLS0tLS0tLS0tCisKK0l0IGlzIHBvc3NpYmxlIHRvIGNyZWF0ZSBtdWx0aXBsZSBpbnN0 YW5jZXMgb2YgdGhlIENDSUQgZ2FkZ2V0LCBob3dldmVyLAorYSBtdWNoIG1vcmUgZmxleGlibGUg d2F5IGlzIHRvIGNyZWF0ZSBvbmUgZ2FkZ2V0IGFuZCBzZXQgdGhlIGBuc2xvdHNgIGF0dHJpYnV0 ZQordG8gdGhlIG51bWJlciBvZiBkZXNpcmVkIENDSUQgZGV2aWNlcy4KKworQWxsIENDSUQgY29t bWFuZHMgc3BlY2lmeSB3aGljaCBzbG90IGlzIHRoZSByZWNlaXZlciBpbiB0aGUgYGJTbG90YCBm aWVsZAorb2YgdGhlIENDSUQgaGVhZGVyLgorCitVc2FnZQorPT09PT0KKworQWNjZXNzIGZyb20g dXNlcnNwYWNlCistLS0tLS0tLS0tLS0tLS0tLS0tLS0tCitBbGwgY29tbXVuaWNhdGlvbiBpcyBi eSByZWFkKDIpIGFuZCB3cml0ZSgyKSB0byB0aGUgY29ycmVzcG9uZGluZyAvZGV2L2NjaWRnKiBk ZXZpY2UuCitPbmx5IG9uZSBmaWxlIGRlc2NyaXB0b3IgaXMgYWxsb3dlZCB0byBiZSBvcGVuIHRv IHRoZSBkZXZpY2UgYXQgYSB0aW1lLgorCitUaGUgYnVmZmVyIHNpemUgcHJvdmlkZWQgdG8gcmVh ZCgyKSAqKm11c3QgYmUgYXQgbGVhc3QqKiA1MjIgKDEwIGJ5dGVzIGhlYWRlciArIDUxMiBieXRl cyBwYXlsb2FkKQorYnl0ZXMgYXMgd2UgYXJlIHdvcmtpbmcgd2l0aCB3aG9sZSBjb21tYW5kcy4K KworVGhlIGJ1ZmZlciBzaXplIHByb3ZpZGVkIHRvIHdyaXRlKDIpICoqbWF5IG5vdCBleGNlZWQq KiA1MjIgKDEwIGJ5dGVzIGhlYWRlciArIDUxMiBieXRlcyBwYXlsb2FkKQorYnl0ZXMgYXMgd2Ug YXJlIHdvcmtpbmcgd2l0aCB3aG9sZSBjb21tYW5kcy4KKworCitDb25maWd1cmF0aW9uIHdpdGgg Y29uZmlnZnMKKy0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0KKworQ29uZmlnRlMgaXMgdXNl ZCB0byBjcmVhdGUgYW5kIGNvbmZpZ3VyZSB0aGUgQ0NJRCBnYWRnZXQuCitJbiBvcmRlciB0byBn ZXQgYSBkZXZpY2UgdG8gd29yayBhcyBpbnRlbmRlZCwgYSBmZXcgYXR0cmlidXRlcyBtdXN0Citi ZSBjb25zaWRlcmVkLgorCitUaGUgYXR0cmlidXRlcyBhcmUgZGVzY3JpYmVkIGJlbG93IGZvbGxv d2VkIGJ5IGFuIGV4YW1wbGUuCisKK2ZlYXR1cmVzCit+fn5+fn5+fn4KKworVGhlIGBmZWF0dXJl YCBhdHRyaWJ1dGUgd3JpdGVzIHRvIHRoZSBkd0ZlYXR1cmVzIGZpZWxkIGluIHRoZSBjbGFzcyBk ZXNjcmlwdG9yLgorU2VlIFRhYmxlIDUuMS0xIFNtYXJ0IENhcmQgRGV2aWNlIERlc2NyaXB0b3Jz IGluIHRoZSBDQ0lEIFNwZWNpZmljYXRpb24gWzFdXy4KKworVGhlIHZhbHVlIGluZGljYXRlcyB3 aGF0IGludGVsbGlnZW50IGZlYXR1cmVzIHRoZSBDQ0lEIGhhcy4KK1RoZXNlIHZhbHVlcyBhcmUg YXZhaWxhYmxlIHRvIHVzZXIgYXBwbGljYXRpb24gYXMgZGVmaW5lZCBpbiBjY2lkLmggWzJdXy4K K1RoZSBkZWZhdWx0IHZhbHVlIGlzIDB4MDAwMDAwMDAuCisKK1RoZSB2YWx1ZSBpcyBhIGJpdHdp c2UgT1Igb3BlcmF0aW9uIHBlcmZvcm1lZCBvbiB0aGUgZm9sbG93aW5nIHZhbHVlczoKKworKy0t LS0tLS0tLS0tLSstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tKworfCBWYWx1ZSAgICAgIHwgRGVzY3JpcHRpb24gICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgfAorKz09PT09PT09PT09 PSs9PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09 PT09PT09PT09KworfCAweDAwMDAwMDAwIHwgTm8gc3BlY2lhbCBjaGFyYWN0ZXJpc3RpY3MgICAg ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgfAorKy0tLS0tLS0tLS0tLSstLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t KworfCAweDAwMDAwMDAyIHwgQXV0b21hdGljIHBhcmFtZXRlciBjb25maWd1cmF0aW9uIGJhc2Vk IG9uIEFUUiBkYXRhICAgICAgICAgICAgfAorKy0tLS0tLS0tLS0tLSstLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tKworfCAweDAw MDAwMDA0IHwgQXV0b21hdGljIGFjdGl2YXRpb24gb2YgSUNDIG9uIGluc2VydGluZyAgICAgICAg ICAgICAgICAgICAgICAgfAorKy0tLS0tLS0tLS0tLSstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tKworfCAweDAwMDAwMDA4IHwg QXV0b21hdGljIElDQyB2b2x0YWdlIHNlbGVjdGlvbiAgICAgICAgICAgICAgICAgICAgICAgICAg ICAgICAgfAorKy0tLS0tLS0tLS0tLSstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tKworfCAweDAwMDAwMDEwIHwgQXV0b21hdGlj IElDQyBjbG9jayBmcmVxdWVuY3kgY2hhbmdlIGFjY29yZGluZyB0byBhY3RpdmUgICAgICAgfAor fCAgICAgICAgICAgIHwgcGFyYW1ldGVycyBwcm92aWRlZCBieSB0aGUgSG9zdCBvciBzZWxmIGRl dGVybWluZWQgICAgICAgICAgICAgfAorKy0tLS0tLS0tLS0tLSstLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tKworfCAweDAwMDAw MDIwIHwgQXV0b21hdGljIGJhdWQgcmF0ZSBjaGFuZ2UgYWNjb3JkaW5nIHRvIGFjdGl2ZSAgICAg ICAgICAgICAgICAgfAorfCAgICAgICAgICAgIHwgcGFyYW1ldGVycyBwcm92aWRlZCBieSB0aGUg SG9zdCBvciBzZWxmIGRldGVybWluZWQgICAgICAgICAgICAgfAorKy0tLS0tLS0tLS0tLSstLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tKworfCAweDAwMDAwMDQwIHwgQXV0b21hdGljIHBhcmFtZXRlcnMgbmVnb3RpYXRpb24gbWFk ZSBieSB0aGUgQ0NJRCAgICAgICAgICAgICAgfAorKy0tLS0tLS0tLS0tLSstLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tKworfCAw eDAwMDAwMDgwIHwgQXV0b21hdGljIFBQUyBtYWRlIGJ5IHRoZSBDQ0lEIGFjY29yZGluZyB0byB0 aGUgICAgICAgICAgICAgICAgfAorfCAgICAgICAgICAgIHwgYWN0aXZlIHBhcmFtZXRlcnMgICAg ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgfAorKy0tLS0tLS0tLS0t LSstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tKworfCAweDAwMDAwMTAwIHwgQ0NJRCBjYW4gc2V0IElDQyBpbiBjbG9jayBzdG9w IG1vZGUgICAgICAgICAgICAgICAgICAgICAgICAgICAgfAorKy0tLS0tLS0tLS0tLSstLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t KworfCAweDAwMDAwMjAwIHwgTkFEIHZhbHVlIG90aGVyIHRoYW4gMDAgYWNjZXB0ZWQgKFQ9MSBw cm90b2NvbCBpbiB1c2UpICAgICAgICAgfAorKy0tLS0tLS0tLS0tLSstLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tKworfCAweDAw MDAwNDAwIHwgQXV0b21hdGljIElGU0QgZXhjaGFuZ2UgYXMgZmlyc3QgZXhjaGFuZ2UgICAgICAg ICAgICAgICAgICAgICAgfAorKy0tLS0tLS0tLS0tLSstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tKworCisKK09ubHkgb25lIG9m IHRoZSBmb2xsb3dpbmcgdmFsdWVzIG1heSBiZSBwcmVzZW50IHRvIHNlbGVjdCBhIGxldmVsIG9m IGV4Y2hhbmdlOgorCisrLS0tLS0tLS0tLS0tKy0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tKworfCBWYWx1ZSAgICAgIHwgRGVzY3JpcHRpb24gICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIHwKKys9PT09PT09PT09PT0rPT09PT09PT09 PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT0rCit8IDB4MDAwMTAwMDAg fCBUUERVIGxldmVsIGV4Y2hhbmdlcyB3aXRoIENDSUQgICAgICAgICAgICAgICAgICAgfAorKy0t LS0tLS0tLS0tLSstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLSsKK3wgMHgwMDAyMDAwMCB8IFNob3J0IEFQRFUgbGV2ZWwgZXhjaGFuZ2Ugd2l0aCBDQ0lE ICAgICAgICAgICAgICB8CisrLS0tLS0tLS0tLS0tKy0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tKworfCAweDAwMDQwMDAwIHwgU2hvcnQgYW5kIEV4dGVu ZGVkIEFQRFUgbGV2ZWwgZXhjaGFuZ2Ugd2l0aCBDQ0lEIHwKKystLS0tLS0tLS0tLS0rLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0rCisKK0lmIG5vbmUg b2YgdGhvc2UgdmFsdWVzIGlzIGluZGljYXRlZCB0aGUgbGV2ZWwgb2YgZXhjaGFuZ2UgaXMKK2No YXJhY3Rlci4KKworCitwcm90b2NvbHMKK35+fn5+fn5+fn4KK1RoZSBgcHJvdG9jb2xzYCBhdHRy aWJ1dGUgd3JpdGVzIHRvIHRoZSBkd1Byb3RvY29scyBmaWVsZCBpbiB0aGUgY2xhc3MgZGVzY3Jp cHRvci4KK1NlZSBUYWJsZSA1LjEtMSBTbWFydCBDYXJkIERldmljZSBEZXNjcmlwdG9ycyBpbiB0 aGUgQ0NJRCBTcGVjaWZpY2F0aW9uIFsxXV8uCisKK1RoZSB2YWx1ZSBpcyBhIGJpdHdpc2UgT1Ig b3BlcmF0aW9uIHBlcmZvcm1lZCBvbiB0aGUgZm9sbG93aW5nIHZhbHVlczoKKworKy0tLS0tLS0t Ky0tLS0tLS0tLS0tLS0tKworfCBWYWx1ZSAgfCBEZXNjcmlwdGlvbiAgfAorKz09PT09PT09Kz09 PT09PT09PT09PT09KworfCAweDAwMDEgfCBQcm90b2NvbCBUPTAgfAorKy0tLS0tLS0tKy0tLS0t LS0tLS0tLS0tKworfCAweDAwMDIgfCBQcm90b2NvbCBUPTEgfAorKy0tLS0tLS0tKy0tLS0tLS0t LS0tLS0tKworCitJZiBubyBwcm90b2NvbCBpcyBzZWxlY3RlZCBib3RoIFQ9MCBhbmQgVD0xIHdp bGwgYmUgc3VwcG9ydGVkIChgcHJvdG9jb2xzYCA9IDB4MDAwMykuCisKK25zbG90cworfn5+fn5+ CisKK1RoZSBgbnNsb3RzYCBhdHRyaWJ1dGUgd3JpdGVzIHRvIHRoZSBiTWF4U2xvdEluZGV4IGZp ZWxkIGluIHRoZSBjbGFzcyBkZXNjcmlwdG9yLgorU2VlIFRhYmxlIDUuMS0xIFNtYXJ0IENhcmQg RGV2aWNlIERlc2NyaXB0b3JzIGluIHRoZSBDQ0lEIFNwZWNpZmljYXRpb24gWzFdXy4KKworVGhp cyBpcyB0aGUgaW5kZXggb2YgdGhlIGhpZ2hlc3QgYXZhaWxhYmxlIHNsb3Qgb24gdGhpcyBkZXZp Y2UuIEFsbCBzbG90cyBhcmUgY29uc2VjdXRpdmUgc3RhcnRpbmcgYXQgMDBoLgoraS5lLiAwRmgg PSAxNiBzbG90cyBvbiB0aGlzIGRldmljZSBudW1iZXJlZCAwMGggdG8gMEZoLgorCitUaGUgZGVm YXVsdCB2YWx1ZSBpcyAwLCB3aGljaCBtZWFucyBvbmUgc2xvdC4KKworCitwaW5zdXBwb3J0Cit+ fn5+fn5+fn5+fn4KKworVGhpcyB2YWx1ZSBpbmRpY2F0ZXMgd2hhdCBQSU4gc3VwcG9ydCBmZWF0 dXJlcyB0aGUgQ0NJRCBoYXMuCisKK1RoZSBgcGluc3VwcG9ydGAgYXR0cmlidXRlIHdyaXRlcyB0 byB0aGUgZHdQSU5TdXBwb3J0IGZpZWxkIGluIHRoZSBjbGFzcyBkZXNjcmlwdG9yLgorU2VlIFRh YmxlIDUuMS0xIFNtYXJ0IENhcmQgRGV2aWNlIERlc2NyaXB0b3JzIGluIHRoZSBDQ0lEIFNwZWNp ZmljYXRpb24gWzFdXy4KKworCitUaGUgdmFsdWUgaXMgYSBiaXR3aXNlIE9SIG9wZXJhdGlvbiBw ZXJmb3JtZWQgb24gdGhlIGZvbGxvd2luZyB2YWx1ZXM6CisKKystLS0tLS0tLSstLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tKworfCBWYWx1ZSAgfCBEZXNjcmlwdGlvbiAgICAgICAgICAgICAg ICB8CisrPT09PT09PT0rPT09PT09PT09PT09PT09PT09PT09PT09PT09PSsKK3wgMHgwMCAgIHwg Tm8gUElOIHN1cHBvcnQgICAgICAgICAgICAgfAorKy0tLS0tLS0tKy0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0rCit8IDB4MDEgICB8IFBJTiBWZXJpZmljYXRpb24gc3VwcG9ydGVkIHwKKyst LS0tLS0tLSstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tKworfCAweDAyICAgfCBQSU4gTW9k aWZpY2F0aW9uIHN1cHBvcnRlZCB8CisrLS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLSsKKworVGhlIGRlZmF1bHQgdmFsdWUgaXMgc2V0IHRvIDB4MDAuCisKKworbGNkbGF5b3V0 Cit+fn5+fn5+fn5+CisKK051bWJlciBvZiBsaW5lcyBhbmQgY2hhcmFjdGVycyBmb3IgdGhlIExD RCBkaXNwbGF5IHVzZWQgdG8gc2VuZCBtZXNzYWdlcyBmb3IgUElOIGVudHJ5LgorCitUaGUgYGxj ZExheW91dGAgYXR0cmlidXRlIHdyaXRlcyB0byB0aGUgd0xjZExheW91dCBmaWVsZCBpbiB0aGUg Y2xhc3MgZGVzY3JpcHRvci4KK1NlZSBUYWJsZSA1LjEtMSBTbWFydCBDYXJkIERldmljZSBEZXNj cmlwdG9ycyBpbiB0aGUgQ0NJRCBTcGVjaWZpY2F0aW9uIFsxXV8uCisKKworVGhlIHZhbHVlIGlz IHNldCBhcyBmb2xsb3dzOgorCisrLS0tLS0tLS0rLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tKworfCBWYWx1ZSAgfCBEZXNjcmlwdGlvbiAgICAgICAgICAgICAgICAgICAgICAg IHwKKys9PT09PT09PSs9PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT0rCit8IDB4 MDAwMCB8IE5vIExDRCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgfAorKy0tLS0tLS0tKy0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLSsKK3wgMHhYWFlZIHwgWFg6IG51bWJl ciBvZiBsaW5lcyAgICAgICAgICAgICAgICB8Cit8ICAgICAgICB8IFlZOiBudW1iZXIgb2YgY2hh cmFjdGVycyBwZXIgbGluZS4gfAorKy0tLS0tLS0tKy0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLSsKKworVGhlIGRlZmF1bHQgdmFsdWUgaXMgc2V0IHRvIDB4MDAwMC4KKworCitF eGFtcGxlCistLS0tLS0tCisKK0hlcmUgaXMgYW4gZXhhbXBsZSBvbiBob3cgdG8gc2V0dXAgYSBD Q0lEIGdhZGdldCB3aXRoIGNvbmZpZ2ZzIDo6CisKKyAgICAjIS9iaW4vc2gKKworICAgIENPTkZJ R0RJUj0vc3lzL2tlcm5lbC9jb25maWcKKyAgICBHQURHRVQ9JENPTkZJR0RJUi91c2JfZ2FkZ2V0 L2cwCisgICAgRlVOQ1RJT049JEdBREdFVC9mdW5jdGlvbnMvY2NpZC5zYzAKKworICAgIFZJRD1Z T1VSX1ZFTkRPUl9JRF9IRVJFCisgICAgUElEPVlPVVJfUFJPRFVDVF9JRF9IRVJFCisgICAgVURD PVlPVVJfVURDX0hFUkUKKworICAgICNNb3VudCBmaWxlc3lzdGVtCisgICAgbW91bnQgbm9uZSAt dCBjb25maWdmcyAkQ09ORklHRElSCisKKyAgICAjUG9wdWxhdGUgSUQ6cworICAgIGVjaG8gJFZJ RCA+ICRHQURHRVQvaWRWZW5kb3IKKyAgICBlY2hvICRQSUQgPiAkR0FER0VUL2lkUHJvZHVjdAor CisgICAgI0NyZWF0ZSBhbmQgY29uZmlndXJlIHRoZSBnYWRnZXQKKyAgICBta2RpciAkRlVOQ1RJ T04KKyAgICBlY2hvIDB4MDAwNDA3QjggPiAkRlVOQ1RJT04vZmVhdHVyZXMKKyAgICBlY2hvIDB4 MDIgPiAkRlVOQ1RJT04vcHJvdG9jb2xzCisKKyAgICAjQ3JlYXRlIG91ciBFbmdsaXNoIHN0cmlu Z3MKKyAgICBta2RpciAgJEdBREdFVC9zdHJpbmdzLzB4NDA5CisgICAgZWNobyA1NTY2NzcgPiAk R0FER0VUL3N0cmluZ3MvMHg0MDkvc2VyaWFsbnVtYmVyCisgICAgZWNobyAiSHVuZ3J5IFBlbmd1 aW5zIiA+ICRHQURHRVQvc3RyaW5ncy8weDQwOS9tYW51ZmFjdHVyZXIKKyAgICBlY2hvICJIYXJw b29uIFdpdGggU21hcnQgQ2FyZCIgID4gJEdBREdFVC9zdHJpbmdzLzB4NDA5L3Byb2R1Y3QKKwor ICAgICNDcmVhdGUgY29uZmlndXJhdGlvbgorICAgIG1rZGlyICAkR0FER0VUL2NvbmZpZ3MvYy4x CisgICAgbWtkaXIgICRHQURHRVQvY29uZmlncy9jLjEvc3RyaW5ncy8weDQwOQorICAgIGVjaG8g Q29uZmlnMSA+ICRHQURHRVQvY29uZmlncy9jLjEvc3RyaW5ncy8weDQwOS9jb25maWd1cmF0aW9u CisKKyAgICAjVXNlIGBDb25maWcxYCBmb3Igb3VyIENDSUQgZ2FkZ2V0CisgICAgbG4gLXMgJEZV TkNUSU9OICRHQURHRVQvY29uZmlncy9jLjEKKworICAgICNFeGVjdXRlCisgICAgZWNobyAkVURD ID4gJEdBREdFVC9VREMKKworCitSZWZlcmVuY2VzCis9PT09PT09PT09CisKKy4uIFsxXSBodHRw Oi8vd3d3LnVzYi5vcmcvZGV2ZWxvcGVycy9kb2NzL2RldmNsYXNzX2RvY3MvRFdHX1NtYXJ0LUNh cmRfQ0NJRF9SZXYxMTAucGRmCisuLiBbMl0gaW5jbHVkZS91YXBpL2xpbnV4L3VzYi9jY2lkLmgK From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.6 required=3.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,SPF_PASS,URIBL_BLOCKED, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id E2DF0C43144 for ; Tue, 26 Jun 2018 08:15:31 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 7FF452668D for ; Tue, 26 Jun 2018 08:15:31 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="WxONe6fS" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 7FF452668D Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752948AbeFZIO4 (ORCPT ); Tue, 26 Jun 2018 04:14:56 -0400 Received: from mail-lf0-f68.google.com ([209.85.215.68]:36485 "EHLO mail-lf0-f68.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752669AbeFZIOm (ORCPT ); Tue, 26 Jun 2018 04:14:42 -0400 Received: by mail-lf0-f68.google.com with SMTP id n24-v6so16671129lfh.3; Tue, 26 Jun 2018 01:14:41 -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=sXg7Ly2hHNzrjG5wNU8iGTxdYK3Jbxx11AygjgUXt8Q=; b=WxONe6fSNL2QHiTFVxgce2YWb1QWVYEZZUH/YAoC0pjPJMicdjdm0w1cGSsbxxG7Xg KCE38hrwUSWFMs6mTf0yegrNzrdLvy2MbLDBxVNjmKbwHefIzBSkxTC56I3ycrvy6Mw9 uf7GVw7wZNuJPlnM2XjaAJtipFLRsPQg9naSy210cUt7CxRzmU8ZPLhkikHrBcKyHunb jo8ALOE5WXObqs4T7OZb20PTh0bztgdHN5+IHRSKSVm8wrWil2SHVlaC2SljObms1PdV Ffy8qDqFdct72IsLpvVLIH705dl6AGYDJBSzjgUaBxwOaqlugcC6wg+decrLh/4Zg9qn TJAw== 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=sXg7Ly2hHNzrjG5wNU8iGTxdYK3Jbxx11AygjgUXt8Q=; b=UWZxZFy8nJZy9t9vaBrPniECe4jz/eKo8+19DLNOXNCTFYai604U4ScLH0yC0g3lKW m/K3MhKsxLClVKs2IZQFzuJ1viLV37X9LEe3vrYyH0sXFk8/JlOqoDLs9GmDa+xGyaqI dDqfAXk6d0Bj5hX3/deml5tPXkmtq/0qHXRpfFT7HeLX0bGbux2I6qKPMTpiyGN52q2g dKAjCGyS713mg65M7hDkjCuwHO/y0hVUr2ZXHnfmT/2GE08LW8/KbivRC8TPw8A7FpeH R6uSjPinnDLmWOOyR1SQ2qf6tkrQ/Np+zNoTHXMlHyfdhRwrOaMATP+7IXJn9ah8F8YZ tRSw== X-Gm-Message-State: APt69E2a2vExzErV2S/QgwF8qkpxFpkk12zg1gNVe8QH2+ro2YBTiEJ6 7aat02JvWREgmD98MpYrReZS4raD X-Google-Smtp-Source: AAOMgpecrbBmmf3HU09l+jPeodNEKHWpiK4lt0na4At8d6Fltjz/vyqWDDtin6/5nErhMVa3n06l/g== X-Received: by 2002:a19:cb12:: with SMTP id b18-v6mr455907lfg.64.1530000880743; Tue, 26 Jun 2018 01:14:40 -0700 (PDT) Received: from localhost.localdomain (c-2ec26030-74736162.cust.telenor.se. [46.194.96.48]) by smtp.gmail.com with ESMTPSA id p28-v6sm149783lja.13.2018.06.26.01.14.38 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 26 Jun 2018 01:14:39 -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 v4 2/3] Documentation: usb: add documentation for USB CCID Gadget Device Date: Tue, 26 Jun 2018 10:14:21 +0200 Message-Id: <20180626081422.19237-2-marcus.folkesson@gmail.com> X-Mailer: git-send-email 2.18.0 In-Reply-To: <20180626081422.19237-1-marcus.folkesson@gmail.com> References: <20180626081422.19237-1-marcus.folkesson@gmail.com> Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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. Reviewed-by: Randy Dunlap Signed-off-by: Marcus Folkesson --- Notes: v4: - clarify how to use /dev/ccidg and BULK endpoind (thanks Randy) v3: - correct the grammer (thanks Randy) v2: - add the missing changelog text Documentation/usb/gadget_ccid.rst | 269 ++++++++++++++++++++++++++++++ 1 file changed, 269 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..c8f25080c9e7 --- /dev/null +++ b/Documentation/usb/gadget_ccid.rst @@ -0,0 +1,269 @@ +.. 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 are exposed to userspace via /dev/ccidgX where `X` is +the device enumeration number. +Use read(2) and write(3) to operate on BULK_IN and BULK_OUT respectively. + +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-byte 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 specify which slot 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 file descriptor 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 are 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 defined 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 Smart Card" > $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.18.0