* Re: [PATCH v2 1/3] usb: gadget: ccid: add support for USB CCID Gadget Device
From: Andrzej Pietrasiewicz @ 2018-05-28 9:58 UTC (permalink / raw)
To: Marcus Folkesson
Cc: Greg Kroah-Hartman, Jonathan Corbet, Felipe Balbi, davem,
Mauro Carvalho Chehab, Andrew Morton, Randy Dunlap,
Ruslan Bilovol, Thomas Gleixner, Kate Stewart, linux-usb,
linux-doc, linux-kernel
In-Reply-To: <20180528093254.GC4651@gmail.com>
W dniu 28.05.2018 o 11:32, Marcus Folkesson pisze:
> Hi Andrzej,
>
> Thank you for reviewing.
>
> On Mon, May 28, 2018 at 11:12:27AM +0200, Andrzej Pietrasiewicz wrote:
>> W dniu 28.05.2018 o 10:38, Marcus Folkesson pisze:
>>> Hi Andrzej,
>>>
>>> On Mon, May 28, 2018 at 09:04:51AM +0200, Andrzej Pietrasiewicz wrote:
>>>> Mi Marcus,
>>>>
>>>> W dniu 26.05.2018 o 23:19, Marcus Folkesson pisze:
>>>>> Chip Card Interface Device (CCID) protocol is a USB protocol that
>>>>> allows a smartcard device to be connected to a computer via a card
>>>>> reader using a standard USB interface, without the need for each manufacturer
>>>>> of smartcards to provide its own reader or protocol.
>>>>>
>>>>> This gadget driver makes Linux show up as a CCID device to the host and let a
>>>>> userspace daemon act as the smartcard.
>>>>>
>>>>> This is useful when the Linux gadget itself should act as a cryptographic
>>>>> device or forward APDUs to an embedded smartcard device.
>>>>>
>>>>> Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
>>>>> ---
>>>>
>>>>>
>>>>> +config USB_CONFIGFS_CCID
>>>>> + bool "Chip Card Interface Device (CCID)"
>>>>> + depends on USB_CONFIGFS
>>>>> + select USB_F_CCID
>>>>> + help
>>>>> + The CCID function driver provides generic emulation of a
>>>>> + Chip Card Interface Device (CCID).
>>>>> +
>>>>> + You will need a user space server talking to /dev/ccidg*,
>>>>> + since the kernel itself does not implement CCID/TPDU/APDU
>>>>> + protocol.
>>>>
>>>> Your function needs a userspace daemon to work.
>>>> It seems you want to use FunctionFS for such a purpose
>>>> instead of creating a new function.
>>>>
>>>> Andrzej
>>>
>>>>> + since the kernel itself does not implement CCID/TPDU/APDU
>>> Oops, the driver does handle CCID.
>>
>> Which parts of code do this handling?
>
> My bad, I was thinking about the USB descriptors and endpoints setup.
> That is of cause not part of the CCID protocol.
>
>>
>> Is there any kind of state machine usual for protocols?
>> If the protocol is stateless then isn't it just a data format then?
>
> The protocol is stateless.
>
>>
>> Which part of this handling must be done in kernel and why?
>>
>> Does the said handling do anything other than forwarding the
>> traffic between USB and a character device?
>
> No, it forward the CCID messages to the character device to be handled
> by the application.
>
>>
My opinion is: this wants to be done with FunctionFS.
Andrzej
--
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
^ permalink raw reply
* Re: [PATCH v2 1/3] usb: gadget: ccid: add support for USB CCID Gadget Device
From: Marcus Folkesson @ 2018-05-28 9:32 UTC (permalink / raw)
To: Andrzej Pietrasiewicz
Cc: Greg Kroah-Hartman, Jonathan Corbet, Felipe Balbi, davem,
Mauro Carvalho Chehab, Andrew Morton, Randy Dunlap,
Ruslan Bilovol, Thomas Gleixner, Kate Stewart, linux-usb,
linux-doc, linux-kernel
In-Reply-To: <20180528091229eucas1p20cfbb68cdfaa6de2cf5b5a7e2bdac72c~yxAUSF7e61070710707eucas1p2j@eucas1p2.samsung.com>
Hi Andrzej,
Thank you for reviewing.
On Mon, May 28, 2018 at 11:12:27AM +0200, Andrzej Pietrasiewicz wrote:
> W dniu 28.05.2018 o 10:38, Marcus Folkesson pisze:
> > Hi Andrzej,
> >
> > On Mon, May 28, 2018 at 09:04:51AM +0200, Andrzej Pietrasiewicz wrote:
> >> Mi Marcus,
> >>
> >> W dniu 26.05.2018 o 23:19, Marcus Folkesson pisze:
> >>> Chip Card Interface Device (CCID) protocol is a USB protocol that
> >>> allows a smartcard device to be connected to a computer via a card
> >>> reader using a standard USB interface, without the need for each manufacturer
> >>> of smartcards to provide its own reader or protocol.
> >>>
> >>> This gadget driver makes Linux show up as a CCID device to the host and let a
> >>> userspace daemon act as the smartcard.
> >>>
> >>> This is useful when the Linux gadget itself should act as a cryptographic
> >>> device or forward APDUs to an embedded smartcard device.
> >>>
> >>> Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
> >>> ---
> >>
> >>>
> >>> +config USB_CONFIGFS_CCID
> >>> + bool "Chip Card Interface Device (CCID)"
> >>> + depends on USB_CONFIGFS
> >>> + select USB_F_CCID
> >>> + help
> >>> + The CCID function driver provides generic emulation of a
> >>> + Chip Card Interface Device (CCID).
> >>> +
> >>> + You will need a user space server talking to /dev/ccidg*,
> >>> + since the kernel itself does not implement CCID/TPDU/APDU
> >>> + protocol.
> >>
> >> Your function needs a userspace daemon to work.
> >> It seems you want to use FunctionFS for such a purpose
> >> instead of creating a new function.
> >>
> >> Andrzej
> >
> >>> + since the kernel itself does not implement CCID/TPDU/APDU
> > Oops, the driver does handle CCID.
>
> Which parts of code do this handling?
My bad, I was thinking about the USB descriptors and endpoints setup.
That is of cause not part of the CCID protocol.
>
> Is there any kind of state machine usual for protocols?
> If the protocol is stateless then isn't it just a data format then?
The protocol is stateless.
>
> Which part of this handling must be done in kernel and why?
>
> Does the said handling do anything other than forwarding the
> traffic between USB and a character device?
No, it forward the CCID messages to the character device to be handled
by the application.
>
> What is the character device used for? I know: read, write and poll.
> But why? To do what?
It is used for the application to fetch, interpret and then perform actions depending on
commands.
>
> >
> > Well, yes, It needs an application that perform the "smartcard operations", such as
> > generate keys or sign data, as this depends on how it should be used.
> >
> > The actual smartcard operations could for example be in software,
> > use a crypto engine in SoC or external HSM (Hardware Security Module).
> >
> > Without the application, the gadget shows up as a smart card reader
> > with an unconnected smartcard.
> >
>
> Does showing up as anything require anything other than merely
> providing USB descriptors?
I guess.
>
> Andrzej
Thank you,
Marcus
--
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
^ permalink raw reply
* Re: [PATCH v2 1/3] usb: gadget: ccid: add support for USB CCID Gadget Device
From: Andrzej Pietrasiewicz @ 2018-05-28 9:12 UTC (permalink / raw)
To: Marcus Folkesson
Cc: Greg Kroah-Hartman, Jonathan Corbet, Felipe Balbi, davem,
Mauro Carvalho Chehab, Andrew Morton, Randy Dunlap,
Ruslan Bilovol, Thomas Gleixner, Kate Stewart, linux-usb,
linux-doc, linux-kernel
In-Reply-To: <20180528083834.GB4651@gmail.com>
W dniu 28.05.2018 o 10:38, Marcus Folkesson pisze:
> Hi Andrzej,
>
> On Mon, May 28, 2018 at 09:04:51AM +0200, Andrzej Pietrasiewicz wrote:
>> Mi Marcus,
>>
>> W dniu 26.05.2018 o 23:19, Marcus Folkesson pisze:
>>> Chip Card Interface Device (CCID) protocol is a USB protocol that
>>> allows a smartcard device to be connected to a computer via a card
>>> reader using a standard USB interface, without the need for each manufacturer
>>> of smartcards to provide its own reader or protocol.
>>>
>>> This gadget driver makes Linux show up as a CCID device to the host and let a
>>> userspace daemon act as the smartcard.
>>>
>>> This is useful when the Linux gadget itself should act as a cryptographic
>>> device or forward APDUs to an embedded smartcard device.
>>>
>>> Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
>>> ---
>>
>>>
>>> +config USB_CONFIGFS_CCID
>>> + bool "Chip Card Interface Device (CCID)"
>>> + depends on USB_CONFIGFS
>>> + select USB_F_CCID
>>> + help
>>> + The CCID function driver provides generic emulation of a
>>> + Chip Card Interface Device (CCID).
>>> +
>>> + You will need a user space server talking to /dev/ccidg*,
>>> + since the kernel itself does not implement CCID/TPDU/APDU
>>> + protocol.
>>
>> Your function needs a userspace daemon to work.
>> It seems you want to use FunctionFS for such a purpose
>> instead of creating a new function.
>>
>> Andrzej
>
>>> + since the kernel itself does not implement CCID/TPDU/APDU
> Oops, the driver does handle CCID.
Which parts of code do this handling?
Is there any kind of state machine usual for protocols?
If the protocol is stateless then isn't it just a data format then?
Which part of this handling must be done in kernel and why?
Does the said handling do anything other than forwarding the
traffic between USB and a character device?
What is the character device used for? I know: read, write and poll.
But why? To do what?
>
> Well, yes, It needs an application that perform the "smartcard operations", such as
> generate keys or sign data, as this depends on how it should be used.
>
> The actual smartcard operations could for example be in software,
> use a crypto engine in SoC or external HSM (Hardware Security Module).
>
> Without the application, the gadget shows up as a smart card reader
> with an unconnected smartcard.
>
Does showing up as anything require anything other than merely
providing USB descriptors?
Andrzej
--
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
^ permalink raw reply
* [RFT v3 4/4] coresight: Document for CoreSight trace disassembler
From: Leo Yan @ 2018-05-28 8:45 UTC (permalink / raw)
To: Arnaldo Carvalho de Melo, Mathieu Poirier, Jonathan Corbet,
Robert Walker, mike.leach, kim.phillips, Tor Jeremiassen
Cc: Peter Zijlstra, Ingo Molnar, Alexander Shishkin, Jiri Olsa,
Namhyung Kim, linux-arm-kernel, linux-doc, linux-kernel,
coresight, Leo Yan
In-Reply-To: <1527497103-3593-1-git-send-email-leo.yan@linaro.org>
This commit documents CoreSight trace disassembler usage and gives
example for it.
Signed-off-by: Leo Yan <leo.yan@linaro.org>
---
Documentation/trace/coresight.txt | 52 +++++++++++++++++++++++++++++++++++++++
1 file changed, 52 insertions(+)
diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.txt
index 6f0120c..b8f2359 100644
--- a/Documentation/trace/coresight.txt
+++ b/Documentation/trace/coresight.txt
@@ -381,3 +381,55 @@ sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tuto
$ taskset -c 2 ./sort_autofdo
Bubble sorting array of 30000 elements
5806 ms
+
+
+Tracing data disassembler
+-------------------------
+
+'perf script' supports to use script to parse tracing packet and rely on
+'objdump' for disassembled lines, this can convert tracing data to readable
+program execution flow for easily reviewing tracing data.
+
+The CoreSight trace disassembler is located in the folder:
+tools/perf/scripts/python/arm-cs-trace-disasm.py. This script support below
+options:
+
+ -d, --objdump: Set path to objdump executable, this option is
+ mandatory.
+ -k, --vmlinux: Set path to vmlinux file.
+ -v, --verbose: Enable debugging log, after enable this option the
+ script dumps every event data.
+
+Below is one example for using python script to dump CoreSight trace
+disassembler:
+
+ $ perf script -s arm-cs-trace-disasm.py -i perf.data \
+ -F cpu,event,ip,addr,sym -- -d objdump -k ./vmlinux > cs-disasm.log
+
+Below is one example for the disassembler log:
+
+ARM CoreSight Trace Data Assembler Dump
+ ffff000008a5f2dc <etm4_enable_hw+0x344>:
+ ffff000008a5f2dc: 340000a0 cbz w0, ffff000008a5f2f0 <etm4_enable_hw+0x358>
+ ffff000008a5f2f0 <etm4_enable_hw+0x358>:
+ ffff000008a5f2f0: f9400260 ldr x0, [x19]
+ ffff000008a5f2f4: d5033f9f dsb sy
+ ffff000008a5f2f8: 913ec000 add x0, x0, #0xfb0
+ ffff000008a5f2fc: b900001f str wzr, [x0]
+ ffff000008a5f300: f9400bf3 ldr x19, [sp, #16]
+ ffff000008a5f304: a8c27bfd ldp x29, x30, [sp], #32
+ ffff000008a5f308: d65f03c0 ret
+ ffff000008a5fa18 <etm4_enable+0x1b0>:
+ ffff000008a5fa18: 14000025 b ffff000008a5faac <etm4_enable+0x244>
+ ffff000008a5faac <etm4_enable+0x244>:
+ ffff000008a5faac: b9406261 ldr w1, [x19, #96]
+ ffff000008a5fab0: 52800015 mov w21, #0x0 // #0
+ ffff000008a5fab4: f901ca61 str x1, [x19, #912]
+ ffff000008a5fab8: 2a1503e0 mov w0, w21
+ ffff000008a5fabc: 3940e261 ldrb w1, [x19, #56]
+ ffff000008a5fac0: f901ce61 str x1, [x19, #920]
+ ffff000008a5fac4: a94153f3 ldp x19, x20, [sp, #16]
+ ffff000008a5fac8: a9425bf5 ldp x21, x22, [sp, #32]
+ ffff000008a5facc: a94363f7 ldp x23, x24, [sp, #48]
+ ffff000008a5fad0: a8c47bfd ldp x29, x30, [sp], #64
+ ffff000008a5fad4: d65f03c0 ret
--
2.7.4
--
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
^ permalink raw reply related
* [RFT v3 3/4] perf script python: Add script for CoreSight trace disassembler
From: Leo Yan @ 2018-05-28 8:45 UTC (permalink / raw)
To: Arnaldo Carvalho de Melo, Mathieu Poirier, Jonathan Corbet,
Robert Walker, mike.leach, kim.phillips, Tor Jeremiassen
Cc: Peter Zijlstra, Ingo Molnar, Alexander Shishkin, Jiri Olsa,
Namhyung Kim, linux-arm-kernel, linux-doc, linux-kernel,
coresight, Leo Yan
In-Reply-To: <1527497103-3593-1-git-send-email-leo.yan@linaro.org>
This commit adds python script to parse CoreSight tracing event and
use command 'objdump' for disassembled lines, finally we can generate
readable program execution flow for reviewing tracing data.
The script receives CoreSight tracing packet with below format:
+------------+------------+------------+
packet(n): | addr | ip | cpu |
+------------+------------+------------+
packet(n+1): | addr | ip | cpu |
+------------+------------+------------+
packet::ip is the last address of current branch instruction and
packet::addr presents the start address of the next coming branch
instruction. So for one branch instruction which starts in packet(n),
its execution flow starts from packet(n)::addr and it stops at
packet(n+1)::ip. As results we need to combine the two continuous
packets to generate the instruction range, this is the rationale for the
script implementation:
[ sample(n)::addr .. sample(n+1)::ip ]
Credits to Tor Jeremiassen who have written the script skeleton and
provides the ideas for reading symbol file according to build-id,
creating memory map for dso and basic packet handling. Mathieu Poirier
contributed fixes for build-id and memory map bugs. The detailed
development history for this script you can find from [1]. Based on Tor
and Mathieu work, the script is updated samples handling for the
corrected sample format. Another minor enhancement is to support for
without build-id case, the script can parse kernel symbols with option
'-k' for vmlinux file path.
[1] https://github.com/Linaro/perf-opencsd/commits/perf-opencsd-v4.15/tools/perf/scripts/python/cs-trace-disasm.py
Co-authored-by: Tor Jeremiassen <tor@ti.com>
Co-authored-by: Mathieu Poirier <mathieu.poirier@linaro.org>
Signed-off-by: Leo Yan <leo.yan@linaro.org>
---
tools/perf/scripts/python/arm-cs-trace-disasm.py | 235 +++++++++++++++++++++++
1 file changed, 235 insertions(+)
create mode 100644 tools/perf/scripts/python/arm-cs-trace-disasm.py
diff --git a/tools/perf/scripts/python/arm-cs-trace-disasm.py b/tools/perf/scripts/python/arm-cs-trace-disasm.py
new file mode 100644
index 0000000..1239ab4
--- /dev/null
+++ b/tools/perf/scripts/python/arm-cs-trace-disasm.py
@@ -0,0 +1,235 @@
+# arm-cs-trace-disasm.py: ARM CoreSight Trace Dump With Disassember
+# SPDX-License-Identifier: GPL-2.0
+#
+# Tor Jeremiassen <tor@ti.com> is original author who wrote script
+# skeleton, Mathieu Poirier <mathieu.poirier@linaro.org> contributed
+# fixes for build-id and memory map; Leo Yan <leo.yan@linaro.org>
+# updated the packet parsing with new samples format.
+
+import os
+import sys
+import re
+from subprocess import *
+from optparse import OptionParser, make_option
+
+# Command line parsing
+
+option_list = [
+ # formatting options for the bottom entry of the stack
+ make_option("-k", "--vmlinux", dest="vmlinux_name",
+ help="Set path to vmlinux file"),
+ make_option("-d", "--objdump", dest="objdump_name",
+ help="Set path to objdump executable file"),
+ make_option("-v", "--verbose", dest="verbose",
+ action="store_true", default=False,
+ help="Enable debugging log")
+]
+
+parser = OptionParser(option_list=option_list)
+(options, args) = parser.parse_args()
+
+if (options.objdump_name == None):
+ sys.exit("No objdump executable file specified - use -d or --objdump option")
+
+# Initialize global dicts and regular expression
+
+build_ids = dict()
+mmaps = dict()
+disasm_cache = dict()
+cpu_data = dict()
+disasm_re = re.compile("^\s*([0-9a-fA-F]+):")
+disasm_func_re = re.compile("^\s*([0-9a-fA-F]+)\s\<.*\>:")
+cache_size = 32*1024
+prev_cpu = -1
+
+def parse_buildid():
+ global build_ids
+
+ buildid_regex = "([a-fA-f0-9]+)[ \t]([^ \n]+)"
+ buildid_re = re.compile(buildid_regex)
+
+ results = check_output(["perf", "buildid-list"]).split('\n');
+ for line in results:
+ m = buildid_re.search(line)
+ if (m == None):
+ continue;
+
+ id_name = m.group(2)
+ id_num = m.group(1)
+
+ if (id_name == "[kernel.kallsyms]") :
+ append = "/kallsyms"
+ elif (id_name == "[vdso]") :
+ append = "/vdso"
+ else:
+ append = "/elf"
+
+ build_ids[id_name] = os.environ['PERF_BUILDID_DIR'] + \
+ "/" + id_name + "/" + id_num + append;
+ # Replace duplicate slash chars to single slash char
+ build_ids[id_name] = build_ids[id_name].replace('//', '/', 1)
+
+ if ((options.vmlinux_name == None) and ("[kernel.kallsyms]" in build_ids)):
+ print "kallsyms cannot be used to dump assembler"
+
+ # Set vmlinux path to replace kallsyms file, if without buildid we still
+ # can use vmlinux to prase kernel symbols
+ if ((options.vmlinux_name != None)):
+ build_ids['[kernel.kallsyms]'] = options.vmlinux_name;
+
+def parse_mmap():
+ global mmaps
+
+ # Check mmap for PERF_RECORD_MMAP and PERF_RECORD_MMAP2
+ mmap_regex = "PERF_RECORD_MMAP.* -?[0-9]+/[0-9]+: \[(0x[0-9a-fA-F]+)\((0x[0-9a-fA-F]+)\).*:\s.*\s(\S*)"
+ mmap_re = re.compile(mmap_regex)
+
+ results = check_output("perf script --show-mmap-events | fgrep PERF_RECORD_MMAP", shell=True).split('\n')
+ for line in results:
+ m = mmap_re.search(line)
+ if (m != None):
+ if (m.group(3) == '[kernel.kallsyms]_text'):
+ dso = '[kernel.kallsyms]'
+ else:
+ dso = m.group(3)
+
+ start = int(m.group(1),0)
+ end = int(m.group(1),0) + int(m.group(2),0)
+ mmaps[dso] = [start, end]
+
+def find_dso_mmap(addr):
+ global mmaps
+
+ for key, value in mmaps.items():
+ if (addr >= value[0] and addr < value[1]):
+ return key
+
+ return None
+
+def read_disam(dso, start_addr, stop_addr):
+ global mmaps
+ global build_ids
+
+ addr_range = start_addr + ":" + stop_addr;
+
+ # Don't let the cache get too big, clear it when it hits max size
+ if (len(disasm_cache) > cache_size):
+ disasm_cache.clear();
+
+ try:
+ disasm_output = disasm_cache[addr_range];
+ except:
+ try:
+ fname = build_ids[dso];
+ except KeyError:
+ sys.exit("cannot find symbol file for " + dso)
+
+ disasm = [ options.objdump_name, "-d", "-z",
+ "--start-address="+start_addr,
+ "--stop-address="+stop_addr, fname ]
+
+ disasm_output = check_output(disasm).split('\n')
+ disasm_cache[addr_range] = disasm_output;
+
+ return disasm_output
+
+def dump_disam(dso, start_addr, stop_addr):
+ for line in read_disam(dso, start_addr, stop_addr):
+ m = disasm_func_re.search(line)
+ if (m != None):
+ print "\t",line
+ continue
+
+ m = disasm_re.search(line)
+ if (m == None):
+ continue;
+
+ print "\t",line
+
+def dump_packet(sample):
+ print "Packet = { cpu: 0x%d addr: 0x%x phys_addr: 0x%x ip: 0x%x " \
+ "pid: %d tid: %d period: %d time: %d }" % \
+ (sample['cpu'], sample['addr'], sample['phys_addr'], \
+ sample['ip'], sample['pid'], sample['tid'], \
+ sample['period'], sample['time'])
+
+def trace_begin():
+ print 'ARM CoreSight Trace Data Assembler Dump'
+ parse_buildid()
+ parse_mmap()
+
+def trace_end():
+ print 'End'
+
+def trace_unhandled(event_name, context, event_fields_dict):
+ print ' '.join(['%s=%s'%(k,str(v))for k,v in sorted(event_fields_dict.items())])
+
+def process_event(param_dict):
+ global cache_size
+ global options
+ global prev_cpu
+
+ sample = param_dict["sample"]
+
+ if (options.verbose == True):
+ dump_packet(sample)
+
+ # If period doesn't equal to 1, this packet is for instruction sample
+ # packet, we need drop this synthetic packet.
+ if (sample['period'] != 1):
+ print "Skip synthetic instruction sample"
+ return
+
+ cpu = format(sample['cpu'], "d");
+
+ # Initialize CPU data if it's empty, and directly return back
+ # if this is the first tracing event for this CPU.
+ if (cpu_data.get(str(cpu) + 'addr') == None):
+ cpu_data[str(cpu) + 'addr'] = format(sample['addr'], "#x")
+ prev_cpu = cpu
+ return
+
+ # The format for packet is:
+ #
+ # +------------+------------+------------+
+ # sample_prev: | addr | ip | cpu |
+ # +------------+------------+------------+
+ # sample_next: | addr | ip | cpu |
+ # +------------+------------+------------+
+ #
+ # We need to combine the two continuous packets to get the instruction
+ # range for sample_prev::cpu:
+ #
+ # [ sample_prev::addr .. sample_next::ip ]
+ #
+ # For this purose, sample_prev::addr is stored into cpu_data structure
+ # and read back for 'start_addr' when the new packet comes, and we need
+ # to use sample_next::ip to calculate 'stop_addr', plusing extra 4 for
+ # 'stop_addr' is for the sake of objdump so the final assembler dump can
+ # include last instruction for sample_next::ip.
+
+ start_addr = cpu_data[str(prev_cpu) + 'addr']
+ stop_addr = format(sample['ip'] + 4, "#x")
+
+ # Record for previous sample packet
+ cpu_data[str(cpu) + 'addr'] = format(sample['addr'], "#x")
+ prev_cpu = cpu
+
+ # Handle CS_ETM_TRACE_ON packet if start_addr=0 and stop_addr=4
+ if (int(start_addr, 0) == 0 and int(stop_addr, 0) == 4):
+ print "CPU%s: CS_ETM_TRACE_ON packet is inserted" % cpu
+ return
+
+ # Sanity checking dso for start_addr and stop_addr
+ prev_dso = find_dso_mmap(int(start_addr, 0))
+ next_dso = find_dso_mmap(int(stop_addr, 0))
+
+ # If cannot find dso so cannot dump assembler, bail out
+ if (prev_dso == None or next_dso == None):
+ print "Address range [ %s .. %s ]: failed to find dso" % (start_addr, stop_addr)
+ return
+ elif (prev_dso != next_dso):
+ print "Address range [ %s .. %s ]: isn't in same dso" % (start_addr, stop_addr)
+ return
+
+ dump_disam(prev_dso, start_addr, stop_addr)
--
2.7.4
--
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
^ permalink raw reply related
* [RFT v3 2/4] perf script python: Add addr into perf sample dict
From: Leo Yan @ 2018-05-28 8:45 UTC (permalink / raw)
To: Arnaldo Carvalho de Melo, Mathieu Poirier, Jonathan Corbet,
Robert Walker, mike.leach, kim.phillips, Tor Jeremiassen
Cc: Peter Zijlstra, Ingo Molnar, Alexander Shishkin, Jiri Olsa,
Namhyung Kim, linux-arm-kernel, linux-doc, linux-kernel,
coresight, Leo Yan
In-Reply-To: <1527497103-3593-1-git-send-email-leo.yan@linaro.org>
ARM CoreSight auxtrace uses 'sample->addr' to record the target address
for branch instructions, so the data of 'sample->addr' is required for
tracing data analysis.
This commit collects data of 'sample->addr' into perf sample dict,
finally can be used for python script for parsing event.
Signed-off-by: Leo Yan <leo.yan@linaro.org>
---
tools/perf/util/scripting-engines/trace-event-python.c | 2 ++
1 file changed, 2 insertions(+)
diff --git a/tools/perf/util/scripting-engines/trace-event-python.c b/tools/perf/util/scripting-engines/trace-event-python.c
index 10dd5fc..7f8afac 100644
--- a/tools/perf/util/scripting-engines/trace-event-python.c
+++ b/tools/perf/util/scripting-engines/trace-event-python.c
@@ -531,6 +531,8 @@ static PyObject *get_perf_sample_dict(struct perf_sample *sample,
PyLong_FromUnsignedLongLong(sample->period));
pydict_set_item_string_decref(dict_sample, "phys_addr",
PyLong_FromUnsignedLongLong(sample->phys_addr));
+ pydict_set_item_string_decref(dict_sample, "addr",
+ PyLong_FromUnsignedLongLong(sample->addr));
set_sample_read_in_dict(dict_sample, sample, evsel);
pydict_set_item_string_decref(dict, "sample", dict_sample);
--
2.7.4
--
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
^ permalink raw reply related
* [RFT v3 1/4] perf cs-etm: Generate branch sample for missed packets
From: Leo Yan @ 2018-05-28 8:45 UTC (permalink / raw)
To: Arnaldo Carvalho de Melo, Mathieu Poirier, Jonathan Corbet,
Robert Walker, mike.leach, kim.phillips, Tor Jeremiassen
Cc: Peter Zijlstra, Ingo Molnar, Alexander Shishkin, Jiri Olsa,
Namhyung Kim, linux-arm-kernel, linux-doc, linux-kernel,
coresight, Leo Yan
In-Reply-To: <1527497103-3593-1-git-send-email-leo.yan@linaro.org>
Commit e573e978fb12 ("perf cs-etm: Inject capabilitity for CoreSight
traces") reworks the samples generation flow from CoreSight trace to
match the correct format so Perf report tool can display the samples
properly.
But the change has side effect for branch packet handling, it only
generate branch samples by checking previous packet flag
'last_instr_taken_branch' is true, this results in below three kinds
packets are missed to generate branch samples:
- The start tracing packet at the beginning of tracing data;
- The exception handling packet;
- If one CS_ETM_TRACE_ON packet is inserted, we also miss to handle it
for branch samples. CS_ETM_TRACE_ON packet itself can give the info
that there have a discontinuity in the trace, on the other hand we
also miss to generate proper branch sample for packets before and
after CS_ETM_TRACE_ON packet.
This patch is to add branch sample handling for up three kinds packets:
- In function cs_etm__sample(), check if 'prev_packet->sample_type' is
zero and in this case it generates branch sample for the start tracing
packet; furthermore, we also need to handle the condition for
prev_packet::end_addr is zero in the cs_etm__last_executed_instr();
- In function cs_etm__sample(), check if 'prev_packet->exc' is true and
generate branch sample for exception handling packet;
- If there has one CS_ETM_TRACE_ON packet is coming, we firstly generate
branch sample in the function cs_etm__flush(), this can save complete
info for the previous CS_ETM_RANGE packet just before CS_ETM_TRACE_ON
packet. We also generate branch sample for the new CS_ETM_RANGE
packet after CS_ETM_TRACE_ON packet, this have two purposes, the
first one purpose is to save the info for the new CS_ETM_RANGE packet,
the second purpose is to save CS_ETM_TRACE_ON packet info so we can
have hint for a discontinuity in the trace.
For CS_ETM_TRACE_ON packet, its fields 'packet->start_addr' and
'packet->end_addr' equal to 0xdeadbeefdeadbeefUL which are emitted in
the decoder layer as dummy value. This patch is to convert these
values to zeros for more readable; this is accomplished by functions
cs_etm__last_executed_instr() and cs_etm__first_executed_instr(). The
later one is a new function introduced by this patch.
Reviewed-by: Robert Walker <robert.walker@arm.com>
Fixes: e573e978fb12 ("perf cs-etm: Inject capabilitity for CoreSight traces")
Signed-off-by: Leo Yan <leo.yan@linaro.org>
---
tools/perf/util/cs-etm.c | 93 +++++++++++++++++++++++++++++++++++++-----------
1 file changed, 73 insertions(+), 20 deletions(-)
diff --git a/tools/perf/util/cs-etm.c b/tools/perf/util/cs-etm.c
index 822ba91..8418173 100644
--- a/tools/perf/util/cs-etm.c
+++ b/tools/perf/util/cs-etm.c
@@ -495,6 +495,20 @@ static inline void cs_etm__reset_last_branch_rb(struct cs_etm_queue *etmq)
static inline u64 cs_etm__last_executed_instr(struct cs_etm_packet *packet)
{
/*
+ * The packet is the start tracing packet if the end_addr is zero,
+ * returns 0 for this case.
+ */
+ if (!packet->end_addr)
+ return 0;
+
+ /*
+ * The packet is the CS_ETM_TRACE_ON packet if the end_addr is
+ * magic number 0xdeadbeefdeadbeefUL, returns 0 for this case.
+ */
+ if (packet->end_addr == 0xdeadbeefdeadbeefUL)
+ return 0;
+
+ /*
* The packet records the execution range with an exclusive end address
*
* A64 instructions are constant size, so the last executed
@@ -505,6 +519,18 @@ static inline u64 cs_etm__last_executed_instr(struct cs_etm_packet *packet)
return packet->end_addr - A64_INSTR_SIZE;
}
+static inline u64 cs_etm__first_executed_instr(struct cs_etm_packet *packet)
+{
+ /*
+ * The packet is the CS_ETM_TRACE_ON packet if the start_addr is
+ * magic number 0xdeadbeefdeadbeefUL, returns 0 for this case.
+ */
+ if (packet->start_addr == 0xdeadbeefdeadbeefUL)
+ return 0;
+
+ return packet->start_addr;
+}
+
static inline u64 cs_etm__instr_count(const struct cs_etm_packet *packet)
{
/*
@@ -546,7 +572,7 @@ static void cs_etm__update_last_branch_rb(struct cs_etm_queue *etmq)
be = &bs->entries[etmq->last_branch_pos];
be->from = cs_etm__last_executed_instr(etmq->prev_packet);
- be->to = etmq->packet->start_addr;
+ be->to = cs_etm__first_executed_instr(etmq->packet);
/* No support for mispredict */
be->flags.mispred = 0;
be->flags.predicted = 1;
@@ -701,7 +727,7 @@ static int cs_etm__synth_branch_sample(struct cs_etm_queue *etmq)
sample.ip = cs_etm__last_executed_instr(etmq->prev_packet);
sample.pid = etmq->pid;
sample.tid = etmq->tid;
- sample.addr = etmq->packet->start_addr;
+ sample.addr = cs_etm__first_executed_instr(etmq->packet);
sample.id = etmq->etm->branches_id;
sample.stream_id = etmq->etm->branches_id;
sample.period = 1;
@@ -897,13 +923,28 @@ static int cs_etm__sample(struct cs_etm_queue *etmq)
etmq->period_instructions = instrs_over;
}
- if (etm->sample_branches &&
- etmq->prev_packet &&
- etmq->prev_packet->sample_type == CS_ETM_RANGE &&
- etmq->prev_packet->last_instr_taken_branch) {
- ret = cs_etm__synth_branch_sample(etmq);
- if (ret)
- return ret;
+ if (etm->sample_branches && etmq->prev_packet) {
+ bool generate_sample = false;
+
+ /* Generate sample for start tracing packet */
+ if (etmq->prev_packet->sample_type == 0 ||
+ etmq->prev_packet->sample_type == CS_ETM_TRACE_ON)
+ generate_sample = true;
+
+ /* Generate sample for exception packet */
+ if (etmq->prev_packet->exc == true)
+ generate_sample = true;
+
+ /* Generate sample for normal branch packet */
+ if (etmq->prev_packet->sample_type == CS_ETM_RANGE &&
+ etmq->prev_packet->last_instr_taken_branch)
+ generate_sample = true;
+
+ if (generate_sample) {
+ ret = cs_etm__synth_branch_sample(etmq);
+ if (ret)
+ return ret;
+ }
}
if (etm->sample_branches || etm->synth_opts.last_branch) {
@@ -922,11 +963,16 @@ static int cs_etm__sample(struct cs_etm_queue *etmq)
static int cs_etm__flush(struct cs_etm_queue *etmq)
{
int err = 0;
+ struct cs_etm_auxtrace *etm = etmq->etm;
struct cs_etm_packet *tmp;
- if (etmq->etm->synth_opts.last_branch &&
- etmq->prev_packet &&
- etmq->prev_packet->sample_type == CS_ETM_RANGE) {
+ if (!etmq->prev_packet)
+ return 0;
+
+ if (etmq->prev_packet->sample_type != CS_ETM_RANGE)
+ return 0;
+
+ if (etmq->etm->synth_opts.last_branch) {
/*
* Generate a last branch event for the branches left in the
* circular buffer at the end of the trace.
@@ -939,18 +985,25 @@ static int cs_etm__flush(struct cs_etm_queue *etmq)
err = cs_etm__synth_instruction_sample(
etmq, addr,
etmq->period_instructions);
+ if (err)
+ return err;
etmq->period_instructions = 0;
+ }
- /*
- * Swap PACKET with PREV_PACKET: PACKET becomes PREV_PACKET for
- * the next incoming packet.
- */
- tmp = etmq->packet;
- etmq->packet = etmq->prev_packet;
- etmq->prev_packet = tmp;
+ if (etm->sample_branches) {
+ err = cs_etm__synth_branch_sample(etmq);
+ if (err)
+ return err;
}
- return err;
+ /*
+ * Swap PACKET with PREV_PACKET: PACKET becomes PREV_PACKET for
+ * the next incoming packet.
+ */
+ tmp = etmq->packet;
+ etmq->packet = etmq->prev_packet;
+ etmq->prev_packet = tmp;
+ return 0;
}
static int cs_etm__run_decoder(struct cs_etm_queue *etmq)
--
2.7.4
--
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
^ permalink raw reply related
* [RFT v3 0/4] Perf script: Add python script for CoreSight trace disassembler
From: Leo Yan @ 2018-05-28 8:44 UTC (permalink / raw)
To: Arnaldo Carvalho de Melo, Mathieu Poirier, Jonathan Corbet,
Robert Walker, mike.leach, kim.phillips, Tor Jeremiassen
Cc: Peter Zijlstra, Ingo Molnar, Alexander Shishkin, Jiri Olsa,
Namhyung Kim, linux-arm-kernel, linux-doc, linux-kernel,
coresight, Leo Yan
This patch series is to support for using 'perf script' for CoreSight
trace disassembler, for this purpose this patch series adds a new
python script to parse CoreSight tracing event and use command 'objdump'
for disassembled lines, finally this can generate readable program
execution flow for reviewing tracing data.
Patch 0001 is one fixing patch to generate samples for the start packet
and exception packets.
Patch 0002 is the prerequisite to add addr into sample dict, so this
value can be used by python script to analyze instruction range.
Patch 0003 is to add python script for trace disassembler.
Patch 0004 is to add doc to explain python script usage and give
example for it.
This patch series has been rebased on acme git tree [1] with the commit
19422a9f2a3b ("perf tools: Fix kernel_start for PTI on x86") and tested
on Hikey (ARM64 octa CA53 cores).
In this version the script has no dependency on ARM64 platform and is
expected to support ARM32 platform, but I am lacking ARM32 platform for
testing on it, so firstly upstream to support ARM64 platform.
This patch series is firstly to support 'per-thread' recording tracing
data, but we also need to verify the script can dump trace disassembler
CPU wide tracing and kernel panic kdump tracing data. I also verified
this patch series which can work with kernel panic kdump tracing data,
because Mathieu is working on CPU wide tracing related work, so after
this we need to retest for CPU wide tracing and kdump tracing to ensure
the python script can handle well for all cases.
You are very welcome to test the script in this patch series, your
testing result and suggestion are very valuable to perfect this script
to cover more cases.
Changes from v2:
* Synced with Rob for handling CS_ETM_TRACE_ON packet, so refined 0001
patch according to dicussion;
* Minor cleanup and fixes in 0003 patch for python script: remove 'svc'
checking.
Changes from v1:
* According to Mike and Rob suggestion, add the fixing to generate samples
for the start packet and exception packets.
* Simplify the python script to remove the exception prediction algorithm,
we can rely on the sane exception packets for disassembler.
Leo Yan (4):
perf cs-etm: Generate branch sample for missed packets
perf script python: Add addr into perf sample dict
perf script python: Add script for CoreSight trace disassembler
coresight: Document for CoreSight trace disassembler
Documentation/trace/coresight.txt | 52 +++++
tools/perf/scripts/python/arm-cs-trace-disasm.py | 235 +++++++++++++++++++++
tools/perf/util/cs-etm.c | 93 ++++++--
.../util/scripting-engines/trace-event-python.c | 2 +
4 files changed, 362 insertions(+), 20 deletions(-)
create mode 100644 tools/perf/scripts/python/arm-cs-trace-disasm.py
--
2.7.4
--
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
^ permalink raw reply
* Re: [PATCH v2 1/3] usb: gadget: ccid: add support for USB CCID Gadget Device
From: Marcus Folkesson @ 2018-05-28 8:38 UTC (permalink / raw)
To: Andrzej Pietrasiewicz
Cc: Greg Kroah-Hartman, Jonathan Corbet, Felipe Balbi, davem,
Mauro Carvalho Chehab, Andrew Morton, Randy Dunlap,
Ruslan Bilovol, Thomas Gleixner, Kate Stewart, linux-usb,
linux-doc, linux-kernel
In-Reply-To: <20180528070453eucas1p294be19abd2cab7d112404d15710edfde~yvQ5mevbz2769227692eucas1p2k@eucas1p2.samsung.com>
Hi Andrzej,
On Mon, May 28, 2018 at 09:04:51AM +0200, Andrzej Pietrasiewicz wrote:
> Mi Marcus,
>
> W dniu 26.05.2018 o 23:19, Marcus Folkesson pisze:
> > Chip Card Interface Device (CCID) protocol is a USB protocol that
> > allows a smartcard device to be connected to a computer via a card
> > reader using a standard USB interface, without the need for each manufacturer
> > of smartcards to provide its own reader or protocol.
> >
> > This gadget driver makes Linux show up as a CCID device to the host and let a
> > userspace daemon act as the smartcard.
> >
> > This is useful when the Linux gadget itself should act as a cryptographic
> > device or forward APDUs to an embedded smartcard device.
> >
> > Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
> > ---
>
> >
> > +config USB_CONFIGFS_CCID
> > + bool "Chip Card Interface Device (CCID)"
> > + depends on USB_CONFIGFS
> > + select USB_F_CCID
> > + help
> > + The CCID function driver provides generic emulation of a
> > + Chip Card Interface Device (CCID).
> > +
> > + You will need a user space server talking to /dev/ccidg*,
> > + since the kernel itself does not implement CCID/TPDU/APDU
> > + protocol.
>
> Your function needs a userspace daemon to work.
> It seems you want to use FunctionFS for such a purpose
> instead of creating a new function.
>
> Andrzej
> > + since the kernel itself does not implement CCID/TPDU/APDU
Oops, the driver does handle CCID.
Well, yes, It needs an application that perform the "smartcard operations", such as
generate keys or sign data, as this depends on how it should be used.
The actual smartcard operations could for example be in software,
use a crypto engine in SoC or external HSM (Hardware Security Module).
Without the application, the gadget shows up as a smart card reader
with an unconnected smartcard.
I guess it could be accomplished with FunctionFS as well.
Best regards
Marcus Folkesson
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* Re: [PATCH v2 2/3] Documentation: usb: add documentation for USB CCID Gadget Device
From: Marcus Folkesson @ 2018-05-28 7:42 UTC (permalink / raw)
To: Randy Dunlap
Cc: Greg Kroah-Hartman, Jonathan Corbet, Felipe Balbi, davem,
Mauro Carvalho Chehab, Andrew Morton, Ruslan Bilovol,
Thomas Gleixner, Kate Stewart, linux-usb, linux-doc, linux-kernel
In-Reply-To: <2225254e-a8f1-570e-8b1c-f68168376784@infradead.org>
Hi Randy,
On Sun, May 27, 2018 at 04:36:24PM -0700, Randy Dunlap wrote:
> Hi,
>
> I have a few documentation comments below...
>
> On 05/26/2018 02:19 PM, Marcus Folkesson wrote:
> > Add documentation to give a brief description on how to use the
> > CCID Gadget Device.
> > This includes a description for all attributes followed by an example on
> > how to setup the device with ConfigFS.
> >
> > Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
> > ---
> > 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 <marcus.folkesson@gmail.com>
> > +
> > +Introduction
> > +============
> > +
> > +The CCID Gadget will present itself as a CCID device to the host system.
> > +The device supports two endpoints for now; BULK IN and BULK OUT.
> > +These endpoints is exposed to userspace via /dev/ccidg*.
>
> are exposed
>
> > +
> > +All CCID commands are sent on the BULK-OUT endpoint. Each command sent to the CCID
> > +has an associated ending response. Some commands can also have intermediate
> > +responses. The response is sent on the BULK-IN endpoint.
> > +See Figure 3-3 in the CCID Specification [1]_ for more details.
> > +
> > +The CCID commands must be handled in userspace since the driver is only working
> > +as a transport layer for the TPDUs.
> > +
> > +
> > +CCID Commands
> > +--------------
> > +
> > +All CCID commands begins with a 10 bytes header followed by an optional
>
> with a 10-byte header
> (or maybe that's a locale difference)
>
> > +data field depending on message type.
> > +
> > ++--------+--------------+-------+----------------------------------+
> > +| Offset | Field | Size | Description |
> > ++========+==============+=======+==================================+
> > +| 0 | bMessageType | 1 | Type of message |
> > ++--------+--------------+-------+----------------------------------+
> > +| 1 | dwLength | 4 | Message specific data length |
> > +| | | | |
> > ++--------+--------------+-------+----------------------------------+
> > +| 5 | bSlot | 1 | Identifies the slot number |
> > +| | | | for this command |
> > ++--------+--------------+-------+----------------------------------+
> > +| 6 | bSeq | 1 | Sequence number for command |
> > ++--------+--------------+-------+----------------------------------+
> > +| 7 | ... | 3 | Fields depends on message type |
> > ++--------+--------------+-------+----------------------------------+
> > +| 10 | abData | array | Message specific data (OPTIONAL) |
> > ++--------+--------------+-------+----------------------------------+
> > +
> > +
> > +Multiple CCID gadgets
> > +----------------------
> > +
> > +It is possible to create multiple instances of the CCID gadget, however,
> > +a much more flexible way is to create one gadget and set the `nslots` attribute
> > +to the number of desired CCID devices.
> > +
> > +All CCID commands specifies which slot that is the receiver in the `bSlot` field
>
> specify which slot is the receiver
>
> > +of the CCID header.
> > +
> > +Usage
> > +=====
> > +
> > +Access from userspace
> > +----------------------
> > +All communication is by read(2) and write(2) to the corresponding /dev/ccidg* device.
> > +Only one filedescriptor is allowed to be open to the device at a time.
>
> file descriptor
>
> > +
> > +The buffer size provided to read(2) **must be at least** 522 (10 bytes header + 512 bytes payload)
> > +bytes as we are working with whole commands.
> > +
> > +The buffer size provided to write(2) **may not exceed** 522 (10 bytes header + 512 bytes payload)
> > +bytes as we are working with whole commands.
> > +
> > +
> > +Configuration with configfs
> > +----------------------------
> > +
> > +ConfigFS is used to create and configure the CCID gadget.
> > +In order to get a device to work as intended, a few attributes must
> > +be considered.
> > +
> > +The attributes is described below followed by an example.
>
> are
>
> > +
> > +features
> > +~~~~~~~~~
> > +
> > +The `feature` attribute writes to the dwFeatures field in the class descriptor.
> > +See Table 5.1-1 Smart Card Device Descriptors in the CCID Specification [1]_.
> > +
> > +The value indicates what intelligent features the CCID has.
> > +These values are available to user application as defines in ccid.h [2]_.
>
> as defined
>
> > +The default value is 0x00000000.
>
>
> [snip]
>
> HTH.
> --
> ~Randy
Thank you for your comments, I will take it with me for v3.
Best regards
Marcus Folkesson
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* Re: [PATCH v2 1/3] usb: gadget: ccid: add support for USB CCID Gadget Device
From: Andrzej Pietrasiewicz @ 2018-05-28 7:04 UTC (permalink / raw)
To: Marcus Folkesson, Greg Kroah-Hartman, Jonathan Corbet,
Felipe Balbi, davem, Mauro Carvalho Chehab, Andrew Morton,
Randy Dunlap, Ruslan Bilovol, Thomas Gleixner, Kate Stewart
Cc: linux-usb, linux-doc, linux-kernel
In-Reply-To: <20180526211940.25474-1-marcus.folkesson@gmail.com>
Mi Marcus,
W dniu 26.05.2018 o 23:19, Marcus Folkesson pisze:
> Chip Card Interface Device (CCID) protocol is a USB protocol that
> allows a smartcard device to be connected to a computer via a card
> reader using a standard USB interface, without the need for each manufacturer
> of smartcards to provide its own reader or protocol.
>
> This gadget driver makes Linux show up as a CCID device to the host and let a
> userspace daemon act as the smartcard.
>
> This is useful when the Linux gadget itself should act as a cryptographic
> device or forward APDUs to an embedded smartcard device.
>
> Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
> ---
>
> +config USB_CONFIGFS_CCID
> + bool "Chip Card Interface Device (CCID)"
> + depends on USB_CONFIGFS
> + select USB_F_CCID
> + help
> + The CCID function driver provides generic emulation of a
> + Chip Card Interface Device (CCID).
> +
> + You will need a user space server talking to /dev/ccidg*,
> + since the kernel itself does not implement CCID/TPDU/APDU
> + protocol.
Your function needs a userspace daemon to work.
It seems you want to use FunctionFS for such a purpose
instead of creating a new function.
Andrzej
--
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
^ permalink raw reply
* Re: [PATCH v2 2/3] Documentation: usb: add documentation for USB CCID Gadget Device
From: Randy Dunlap @ 2018-05-27 23:36 UTC (permalink / raw)
To: Marcus Folkesson, Greg Kroah-Hartman, Jonathan Corbet,
Felipe Balbi, davem, Mauro Carvalho Chehab, Andrew Morton,
Ruslan Bilovol, Thomas Gleixner, Kate Stewart
Cc: linux-usb, linux-doc, linux-kernel
In-Reply-To: <20180526211940.25474-2-marcus.folkesson@gmail.com>
Hi,
I have a few documentation comments below...
On 05/26/2018 02:19 PM, Marcus Folkesson wrote:
> Add documentation to give a brief description on how to use the
> CCID Gadget Device.
> This includes a description for all attributes followed by an example on
> how to setup the device with ConfigFS.
>
> Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
> ---
> 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 <marcus.folkesson@gmail.com>
> +
> +Introduction
> +============
> +
> +The CCID Gadget will present itself as a CCID device to the host system.
> +The device supports two endpoints for now; BULK IN and BULK OUT.
> +These endpoints is exposed to userspace via /dev/ccidg*.
are exposed
> +
> +All CCID commands are sent on the BULK-OUT endpoint. Each command sent to the CCID
> +has an associated ending response. Some commands can also have intermediate
> +responses. The response is sent on the BULK-IN endpoint.
> +See Figure 3-3 in the CCID Specification [1]_ for more details.
> +
> +The CCID commands must be handled in userspace since the driver is only working
> +as a transport layer for the TPDUs.
> +
> +
> +CCID Commands
> +--------------
> +
> +All CCID commands begins with a 10 bytes header followed by an optional
with a 10-byte header
(or maybe that's a locale difference)
> +data field depending on message type.
> +
> ++--------+--------------+-------+----------------------------------+
> +| Offset | Field | Size | Description |
> ++========+==============+=======+==================================+
> +| 0 | bMessageType | 1 | Type of message |
> ++--------+--------------+-------+----------------------------------+
> +| 1 | dwLength | 4 | Message specific data length |
> +| | | | |
> ++--------+--------------+-------+----------------------------------+
> +| 5 | bSlot | 1 | Identifies the slot number |
> +| | | | for this command |
> ++--------+--------------+-------+----------------------------------+
> +| 6 | bSeq | 1 | Sequence number for command |
> ++--------+--------------+-------+----------------------------------+
> +| 7 | ... | 3 | Fields depends on message type |
> ++--------+--------------+-------+----------------------------------+
> +| 10 | abData | array | Message specific data (OPTIONAL) |
> ++--------+--------------+-------+----------------------------------+
> +
> +
> +Multiple CCID gadgets
> +----------------------
> +
> +It is possible to create multiple instances of the CCID gadget, however,
> +a much more flexible way is to create one gadget and set the `nslots` attribute
> +to the number of desired CCID devices.
> +
> +All CCID commands specifies which slot that is the receiver in the `bSlot` field
specify which slot is the receiver
> +of the CCID header.
> +
> +Usage
> +=====
> +
> +Access from userspace
> +----------------------
> +All communication is by read(2) and write(2) to the corresponding /dev/ccidg* device.
> +Only one filedescriptor is allowed to be open to the device at a time.
file descriptor
> +
> +The buffer size provided to read(2) **must be at least** 522 (10 bytes header + 512 bytes payload)
> +bytes as we are working with whole commands.
> +
> +The buffer size provided to write(2) **may not exceed** 522 (10 bytes header + 512 bytes payload)
> +bytes as we are working with whole commands.
> +
> +
> +Configuration with configfs
> +----------------------------
> +
> +ConfigFS is used to create and configure the CCID gadget.
> +In order to get a device to work as intended, a few attributes must
> +be considered.
> +
> +The attributes is described below followed by an example.
are
> +
> +features
> +~~~~~~~~~
> +
> +The `feature` attribute writes to the dwFeatures field in the class descriptor.
> +See Table 5.1-1 Smart Card Device Descriptors in the CCID Specification [1]_.
> +
> +The value indicates what intelligent features the CCID has.
> +These values are available to user application as defines in ccid.h [2]_.
as defined
> +The default value is 0x00000000.
[snip]
HTH.
--
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* [PATCH 4/5] doc:it_IT: add doc-guide translation
From: Federico Vaga @ 2018-05-27 14:55 UTC (permalink / raw)
To: Jonathan Corbet
Cc: linux-doc, linux-kernel, Alessia Mantegazza, Federico Vaga
In-Reply-To: <20180527145559.16411-1-federico.vaga@vaga.pv.it>
Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Alessia Mantegazza <amantegazza@vaga.pv.it>
---
.../translations/it_IT/doc-guide/hello.dot | 3 +
.../translations/it_IT/doc-guide/index.rst | 24 ++
.../translations/it_IT/doc-guide/kernel-doc.rst | 402 ++++++++++++++++++
| 196 +++++++++
.../translations/it_IT/doc-guide/sphinx.rst | 455 +++++++++++++++++++++
.../translations/it_IT/doc-guide/svg_image.svg | 1 +
Documentation/translations/it_IT/index.rst | 8 +
7 files changed, 1089 insertions(+)
create mode 100644 Documentation/translations/it_IT/doc-guide/hello.dot
create mode 100644 Documentation/translations/it_IT/doc-guide/index.rst
create mode 100644 Documentation/translations/it_IT/doc-guide/kernel-doc.rst
create mode 100644 Documentation/translations/it_IT/doc-guide/parse-headers.rst
create mode 100644 Documentation/translations/it_IT/doc-guide/sphinx.rst
create mode 120000 Documentation/translations/it_IT/doc-guide/svg_image.svg
diff --git a/Documentation/translations/it_IT/doc-guide/hello.dot b/Documentation/translations/it_IT/doc-guide/hello.dot
new file mode 100644
index 000000000000..eee1e5864b3e
--- /dev/null
+++ b/Documentation/translations/it_IT/doc-guide/hello.dot
@@ -0,0 +1,3 @@
+graph G {
+ Ciao -- Mondo
+}
diff --git a/Documentation/translations/it_IT/doc-guide/index.rst b/Documentation/translations/it_IT/doc-guide/index.rst
new file mode 100644
index 000000000000..7a6562b547ee
--- /dev/null
+++ b/Documentation/translations/it_IT/doc-guide/index.rst
@@ -0,0 +1,24 @@
+.. include:: ../disclaimer-ita.rst
+
+.. note:: Per leggere la documentazione originale in inglese:
+ :ref:`Documentation/doc-guide/index.rst <doc_guide>`
+
+.. _it_doc_guide:
+
+==========================================
+Come scrivere la documentazione del kernel
+==========================================
+
+.. toctree::
+ :maxdepth: 1
+
+ sphinx.rst
+ kernel-doc.rst
+ parse-headers.rst
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
new file mode 100644
index 000000000000..77f6ec7aa38d
--- /dev/null
+++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
@@ -0,0 +1,402 @@
+.. include:: ../disclaimer-ita.rst
+
+.. note:: Per leggere la documentazione originale in inglese:
+ :ref:`Documentation/doc-guide/index.rst <doc_guide>`
+
+Includere i commenti di tipo kernel-doc
+=======================================
+
+I sorgenti del kernel Linux possono contenere commenti strutturati per
+la documentazione, oppure commenti di tipo kernel-doc che descrivono
+le funzioni, i tipi e la struttura del codice. I commenti di documentazione
+possono essere aggiunti ad un qualsiasi documento reStructuredtext
+utilizzando l'apposita estensione Sphinx per le direttive kernel-doc.
+
+Le direttive kernel-doc sono nel formato::
+
+ .. kernel-doc:: source
+ :option:
+
+Il campo *source* è il percorso ad un file sorgente, relativo alla cartella
+principale dei sorgenti del kernel. La direttiva supporta le seguenti opzioni:
+
+
+export: *[source-pattern ...]*
+ Include la documentazione per tutte le funzioni presenti nel file sorgente
+ (*source*) che sono state esportate utilizzando ``EXPORT_SYMBOL`` o
+ ``EXPORT_SYMBOL_GPL`` in *source* o in qualsiasi altro *source-pattern*
+ specificato.
+
+ Il campo *source-patter* è utile quando i commenti kernel-doc sono stati
+ scritti nei file d'intestazione, mentre ``EXPORT_SYMBOL`` e
+ ``EXPORT_SYMBOL_GPL`` si trovano vicino alla definizione delle funzioni.
+
+ Esempi::
+
+ .. kernel-doc:: lib/bitmap.c
+ :export:
+
+ .. kernel-doc:: include/net/mac80211.h
+ :export: net/mac80211/*.c
+
+internal: *[source-pattern ...]*
+ Include la documentazione per tutte le funzioni ed i tipi presenti nel file
+ sorgente (*source*) che **non** sono stati esportati utilizzando
+ ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` né in *source* né in qualsiasi
+ altro *source-pattern* specificato.
+
+ Esempio::
+
+ .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
+ :internal:
+
+doc: *title*
+ Include la documentazione per il paragrafo ``DOC:`` identificato dal titolo
+ (*title*) all'interno del file sorgente (*source*). Gli spazi in *title* sono
+ permessi; non virgolettate *title*. Il campo *title* è utilizzato per
+ identificare un paragrafo e per questo non viene incluso nella documentazione
+ finale. Verificate d'avere l'intestazione appropriata nei documenti
+ reStructuredText.
+
+ Esempio::
+
+ .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
+ :doc: High Definition Audio over HDMI and Display Port
+
+functions: *function* *[...]*
+ Dal file sorgente (*source*) include la documentazione per le funzioni elencate
+ (*function*).
+
+ Esempio::
+
+ .. kernel-doc:: lib/bitmap.c
+ :functions: bitmap_parselist bitmap_parselist_user
+
+Senza alcuna opzione, la direttiva kernel-doc include tutti i commenti di
+documentazione presenti nel file sorgente (*source*).
+
+L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare
+in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato
+lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione
+dai file sorgenti.
+
+.. _it_kernel_doc:
+
+Scrivere i commenti in kernel-doc
+=================================
+
+Al fine di fornire una documentazione integrata, orientata al C, facile da
+mantenere, ma al contempo consistente e frazionabile, per le funzioni
+ed i tipi, il kernel Linux mantiene uno stile consistente per i commenti
+di documentazione. Il formato per questa documentazione è chiamato kernel-doc,
+ed è descritto di seguito. Questo stile incorpora la documentazione
+all'interno dei file sorgenti; esso utilizza poche e semplici convenzioni
+per l'aggiunta di paragrafi di documentazione e per documentare le funzioni
+ed i loro parametri, le strutture e le unioni coi loro membri, le enumerazioni,
+ed i tipi di dato.
+
+.. note:: Il formato kernel-doc può sembrare simile a gtk-doc o Doxygen ma
+ in realtà è molto differente per ragioni storiche. I sorgenti del kernel
+ contengono decine di migliaia di commenti kernel-doc. Siete pregati
+ d'attenervi allo stile qui descritto.
+
+Durante la generazione della documentazione nei vari formati HTML, PDF,
+od altri, l'estensione kernel-doc per Sphinx utilizza lo script
+``scripts/kernel-doc`` per l'estrazione della documentazione dai sorgenti.
+
+Allo scopo d'avere una buona documentazione delle funzioni e delle strutture dati
+del kernel, siete pregati di formattare i vostri commenti kernel-doc nei sorgenti
+del kernel Linux secondo le seguenti convenzioni
+
+Formato dei commenti in kernel-doc
+----------------------------------
+
+L'utilizzo di ``/**``come inizio di un commento è riservato unicamente ai
+commenti kernel-doc. Solo i commenti così indicati verranno presi in
+considerazione dal programma ``kernel-doc``. Utilizzate questa forma solo
+per i blocchi di commenti formattati nel formato kernel-doc. Il tipico
+``*/`` dovrebbe essere utilizzato per chiudere il blocco di commenti.
+Tutte le linee comprese fra questi due marcatori dovrebbero avere come
+prefisso ``_*_`` (spazio asterisco spazio).
+
+Si suggerisce di posizionare i commenti kernel-doc appena prima della
+funzione o del tipo di dato che descrivono. I commenti generici di tipo
+kernel-doc possono essere posizionati liberamente.
+
+Esempio di un commento kernel-doc per una funzione::
+
+ /**
+ * foobar() - Brief description of foobar.
+ * @arg: Description of argument of foobar.
+ *
+ * Longer description of foobar.
+ *
+ * Return: Description of return value of foobar.
+ */
+ int foobar(int arg)
+
+Il formato è simile anche per la documentazione di strutture dati, enumerati,
+paragrafi, eccetera. Consultate la sezione successiva per maggiori dettagli.
+
+La struttura kernel-doc è estratta a partire dai commenti; da questi viene
+generato il `dominio Sphinx per il C`_ con un'adeguata descrizione per le funzioni
+e i tipi di dato con i loro relativi collegamenti.
+
+.. _`dominio Sphinx per il C`: http://www.sphinx-doc.org/en/stable/domains.html
+
+Evidenziare codice e riferimenti
+--------------------------------
+
+All'interno dei commenti di tipo kernel-doc vengono riconosciuti i seguenti
+*pattern* che vengono convertiti in marcatori reStructuredText ed in riferimenti
+del `dominio Sphinx per il C`_.
+
+.. attention:: Questi sono riconosciuti **solo** all'interno di commenti
+ kernel-doc, e **non** all'interno di documenti reStructuredText.
+
+``funcname()``
+ Riferimento ad una funzione.
+
+``@parameter``
+ Nome di un parametro di una funzione (nessun riferimento, solo formattazione).
+
+``%CONST``
+ Il nome di una costante (nessun riferimento, solo formattazione)
+
+````literal````
+ Un blocco di testo che deve essere riportato così com'è. La rappresentazione
+ finale utilizzerà caratteri a ``spaziatura fissa``.
+
+ Questo è utile se dovete utilizzare caratteri speciali che altrimenti
+ potrebbero assumere un significato diverso in kernel-doc o in reStructuredText
+
+ Questo è particolarmente utile se dovete scrivere qualcosa come ``%ph``
+ all'interno della descrizione di una funzione.
+
+``$ENVVAR``
+ Il nome di una variabile d'ambiente (nessun riferimento, solo formattazione).
+
+``&struct name``
+ Riferimento ad una struttura.
+
+``&enum name``
+ Riferimento ad un'enumerazione.
+
+``&typedef name``
+ Riferimento ad un tipo di dato.
+
+``&struct_name->member`` or ``&struct_name.member``
+ Riferimento ad un membro di una struttura o di un'unione. Il riferimento sarà
+ la struttura o l'unione, non il memembro.
+
+``&name``
+ Un generico riferimento ad un tipo. Usate, preferibilmente, il riferimento
+ completo come descritto sopra. Questo è dedicato ai commenti obsoleti.
+
+Riferimenti usando reStructuredText
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Per fare riferimento a funzioni e tipi di dato definiti nei commenti kernel-doc
+all'interno dei documenti reStructuredText, utilizzate i riferimenti dal
+`dominio Sphinx per il C`_. Per esempio::
+
+ See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
+
+Nonostante il riferimento ai tipi di dato funzioni col solo nome,
+ovvero senza specificare struct/union/enum/typedef, potreste preferire il
+seguente::
+
+ See :c:type:`struct foo <foo>`.
+ See :c:type:`union bar <bar>`.
+ See :c:type:`enum baz <baz>`.
+ See :c:type:`typedef meh <meh>`.
+
+Questo produce dei collegamenti migliori, ed è in linea con il modo in cui
+kernel-doc gestisce i riferimenti.
+
+Per maggiori informazioni, siete pregati di consultare la documentazione
+del `dominio Sphinx per il C`_.
+
+Documentare le funzioni
+------------------------
+
+Generalmente il formato di un commento kernel-doc per funzioni e
+macro simil-funzioni è il seguente::
+
+ /**
+ * function_name() - Brief description of function.
+ * @arg1: Describe the first argument.
+ * @arg2: Describe the second argument.
+ * One can provide multiple line descriptions
+ * for arguments.
+ *
+ * A longer description, with more discussion of the function function_name()
+ * that might be useful to those using or modifying it. Begins with an
+ * empty comment line, and may include additional embedded empty
+ * comment lines.
+ *
+ * The longer description may have multiple paragraphs.
+ *
+ * Return: Describe the return value of foobar.
+ *
+ * The return value description can also have multiple paragraphs, and should
+ * be placed at the end of the comment block.
+ */
+
+La breve descrizione (*brief description*) che segue il nome della funzione può
+continuare su righe successive; essa termina con la descrizione di un argomento
+``@argument:``, una linea di commento vuota, oppure la fine del blocco di
+commenti.
+
+Un commento kernel-doc per una funzione descrive ogni suo parametro, in ordine,
+utilizzando i descrittori ``@argument:``. I descrittori
+``@argument:`` devono iniziare immediatamente dopo la breve descrizione
+iniziale, senza lasciare alcuna riga vuota. I descrittori ``@argument:``
+possono estendersi su linee successive. La continuazione su d'una riga
+successiva può essere indentata. Se il parametro di una funzione dovesse essere
+``...`` (varargs), devete utilizzare la notazione kernel-doc ``@...:``.
+
+Il valore di ritorno, se presente, dev'essere descritto in una sezione dedicata
+situata alla fine del commenti e che inizia con "Return:"
+
+Documentare strutture, unioni ed enumerazioni
+---------------------------------------------
+Generalmente il formato di un commento kernel-doc per struct, union ed enum è::
+
+ /**
+ * struct struct_name - Brief description.
+ * @member_name: Description of member member_name.
+ *
+ * Description of the structure.
+ */
+
+Successivamente, "struct" verrà utilizzato per indicare strutture, unioni ed
+enumerazioni, mentre "member" verrà utilizzato per indicare i membri di
+strutture ed unioni così come i valori di un'enumerazione.
+
+La breve descrizione che segue il nome della struttura può estendersi su righe
+successive, e terminare con ``@member:``, una riga vuota, o la fine del blocco
+di commento.
+
+Un commento kernel-doc per una struttura dati descrive ogni suo membro, in ordine,
+utilizzando ``@member:``. Le descrizioni ``@member:`` devono iniziare
+immediatamente dopo la breve descrizione della struttura, senza lasciare alcuna
+riga vuota. Le descrizioni ``@member:`` possono estendersi su righe successive.
+La continuazione delle righe può essere indentata.
+
+Documentare i campi con commenti in-linea
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+I membri di una struttura possono essere documentati utilizzando commenti
+all'interno della definizione stessa. Ci sono due stili, un commento su d'una
+singola riga iniziato con ``/**`` e chiuso con ``*/`` sulla stessa riga,
+oppure commenti su più righe, come ogni altro commento kernel-doc::
+
+ /**
+ * struct foo - Brief description.
+ * @foo: The Foo member.
+ */
+ struct foo {
+ int foo;
+ /**
+ * @bar: The Bar member.
+ */
+ int bar;
+ /**
+ * @baz: The Baz member.
+ *
+ * Here, the member description may contain several paragraphs.
+ */
+ int baz;
+ /** @foobar: Single line description. */
+ int foobar;
+ }
+
+Documentare i campi privati
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+All'interno della descrizione d'una struttura, potete usare le etichette
+"private:" e "public:". I campi d'una struttura che si trovano all'interno
+di un'area privata "private:" non verranno inclusi nella documentazione finale.
+Le etichette "private:" e "public:" devono trovarsi immediatamente dopo
+il marcatore d'inizio commento ``/*``. Facoltativamente, si possono includere
+commenti fra ``:`` e il marcatore di fine commento ``*/``
+
+Esempio::
+
+ /**
+ * struct my_struct - short description
+ * @a: first member
+ * @b: second member
+ *
+ * Longer description
+ */
+ struct my_struct {
+ int a;
+ int b;
+ /* private: internal use only */
+ int c;
+ };
+
+
+Documentazione dei tipi di dato
+-------------------------------
+Generalmente il formato di un commento kernel-doc per typedef è
+il seguente::
+
+ /**
+ * typedef type_name - Brief description.
+ *
+ * Description of the type.
+ */
+
+Commenti per una documentazione generale
+----------------------------------------
+
+Al fine d'avere il codice ed i commenti nello stesso file, potete includere
+dei blocchi di documentazione kernel-doc con un formato libero invece
+che nel formato specifico per funzioni, strutture, unioni, enumerati o tipi
+di dato.
+
+Per esempio, questo tipo di commento potrebbe essere usato per la spiegazione
+delle operazioni di un driver o di una libreria
+
+Questo s'ottiene utilizzando la parola chiave ``DOC:`` a cui viene associato
+un titolo.
+
+Generalmente il formato di un commento generico o di visione d'insieme è
+il seguente::
+
+ /**
+ * DOC: Theory of Operation
+ *
+ * The whizbang foobar is a dilly of a gizmo. It can do whatever you
+ * want it to do, at any time. It reads your mind. Here's how it works.
+ *
+ * foo bar splat
+ *
+ * The only drawback to this gizmo is that is can sometimes damage
+ * hardware, software, or its subject(s).
+ */
+
+Il titolo che segue ``DOC:`` funziona da intestazione all'interno del file
+sorgente, ma anche come identificatore per l'estrazione di questi commenti di
+documentazione. Quindi, il titolo dev'essere unico all'interno del file.
+
+Raccomandazioni
+---------------
+
+Sicuramente la documentazione formattata con kernel-doc è necessaria per
+le funzioni che sono esportate verso i moduli esterni utilizzando
+``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL``.
+
+Cerchiamo anche di fornire una documentazione formattata secondo kernel-doc
+per le funzioni che sono visibili da altri file del kernel (ovvero, che non
+siano dichiarate utilizzando "static")
+
+Raccomandiamo, inoltre, di fornire una documentazione formattata con kernel-doc
+anche per procedure private (ovvero, dichiarate "static") al fine di fornire
+una struttura consistente dei sorgenti. Questa raccomandazione ha una priorità
+più bassa ed è a discrezione dal manutentore (MAINTAINER) del file sorgente.
+
+Le strutture dati visibili nei file di intestazione dovrebbero essere anch'esse
+documentate utilizzando commenti formattati con kernel-doc.
--git a/Documentation/translations/it_IT/doc-guide/parse-headers.rst b/Documentation/translations/it_IT/doc-guide/parse-headers.rst
new file mode 100644
index 000000000000..dfe6dc8d2c6c
--- /dev/null
+++ b/Documentation/translations/it_IT/doc-guide/parse-headers.rst
@@ -0,0 +1,196 @@
+.. include:: ../disclaimer-ita.rst
+
+.. note:: Per leggere la documentazione originale in inglese:
+ :ref:`Documentation/doc-guide/index.rst <doc_guide>`
+
+=========================================
+Includere gli i file di intestazione uAPI
+=========================================
+
+Qualche volta è utile includere dei file di intestazione e degli esempi di codice C
+al fine di descrivere l'API per lo spazio utente e per generare dei riferimenti
+fra il codice e la documentazione. Aggiungere i riferimenti ai file dell'API
+dello spazio utente ha ulteriori vantaggi: Sphinx genererà dei messaggi
+d'avviso se un simbolo non viene trovato nella documentazione. Questo permette
+di mantenere allineate la documentazione della uAPI (API spazio utente)
+con le modifiche del kernel.
+Il programma :ref:`parse_headers.pl <it_parse_headers>` genera questi riferimenti.
+Esso dev'essere invocato attraverso un Makefile, mentre si genera la
+documentazione. Per avere un esempio su come utilizzarlo all'interno del kernel
+consultate ``Documentation/media/Makefile``.
+
+.. _it_parse_headers:
+
+parse_headers.pl
+^^^^^^^^^^^^^^^^
+
+NOME
+****
+
+
+parse_headers.pl - analizza i file C al fine di identificare funzioni,
+strutture, enumerati e definizioni, e creare riferimenti per Sphinx
+
+SINTASSI
+********
+
+
+\ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
+
+Dove <options> può essere: --debug, --usage o --help.
+
+
+OPZIONI
+*******
+
+
+
+\ **--debug**\
+
+ Lo script viene messo in modalità verbosa, utile per il debugging.
+
+
+\ **--usage**\
+
+ Mostra un messaggio d'aiuto breve e termina.
+
+
+\ **--help**\
+
+ Mostra un messaggio d'aiuto dettagliato e termina.
+
+
+DESCRIZIONE
+***********
+
+Converte un file d'intestazione o un file sorgente C (C_FILE) in un testo
+ReStructuredText incluso mediante il blocco ..parsed-literal
+con riferimenti alla documentazione che descrive l'API. Opzionalmente,
+il programma accetta anche un altro file (EXCEPTIONS_FILE) che
+descrive quali elementi debbano essere ignorati o il cui riferimento
+deve puntare ad elemento diverso dal predefinito.
+
+Il file generato sarà disponibile in (OUT_FILE).
+
+Il programma è capace di identificare *define*, funzioni, strutture,
+tipi di dato, enumerati e valori di enumerati, e di creare i riferimenti
+per ognuno di loro. Inoltre, esso è capace di distinguere le #define
+utilizzate per specificare i comandi ioctl di Linux.
+
+Il file EXCEPTIONS_FILE contiene due tipi di dichiarazioni:
+\ **ignore**\ o \ **replace**\ .
+
+La sintassi per ignore è:
+
+ignore \ **tipo**\ \ **nome**\
+
+La dichiarazione \ **ignore**\ significa che non verrà generato alcun
+riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ .
+
+
+La sintassi per replace è:
+
+replace \ **tipo**\ \ **nome**\ \ **nuovo_valore**\
+
+La dichiarazione \ **replace**\ significa che verrà generato un
+riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ , ma, invece
+di utilizzare il valore predefinito, verrà utilizzato il valore
+\ **nuovo_valore**\ .
+
+Per entrambe le dichiarazioni, il \ **tipo**\ può essere uno dei seguenti:
+
+
+\ **ioctl**\
+
+ La dichiarazione ignore o replace verrà applicata su definizioni di ioctl
+ come la seguente:
+
+ #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)
+
+
+
+\ **define**\
+
+ La dichiarazione ignore o replace verrà applicata su una qualsiasi #define
+ trovata in C_FILE.
+
+
+
+\ **typedef**\
+
+ La dichiarazione ignore o replace verrà applicata ad una dichiarazione typedef
+ in C_FILE.
+
+
+
+\ **struct**\
+
+ La dichiarazione ignore o replace verrà applicata ai nomi di strutture
+ in C_FILE.
+
+
+
+\ **enum**\
+
+ La dichiarazione ignore o replace verrà applicata ai nomi di enumerati
+ in C_FILE.
+
+
+
+\ **symbol**\
+
+ La dichiarazione ignore o replace verrà applicata ai nomi di valori di
+ enumerati in C_FILE.
+
+ Per le dichiarazioni di tipo replace, il campo \ **new_value**\ utilizzerà
+ automaticamente i riferimenti :c:type: per \ **typedef**\ , \ **enum**\ e
+ \ **struct**\. Invece, utilizzerà :ref: per \ **ioctl**\ , \ **define**\ e
+ \ **symbol**\. Il tipo di riferimento può essere definito esplicitamente
+ nella dichiarazione stessa.
+
+
+ESEMPI
+******
+
+
+ignore define _VIDEODEV2_H
+
+
+Ignora una definizione #define _VIDEODEV2_H nel file C_FILE.
+
+ignore symbol PRIVATE
+
+
+In un enumerato come il seguente:
+
+enum foo { BAR1, BAR2, PRIVATE };
+
+Non genererà alcun riferimento per \ **PRIVATE**\ .
+
+replace symbol BAR1 :c:type:\`foo\`
+replace symbol BAR2 :c:type:\`foo\`
+
+
+In un enumerato come il seguente:
+
+enum foo { BAR1, BAR2, PRIVATE };
+
+Genererà un riferimento ai valori BAR1 e BAR2 dal simbolo foo nel dominio C.
+
+
+BUGS
+****
+
+Riferire ogni malfunzionamento a Mauro Carvalho Chehab <mchehab@s-opensource.com>
+
+
+COPYRIGHT
+*********
+
+
+Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
+
+License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
+
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst
new file mode 100644
index 000000000000..94de4b244405
--- /dev/null
+++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst
@@ -0,0 +1,455 @@
+.. include:: ../disclaimer-ita.rst
+
+.. note:: Per leggere la documentazione originale in inglese:
+ :ref:`Documentation/doc-guide/index.rst <doc_guide>`
+
+Introduzione
+============
+
+Il kernel Linux usa `Sphinx`_ per la generazione della documentazione a partire
+dai file `reStructuredText`_ che si trovano nella cartella ``Documentation``.
+Per generare la documentazione in HTML o PDF, usate comandi ``make htmldocs`` o
+``make pdfdocs``. La documentazione così generata sarà disponibile nella
+cartella ``Documentation/output``.
+
+.. _Sphinx: http://www.sphinx-doc.org/
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+
+I file reStructuredText possono contenere delle direttive che permettono di
+includere i commenti di documentazione, o di tipo kernel-doc, dai file sorgenti.
+Solitamente questi commenti sono utilizzati per descrivere le funzioni, i tipi
+e l'architettura del codice. I commenti di tipo kernel-doc hanno una struttura
+e formato speciale, ma a parte questo vengono processati come reStructuredText.
+
+Inoltre, ci sono migliaia di altri documenti in formato testo sparsi nella
+cartella ``Documentation``. Alcuni di questi verranno probabilmente convertiti,
+nel tempo, in formato reStructuredText, ma la maggior parte di questi rimarranno
+in formato testo.
+
+.. _it_sphinx_install:
+
+Installazione Sphinx
+====================
+
+I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere
+processati da ``Sphinx`` nella versione 1.3 o superiore. Se desiderate produrre
+un documento PDF è raccomandato l'utilizzo di una versione superiore alle 1.4.6.
+
+Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli
+consultate :ref:`it_sphinx-pre-install`.
+
+La maggior parte delle distribuzioni Linux forniscono Sphinx, ma l'insieme dei
+programmi e librerie è fragile e non è raro che dopo un aggiornamento di
+Sphinx, o qualche altro pacchetto Python, la documentazione non venga più
+generata correttamente.
+
+Un modo per evitare questo genere di problemi è quello di utilizzare una
+versione diversa da quella fornita dalla vostra distribuzione. Per fare questo,
+vi raccomandiamo di installare Sphinx dentro ad un ambiente virtuale usando
+``virtualenv-3`` o ``virtualenv`` a seconda di come Python 3 è stato
+pacchettizzato dalla vostra distribuzione.
+
+.. note::
+
+ #) Le versioni di Sphinx inferiori alla 1.5 non funzionano bene
+ con il pacchetto Python docutils versione 0.13.1 o superiore.
+ Se volete usare queste versioni, allora dovere eseguire
+ ``pip install 'docutils==0.12'``.
+
+ #) Viene raccomandato l'uso del tema RTD per la documentazione in HTML.
+ A seconda della versione di Sphinx, potrebbe essere necessaria
+ l'installazione tramite il comando ``pip install sphinx_rtd_theme``.
+
+ #) Alcune pagine ReST contengono delle formule matematiche. A causa del
+ modo in cui Sphinx funziona, queste espressioni sono scritte
+ utilizzando LaTeX. Per una corretta interpretazione, è necessario aver
+ installato texlive con i pacchetti amdfonts e amsmath.
+
+Riassumendo, se volete installare la versione 1.4.9 di Sphinx dovete eseguire::
+
+ $ virtualenv sphinx_1.4
+ $ . sphinx_1.4/bin/activate
+ (sphinx_1.4) $ pip install -r Documentation/sphinx/requirements.txt
+
+Dopo aver eseguito ``. sphinx_1.4/bin/activate``, il prompt cambierà per
+indicare che state usando il nuovo ambiente. Se aprite un nuova sessione,
+prima di generare la documentazione, dovrete rieseguire questo comando per
+rientrare nell'ambiente virtuale.
+
+Generazione d'immagini
+----------------------
+
+Il meccanismo che genera la documentazione del kernel contiene un'estensione
+capace di gestire immagini in formato Graphviz e SVG (per maggior informazioni
+vedere :ref:`it_sphinx_kfigure`).
+
+Per far si che questo funzioni, dovete installare entrambe i pacchetti
+Graphviz e ImageMagick. Il sistema di generazione della documentazione è in
+grado di procedere anche se questi pacchetti non sono installati, ma il
+risultato, ovviamente, non includerà le immagini.
+
+Generazione in PDF e LaTeX
+--------------------------
+
+Al momento, la generazione di questi documenti è supportata solo dalle
+versioni di Sphinx superiori alla 1.4.
+
+Per la generazione di PDF e LaTeX, avrete bisogno anche del pacchetto
+``XeLaTeX`` nella versione 3.14159265
+
+Per alcune distribuzioni Linux potrebbe essere necessario installare
+anche una serie di pacchetti ``texlive`` in modo da fornire il supporto
+minimo per il funzionamento di ``XeLaTeX``.
+
+.. _it_sphinx-pre-install:
+
+Verificare le dipendenze Sphinx
+-------------------------------
+
+Esiste uno script che permette di verificare automaticamente le dipendenze di
+Sphinx. Se lo script riesce a riconoscere la vostra distribuzione, allora
+sarà in grado di darvi dei suggerimenti su come procedere per completare
+l'installazione::
+
+ $ ./scripts/sphinx-pre-install
+ Checking if the needed tools for Fedora release 26 (Twenty Six) are available
+ Warning: better to also install "texlive-luatex85".
+ You should run:
+
+ sudo dnf install -y texlive-luatex85
+ /usr/bin/virtualenv sphinx_1.4
+ . sphinx_1.4/bin/activate
+ pip install -r Documentation/sphinx/requirements.txt
+
+ Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
+
+L'impostazione predefinita prevede il controllo dei requisiti per la generazione
+di documenti html e PDF, includendo anche il supporto per le immagini, le
+espressioni matematiche e LaTeX; inoltre, presume che venga utilizzato un
+ambiente virtuale per Python. I requisiti per generare i documenti html
+sono considerati obbligatori, gli altri sono opzionali.
+
+Questo script ha i seguenti parametri:
+
+``--no-pdf``
+ Disabilita i controlli per la generazione di PDF;
+
+``--no-virtualenv``
+ Utilizza l'ambiente predefinito dal sistema operativo invece che
+ l'ambiente virtuale per Python;
+
+
+Generazione della documentazione Sphinx
+=======================================
+
+Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi
+comandi ``make htmldocs`` o ``make pdfdocs``. Esistono anche altri formati
+in cui è possibile generare la documentazione; per maggiori informazioni
+potere eseguire il comando ``make help``.
+La documentazione così generata sarà disponibile nella sottocartella
+``Documentation/output``.
+
+Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``)
+dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx
+verrà utilizzato per ottenere una documentazione HTML più gradevole.
+Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX`
+e di ``convert(1)`` disponibile in ImageMagick (https://www.imagemagick.org).
+Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle
+distribuzioni Linux.
+
+Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile
+make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante
+la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``.
+
+Potete eliminare la documentazione generata tramite il comando ``make cleandocs``.
+
+Scrivere la documentazione
+==========================
+
+Aggiungere nuova documentazione è semplice:
+
+1. aggiungete un file ``.rst`` nella sottocartella ``Documentation``
+2. aggiungete un riferimento ad esso nell'indice (`TOC tree`_) in
+ ``Documentation/index.rst``.
+
+.. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
+
+Questo, di solito, è sufficiente per la documentazione più semplice (come
+quella che state leggendo ora), ma per una documentazione più elaborata è
+consigliato creare una sottocartella dedicata (o, quando possibile, utilizzarne
+una già esistente). Per esempio, il sottosistema grafico è documentato nella
+sottocartella ``Documentation/gpu``; questa documentazione è divisa in
+diversi file ``.rst`` ed un indice ``index.rst`` (con un ``toctree``
+dedicato) a cui si fa riferimento nell'indice principale.
+
+Consultate la documentazione di `Sphinx`_ e `reStructuredText`_ per maggiori
+informazione circa le loro potenzialità. In particolare, il
+`manuale introduttivo a reStructuredText`_ di Sphinx è un buon punto da
+cui cominciare. Esistono, inoltre, anche alcuni
+`costruttori specifici per Sphinx`_.
+
+.. _`manuale introduttivo a reStructuredText`: http://www.sphinx-doc.org/en/stable/rest.html
+.. _`costruttori specifici per Sphinx`: http://www.sphinx-doc.org/en/stable/markup/index.html
+
+Guide linea per la documentazione del kernel
+--------------------------------------------
+
+In questa sezione troverete alcune linee guida specifiche per la documentazione
+del kernel:
+
+* Non esagerate con i costrutti di reStructuredText. Mantenete la
+ documentazione semplice. La maggior parte della documentazione dovrebbe
+ essere testo semplice con una strutturazione minima che permetta la
+ conversione in diversi formati.
+
+* Mantenete la strutturazione il più fedele possibile all'originale quando
+ convertite un documento in formato reStructuredText.
+
+* Aggiornate i contenuti quando convertite della documentazione, non limitatevi
+ solo alla formattazione.
+
+* Mantenete la decorazione dei livelli di intestazione come segue:
+
+ 1. ``=`` con una linea superiore per il titolo del documento::
+
+ ======
+ Titolo
+ ======
+
+ 2. ``=`` per i capitoli::
+
+ Capitoli
+ ========
+
+ 3. ``-`` per le sezioni::
+
+ Sezioni
+ -------
+
+ 4. ``~`` per le sottosezioni::
+
+ Sottosezioni
+ ~~~~~~~~~~~~
+
+ Sebbene RST non forzi alcun ordine specifico (*Piuttosto che imporre
+ un numero ed un ordine fisso di decorazioni, l'ordine utilizzato sarà
+ quello incontrato*), avere uniformità dei livelli principali rende più
+ semplice la lettura dei documenti.
+
+* Per inserire blocchi di testo con caratteri a dimensione fissa (codici di
+ esempio, casi d'uso, eccetera): utilizzate ``::`` quando non è necessario
+ evidenziare la sintassi, specialmente per piccoli frammenti; invece,
+ utilizzate ``.. code-block:: <language>`` per blocchi di più lunghi che
+ potranno beneficiare dell'avere la sintassi evidenziata.
+
+
+Il dominio C
+------------
+
+Il **Dominio Sphinx C** (denominato c) è adatto alla documentazione delle API C.
+Per esempio, un prototipo di una funzione:
+
+.. code-block:: rst
+
+ .. c:function:: int ioctl( int fd, int request )
+
+Il dominio C per kernel-doc ha delle funzionalità aggiuntive. Per esempio,
+potete assegnare un nuovo nome di riferimento ad una funzione con un nome
+molto comune come ``open`` o ``ioctl``:
+
+.. code-block:: rst
+
+ .. c:function:: int ioctl( int fd, int request )
+ :name: VIDIOC_LOG_STATUS
+
+Il nome della funzione (per esempio ioctl) rimane nel testo ma il nome del suo
+riferimento cambia da ``ioctl`` a ``VIDIOC_LOG_STATUS``. Anche la voce nell'indice
+cambia in ``VIDIOC_LOG_STATUS`` e si potrà quindi fare riferimento a questa
+funzione scrivendo:
+
+.. code-block:: rst
+
+ :c:func:`VIDIOC_LOG_STATUS`
+
+
+Tabelle a liste
+---------------
+
+Raccomandiamo l'uso delle tabelle in formato lista (*list table*). Le tabelle
+in formato lista sono liste di liste. In confronto all'ASCII-art potrebbero
+non apparire di facile lettura nei file in formato testo. Il loro vantaggio è
+che sono facili da creare o modificare e che la differenza di una modifica è
+molto più significativa perché limitata alle modifiche del contenuto.
+
+La ``flat-table`` è anch'essa una lista di liste simile alle ``list-table``
+ma con delle funzionalità aggiuntive:
+
+* column-span: col ruolo ``cspan`` una cella può essere estesa attraverso
+ colonne successive
+
+* raw-span: col ruolo ``rspan`` una cella può essere estesa attraverso
+ righe successive
+
+* auto-span: la cella più a destra viene estesa verso destra per compensare
+ la mancanza di celle. Con l'opzione ``:fill-cells:`` questo comportamento
+ può essere cambiato da *auto-span* ad *auto-fill*, il quale inserisce
+ automaticamente celle (vuote) invece che estendere l'ultima.
+
+opzioni:
+
+* ``:header-rows:`` [int] conta le righe di intestazione
+* ``:stub-columns:`` [int] conta le colonne di stub
+* ``:widths:`` [[int] [int] ... ] larghezza delle colonne
+* ``:fill-cells:`` invece di estendere automaticamente una cella su quelle
+ mancanti, ne crea di vuote.
+
+ruoli:
+
+* ``:cspan:`` [int] colonne successive (*morecols*)
+* ``:rspan:`` [int] righe successive (*morerows*)
+
+L'esempio successivo mostra come usare questo marcatore. Il primo livello della
+nostra lista di liste è la *riga*. In una *riga* è possibile inserire solamente
+la lista di celle che compongono la *riga* stessa. Fanno eccezione i *commenti*
+( ``..`` ) ed i *collegamenti* (per esempio, un riferimento a
+``:ref:`last row <last row>``` / :ref:`last row <it last row>`)
+
+.. code-block:: rst
+
+ .. flat-table:: table title
+ :widths: 2 1 1 3
+
+ * - head col 1
+ - head col 2
+ - head col 3
+ - head col 4
+
+ * - column 1
+ - field 1.1
+ - field 1.2 with autospan
+
+ * - column 2
+ - field 2.1
+ - :rspan:`1` :cspan:`1` field 2.2 - 3.3
+
+ * .. _`it last row`:
+
+ - column 3
+
+Che verrà rappresentata nel seguente modo:
+
+ .. flat-table:: table title
+ :widths: 2 1 1 3
+
+ * - head col 1
+ - head col 2
+ - head col 3
+ - head col 4
+
+ * - column 1
+ - field 1.1
+ - field 1.2 with autospan
+
+ * - column 2
+ - field 2.1
+ - :rspan:`1` :cspan:`1` field 2.2 - 3.3
+
+ * .. _`it last row`:
+
+ - column 3
+
+.. _it_sphinx_kfigure:
+
+Figure ed immagini
+==================
+
+Se volete aggiungere un'immagine, utilizzate le direttive ``kernel-figure``
+e ``kernel-image``. Per esempio, per inserire una figura di un'immagine in
+formato SVG::
+
+ .. kernel-figure:: svg_image.svg
+ :alt: semplice immagine SVG
+
+ Semplice immagine SVG
+
+.. _it_svg_image_example:
+
+.. kernel-figure:: svg_image.svg
+ :alt: semplice immagine SVG
+
+ Semplice immagine SVG
+
+Le direttive del kernel per figure ed immagini supportano il formato **DOT**,
+per maggiori informazioni
+
+* DOT: http://graphviz.org/pdf/dotguide.pdf
+* Graphviz: http://www.graphviz.org/content/dot-language
+
+Un piccolo esempio (:ref:`it_hello_dot_file`)::
+
+ .. kernel-figure:: hello.dot
+ :alt: ciao mondo
+
+ Esempio DOT
+
+.. _it_hello_dot_file:
+
+.. kernel-figure:: hello.dot
+ :alt: ciao mondo
+
+ Esempio DOT
+
+Tramite la direttiva ``kernel-render`` è possibile aggiungere codice specifico;
+ad esempio nel formato **DOT** di Graphviz.::
+
+ .. kernel-render:: DOT
+ :alt: foobar digraph
+ :caption: Codice **DOT** (Graphviz) integrato
+
+ digraph foo {
+ "bar" -> "baz";
+ }
+
+La rappresentazione dipenderà dei programmi installati. Se avete Graphviz
+installato, vedrete un'immagine vettoriale. In caso contrario, il codice grezzo
+verrà rappresentato come *blocco testuale* (:ref:`it_hello_dot_render`).
+
+.. _it_hello_dot_render:
+
+.. kernel-render:: DOT
+ :alt: foobar digraph
+ :caption: Codice **DOT** (Graphviz) integrato
+
+ digraph foo {
+ "bar" -> "baz";
+ }
+
+La direttiva *render* ha tutte le opzioni della direttiva *figure*, con
+l'aggiunta dell'opzione ``caption``. Se ``caption`` ha un valore allora
+un nodo *figure* viene aggiunto. Altrimenti verrà aggiunto un nodo *image*.
+L'opzione ``caption`` è necessaria in caso si vogliano aggiungere dei
+riferimenti (:ref:`it_hello_svg_render`).
+
+Per la scrittura di codice **SVG**::
+
+ .. kernel-render:: SVG
+ :caption: Integrare codice **SVG**
+ :alt: so-nw-arrow
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
+ ...
+ </svg>
+
+.. _it_hello_svg_render:
+
+.. kernel-render:: SVG
+ :caption: Integrare codice **SVG**
+ :alt: so-nw-arrow
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <svg xmlns="http://www.w3.org/2000/svg"
+ version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
+ <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
+ <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
+ </svg>
diff --git a/Documentation/translations/it_IT/doc-guide/svg_image.svg b/Documentation/translations/it_IT/doc-guide/svg_image.svg
new file mode 120000
index 000000000000..4b1c287bb16f
--- /dev/null
+++ b/Documentation/translations/it_IT/doc-guide/svg_image.svg
@@ -0,0 +1 @@
+../../../doc-guide/svg_image.svg
\ No newline at end of file
diff --git a/Documentation/translations/it_IT/index.rst b/Documentation/translations/it_IT/index.rst
index e688c06fd9a4..61f9fdb2bb72 100644
--- a/Documentation/translations/it_IT/index.rst
+++ b/Documentation/translations/it_IT/index.rst
@@ -72,9 +72,17 @@ sviluppatori che contribuiscono ogni anno. Come in ogni grande comunità,
sapere come le cose vengono fatte renderà il processo di integrazione delle
vostre modifiche molto più semplice
+.. toctree::
+ :maxdepth: 2
+
+ doc-guide/index
+
.. warning::
TODO ancora da tradurre
+ - process/index
+ - dev-tools/index
+ - kernel-hacking/index
Documentazione della API del kernel
-----------------------------------
--
2.14.3
--
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
^ permalink raw reply related
* [PATCH 3/5] doc: add Italian translation skeleton
From: Federico Vaga @ 2018-05-27 14:55 UTC (permalink / raw)
To: Jonathan Corbet
Cc: linux-doc, linux-kernel, Alessia Mantegazza, Federico Vaga
In-Reply-To: <20180527145559.16411-1-federico.vaga@vaga.pv.it>
Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Alessia Mantegazza <amantegazza@vaga.pv.it>
---
Documentation/index.rst | 8 ++
.../translations/it_IT/disclaimer-ita.rst | 11 +++
Documentation/translations/it_IT/index.rst | 101 +++++++++++++++++++++
3 files changed, 120 insertions(+)
create mode 100644 Documentation/translations/it_IT/disclaimer-ita.rst
create mode 100644 Documentation/translations/it_IT/index.rst
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 8f11fccb9744..e6075bdacbbd 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -113,6 +113,14 @@ Japanese translations
translations/ja_JP/index
+Italian translations
+---------------------
+
+.. toctree::
+ :maxdepth: 1
+
+ translations/it_IT/index
+
Indices and tables
==================
diff --git a/Documentation/translations/it_IT/disclaimer-ita.rst b/Documentation/translations/it_IT/disclaimer-ita.rst
new file mode 100644
index 000000000000..0c439117ed7f
--- /dev/null
+++ b/Documentation/translations/it_IT/disclaimer-ita.rst
@@ -0,0 +1,11 @@
+:orphan:
+
+.. note::
+ This document is maintained by Federico Vaga <federico.vaga@vaga.pv.it>.
+ If you find any difference between this document and the original file or a
+ problem with the translation, please contact the maintainer of this file.
+
+.. warning::
+ The purpose of this file is to be easier to read and understand for Italian
+ speakers and is not intended as a fork. So, if you have any comments or
+ updates for this file please try to update the original English file first.
diff --git a/Documentation/translations/it_IT/index.rst b/Documentation/translations/it_IT/index.rst
new file mode 100644
index 000000000000..e688c06fd9a4
--- /dev/null
+++ b/Documentation/translations/it_IT/index.rst
@@ -0,0 +1,101 @@
+.. _it_linux_doc:
+
+===================
+Traduzione italiana
+===================
+
+L'obiettivo di questa traduzione è di rendere più facile la lettura e
+la comprensione per chi preferisce leggere in lingua italiana.
+Tenete presente che la documentazione di riferimento rimane comunque
+quella in lingua inglese: :ref:`linux_doc`
+
+Questa traduzione cerca di essere il più fedele possibile all'originale ma
+è ovvio che alcune frasi vadano trasformate: non aspettatevi una traduzione
+letterale. Quando possibile, si eviteranno gli inglesismi ed al loro posto
+verranno utilizzate le corrispettive parole italiane.
+
+Se notate che la traduzione non è più aggiornata potete contattare
+direttamente il manutentore della traduzione italiana.
+
+Se notate che la documentazione contiene errori o dimenticanze, allora
+verificate la documentazione di riferimento in lingua inglese. Se il problema
+è presente anche nella documentazione di riferimento, contattate il suo
+manutentore. Se avete problemi a scrivere in inglese, potete comunque
+riportare il problema al manutentore della traduzione italiana.
+
+Manutentore della traduzione italiana: Federico Vaga <federico.vaga@vaga.pv.it>
+
+La documentazione del kernel Linux
+==================================
+
+Questo è il livello principale della documentazione del kernel in
+lingua italiana. La traduzione è incompleta, noterete degli avvisi
+che vi segnaleranno la mancanza di una traduzione o di un gruppo di
+traduzioni.
+
+Più in generale, la documentazione, come il kernel stesso, sono in
+costante sviluppo; particolarmente vero in quanto stiamo lavorando
+alla riorganizzazione della documentazione in modo più coerente.
+I miglioramenti alla documentazione sono sempre i benvenuti; per cui,
+se vuoi aiutare, iscriviti alla lista di discussione linux-doc presso
+vger.kernel.org.
+
+Documentazione per gli utenti
+-----------------------------
+
+I seguenti manuali sono scritti per gli *utenti* del kernel - ovvero,
+coloro che cercano di farlo funzionare in modo ottimale su un dato sistema
+
+.. warning::
+
+ TODO ancora da tradurre
+
+Documentazione per gli sviluppatori di applicazioni
+---------------------------------------------------
+
+Il manuale delle API verso lo spazio utente è una collezione di documenti
+che descrivono le interfacce del kernel viste dagli sviluppatori
+di applicazioni.
+
+.. warning::
+
+ TODO ancora da tradurre
+
+
+Introduzione allo sviluppo del kernel
+-------------------------------------
+
+Questi manuali contengono informazioni su come contribuire allo sviluppo
+del kernel.
+Attorno al kernel Linux gira una comunità molto grande con migliaia di
+sviluppatori che contribuiscono ogni anno. Come in ogni grande comunità,
+sapere come le cose vengono fatte renderà il processo di integrazione delle
+vostre modifiche molto più semplice
+
+.. warning::
+
+ TODO ancora da tradurre
+
+Documentazione della API del kernel
+-----------------------------------
+
+Questi manuali forniscono dettagli su come funzionano i sottosistemi del
+kernel dal punto di vista degli sviluppatori del kernel. Molte delle
+informazioni contenute in questi manuali sono prese direttamente dai
+file sorgenti, informazioni aggiuntive vengono aggiunte solo se necessarie
+(o almeno ci proviamo — probabilmente *non* tutto quello che è davvero
+necessario).
+
+.. warning::
+
+ TODO ancora da tradurre
+
+Documentazione specifica per architettura
+-----------------------------------------
+
+Questi manuali forniscono dettagli di programmazione per le diverse
+implementazioni d'architettura.
+
+.. warning::
+
+ TODO ancora da tradurre
--
2.14.3
--
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
^ permalink raw reply related
* [PATCH 2/5] doc: add chapter labels
From: Federico Vaga @ 2018-05-27 14:55 UTC (permalink / raw)
To: Jonathan Corbet
Cc: linux-doc, linux-kernel, Alessia Mantegazza, Federico Vaga
In-Reply-To: <20180527145559.16411-1-federico.vaga@vaga.pv.it>
The idea is to make it easier to create references (doc-guide does the same).
Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
---
Documentation/index.rst | 2 ++
Documentation/kernel-hacking/index.rst | 2 ++
2 files changed, 4 insertions(+)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 331da87c82c8..8f11fccb9744 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -3,6 +3,8 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
+.. _linux_doc:
+
The Linux Kernel documentation
==============================
diff --git a/Documentation/kernel-hacking/index.rst b/Documentation/kernel-hacking/index.rst
index fcb0eda3cca3..f53027652290 100644
--- a/Documentation/kernel-hacking/index.rst
+++ b/Documentation/kernel-hacking/index.rst
@@ -1,3 +1,5 @@
+.. _kernel_hacking:
+
=====================
Kernel Hacking Guides
=====================
--
2.14.3
--
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
^ permalink raw reply related
* [PATCH 1/5] doc: typos and minor fixes
From: Federico Vaga @ 2018-05-27 14:55 UTC (permalink / raw)
To: Jonathan Corbet
Cc: linux-doc, linux-kernel, Alessia Mantegazza, Federico Vaga
In-Reply-To: <20180527145559.16411-1-federico.vaga@vaga.pv.it>
Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
---
Documentation/doc-guide/kernel-doc.rst | 2 +-
| 4 ++--
Documentation/doc-guide/sphinx.rst | 4 ++--
Documentation/index.rst | 2 +-
| 2 +-
5 files changed, 7 insertions(+), 7 deletions(-)
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 0268335414ce..d322367f70d7 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -262,7 +262,7 @@ comment block.
The kernel-doc data structure comments describe each member of the structure, in
order, with the ``@member:`` descriptions. The ``@member:`` descriptions must
-begin on the very next line following the opening brief function description
+begin on the very next line following the opening brief structure description
line, with no intervening blank comment lines. The ``@member:`` descriptions may
span multiple lines. The continuation lines may contain indentation.
--git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst
index 96a0423d5dba..cbfbd1748f8f 100644
--- a/Documentation/doc-guide/parse-headers.rst
+++ b/Documentation/doc-guide/parse-headers.rst
@@ -32,7 +32,7 @@ SYNOPSIS
\ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
-Where <options> can be: --debug, --help or --man.
+Where <options> can be: --debug, --usage or --help.
OPTIONS
@@ -133,7 +133,7 @@ For both statements, \ **type**\ can be either one of the following:
\ **symbol**\
- The ignore or replace statement will apply to the name of enum statements
+ The ignore or replace statement will apply to the name of enum values
at C_FILE.
For replace statements, \ **new_value**\ will automatically use :c:type:
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index a2417633fdd8..8d789a117a4f 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -28,7 +28,7 @@ The ReST markups currently used by the Documentation/ files are meant to be
built with ``Sphinx`` version 1.3 or upper. If you're desiring to build
PDF outputs, it is recommended to use version 1.4.6 or upper.
-There's a script that checks for the Spinx requirements. Please see
+There's a script that checks for the Sphinx requirements. Please see
:ref:`sphinx-pre-install` for further details.
Most distributions are shipped with Sphinx, but its toolchain is fragile,
@@ -266,7 +266,7 @@ some additional features:
* row-span: with the role ``rspan`` a cell can be extended through
additional rows
-* auto span rightmost cell of a table row over the missing cells on the right
+* auto-span: rightmost cell of a table row over the missing cells on the right
side of that table-row. With Option ``:fill-cells:`` this behavior can
changed from *auto span* to *auto fill*, which automatically inserts (empty)
cells instead of spanning the last cell.
diff --git a/Documentation/index.rst b/Documentation/index.rst
index cb7f1ba5b3b1..331da87c82c8 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -33,7 +33,7 @@ the kernel interface as seen by application developers.
.. toctree::
:maxdepth: 2
- userspace-api/index
+ userspace-api/index
Introduction to kernel development
--git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl
index a958d8b5e99d..27117194d41f 100755
--- a/Documentation/sphinx/parse-headers.pl
+++ b/Documentation/sphinx/parse-headers.pl
@@ -344,7 +344,7 @@ enums and defines and create cross-references to a Sphinx book.
B<parse_headers.pl> [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
-Where <options> can be: --debug, --help or --man.
+Where <options> can be: --debug, --help or --usage.
=head1 OPTIONS
--
2.14.3
--
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
^ permalink raw reply related
* doc: Italian translation
From: Federico Vaga @ 2018-05-27 14:55 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Alessia Mantegazza
Ciao Jonathan,
here the doc-guide translated in Italian. This set of patches includes
some minor changes to the main one. The idea of this first set of patches
is also to adjust the structure and our expectations.
We tried to translate everything in **Italian**; which means that we avoided
imported English words wherever there is the possibility to use the Italian
ones. Of course, this is not always possible, or worst doing the translation
make it less clear, for example the word "file".
Another point. I noticed that the disclaimer for other translations is
in English, so I did the same. But actually shouldn't be in Italian, since
that page will be read by Italian speakers?
--
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
^ permalink raw reply
* Re: [PATCH 1/3] usb: gadget: ccid: add support for USB CCID Gadget Device
From: Greg Kroah-Hartman @ 2018-05-27 6:39 UTC (permalink / raw)
To: Marcus Folkesson
Cc: Jonathan Corbet, Felipe Balbi, davem, Mauro Carvalho Chehab,
Andrew Morton, Randy Dunlap, Ruslan Bilovol, Thomas Gleixner,
Kate Stewart, linux-usb, linux-doc, linux-kernel
In-Reply-To: <20180527054847.GB22105@gmail.com>
On Sun, May 27, 2018 at 07:48:47AM +0200, Marcus Folkesson wrote:
> On Sat, May 26, 2018 at 10:56:52PM +0200, Greg Kroah-Hartman wrote:
> > On Sat, May 26, 2018 at 10:33:59PM +0200, Marcus Folkesson wrote:
> > > Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
> >
> > I can't take patches without any changelog text. And why would you
> > submit a patch over 1000 lines without any?
>
> I'm sorry, obviously not much went well for me yesterday.
> The changlelog was "fixup:ed" away and now I noticed that my
> patch version history did not follow for v2.
>
> Is it better to send a v3 with updated version history or wait for more
> comments?
Nah, that's fine, but I'll let Felipe decide as he is the one that has
to review this, not me.
thanks,
greg k-h
--
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
^ permalink raw reply
* Re: [PATCH 1/3] usb: gadget: ccid: add support for USB CCID Gadget Device
From: Marcus Folkesson @ 2018-05-27 5:48 UTC (permalink / raw)
To: Greg Kroah-Hartman
Cc: Jonathan Corbet, Felipe Balbi, davem, Mauro Carvalho Chehab,
Andrew Morton, Randy Dunlap, Ruslan Bilovol, Thomas Gleixner,
Kate Stewart, linux-usb, linux-doc, linux-kernel
In-Reply-To: <20180526205652.GA25534@kroah.com>
On Sat, May 26, 2018 at 10:56:52PM +0200, Greg Kroah-Hartman wrote:
> On Sat, May 26, 2018 at 10:33:59PM +0200, Marcus Folkesson wrote:
> > Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
>
> I can't take patches without any changelog text. And why would you
> submit a patch over 1000 lines without any?
I'm sorry, obviously not much went well for me yesterday.
The changlelog was "fixup:ed" away and now I noticed that my
patch version history did not follow for v2.
Is it better to send a v3 with updated version history or wait for more
comments?
I'll start review my patches better before sending them.
Thank you for your time and comments.
>
> Please fix.
>
> thanks,
>
> greg k-h
--
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
^ permalink raw reply
* [PATCH v2 2/3] Documentation: usb: add documentation for USB CCID Gadget Device
From: Marcus Folkesson @ 2018-05-26 21:19 UTC (permalink / raw)
To: Greg Kroah-Hartman, Jonathan Corbet, Felipe Balbi, davem,
Mauro Carvalho Chehab, Andrew Morton, Randy Dunlap,
Ruslan Bilovol, Thomas Gleixner, Kate Stewart
Cc: linux-usb, linux-doc, linux-kernel, Marcus Folkesson
In-Reply-To: <20180526211940.25474-1-marcus.folkesson@gmail.com>
Add documentation to give a brief description on how to use the
CCID Gadget Device.
This includes a description for all attributes followed by an example on
how to setup the device with ConfigFS.
Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
---
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 <marcus.folkesson@gmail.com>
+
+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
^ permalink raw reply related
* [PATCH v2 3/3] MAINTAINERS: add USB CCID Gadget Device
From: Marcus Folkesson @ 2018-05-26 21:19 UTC (permalink / raw)
To: Greg Kroah-Hartman, Jonathan Corbet, Felipe Balbi, davem,
Mauro Carvalho Chehab, Andrew Morton, Randy Dunlap,
Ruslan Bilovol, Thomas Gleixner, Kate Stewart
Cc: linux-usb, linux-doc, linux-kernel, Marcus Folkesson
In-Reply-To: <20180526211940.25474-1-marcus.folkesson@gmail.com>
Add MAINTAINERS entry for USB CCID Gadget Device
Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
---
MAINTAINERS | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 078fd80f664f..e77c3d2bec89 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14541,6 +14541,14 @@ L: linux-scsi@vger.kernel.org
S: Maintained
F: drivers/usb/storage/uas.c
+USB CCID GADGET
+M: Marcus Folkesson <marcus.folkesson@gmail.com>
+L: linux-usb@vger.kernel.org
+S: Maintained
+F: drivers/usb/gadget/function/f_ccid.*
+F: include/uapi/linux/usb/ccid.h
+F: Documentation/usb/gadget_ccid.rst
+
USB CDC ETHERNET DRIVER
M: Oliver Neukum <oliver@neukum.org>
L: linux-usb@vger.kernel.org
--
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
^ permalink raw reply related
* [PATCH v2 1/3] usb: gadget: ccid: add support for USB CCID Gadget Device
From: Marcus Folkesson @ 2018-05-26 21:19 UTC (permalink / raw)
To: Greg Kroah-Hartman, Jonathan Corbet, Felipe Balbi, davem,
Mauro Carvalho Chehab, Andrew Morton, Randy Dunlap,
Ruslan Bilovol, Thomas Gleixner, Kate Stewart
Cc: linux-usb, linux-doc, linux-kernel, Marcus Folkesson
Chip Card Interface Device (CCID) protocol is a USB protocol that
allows a smartcard device to be connected to a computer via a card
reader using a standard USB interface, without the need for each manufacturer
of smartcards to provide its own reader or protocol.
This gadget driver makes Linux show up as a CCID device to the host and let a
userspace daemon act as the smartcard.
This is useful when the Linux gadget itself should act as a cryptographic
device or forward APDUs to an embedded smartcard device.
Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
---
drivers/usb/gadget/Kconfig | 17 +
drivers/usb/gadget/function/Makefile | 1 +
drivers/usb/gadget/function/f_ccid.c | 988 +++++++++++++++++++++++++++++++++++
drivers/usb/gadget/function/f_ccid.h | 91 ++++
include/uapi/linux/usb/ccid.h | 93 ++++
5 files changed, 1190 insertions(+)
create mode 100644 drivers/usb/gadget/function/f_ccid.c
create mode 100644 drivers/usb/gadget/function/f_ccid.h
create mode 100644 include/uapi/linux/usb/ccid.h
diff --git a/drivers/usb/gadget/Kconfig b/drivers/usb/gadget/Kconfig
index 31cce7805eb2..bdebdf1ffa2b 100644
--- a/drivers/usb/gadget/Kconfig
+++ b/drivers/usb/gadget/Kconfig
@@ -149,6 +149,9 @@ config USB_LIBCOMPOSITE
config USB_F_ACM
tristate
+config USB_F_CCID
+ tristate
+
config USB_F_SS_LB
tristate
@@ -248,6 +251,20 @@ config USB_CONFIGFS_ACM
ACM serial link. This function can be used to interoperate with
MS-Windows hosts or with the Linux-USB "cdc-acm" driver.
+config USB_CONFIGFS_CCID
+ bool "Chip Card Interface Device (CCID)"
+ depends on USB_CONFIGFS
+ select USB_F_CCID
+ help
+ The CCID function driver provides generic emulation of a
+ Chip Card Interface Device (CCID).
+
+ You will need a user space server talking to /dev/ccidg*,
+ since the kernel itself does not implement CCID/TPDU/APDU
+ protocol.
+
+ For more information, see Documentation/usb/gadget_ccid.rst.
+
config USB_CONFIGFS_OBEX
bool "Object Exchange Model (CDC OBEX)"
depends on USB_CONFIGFS
diff --git a/drivers/usb/gadget/function/Makefile b/drivers/usb/gadget/function/Makefile
index 5d3a6cf02218..629851009e1a 100644
--- a/drivers/usb/gadget/function/Makefile
+++ b/drivers/usb/gadget/function/Makefile
@@ -9,6 +9,7 @@ ccflags-y += -I$(srctree)/drivers/usb/gadget/udc/
# USB Functions
usb_f_acm-y := f_acm.o
obj-$(CONFIG_USB_F_ACM) += usb_f_acm.o
+obj-$(CONFIG_USB_F_CCID) += f_ccid.o
usb_f_ss_lb-y := f_loopback.o f_sourcesink.o
obj-$(CONFIG_USB_F_SS_LB) += usb_f_ss_lb.o
obj-$(CONFIG_USB_U_SERIAL) += u_serial.o
diff --git a/drivers/usb/gadget/function/f_ccid.c b/drivers/usb/gadget/function/f_ccid.c
new file mode 100644
index 000000000000..9ff8615ca303
--- /dev/null
+++ b/drivers/usb/gadget/function/f_ccid.c
@@ -0,0 +1,988 @@
+// SPDX-License-Identifier: GPL-2.0
+/*
+ * f_ccid.c -- Chip Card Interface Device (CCID) function Driver
+ *
+ * Copyright (C) 2018 Marcus Folkesson <marcus.folkesson@gmail.com>
+ *
+ */
+#include <linux/cdev.h>
+#include <linux/device.h>
+#include <linux/fs.h>
+#include <linux/kernel.h>
+#include <linux/module.h>
+#include <linux/poll.h>
+#include <linux/slab.h>
+#include <linux/uaccess.h>
+#include <linux/usb/composite.h>
+#include <uapi/linux/usb/ccid.h>
+
+#include "f_ccid.h"
+#include "u_f.h"
+
+/* Number of tx requests to allocate */
+#define N_TX_REQS 4
+
+/* Maximum number of devices */
+#define CCID_MINORS 4
+
+struct ccidg_bulk_dev {
+ atomic_t is_open;
+ atomic_t rx_req_busy;
+ wait_queue_head_t read_wq;
+ wait_queue_head_t write_wq;
+ struct usb_request *rx_req;
+ atomic_t rx_done;
+ struct list_head tx_idle;
+};
+
+struct f_ccidg {
+ struct usb_function_instance func_inst;
+ struct usb_function function;
+ spinlock_t lock;
+ atomic_t online;
+
+ /* Character device */
+ struct cdev cdev;
+ int minor;
+
+ /* Dynamic attributes */
+ u32 features;
+ u32 protocols;
+ u8 pinsupport;
+ u8 nslots;
+ u8 lcdlayout;
+
+ /* Endpoints */
+ struct usb_ep *in;
+ struct usb_ep *out;
+ struct ccidg_bulk_dev bulk_dev;
+};
+
+/* Interface Descriptor: */
+static struct usb_interface_descriptor ccid_interface_desc = {
+ .bLength = USB_DT_INTERFACE_SIZE,
+ .bDescriptorType = USB_DT_INTERFACE,
+ .bNumEndpoints = 2,
+ .bInterfaceClass = USB_CLASS_CSCID,
+ .bInterfaceSubClass = 0,
+ .bInterfaceProtocol = 0,
+};
+
+/* CCID Class Descriptor */
+static struct ccid_class_descriptor ccid_class_desc = {
+ .bLength = sizeof(ccid_class_desc),
+ .bDescriptorType = CCID_DECRIPTOR_TYPE,
+ .bcdCCID = CCID1_10,
+ /* .bMaxSlotIndex = DYNAMIC */
+ .bVoltageSupport = CCID_VOLTS_3_0,
+ /* .dwProtocols = DYNAMIC */
+ .dwDefaultClock = 3580,
+ .dwMaximumClock = 3580,
+ .bNumClockSupported = 0,
+ .dwDataRate = 9600,
+ .dwMaxDataRate = 9600,
+ .bNumDataRatesSupported = 0,
+ .dwMaxIFSD = 0,
+ .dwSynchProtocols = 0,
+ .dwMechanical = 0,
+ /* .dwFeatures = DYNAMIC */
+
+ /* extended APDU level Message Length */
+ .dwMaxCCIDMessageLength = 0x200,
+ .bClassGetResponse = 0x0,
+ .bClassEnvelope = 0x0,
+ /* .wLcdLayout = DYNAMIC */
+ /* .bPINSupport = DYNAMIC */
+ .bMaxCCIDBusySlots = 1
+};
+
+/* Full speed support: */
+static struct usb_endpoint_descriptor ccid_fs_in_desc = {
+ .bLength = USB_DT_ENDPOINT_SIZE,
+ .bDescriptorType = USB_DT_ENDPOINT,
+ .bEndpointAddress = USB_DIR_IN,
+ .bmAttributes = USB_ENDPOINT_XFER_BULK,
+ .wMaxPacketSize = cpu_to_le16(64),
+};
+
+static struct usb_endpoint_descriptor ccid_fs_out_desc = {
+ .bLength = USB_DT_ENDPOINT_SIZE,
+ .bDescriptorType = USB_DT_ENDPOINT,
+ .bEndpointAddress = USB_DIR_OUT,
+ .bmAttributes = USB_ENDPOINT_XFER_BULK,
+ .wMaxPacketSize = cpu_to_le16(64),
+};
+
+static struct usb_descriptor_header *ccid_fs_descs[] = {
+ (struct usb_descriptor_header *) &ccid_interface_desc,
+ (struct usb_descriptor_header *) &ccid_class_desc,
+ (struct usb_descriptor_header *) &ccid_fs_in_desc,
+ (struct usb_descriptor_header *) &ccid_fs_out_desc,
+ NULL,
+};
+
+/* High speed support: */
+static struct usb_endpoint_descriptor ccid_hs_in_desc = {
+ .bLength = USB_DT_ENDPOINT_SIZE,
+ .bDescriptorType = USB_DT_ENDPOINT,
+ .bEndpointAddress = USB_DIR_IN,
+ .bmAttributes = USB_ENDPOINT_XFER_BULK,
+ .wMaxPacketSize = cpu_to_le16(512),
+};
+
+static struct usb_endpoint_descriptor ccid_hs_out_desc = {
+ .bLength = USB_DT_ENDPOINT_SIZE,
+ .bDescriptorType = USB_DT_ENDPOINT,
+ .bEndpointAddress = USB_DIR_OUT,
+ .bmAttributes = USB_ENDPOINT_XFER_BULK,
+ .wMaxPacketSize = cpu_to_le16(512),
+};
+
+static struct usb_descriptor_header *ccid_hs_descs[] = {
+ (struct usb_descriptor_header *) &ccid_interface_desc,
+ (struct usb_descriptor_header *) &ccid_class_desc,
+ (struct usb_descriptor_header *) &ccid_hs_in_desc,
+ (struct usb_descriptor_header *) &ccid_hs_out_desc,
+ NULL,
+};
+
+static DEFINE_IDA(ccidg_ida);
+static int major;
+static DEFINE_MUTEX(ccidg_ida_lock); /* protects access to ccidg_ida */
+static struct class *ccidg_class;
+
+static inline struct f_ccidg_opts *to_f_ccidg_opts(struct config_item *item)
+{
+ return container_of(to_config_group(item), struct f_ccidg_opts,
+ func_inst.group);
+}
+
+static inline struct f_ccidg *func_to_ccidg(struct usb_function *f)
+{
+ return container_of(f, struct f_ccidg, function);
+}
+
+static inline int ccidg_get_minor(void)
+{
+ int ret;
+
+ ret = ida_simple_get(&ccidg_ida, 0, 0, GFP_KERNEL);
+ if (ret >= CCID_MINORS) {
+ ida_simple_remove(&ccidg_ida, ret);
+ ret = -ENODEV;
+ }
+
+ return ret;
+}
+
+static inline void ccidg_put_minor(int minor)
+{
+ ida_simple_remove(&ccidg_ida, minor);
+}
+
+static int ccidg_setup(void)
+{
+ int ret;
+ dev_t dev;
+
+ ccidg_class = class_create(THIS_MODULE, "ccidg");
+ if (IS_ERR(ccidg_class)) {
+ ccidg_class = NULL;
+ return PTR_ERR(ccidg_class);
+ }
+
+ ret = alloc_chrdev_region(&dev, 0, CCID_MINORS, "ccidg");
+ if (ret) {
+ class_destroy(ccidg_class);
+ ccidg_class = NULL;
+ return ret;
+ }
+
+ major = MAJOR(dev);
+
+ return 0;
+}
+
+static void ccidg_cleanup(void)
+{
+ if (major) {
+ unregister_chrdev_region(MKDEV(major, 0), CCID_MINORS);
+ major = 0;
+ }
+
+ class_destroy(ccidg_class);
+ ccidg_class = NULL;
+}
+
+static void ccidg_attr_release(struct config_item *item)
+{
+ struct f_ccidg_opts *opts = to_f_ccidg_opts(item);
+
+ usb_put_function_instance(&opts->func_inst);
+}
+
+static struct configfs_item_operations ccidg_item_ops = {
+ .release = ccidg_attr_release,
+};
+
+#define F_CCIDG_OPT(name, prec, limit) \
+static ssize_t f_ccidg_opts_##name##_show(struct config_item *item, char *page)\
+{ \
+ struct f_ccidg_opts *opts = to_f_ccidg_opts(item); \
+ int result; \
+ \
+ mutex_lock(&opts->lock); \
+ result = sprintf(page, "%x\n", opts->name); \
+ mutex_unlock(&opts->lock); \
+ \
+ return result; \
+} \
+ \
+static ssize_t f_ccidg_opts_##name##_store(struct config_item *item, \
+ const char *page, size_t len) \
+{ \
+ struct f_ccidg_opts *opts = to_f_ccidg_opts(item); \
+ int ret; \
+ u##prec num; \
+ \
+ mutex_lock(&opts->lock); \
+ if (opts->refcnt) { \
+ ret = -EBUSY; \
+ goto end; \
+ } \
+ \
+ ret = kstrtou##prec(page, 0, &num); \
+ if (ret) \
+ goto end; \
+ \
+ if (num > limit) { \
+ ret = -EINVAL; \
+ goto end; \
+ } \
+ opts->name = num; \
+ ret = len; \
+ \
+end: \
+ mutex_unlock(&opts->lock); \
+ return ret; \
+} \
+ \
+CONFIGFS_ATTR(f_ccidg_opts_, name)
+
+F_CCIDG_OPT(features, 32, 0xffffffff);
+F_CCIDG_OPT(protocols, 32, 0x03);
+F_CCIDG_OPT(pinsupport, 8, 0x03);
+F_CCIDG_OPT(lcdlayout, 16, 0xffff);
+F_CCIDG_OPT(nslots, 8, 0xff);
+
+static struct configfs_attribute *ccidg_attrs[] = {
+ &f_ccidg_opts_attr_features,
+ &f_ccidg_opts_attr_protocols,
+ &f_ccidg_opts_attr_pinsupport,
+ &f_ccidg_opts_attr_lcdlayout,
+ &f_ccidg_opts_attr_nslots,
+ NULL,
+};
+
+static struct config_item_type ccidg_func_type = {
+ .ct_item_ops = &ccidg_item_ops,
+ .ct_attrs = ccidg_attrs,
+ .ct_owner = THIS_MODULE,
+};
+
+static void ccidg_req_put(struct f_ccidg *ccidg, struct list_head *head,
+ struct usb_request *req)
+{
+ unsigned long flags;
+
+ spin_lock_irqsave(&ccidg->lock, flags);
+ list_add_tail(&req->list, head);
+ spin_unlock_irqrestore(&ccidg->lock, flags);
+}
+
+static struct usb_request *ccidg_req_get(struct f_ccidg *ccidg,
+ struct list_head *head)
+{
+ unsigned long flags;
+ struct usb_request *req = NULL;
+
+ spin_lock_irqsave(&ccidg->lock, flags);
+ if (!list_empty(head)) {
+ req = list_first_entry(head, struct usb_request, list);
+ list_del(&req->list);
+ }
+ spin_unlock_irqrestore(&ccidg->lock, flags);
+
+ return req;
+}
+
+static void ccidg_bulk_complete_tx(struct usb_ep *ep, struct usb_request *req)
+{
+ struct f_ccidg *ccidg = (struct f_ccidg *)ep->driver_data;
+ struct ccidg_bulk_dev *bulk_dev = &ccidg->bulk_dev;
+ struct usb_composite_dev *cdev = ccidg->function.config->cdev;
+
+ switch (req->status) {
+ default:
+ VDBG(cdev, "ccid: tx err %d\n", req->status);
+ /* FALLTHROUGH */
+ case -ECONNRESET: /* unlink */
+ case -ESHUTDOWN: /* disconnect etc */
+ break;
+ case 0:
+ break;
+ }
+
+ ccidg_req_put(ccidg, &bulk_dev->tx_idle, req);
+ wake_up(&bulk_dev->write_wq);
+}
+
+static void ccidg_bulk_complete_rx(struct usb_ep *ep, struct usb_request *req)
+{
+ struct f_ccidg *ccidg = (struct f_ccidg *)ep->driver_data;
+ struct ccidg_bulk_dev *bulk_dev = &ccidg->bulk_dev;
+ struct usb_composite_dev *cdev = ccidg->function.config->cdev;
+
+ switch (req->status) {
+
+ /* normal completion */
+ case 0:
+ /* We only cares about packets with nonzero length */
+ if (req->actual > 0)
+ atomic_set(&bulk_dev->rx_done, 1);
+ break;
+
+ /* software-driven interface shutdown */
+ case -ECONNRESET: /* unlink */
+ case -ESHUTDOWN: /* disconnect etc */
+ VDBG(cdev, "ccid: rx shutdown, code %d\n", req->status);
+ break;
+
+ /* for hardware automagic (such as pxa) */
+ case -ECONNABORTED: /* endpoint reset */
+ DBG(cdev, "ccid: rx %s reset\n", ep->name);
+ break;
+
+ /* data overrun */
+ case -EOVERFLOW:
+ /* FALLTHROUGH */
+ default:
+ DBG(cdev, "ccid: rx status %d\n", req->status);
+ break;
+ }
+
+ wake_up(&bulk_dev->read_wq);
+}
+
+static struct usb_request *
+ccidg_request_alloc(struct usb_ep *ep, unsigned int len)
+{
+ struct usb_request *req;
+
+ req = usb_ep_alloc_request(ep, GFP_ATOMIC);
+ if (!req)
+ return ERR_PTR(-ENOMEM);
+
+ req->length = len;
+ req->buf = kmalloc(len, GFP_ATOMIC);
+ if (req->buf == NULL) {
+ usb_ep_free_request(ep, req);
+ return ERR_PTR(-ENOMEM);
+ }
+
+ return req;
+}
+
+static void ccidg_request_free(struct usb_request *req, struct usb_ep *ep)
+{
+ if (req) {
+ kfree(req->buf);
+ usb_ep_free_request(ep, req);
+ }
+}
+
+static int ccidg_function_setup(struct usb_function *f,
+ const struct usb_ctrlrequest *ctrl)
+{
+ struct f_ccidg *ccidg = container_of(f, struct f_ccidg, function);
+ struct usb_composite_dev *cdev = f->config->cdev;
+ struct usb_request *req = cdev->req;
+ int ret = -EOPNOTSUPP;
+ u16 w_index = le16_to_cpu(ctrl->wIndex);
+ u16 w_value = le16_to_cpu(ctrl->wValue);
+ u16 w_length = le16_to_cpu(ctrl->wLength);
+
+ if (!atomic_read(&ccidg->online))
+ return -ENOTCONN;
+
+ switch (ctrl->bRequestType & USB_TYPE_MASK) {
+ case USB_TYPE_CLASS:
+ {
+ switch (ctrl->bRequest) {
+ case CCIDGENERICREQ_GET_CLOCK_FREQUENCIES:
+ *(u32 *) req->buf = cpu_to_le32(ccid_class_desc.dwDefaultClock);
+ ret = min_t(u32, w_length,
+ sizeof(ccid_class_desc.dwDefaultClock));
+ break;
+
+ case CCIDGENERICREQ_GET_DATA_RATES:
+ *(u32 *) req->buf = cpu_to_le32(ccid_class_desc.dwDataRate);
+ ret = min_t(u32, w_length, sizeof(ccid_class_desc.dwDataRate));
+ break;
+
+ default:
+ VDBG(f->config->cdev,
+ "ccid: invalid control req%02x.%02x v%04x i%04x l%d\n",
+ ctrl->bRequestType, ctrl->bRequest,
+ w_value, w_index, w_length);
+ }
+ }
+ }
+
+ /* responded with data transfer or status phase? */
+ if (ret >= 0) {
+ VDBG(f->config->cdev, "ccid: req%02x.%02x v%04x i%04x l%d\n",
+ ctrl->bRequestType, ctrl->bRequest,
+ w_value, w_index, w_length);
+
+ req->length = ret;
+ ret = usb_ep_queue(cdev->gadget->ep0, req, GFP_ATOMIC);
+ if (ret < 0)
+ ERROR(f->config->cdev,
+ "ccid: ep0 enqueue err %d\n", ret);
+ }
+
+ return ret;
+}
+
+static void ccidg_function_disable(struct usb_function *f)
+{
+ struct f_ccidg *ccidg = func_to_ccidg(f);
+ struct ccidg_bulk_dev *bulk_dev = &ccidg->bulk_dev;
+ struct usb_request *req;
+
+ /* Disable endpoints */
+ usb_ep_disable(ccidg->in);
+ usb_ep_disable(ccidg->out);
+
+ /* Free endpoint related requests */
+ if (!atomic_read(&bulk_dev->rx_req_busy))
+ ccidg_request_free(bulk_dev->rx_req, ccidg->out);
+ while ((req = ccidg_req_get(ccidg, &bulk_dev->tx_idle)))
+ ccidg_request_free(req, ccidg->in);
+
+ atomic_set(&ccidg->online, 0);
+
+ /* Wake up threads */
+ wake_up(&bulk_dev->write_wq);
+ wake_up(&bulk_dev->read_wq);
+}
+
+int ccidg_start_ep(struct f_ccidg *ccidg, struct usb_function *f,
+ struct usb_ep *ep)
+{
+ struct usb_composite_dev *cdev = f->config->cdev;
+ int ret;
+
+ usb_ep_disable(ep);
+
+ ret = config_ep_by_speed(cdev->gadget, f, ep);
+ if (ret) {
+ ERROR(cdev, "ccid: can't configure %s: %d\n", ep->name, ret);
+ return ret;
+ }
+
+ ret = usb_ep_enable(ep);
+ if (ret) {
+ ERROR(cdev, "ccid: can't start %s: %d\n", ep->name, ret);
+ return ret;
+ }
+
+ ep->driver_data = ccidg;
+
+ return ret;
+}
+
+static int ccidg_function_set_alt(struct usb_function *f,
+ unsigned int intf, unsigned int alt)
+{
+ struct f_ccidg *ccidg = func_to_ccidg(f);
+ struct usb_composite_dev *cdev = f->config->cdev;
+ struct ccidg_bulk_dev *bulk_dev = &ccidg->bulk_dev;
+ struct usb_request *req;
+ int ret;
+ int i;
+
+ /* Allocate requests for our endpoints */
+ req = ccidg_request_alloc(ccidg->out,
+ sizeof(struct ccidg_bulk_out_header));
+ if (IS_ERR(req)) {
+ ERROR(cdev, "ccid: uname to allocate memory for out req\n");
+ return PTR_ERR(req);
+ }
+ req->complete = ccidg_bulk_complete_rx;
+ req->context = ccidg;
+ bulk_dev->rx_req = req;
+
+ /* Allocate bunch of in requests */
+ for (i = 0; i < N_TX_REQS; i++) {
+ req = ccidg_request_alloc(ccidg->in,
+ sizeof(struct ccidg_bulk_in_header));
+
+ if (IS_ERR(req)) {
+ ret = PTR_ERR(req);
+ ERROR(cdev,
+ "ccid: uname to allocate memory for in req\n");
+ goto free_bulk_out;
+ }
+ req->complete = ccidg_bulk_complete_tx;
+ req->context = ccidg;
+ ccidg_req_put(ccidg, &bulk_dev->tx_idle, req);
+ }
+
+ /* choose the descriptors and enable endpoints */
+ ret = ccidg_start_ep(ccidg, f, ccidg->in);
+ if (ret)
+ goto free_bulk_in;
+
+ ret = ccidg_start_ep(ccidg, f, ccidg->out);
+ if (ret)
+ goto disable_ep_in;
+
+ atomic_set(&ccidg->online, 1);
+ return ret;
+
+disable_ep_in:
+ usb_ep_disable(ccidg->in);
+free_bulk_in:
+ while ((req = ccidg_req_get(ccidg, &bulk_dev->tx_idle)))
+ ccidg_request_free(req, ccidg->in);
+free_bulk_out:
+ ccidg_request_free(bulk_dev->rx_req, ccidg->out);
+ return ret;
+}
+
+static int ccidg_bulk_open(struct inode *inode, struct file *file)
+{
+ struct f_ccidg *ccidg;
+ struct ccidg_bulk_dev *bulk_dev;
+
+ ccidg = container_of(inode->i_cdev, struct f_ccidg, cdev);
+ bulk_dev = &ccidg->bulk_dev;
+
+ if (!atomic_read(&ccidg->online)) {
+ DBG(ccidg->function.config->cdev, "ccid: device not online\n");
+ return -ENODEV;
+ }
+
+ if (atomic_read(&bulk_dev->is_open)) {
+ DBG(ccidg->function.config->cdev,
+ "ccid: device already opened\n");
+ return -EBUSY;
+ }
+
+ atomic_set(&bulk_dev->is_open, 1);
+
+ file->private_data = ccidg;
+
+ return 0;
+}
+
+static int ccidg_bulk_release(struct inode *inode, struct file *file)
+{
+ struct f_ccidg *ccidg = file->private_data;
+ struct ccidg_bulk_dev *bulk_dev = &ccidg->bulk_dev;
+
+ atomic_set(&bulk_dev->is_open, 0);
+ return 0;
+}
+
+static ssize_t ccidg_bulk_read(struct file *file, char __user *buf,
+ size_t count, loff_t *pos)
+{
+ struct f_ccidg *ccidg = file->private_data;
+ struct ccidg_bulk_dev *bulk_dev = &ccidg->bulk_dev;
+ struct usb_request *req;
+ int r = count, xfer;
+ int ret;
+
+ /* Make sure we have enough space for a whole package */
+ if (count < sizeof(struct ccidg_bulk_out_header)) {
+ DBG(ccidg->function.config->cdev,
+ "ccid: too small buffer size. %i provided, need at least %i\n",
+ count, sizeof(struct ccidg_bulk_out_header));
+ return -ENOMEM;
+ }
+
+ if (!atomic_read(&ccidg->online))
+ return -ENODEV;
+
+ /* queue a request */
+ req = bulk_dev->rx_req;
+ req->length = count;
+ atomic_set(&bulk_dev->rx_done, 0);
+
+ ret = usb_ep_queue(ccidg->out, req, GFP_KERNEL);
+ if (ret < 0) {
+ ERROR(ccidg->function.config->cdev,
+ "ccid: usb ep queue failed\n");
+ return -EIO;
+ }
+
+ if (!atomic_read(&bulk_dev->rx_done) &&
+ file->f_flags & (O_NONBLOCK | O_NDELAY))
+ return -EAGAIN;
+
+ /* wait for a request to complete */
+ ret = wait_event_interruptible(bulk_dev->read_wq,
+ atomic_read(&bulk_dev->rx_done) ||
+ !atomic_read(&ccidg->online));
+ if (ret < 0) {
+ usb_ep_dequeue(ccidg->out, req);
+ return -ERESTARTSYS;
+ }
+
+ /* Still online? */
+ if (!atomic_read(&ccidg->online))
+ return -ENODEV;
+
+ atomic_set(&bulk_dev->rx_req_busy, 1);
+ xfer = (req->actual < count) ? req->actual : count;
+
+ if (copy_to_user(buf, req->buf, xfer))
+ r = -EFAULT;
+
+ atomic_set(&bulk_dev->rx_req_busy, 0);
+ if (!atomic_read(&ccidg->online)) {
+ ccidg_request_free(bulk_dev->rx_req, ccidg->out);
+ return -ENODEV;
+ }
+
+ return xfer;
+}
+
+static ssize_t ccidg_bulk_write(struct file *file, const char __user *buf,
+ size_t count, loff_t *pos)
+{
+ struct f_ccidg *ccidg = file->private_data;
+ struct ccidg_bulk_dev *bulk_dev = &ccidg->bulk_dev;
+ struct usb_request *req = 0;
+ int ret;
+
+ /* Are we online? */
+ if (!atomic_read(&ccidg->online))
+ return -ENODEV;
+
+ /* Avoid Zero Length Packets (ZLP) */
+ if (!count)
+ return 0;
+
+ /* Make sure we have enough space for a whole package */
+ if (count > sizeof(struct ccidg_bulk_out_header)) {
+ DBG(ccidg->function.config->cdev,
+ "ccid: too much data. %i provided, but we can only handle %i\n",
+ count, sizeof(struct ccidg_bulk_out_header));
+ return -ENOMEM;
+ }
+
+ if (list_empty(&bulk_dev->tx_idle) &&
+ file->f_flags & (O_NONBLOCK | O_NDELAY))
+ return -EAGAIN;
+
+ /* get an idle tx request to use */
+ ret = wait_event_interruptible(bulk_dev->write_wq,
+ ((req = ccidg_req_get(ccidg, &bulk_dev->tx_idle))));
+
+ if (ret < 0)
+ return -ERESTARTSYS;
+
+ if (copy_from_user(req->buf, buf, count)) {
+ if (!atomic_read(&ccidg->online)) {
+ ccidg_request_free(req, ccidg->in);
+ return -ENODEV;
+ } else {
+ ccidg_req_put(ccidg, &bulk_dev->tx_idle, req);
+ return -EFAULT;
+ }
+ }
+
+ req->length = count;
+ ret = usb_ep_queue(ccidg->in, req, GFP_KERNEL);
+ if (ret < 0) {
+ ccidg_req_put(ccidg, &bulk_dev->tx_idle, req);
+
+ if (!atomic_read(&ccidg->online)) {
+ /* Free up all requests if we are not online */
+ while ((req = ccidg_req_get(ccidg, &bulk_dev->tx_idle)))
+ ccidg_request_free(req, ccidg->in);
+
+ return -ENODEV;
+ }
+ return -EIO;
+ }
+
+ return count;
+}
+
+static __poll_t ccidg_bulk_poll(struct file *file, poll_table * wait)
+{
+ struct f_ccidg *ccidg = file->private_data;
+ struct ccidg_bulk_dev *bulk_dev = &ccidg->bulk_dev;
+ __poll_t ret = 0;
+
+ poll_wait(file, &bulk_dev->read_wq, wait);
+ poll_wait(file, &bulk_dev->write_wq, wait);
+
+ if (list_empty(&bulk_dev->tx_idle))
+ ret |= EPOLLOUT | EPOLLWRNORM;
+
+ if (atomic_read(&bulk_dev->rx_done))
+ ret |= EPOLLIN | EPOLLRDNORM;
+
+ return ret;
+}
+
+static const struct file_operations f_ccidg_fops = {
+ .owner = THIS_MODULE,
+ .read = ccidg_bulk_read,
+ .write = ccidg_bulk_write,
+ .open = ccidg_bulk_open,
+ .poll = ccidg_bulk_poll,
+ .release = ccidg_bulk_release,
+};
+
+static int ccidg_bulk_device_init(struct f_ccidg *dev)
+{
+ struct ccidg_bulk_dev *bulk_dev = &dev->bulk_dev;
+
+ init_waitqueue_head(&bulk_dev->read_wq);
+ init_waitqueue_head(&bulk_dev->write_wq);
+ INIT_LIST_HEAD(&bulk_dev->tx_idle);
+
+ return 0;
+}
+
+static void ccidg_function_free(struct usb_function *f)
+{
+ struct f_ccidg *ccidg;
+ struct f_ccidg_opts *opts;
+
+ ccidg = func_to_ccidg(f);
+ opts = container_of(f->fi, struct f_ccidg_opts, func_inst);
+
+ kfree(ccidg);
+ mutex_lock(&opts->lock);
+ --opts->refcnt;
+ mutex_unlock(&opts->lock);
+}
+
+static void ccidg_function_unbind(struct usb_configuration *c,
+ struct usb_function *f)
+{
+ struct f_ccidg *ccidg = func_to_ccidg(f);
+
+ device_destroy(ccidg_class, MKDEV(major, ccidg->minor));
+ cdev_del(&ccidg->cdev);
+
+ /* disable/free request and end point */
+ usb_free_all_descriptors(f);
+}
+
+static int ccidg_function_bind(struct usb_configuration *c,
+ struct usb_function *f)
+{
+ struct f_ccidg *ccidg = func_to_ccidg(f);
+ struct usb_ep *ep;
+ struct usb_composite_dev *cdev = c->cdev;
+ struct device *device;
+ dev_t dev;
+ int ifc_id;
+ int ret;
+
+ /* allocate instance-specific interface IDs, and patch descriptors */
+ ifc_id = usb_interface_id(c, f);
+ if (ifc_id < 0) {
+ ERROR(cdev, "ccid: unable to allocate ifc id, err:%d\n",
+ ifc_id);
+ return ifc_id;
+ }
+ ccid_interface_desc.bInterfaceNumber = ifc_id;
+
+ /* allocate instance-specific endpoints */
+ ep = usb_ep_autoconfig(cdev->gadget, &ccid_fs_in_desc);
+ if (!ep) {
+ ERROR(cdev, "ccid: usb epin autoconfig failed\n");
+ ret = -ENODEV;
+ goto ep_auto_in_fail;
+ }
+ ccidg->in = ep;
+ ep->driver_data = ccidg;
+
+ ep = usb_ep_autoconfig(cdev->gadget, &ccid_fs_out_desc);
+ if (!ep) {
+ ERROR(cdev, "ccid: usb epout autoconfig failed\n");
+ ret = -ENODEV;
+ goto ep_auto_out_fail;
+ }
+ ccidg->out = ep;
+ ep->driver_data = ccidg;
+
+ /* set descriptor dynamic values */
+ ccid_class_desc.dwFeatures = cpu_to_le32(ccidg->features);
+ ccid_class_desc.bPINSupport = ccidg->pinsupport;
+ ccid_class_desc.wLcdLayout = cpu_to_le16(ccidg->lcdlayout);
+ ccid_class_desc.bMaxSlotIndex = ccidg->nslots;
+ ccid_class_desc.dwProtocols = cpu_to_le32(ccidg->protocols);
+
+ if (ccidg->protocols == CCID_PROTOCOL_NOT_SEL) {
+ ccidg->protocols = CCID_PROTOCOL_T0 | CCID_PROTOCOL_T1;
+ INFO(ccidg->function.config->cdev,
+ "ccid: No protocol selected. Support both T0 and T1.\n");
+ }
+
+
+ ccid_hs_in_desc.bEndpointAddress =
+ ccid_fs_in_desc.bEndpointAddress;
+ ccid_hs_out_desc.bEndpointAddress =
+ ccid_fs_out_desc.bEndpointAddress;
+
+ ret = usb_assign_descriptors(f, ccid_fs_descs,
+ ccid_hs_descs, NULL, NULL);
+ if (ret)
+ goto ep_auto_out_fail;
+
+ /* create char device */
+ cdev_init(&ccidg->cdev, &f_ccidg_fops);
+ dev = MKDEV(major, ccidg->minor);
+ ret = cdev_add(&ccidg->cdev, dev, 1);
+ if (ret)
+ goto fail_free_descs;
+
+ device = device_create(ccidg_class, NULL, dev, NULL,
+ "%s%d", "ccidg", ccidg->minor);
+ if (IS_ERR(device)) {
+ ret = PTR_ERR(device);
+ goto del;
+ }
+
+ return 0;
+
+del:
+ cdev_del(&ccidg->cdev);
+fail_free_descs:
+ usb_free_all_descriptors(f);
+ep_auto_out_fail:
+ ccidg->out->driver_data = NULL;
+ ccidg->out = NULL;
+ep_auto_in_fail:
+ ccidg->in->driver_data = NULL;
+ ccidg->in = NULL;
+ ERROR(f->config->cdev, "ccidg_bind FAILED\n");
+
+ return ret;
+}
+
+static struct usb_function *ccidg_alloc(struct usb_function_instance *fi)
+{
+ struct f_ccidg *ccidg;
+ struct f_ccidg_opts *opts;
+ int ret;
+
+ ccidg = kzalloc(sizeof(*ccidg), GFP_KERNEL);
+ if (!ccidg)
+ return ERR_PTR(-ENOMEM);
+
+ spin_lock_init(&ccidg->lock);
+
+ ret = ccidg_bulk_device_init(ccidg);
+ if (ret) {
+ kfree(ccidg);
+ return ERR_PTR(ret);
+ }
+
+ opts = container_of(fi, struct f_ccidg_opts, func_inst);
+
+ mutex_lock(&opts->lock);
+ ++opts->refcnt;
+
+ ccidg->minor = opts->minor;
+ ccidg->features = opts->features;
+ ccidg->protocols = opts->protocols;
+ ccidg->pinsupport = opts->pinsupport;
+ ccidg->nslots = opts->nslots;
+ mutex_unlock(&opts->lock);
+
+ ccidg->function.name = "ccid";
+ ccidg->function.bind = ccidg_function_bind;
+ ccidg->function.unbind = ccidg_function_unbind;
+ ccidg->function.set_alt = ccidg_function_set_alt;
+ ccidg->function.disable = ccidg_function_disable;
+ ccidg->function.setup = ccidg_function_setup;
+ ccidg->function.free_func = ccidg_function_free;
+
+ return &ccidg->function;
+}
+
+static void ccidg_free_inst(struct usb_function_instance *f)
+{
+ struct f_ccidg_opts *opts;
+
+ opts = container_of(f, struct f_ccidg_opts, func_inst);
+ mutex_lock(&ccidg_ida_lock);
+
+ ccidg_put_minor(opts->minor);
+ if (ida_is_empty(&ccidg_ida))
+ ccidg_cleanup();
+
+ mutex_unlock(&ccidg_ida_lock);
+
+ kfree(opts);
+}
+
+static struct usb_function_instance *ccidg_alloc_inst(void)
+{
+ struct f_ccidg_opts *opts;
+ struct usb_function_instance *ret;
+ int status = 0;
+
+ opts = kzalloc(sizeof(*opts), GFP_KERNEL);
+ if (!opts)
+ return ERR_PTR(-ENOMEM);
+
+ mutex_init(&opts->lock);
+ opts->func_inst.free_func_inst = ccidg_free_inst;
+ ret = &opts->func_inst;
+
+ mutex_lock(&ccidg_ida_lock);
+
+ if (ida_is_empty(&ccidg_ida)) {
+ status = ccidg_setup();
+ if (status) {
+ ret = ERR_PTR(status);
+ kfree(opts);
+ goto unlock;
+ }
+ }
+
+ opts->minor = ccidg_get_minor();
+ if (opts->minor < 0) {
+ ret = ERR_PTR(opts->minor);
+ kfree(opts);
+ if (ida_is_empty(&ccidg_ida))
+ ccidg_cleanup();
+ goto unlock;
+ }
+
+ config_group_init_type_name(&opts->func_inst.group,
+ "", &ccidg_func_type);
+
+unlock:
+ mutex_unlock(&ccidg_ida_lock);
+ return ret;
+}
+
+DECLARE_USB_FUNCTION_INIT(ccid, ccidg_alloc_inst, ccidg_alloc);
+
+MODULE_DESCRIPTION("USB CCID Gadget driver");
+MODULE_AUTHOR("Marcus Folkesson <marcus.folkesson@gmail.com>");
+MODULE_LICENSE("GPL v2");
diff --git a/drivers/usb/gadget/function/f_ccid.h b/drivers/usb/gadget/function/f_ccid.h
new file mode 100644
index 000000000000..9dc182d1f819
--- /dev/null
+++ b/drivers/usb/gadget/function/f_ccid.h
@@ -0,0 +1,91 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/*
+ * Copyright (C) 2018 Marcus Folkesson <marcus.folkesson@gmail.com>
+ */
+
+#ifndef F_CCID_H
+#define F_CCID_H
+
+#define CCID1_10 0x0110
+#define CCID_DECRIPTOR_TYPE 0x21
+#define ABDATA_SIZE 512
+#define SMART_CARD_DEVICE_CLASS 0x0B
+
+/* CCID Class Specific Request */
+#define CCIDGENERICREQ_ABORT 0x01
+#define CCIDGENERICREQ_GET_CLOCK_FREQUENCIES 0x02
+#define CCIDGENERICREQ_GET_DATA_RATES 0x03
+
+/* Supported voltages */
+#define CCID_VOLTS_AUTO 0x00
+#define CCID_VOLTS_5_0 0x01
+#define CCID_VOLTS_3_0 0x02
+#define CCID_VOLTS_1_8 0x03
+
+struct f_ccidg_opts {
+ struct usb_function_instance func_inst;
+ int minor;
+ __u32 features;
+ __u32 protocols;
+ __u8 pinsupport;
+ __u8 nslots;
+ __u8 lcdlayout;
+
+ /*
+ * Protect the data form concurrent access by read/write
+ * and create symlink/remove symlink.
+ */
+ struct mutex lock;
+ int refcnt;
+};
+
+struct ccidg_bulk_in_header {
+ __u8 bMessageType;
+ __u32 wLength;
+ __u8 bSlot;
+ __u8 bSeq;
+ __u8 bStatus;
+ __u8 bError;
+ __u8 bSpecific;
+ __u8 abData[ABDATA_SIZE];
+ __u8 bSizeToSend;
+} __packed;
+
+struct ccidg_bulk_out_header {
+ __u8 bMessageType;
+ __u32 wLength;
+ __u8 bSlot;
+ __u8 bSeq;
+ __u8 bSpecific_0;
+ __u8 bSpecific_1;
+ __u8 bSpecific_2;
+ __u8 APDU[ABDATA_SIZE];
+} __packed;
+
+struct ccid_class_descriptor {
+ __u8 bLength;
+ __u8 bDescriptorType;
+ __u16 bcdCCID;
+ __u8 bMaxSlotIndex;
+ __u8 bVoltageSupport;
+ __u32 dwProtocols;
+ __u32 dwDefaultClock;
+ __u32 dwMaximumClock;
+ __u8 bNumClockSupported;
+ __u32 dwDataRate;
+ __u32 dwMaxDataRate;
+ __u8 bNumDataRatesSupported;
+ __u32 dwMaxIFSD;
+ __u32 dwSynchProtocols;
+ __u32 dwMechanical;
+ __u32 dwFeatures;
+ __u32 dwMaxCCIDMessageLength;
+ __u8 bClassGetResponse;
+ __u8 bClassEnvelope;
+ __u16 wLcdLayout;
+ __u8 bPINSupport;
+ __u8 bMaxCCIDBusySlots;
+} __packed;
+
+
+#endif
diff --git a/include/uapi/linux/usb/ccid.h b/include/uapi/linux/usb/ccid.h
new file mode 100644
index 000000000000..517897201563
--- /dev/null
+++ b/include/uapi/linux/usb/ccid.h
@@ -0,0 +1,93 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/*
+ * Copyright (C) 2018 Marcus Folkesson <marcus.folkesson@gmail.com>
+ *
+ * This file holds USB constants defined by the CCID Specification.
+ */
+
+#ifndef CCID_H
+#define CCID_H
+
+/* Slot error register when bmCommandStatus = 1 */
+#define CCID_CMD_ABORTED 0xFF
+#define CCID_ICC_MUTE 0xFE
+#define CCID_XFR_PARITY_ERROR 0xFD
+#define CCID_XFR_OVERRUN 0xFC
+#define CCID_HW_ERROR 0xFB
+#define CCID_BAD_ATR_TS 0xF8
+#define CCID_BAD_ATR_TCK 0xF7
+#define CCID_ICC_PROTOCOL_NOT_SUPPORTED 0xF6
+#define CCID_ICC_CLASS_NOT_SUPPORTED 0xF5
+#define CCID_PROCEDURE_BYTE_CONFLICT 0xF4
+#define CCID_DEACTIVATED_PROTOCOL 0xF3
+#define CCID_BUSY_WITH_AUTO_SEQUENCE 0xF2
+#define CCID_PIN_TIMEOUT 0xF0
+#define CCID_PIN_CANCELLED 0xEF
+#define CCID_CMD_SLOT_BUSY 0xE0
+
+/* PC to RDR messages (bulk out) */
+#define CCID_PC_TO_RDR_ICCPOWERON 0x62
+#define CCID_PC_TO_RDR_ICCPOWEROFF 0x63
+#define CCID_PC_TO_RDR_GETSLOTSTATUS 0x65
+#define CCID_PC_TO_RDR_XFRBLOCK 0x6F
+#define CCID_PC_TO_RDR_GETPARAMETERS 0x6C
+#define CCID_PC_TO_RDR_RESETPARAMETERS 0x6D
+#define CCID_PC_TO_RDR_SETPARAMETERS 0x61
+#define CCID_PC_TO_RDR_ESCAPE 0x6B
+#define CCID_PC_TO_RDR_ICCCLOCK 0x6E
+#define CCID_PC_TO_RDR_T0APDU 0x6A
+#define CCID_PC_TO_RDR_SECURE 0x69
+#define CCID_PC_TO_RDR_MECHANICAL 0x71
+#define CCID_PC_TO_RDR_ABORT 0x72
+#define CCID_PC_TO_RDR_SETDATARATEANDCLOCKFREQUENCY 0x73
+
+/* RDR to PC messages (bulk in) */
+#define CCID_RDR_TO_PC_DATABLOCK 0x80
+#define CCID_RDR_TO_PC_SLOTSTATUS 0x81
+#define CCID_RDR_TO_PC_PARAMETERS 0x82
+#define CCID_RDR_TO_PC_ESCAPE 0x83
+#define CCID_RDR_TO_PC_DATARATEANDCLOCKFREQUENCY 0x84
+
+/* Class Features */
+
+/* No special characteristics */
+#define CCID_FEATURES_NADA 0x00000000
+/* Automatic parameter configuration based on ATR data */
+#define CCID_FEATURES_AUTO_PCONF 0x00000002
+/* Automatic activation of ICC on inserting */
+#define CCID_FEATURES_AUTO_ACTIV 0x00000004
+/* Automatic ICC voltage selection */
+#define CCID_FEATURES_AUTO_VOLT 0x00000008
+/* Automatic ICC clock frequency change */
+#define CCID_FEATURES_AUTO_CLOCK 0x00000010
+/* Automatic baud rate change */
+#define CCID_FEATURES_AUTO_BAUD 0x00000020
+/*Automatic parameters negotiation made by the CCID */
+#define CCID_FEATURES_AUTO_PNEGO 0x00000040
+/* Automatic PPS made by the CCID according to the active parameters */
+#define CCID_FEATURES_AUTO_PPS 0x00000080
+/* CCID can set ICC in clock stop mode */
+#define CCID_FEATURES_ICCSTOP 0x00000100
+/* NAD value other than 00 accepted (T=1 protocol in use) */
+#define CCID_FEATURES_NAD 0x00000200
+/* Automatic IFSD exchange as first exchange (T=1 protocol in use) */
+#define CCID_FEATURES_AUTO_IFSD 0x00000400
+/* TPDU level exchanges with CCID */
+#define CCID_FEATURES_EXC_TPDU 0x00010000
+/* Short APDU level exchange with CCID */
+#define CCID_FEATURES_EXC_SAPDU 0x00020000
+/* Short and Extended APDU level exchange with CCID */
+#define CCID_FEATURES_EXC_APDU 0x00040000
+/* USB Wake up signaling supported on card insertion and removal */
+#define CCID_FEATURES_WAKEUP 0x00100000
+
+/* Supported protocols */
+#define CCID_PROTOCOL_NOT_SEL 0x00
+#define CCID_PROTOCOL_T0 0x01
+#define CCID_PROTOCOL_T1 0x02
+
+#define CCID_PINSUPOORT_NONE 0x00
+#define CCID_PINSUPOORT_VERIFICATION (1 << 1)
+#define CCID_PINSUPOORT_MODIFICATION (1 << 2)
+
+#endif
--
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
^ permalink raw reply related
* Re: [PATCH 1/3] usb: gadget: ccid: add support for USB CCID Gadget Device
From: Greg Kroah-Hartman @ 2018-05-26 20:56 UTC (permalink / raw)
To: Marcus Folkesson
Cc: Jonathan Corbet, Felipe Balbi, davem, Mauro Carvalho Chehab,
Andrew Morton, Randy Dunlap, Ruslan Bilovol, Thomas Gleixner,
Kate Stewart, linux-usb, linux-doc, linux-kernel
In-Reply-To: <20180526203401.16586-1-marcus.folkesson@gmail.com>
On Sat, May 26, 2018 at 10:33:59PM +0200, Marcus Folkesson wrote:
> Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
I can't take patches without any changelog text. And why would you
submit a patch over 1000 lines without any?
Please fix.
thanks,
greg k-h
--
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
^ permalink raw reply
* [PATCH 2/3] Documentation: usb: add documentation for USB CCID Gadget Device
From: Marcus Folkesson @ 2018-05-26 20:34 UTC (permalink / raw)
To: Greg Kroah-Hartman, Jonathan Corbet, Felipe Balbi, davem,
Mauro Carvalho Chehab, Andrew Morton, Randy Dunlap,
Ruslan Bilovol, Thomas Gleixner, Kate Stewart
Cc: linux-usb, linux-doc, linux-kernel, Marcus Folkesson
In-Reply-To: <20180526203401.16586-1-marcus.folkesson@gmail.com>
Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
---
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 <marcus.folkesson@gmail.com>
+
+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
^ permalink raw reply related
* [PATCH 3/3] MAINTAINERS: add USB CCID Gadget Device
From: Marcus Folkesson @ 2018-05-26 20:34 UTC (permalink / raw)
To: Greg Kroah-Hartman, Jonathan Corbet, Felipe Balbi, davem,
Mauro Carvalho Chehab, Andrew Morton, Randy Dunlap,
Ruslan Bilovol, Thomas Gleixner, Kate Stewart
Cc: linux-usb, linux-doc, linux-kernel, Marcus Folkesson
In-Reply-To: <20180526203401.16586-1-marcus.folkesson@gmail.com>
Add MAINTAINERS entry for USB CCID Gadget Device
Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
---
MAINTAINERS | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 078fd80f664f..e77c3d2bec89 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14541,6 +14541,14 @@ L: linux-scsi@vger.kernel.org
S: Maintained
F: drivers/usb/storage/uas.c
+USB CCID GADGET
+M: Marcus Folkesson <marcus.folkesson@gmail.com>
+L: linux-usb@vger.kernel.org
+S: Maintained
+F: drivers/usb/gadget/function/f_ccid.*
+F: include/uapi/linux/usb/ccid.h
+F: Documentation/usb/gadget_ccid.rst
+
USB CDC ETHERNET DRIVER
M: Oliver Neukum <oliver@neukum.org>
L: linux-usb@vger.kernel.org
--
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
^ permalink raw reply related
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox