요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
===============
2
USB3 debug port
3
===============
5
:Author: Lu Baolu <[email protected]>
6
:Date: March 2017
8
GENERAL
9
=======
11
This is a HOWTO for using the USB3 debug port on x86 systems.
13
Before using any kernel debugging functionality based on USB3
14
debug port, you need to::
16
1) check whether any USB3 debug port is available in
17
your system;
18
2) check which port is used for debugging purposes;
19
3) have a USB 3.0 super-speed A-to-A debugging cable.
21
INTRODUCTION
22
============
24
The xHCI debug capability (DbC) is an optional but standalone
25
functionality provided by the xHCI host controller. The xHCI
26
specification describes DbC in the section 7.6.
28
When DbC is initialized and enabled, it will present a debug
29
device through the debug port (normally the first USB3
30
super-speed port). The debug device is fully compliant with
31
the USB framework and provides the equivalent of a very high
32
performance full-duplex serial link between the debug target
33
(the system under debugging) and a debug host.
35
EARLY PRINTK
36
============
38
DbC has been designed to log early printk messages. One use for
39
this feature is kernel debugging. For example, when your machine
40
crashes very early before the regular console code is initialized.
41
Other uses include simpler, lockless logging instead of a full-
42
blown printk console driver and klogd.
44
On the debug target system, you need to customize a debugging
45
kernel with CONFIG_EARLY_PRINTK_USB_XDBC enabled. And, add below
46
kernel boot parameter::
48
"earlyprintk=xdbc"
50
If there are multiple xHCI controllers in your system, you can
51
append a host controller index to this kernel parameter. This
52
index starts from 0.
54
Current design doesn't support DbC runtime suspend/resume. As
55
the result, you'd better disable runtime power management for
56
USB subsystem by adding below kernel boot parameter::
58
"usbcore.autosuspend=-1"
60
Before starting the debug target, you should connect the debug
61
port to a USB port (root port or port of any external hub) on
62
the debug host. The cable used to connect these two ports
63
should be a USB 3.0 super-speed A-to-A debugging cable.
65
During early boot of the debug target, DbC will be detected and
66
initialized. After initialization, the debug host should be able
67
to enumerate the debug device in debug target. The debug host
68
will then bind the debug device with the usb_debug driver module
69
and create the /dev/ttyUSB device.
71
If the debug device enumeration goes smoothly, you should be able
72
to see below kernel messages on the debug host::
74
# tail -f /var/log/kern.log
75
[ 1815.983374] usb 4-3: new SuperSpeed USB device number 4 using xhci_hcd
76
[ 1815.999595] usb 4-3: LPM exit latency is zeroed, disabling LPM.
77
[ 1815.999899] usb 4-3: New USB device found, idVendor=1d6b, idProduct=0004
78
[ 1815.999902] usb 4-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
79
[ 1815.999903] usb 4-3: Product: Remote GDB
80
[ 1815.999904] usb 4-3: Manufacturer: Linux
81
[ 1815.999905] usb 4-3: SerialNumber: 0001
82
[ 1816.000240] usb_debug 4-3:1.0: xhci_dbc converter detected
83
[ 1816.000360] usb 4-3: xhci_dbc converter now attached to ttyUSB0
85
You can use any communication program, for example minicom, to
86
read and view the messages. Below simple bash scripts can help
87
you to check the sanity of the setup.
89
.. code-block:: sh
91
===== start of bash scripts =============
92
#!/bin/bash
94
while true ; do
95
while [ ! -d /sys/class/tty/ttyUSB0 ] ; do
96
:
97
done
98
cat /dev/ttyUSB0
99
done
100
===== end of bash scripts ===============
102
Serial TTY
103
==========
105
The DbC support has been added to the xHCI driver. You can get a
106
debug device provided by the DbC at runtime.
108
In order to use this, you need to make sure your kernel has been
109
configured to support USB_XHCI_DBGCAP. A sysfs attribute under
110
the xHCI device node is used to enable or disable DbC. By default,
111
DbC is disabled::
113
root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc
114
disabled
116
Enable DbC with the following command::
118
root@target:/sys/bus/pci/devices/0000:00:14.0# echo enable > dbc
120
You can check the DbC state at anytime::
122
root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc
123
enabled
125
Connect the debug target to the debug host with a USB 3.0 super-
126
speed A-to-A debugging cable. You can see /dev/ttyDBC0 created
127
on the debug target. You will see below kernel message lines::
129
root@target: tail -f /var/log/kern.log
130
[ 182.730103] xhci_hcd 0000:00:14.0: DbC connected
131
[ 191.169420] xhci_hcd 0000:00:14.0: DbC configured
132
[ 191.169597] xhci_hcd 0000:00:14.0: DbC now attached to /dev/ttyDBC0
134
Accordingly, the DbC state has been brought up to::
136
root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc
137
configured
139
On the debug host, you will see the debug device has been enumerated.
140
You will see below kernel message lines::
142
root@host: tail -f /var/log/kern.log
143
[ 79.454780] usb 2-2.1: new SuperSpeed USB device number 3 using xhci_hcd
144
[ 79.475003] usb 2-2.1: LPM exit latency is zeroed, disabling LPM.
145
[ 79.475389] usb 2-2.1: New USB device found, idVendor=1d6b, idProduct=0010
146
[ 79.475390] usb 2-2.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
147
[ 79.475391] usb 2-2.1: Product: Linux USB Debug Target
148
[ 79.475392] usb 2-2.1: Manufacturer: Linux Foundation
149
[ 79.475393] usb 2-2.1: SerialNumber: 0001
151
The debug device works now. You can use any communication or debugging
152
program to talk between the host and the target.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
USB3 Debug Capability 개요와 준비 사항
1-34이 문서는 x86 시스템에서 USB3 debug port를 사용하는 방법을 설명합니다. 작성자는 Lu Baolu이고 문서 날짜는 2017년 3월입니다.
USB3 debug port 기반 kernel debugging을 시작하기 전에 시스템에 해당 port가 있는지, 어느 물리 port가 debugging용인지 확인하고 USB 3.0 SuperSpeed A-to-A debugging cable을 준비해야 합니다.
xHCI Debug Capability(DbC)는 xHCI host controller가 선택적으로 제공하는 독립 기능이며 xHCI specification 7.6절에 정의되어 있습니다.
DbC를 초기화하고 활성화하면 보통 첫 번째 USB3 SuperSpeed port를 통해 USB framework와 완전히 호환되는 debug device가 나타납니다. 이 장치는 debug target과 debug host 사이에 고성능 full-duplex serial link에 해당하는 통신 경로를 제공합니다.
Debug target→xHCI controller의 DbC 활성화
USB3 debug port→보통 첫 번째 SuperSpeed port
A-to-A debugging cable→USB 3.0 SuperSpeed 전용 cable
Debug host→USB device 열거
통신 경로→고성능 full-duplex serial link
Target의 독립 DbC 기능이 USB3 debug port를 통해 host에 USB debug device로 열거됩니다.
===============
USB3 debug port
===============
:Author: Lu Baolu <[email protected]>
:Date: March 2017
GENERAL
=======
This is a HOWTO for using the USB3 debug port on x86 systems.
Before using any kernel debugging functionality based on USB3
debug port, you need to::
1) check whether any USB3 debug port is available in
your system;
2) check which port is used for debugging purposes;
3) have a USB 3.0 super-speed A-to-A debugging cable.
INTRODUCTION
============
The xHCI debug capability (DbC) is an optional but standalone
functionality provided by the xHCI host controller. The xHCI
specification describes DbC in the section 7.6.
When DbC is initialized and enabled, it will present a debug
device through the debug port (normally the first USB3
super-speed port). The debug device is fully compliant with
the USB framework and provides the equivalent of a very high
performance full-duplex serial link between the debug target
(the system under debugging) and a debug host.
Early printk kernel과 boot parameter 설정
35-63DbC는 일반 console code가 초기화되기 전에 machine이 crash하는 상황의 early printk message를 기록하도록 설계되었습니다. 완전한 printk console driver와 klogd 대신 단순하고 lockless한 logging에도 사용할 수 있습니다.
Debug target kernel은 `CONFIG_EARLY_PRINTK_USB_XDBC`를 활성화해 빌드하고 kernel boot parameter에 `earlyprintk=xdbc`를 추가해야 합니다. xHCI controller가 여러 개라면 0부터 시작하는 host controller index를 이 parameter 뒤에 붙일 수 있습니다.
현재 설계는 DbC runtime suspend·resume을 지원하지 않습니다. 따라서 USB subsystem의 runtime power management를 끄도록 `usbcore.autosuspend=-1` boot parameter를 함께 지정하는 편이 안전합니다.
Target을 시작하기 전에 target debug port를 host의 root port 또는 외부 hub port에 USB 3.0 SuperSpeed A-to-A debugging cable로 연결합니다.
단계설정·조건
Kernel config`CONFIG_EARLY_PRINTK_USB_XDBC=y`
Boot parameter`earlyprintk=xdbc`
여러 controller0부터 시작하는 xHCI host controller index 추가
Runtime PM`usbcore.autosuspend=-1`
물리 연결Target debug port ↔ host root·hub port
CableUSB 3.0 SuperSpeed A-to-A debugging cable
EARLY PRINTK
============
DbC has been designed to log early printk messages. One use for
this feature is kernel debugging. For example, when your machine
crashes very early before the regular console code is initialized.
Other uses include simpler, lockless logging instead of a full-
blown printk console driver and klogd.
On the debug target system, you need to customize a debugging
kernel with CONFIG_EARLY_PRINTK_USB_XDBC enabled. And, add below
kernel boot parameter::
"earlyprintk=xdbc"
If there are multiple xHCI controllers in your system, you can
append a host controller index to this kernel parameter. This
index starts from 0.
Current design doesn't support DbC runtime suspend/resume. As
the result, you'd better disable runtime power management for
USB subsystem by adding below kernel boot parameter::
"usbcore.autosuspend=-1"
Before starting the debug target, you should connect the debug
port to a USB port (root port or port of any external hub) on
the debug host. The cable used to connect these two ports
should be a USB 3.0 super-speed A-to-A debugging cable.Early boot 열거, usb_debug binding과 로그 확인
64-100Debug target의 early boot 중 DbC가 감지·초기화됩니다. 이후 debug host가 target의 debug device를 enumerate하고 `usb_debug` driver module을 bind해 `/dev/ttyUSB` 장치를 만듭니다.
정상 열거 시 host kernel log에는 `xhci_hcd`가 새 SuperSpeed USB device를 발견하고 vendor `1d6b`, product `0004`, 제품명 `Remote GDB`를 읽은 뒤 `xhci_dbc converter`를 `ttyUSB0`에 연결했다는 메시지가 나타납니다.
`minicom` 같은 통신 program으로 early message를 읽을 수 있습니다. 원문의 bash script는 `/sys/class/tty/ttyUSB0` directory가 생길 때까지 반복 대기한 뒤 `/dev/ttyUSB0`을 `cat`하고, 장치가 사라졌다 다시 생겨도 바깥 loop에서 다시 연결합니다.
Target early boot→DbC 감지·초기화
Host USB core→Debug device enumerate
`usb_debug` module→Interface bind
`/dev/ttyUSB0`→Character TTY 생성
minicom 또는 script→Message 읽기·표시
Target boot 초기에 생성된 printk가 host ttyUSB 장치까지 전달되는 경로입니다.
During early boot of the debug target, DbC will be detected and
initialized. After initialization, the debug host should be able
to enumerate the debug device in debug target. The debug host
will then bind the debug device with the usb_debug driver module
and create the /dev/ttyUSB device.
If the debug device enumeration goes smoothly, you should be able
to see below kernel messages on the debug host::
# tail -f /var/log/kern.log
[ 1815.983374] usb 4-3: new SuperSpeed USB device number 4 using xhci_hcd
[ 1815.999595] usb 4-3: LPM exit latency is zeroed, disabling LPM.
[ 1815.999899] usb 4-3: New USB device found, idVendor=1d6b, idProduct=0004
[ 1815.999902] usb 4-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[ 1815.999903] usb 4-3: Product: Remote GDB
[ 1815.999904] usb 4-3: Manufacturer: Linux
[ 1815.999905] usb 4-3: SerialNumber: 0001
[ 1816.000240] usb_debug 4-3:1.0: xhci_dbc converter detected
[ 1816.000360] usb 4-3: xhci_dbc converter now attached to ttyUSB0
You can use any communication program, for example minicom, to
read and view the messages. Below simple bash scripts can help
you to check the sanity of the setup.
.. code-block:: sh
===== start of bash scripts =============
#!/bin/bash
while true ; do
while [ ! -d /sys/class/tty/ttyUSB0 ] ; do
:
done
cat /dev/ttyUSB0
done
===== end of bash scripts ===============Runtime Serial TTY와 dbc sysfs 상태
101-124xHCI driver에는 runtime에 DbC debug device를 제공하는 Serial TTY 지원도 포함됩니다. 이를 사용하려면 kernel이 `USB_XHCI_DBGCAP`을 지원하도록 구성되어 있어야 합니다.
xHCI PCI device node 아래의 `dbc` sysfs attribute로 DbC를 활성화하거나 비활성화합니다. 기본 상태는 `disabled`이며 `/sys/bus/pci/devices/0000:00:14.0` 예에서 `echo enable > dbc`를 실행하면 `enabled`로 바뀝니다.
`cat dbc`는 언제든 현재 state를 보여 줍니다. PCI address는 예시이므로 실제 target의 xHCI device node를 선택해야 합니다.
명령·상태의미
`cat dbc` → `disabled`기본값, DbC 비활성
`echo enable > dbc`Runtime DbC 활성화 요청
`cat dbc` → `enabled`활성화되어 cable 연결 대기
PCI node실제 xHCI controller 주소 사용
Serial TTY
==========
The DbC support has been added to the xHCI driver. You can get a
debug device provided by the DbC at runtime.
In order to use this, you need to make sure your kernel has been
configured to support USB_XHCI_DBGCAP. A sysfs attribute under
the xHCI device node is used to enable or disable DbC. By default,
DbC is disabled::
root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc
disabled
Enable DbC with the following command::
root@target:/sys/bus/pci/devices/0000:00:14.0# echo enable > dbc
You can check the DbC state at anytime::
root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc
enabled
Target ttyDBC0와 host debug device 연결
125-152USB 3.0 SuperSpeed A-to-A debugging cable로 target과 host를 연결하면 target에 `/dev/ttyDBC0`이 생성됩니다. Target log는 DbC가 `connected`, `configured` 순서로 진행하고 TTY에 attach되었음을 보여 줍니다.
구성이 끝난 뒤 target의 `dbc` sysfs state는 `configured`가 됩니다. 이 state는 host가 debug device를 실제로 enumerate하고 link가 사용할 수 있음을 뜻합니다.
Host log에는 `xhci_hcd`가 새 SuperSpeed device를 발견하고 vendor `1d6b`, product `0010`, 제품명 `Linux USB Debug Target`, 제조사 `Linux Foundation`을 읽은 기록이 표시됩니다.
이후 host와 target 사이에서 원하는 communication 또는 debugging program을 사용할 수 있습니다. Target의 `/dev/ttyDBC0`과 host에서 열거된 debug device가 양쪽 endpoint 역할을 합니다.
`disabled`→DbC 기본 상태
`echo enable > dbc`→활성화 요청
`enabled`→Cable·host 열거 대기
DbC connected→Target `/dev/ttyDBC0` 생성
DbC configured→Host가 USB debug device 열거
Communication program→Host ↔ target debugging
Sysfs enable부터 양쪽 debug channel 사용 가능 상태까지의 전이입니다.
Connect the debug target to the debug host with a USB 3.0 super-
speed A-to-A debugging cable. You can see /dev/ttyDBC0 created
on the debug target. You will see below kernel message lines::
root@target: tail -f /var/log/kern.log
[ 182.730103] xhci_hcd 0000:00:14.0: DbC connected
[ 191.169420] xhci_hcd 0000:00:14.0: DbC configured
[ 191.169597] xhci_hcd 0000:00:14.0: DbC now attached to /dev/ttyDBC0
Accordingly, the DbC state has been brought up to::
root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc
configured
On the debug host, you will see the debug device has been enumerated.
You will see below kernel message lines::
root@host: tail -f /var/log/kern.log
[ 79.454780] usb 2-2.1: new SuperSpeed USB device number 3 using xhci_hcd
[ 79.475003] usb 2-2.1: LPM exit latency is zeroed, disabling LPM.
[ 79.475389] usb 2-2.1: New USB device found, idVendor=1d6b, idProduct=0010
[ 79.475390] usb 2-2.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[ 79.475391] usb 2-2.1: Product: Linux USB Debug Target
[ 79.475392] usb 2-2.1: Manufacturer: Linux Foundation
[ 79.475393] usb 2-2.1: SerialNumber: 0001
The debug device works now. You can use any communication or debugging
program to talk between the host and the target.
요약·해설
usb3-debug-port.rst:1-152xHCI DbC는 target의 USB3 debug port를 USB 호환 debug device로 노출해 host와 고속 full-duplex serial channel을 만듭니다. Early printk에서는 전용 kernel config와 boot parameter가 필요하고, runtime mode에서는 xHCI PCI node의 dbc sysfs state와 양쪽 TTY를 확인합니다.