[PATCH v4 2/3] Documentation: usb: add documentation for USB CCID Gadget Device
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 ..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 0x. + +The value is a bitwise OR operation performed on the following values: + ++++ +| Value | Description| ++++ +| 0x | No special characteristics |
[PATCH v4 2/3] Documentation: usb: add documentation for USB CCID Gadget Device
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 ..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 0x. + +The value is a bitwise OR operation performed on the following values: + ++++ +| Value | Description| ++++ +| 0x | No special characteristics |
