요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
======
usbmon
======
Introduction
============
The name "usbmon" in lowercase refers to a facility in kernel which is
used to collect traces of I/O on the USB bus. This function is analogous
to a packet socket used by network monitoring tools such as tcpdump(1)
or Ethereal. Similarly, it is expected that a tool such as usbdump or
USBMon (with uppercase letters) is used to examine raw traces produced
by usbmon.
The usbmon reports requests made by peripheral-specific drivers to Host
Controller Drivers (HCD). So, if HCD is buggy, the traces reported by
usbmon may not correspond to bus transactions precisely. This is the same
situation as with tcpdump.
Two APIs are currently implemented: "text" and "binary". The binary API
is available through a character device in /dev namespace and is an ABI.
The text API is deprecated since 2.6.35, but available for convenience.
How to use usbmon to collect raw text traces
============================================
Unlike the packet socket, usbmon has an interface which provides traces
in a text format. This is used for two purposes. First, it serves as a
common trace exchange format for tools while more sophisticated formats
are finalized. Second, humans can read it in case tools are not available.
To collect a raw text trace, execute following steps.
1. Prepare
----------
Mount debugfs (it has to be enabled in your kernel configuration), and
load the usbmon module (if built as module). The second step is skipped
if usbmon is built into the kernel::
# mount -t debugfs none_debugs /sys/kernel/debug
# modprobe usbmon
#
Verify that bus sockets are present::
# ls /sys/kernel/debug/usb/usbmon
0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u
#
Now you can choose to either use the socket '0u' (to capture packets on all
buses), and skip to step #3, or find the bus used by your device with step #2.
This allows to filter away annoying devices that talk continuously.
2. Find which bus connects to the desired device
------------------------------------------------
Run "cat /sys/kernel/debug/usb/devices", and find the T-line which corresponds
to the device. Usually you do it by looking for the vendor string. If you have
many similar devices, unplug one and compare the two
/sys/kernel/debug/usb/devices outputs. The T-line will have a bus number.
Example::
T: Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 0
D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=0557 ProdID=2004 Rev= 1.00
S: Manufacturer=ATEN
S: Product=UC100KM V2.00
"Bus=03" means it's bus 3. Alternatively, you can look at the output from
"lsusb" and get the bus number from the appropriate line. Example:
Bus 003 Device 002: ID 0557:2004 ATEN UC100KM V2.00
3. Start 'cat'
--------------
::
# cat /sys/kernel/debug/usb/usbmon/3u > /tmp/1.mon.out
to listen on a single bus, otherwise, to listen on all buses, type::
# cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out
This process will read until it is killed. Naturally, the output can be
redirected to a desirable location. This is preferred, because it is going
to be quite long.
4. Perform the desired operation on the USB bus
-----------------------------------------------
This is where you do something that creates the traffic: plug in a flash key,
copy files, control a webcam, etc.
5. Kill cat
-----------
Usually it's done with a keyboard interrupt (Control-C).
At this point the output file (/tmp/1.mon.out in this example) can be saved,
sent by e-mail, or inspected with a text editor. In the last case make sure
that the file size is not excessive for your favourite editor.
Raw text data format
====================
Two formats are supported currently: the original, or '1t' format, and
the '1u' format. The '1t' format is deprecated in kernel 2.6.21. The '1u'
format adds a few fields, such as ISO frame descriptors, interval, etc.
It produces slightly longer lines, but otherwise is a perfect superset
of '1t' format.
If it is desired to recognize one from the other in a program, look at the
"address" word (see below), where '1u' format adds a bus number. If 2 colons
are present, it's the '1t' format, otherwise '1u'.
Any text format data consists of a stream of events, such as URB submission,
URB callback, submission error. Every event is a text line, which consists
of whitespace separated words. The number or position of words may depend
on the event type, but there is a set of words, common for all types.
Here is the list of words, from left to right:
- URB Tag. This is used to identify URBs, and is normally an in-kernel address
of the URB structure in hexadecimal, but can be a sequence number or any
other unique string, within reason.
- Timestamp in microseconds, a decimal number. The timestamp's resolution
depends on available clock, and so it can be much worse than a microsecond
(if the implementation uses jiffies, for example).
- Event Type. This type refers to the format of the event, not URB type.
Available types are: S - submission, C - callback, E - submission error.
- "Address" word (formerly a "pipe"). It consists of four fields, separated by
colons: URB type and direction, Bus number, Device address, Endpoint number.
Type and direction are encoded with two bytes in the following manner:
== == =============================
Ci Co Control input and output
Zi Zo Isochronous input and output
Ii Io Interrupt input and output
Bi Bo Bulk input and output
== == =============================
Bus number, Device address, and Endpoint are decimal numbers, but they may
have leading zeros, for the sake of human readers.
- URB Status word. This is either a letter, or several numbers separated
by colons: URB status, interval, start frame, and error count. Unlike the
"address" word, all fields save the status are optional. Interval is printed
only for interrupt and isochronous URBs. Start frame is printed only for
isochronous URBs. Error count is printed only for isochronous callback
events.
The status field is a decimal number, sometimes negative, which represents
a "status" field of the URB. This field makes no sense for submissions, but
is present anyway to help scripts with parsing. When an error occurs, the
field contains the error code.
In case of a submission of a Control packet, this field contains a Setup Tag
instead of an group of numbers. It is easy to tell whether the Setup Tag is
present because it is never a number. Thus if scripts find a set of numbers
in this word, they proceed to read Data Length (except for isochronous URBs).
If they find something else, like a letter, they read the setup packet before
reading the Data Length or isochronous descriptors.
- Setup packet, if present, consists of 5 words: one of each for bmRequestType,
bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0.
These words are safe to decode if Setup Tag was 's'. Otherwise, the setup
packet was present, but not captured, and the fields contain filler.
- Number of isochronous frame descriptors and descriptors themselves.
If an Isochronous transfer event has a set of descriptors, a total number
of them in an URB is printed first, then a word per descriptor, up to a
total of 5. The word consists of 3 colon-separated decimal numbers for
status, offset, and length respectively. For submissions, initial length
is reported. For callbacks, actual length is reported.
- Data Length. For submissions, this is the requested length. For callbacks,
this is the actual length.
- Data tag. The usbmon may not always capture data, even if length is nonzero.
The data words are present only if this tag is '='.
- Data words follow, in big endian hexadecimal format. Notice that they are
not machine words, but really just a byte stream split into words to make
it easier to read. Thus, the last word may contain from one to four bytes.
The length of collected data is limited and can be less than the data length
reported in the Data Length word. In the case of an Isochronous input (Zi)
completion where the received data is sparse in the buffer, the length of
the collected data can be greater than the Data Length value (because Data
Length counts only the bytes that were received whereas the Data words
contain the entire transfer buffer).
Examples:
An input control transfer to get a port status::
d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 <
d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000
An output bulk transfer to send a SCSI command 0x28 (READ_10) in a 31-byte
Bulk wrapper to a storage device at address 5::
dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000
dd65f0e8 4128379808 C Bo:1:005:2 0 31 >
Raw binary format and API
=========================
The overall architecture of the API is about the same as the one above,
only the events are delivered in binary format. Each event is sent in
the following structure (its name is made up, so that we can refer to it)::
struct usbmon_packet {
u64 id; /* 0: URB ID - from submission to callback */
unsigned char type; /* 8: Same as text; extensible. */
unsigned char xfer_type; /* ISO (0), Intr, Control, Bulk (3) */
unsigned char epnum; /* Endpoint number and transfer direction */
unsigned char devnum; /* Device address */
u16 busnum; /* 12: Bus number */
char flag_setup; /* 14: Same as text */
char flag_data; /* 15: Same as text; Binary zero is OK. */
s64 ts_sec; /* 16: gettimeofday */
s32 ts_usec; /* 24: gettimeofday */
int status; /* 28: */
unsigned int length; /* 32: Length of data (submitted or actual) */
unsigned int len_cap; /* 36: Delivered length */
union { /* 40: */
unsigned char setup[SETUP_LEN]; /* Only for Control S-type */
struct iso_rec { /* Only for ISO */
int error_count;
int numdesc;
} iso;
} s;
int interval; /* 48: Only for Interrupt and ISO */
int start_frame; /* 52: For ISO */
unsigned int xfer_flags; /* 56: copy of URB's transfer_flags */
unsigned int ndesc; /* 60: Actual number of ISO descriptors */
}; /* 64 total length */
These events can be received from a character device by reading with read(2),
with an ioctl(2), or by accessing the buffer with mmap. However, read(2)
only returns first 48 bytes for compatibility reasons.
The character device is usually called /dev/usbmonN, where N is the USB bus
number. Number zero (/dev/usbmon0) is special and means "all buses".
Note that specific naming policy is set by your Linux distribution.
If you create /dev/usbmon0 by hand, make sure that it is owned by root
and has mode 0600. Otherwise, unprivileged users will be able to snoop
keyboard traffic.
The following ioctl calls are available, with MON_IOC_MAGIC 0x92:
MON_IOCQ_URB_LEN, defined as _IO(MON_IOC_MAGIC, 1)
This call returns the length of data in the next event. Note that majority of
events contain no data, so if this call returns zero, it does not mean that
no events are available.
MON_IOCG_STATS, defined as _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats)
The argument is a pointer to the following structure::
struct mon_bin_stats {
u32 queued;
u32 dropped;
};
The member "queued" refers to the number of events currently queued in the
buffer (and not to the number of events processed since the last reset).
The member "dropped" is the number of events lost since the last call
to MON_IOCG_STATS.
MON_IOCT_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 4)
This call sets the buffer size. The argument is the size in bytes.
The size may be rounded down to the next chunk (or page). If the requested
size is out of [unspecified] bounds for this kernel, the call fails with
-EINVAL.
MON_IOCQ_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 5)
This call returns the current size of the buffer in bytes.
MON_IOCX_GET, defined as _IOW(MON_IOC_MAGIC, 6, struct mon_get_arg)
MON_IOCX_GETX, defined as _IOW(MON_IOC_MAGIC, 10, struct mon_get_arg)
These calls wait for events to arrive if none were in the kernel buffer,
then return the first event. The argument is a pointer to the following
structure::
struct mon_get_arg {
struct usbmon_packet *hdr;
void *data;
size_t alloc; /* Length of data (can be zero) */
};
Before the call, hdr, data, and alloc should be filled. Upon return, the area
pointed by hdr contains the next event structure, and the data buffer contains
the data, if any. The event is removed from the kernel buffer.
The MON_IOCX_GET copies 48 bytes to hdr area, MON_IOCX_GETX copies 64 bytes.
MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg)
This ioctl is primarily used when the application accesses the buffer
with mmap(2). Its argument is a pointer to the following structure::
struct mon_mfetch_arg {
uint32_t *offvec; /* Vector of events fetched */
uint32_t nfetch; /* Number of events to fetch (out: fetched) */
uint32_t nflush; /* Number of events to flush */
};
The ioctl operates in 3 stages.
First, it removes and discards up to nflush events from the kernel buffer.
The actual number of events discarded is returned in nflush.
Second, it waits for an event to be present in the buffer, unless the pseudo-
device is open with O_NONBLOCK.
Third, it extracts up to nfetch offsets into the mmap buffer, and stores
them into the offvec. The actual number of event offsets is stored into
the nfetch.
MON_IOCH_MFLUSH, defined as _IO(MON_IOC_MAGIC, 8)
This call removes a number of events from the kernel buffer. Its argument
is the number of events to remove. If the buffer contains fewer events
than requested, all events present are removed, and no error is reported.
This works when no events are available too.
FIONBIO
The ioctl FIONBIO may be implemented in the future, if there's a need.
In addition to ioctl(2) and read(2), the special file of binary API can
be polled with select(2) and poll(2). But lseek(2) does not work.
* Memory-mapped access of the kernel buffer for the binary API
The basic idea is simple:
To prepare, map the buffer by getting the current size, then using mmap(2).
Then, execute a loop similar to the one written in pseudo-code below::
struct mon_mfetch_arg fetch;
struct usbmon_packet *hdr;
int nflush = 0;
for (;;) {
fetch.offvec = vec; // Has N 32-bit words
fetch.nfetch = N; // Or less than N
fetch.nflush = nflush;
ioctl(fd, MON_IOCX_MFETCH, &fetch); // Process errors, too
nflush = fetch.nfetch; // This many packets to flush when done
for (i = 0; i < nflush; i++) {
hdr = (struct ubsmon_packet *) &mmap_area[vec[i]];
if (hdr->type == '@') // Filler packet
continue;
caddr_t data = &mmap_area[vec[i]] + 64;
process_packet(hdr, data);
}
}
Thus, the main idea is to execute only one ioctl per N events.
Although the buffer is circular, the returned headers and data do not cross
the end of the buffer, so the above pseudo-code does not need any gathering.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
소개
1-23소문자 `usbmon`은 USB bus의 I/O trace를 수집하는 kernel 기능을 뜻합니다. 이는 `tcpdump(1)`나 Ethereal 같은 network monitoring tool이 사용하는 packet socket과 유사합니다.
usbmon이 만든 raw trace는 `usbdump`나 대문자를 사용한 `USBMon` 같은 tool로 살펴볼 것을 예상합니다.
usbmon은 peripheral-specific driver가 Host Controller Driver(HCD)에 보낸 request를 보고합니다. 따라서 HCD에 bug가 있으면 usbmon trace가 실제 bus transaction과 정확히 일치하지 않을 수 있으며 이는 tcpdump와 같은 상황입니다.
구현된 API는 `text`와 `binary` 두 가지입니다. binary API는 `/dev` namespace의 character device를 통해 제공되는 ABI입니다. text API는 kernel 2.6.35부터 deprecated이지만 편의를 위해 남아 있습니다.
두 수집 interface의 상태와 접근 방법입니다.
======
usbmon
======
Introduction
============
The name "usbmon" in lowercase refers to a facility in kernel which is
used to collect traces of I/O on the USB bus. This function is analogous
to a packet socket used by network monitoring tools such as tcpdump(1)
or Ethereal. Similarly, it is expected that a tool such as usbdump or
USBMon (with uppercase letters) is used to examine raw traces produced
by usbmon.
The usbmon reports requests made by peripheral-specific drivers to Host
Controller Drivers (HCD). So, if HCD is buggy, the traces reported by
usbmon may not correspond to bus transactions precisely. This is the same
situation as with tcpdump.
Two APIs are currently implemented: "text" and "binary". The binary API
is available through a character device in /dev namespace and is an ABI.
The text API is deprecated since 2.6.35, but available for convenience.
Raw text trace 준비
24-54usbmon의 text interface는 도구가 더 정교한 format을 확정하는 동안 공통 trace 교환 format으로 쓰이고, tool이 없을 때 사람이 직접 읽는 용도로도 쓰입니다.
먼저 kernel configuration에서 활성화된 debugfs를 `/sys/kernel/debug`에 mount합니다. usbmon이 module이라면 `modprobe usbmon`으로 load하며 kernel built-in이면 이 단계는 생략합니다.
`ls /sys/kernel/debug/usb/usbmon`으로 bus socket이 존재하는지 확인합니다. 예에는 `0s`, `0u`, bus별 `1s/1t/1u`부터 `4s/4t/4u`까지가 나타납니다.
모든 bus packet을 capture하려면 `0u` socket을 선택하고 3단계로 건너갑니다. 특정 장치의 bus를 2단계에서 찾으면 계속 통신하는 불필요한 장치를 filter할 수 있습니다.
debugfs와 usbmon socket을 준비하는 순서입니다.
How to use usbmon to collect raw text traces
============================================
Unlike the packet socket, usbmon has an interface which provides traces
in a text format. This is used for two purposes. First, it serves as a
common trace exchange format for tools while more sophisticated formats
are finalized. Second, humans can read it in case tools are not available.
To collect a raw text trace, execute following steps.
1. Prepare
----------
Mount debugfs (it has to be enabled in your kernel configuration), and
load the usbmon module (if built as module). The second step is skipped
if usbmon is built into the kernel::
# mount -t debugfs none_debugs /sys/kernel/debug
# modprobe usbmon
#
Verify that bus sockets are present::
# ls /sys/kernel/debug/usb/usbmon
0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u
#
Now you can choose to either use the socket '0u' (to capture packets on all
buses), and skip to step #3, or find the bus used by your device with step #2.
This allows to filter away annoying devices that talk continuously.
대상 장치의 USB bus 찾기
55-75`cat /sys/kernel/debug/usb/devices`를 실행해 대상 장치에 해당하는 T-line을 찾습니다. 보통 vendor string으로 식별하며 비슷한 장치가 많으면 하나를 분리한 전후의 output을 비교합니다.
T-line에는 bus number가 있습니다. 예제의 `T: Bus=03 ... Dev#=2`와 ATEN `Vendor=0557 ProdID=2004`, `Product=UC100KM V2.00`은 bus 3의 장치입니다.
대안으로 `lsusb`의 해당 줄에서 bus number를 얻을 수 있습니다. 예 `Bus 003 Device 002: ID 0557:2004 ATEN UC100KM V2.00` 역시 bus 3을 가리킵니다.
debugfs devices와 lsusb가 같은 장치를 표현합니다.
2. Find which bus connects to the desired device
------------------------------------------------
Run "cat /sys/kernel/debug/usb/devices", and find the T-line which corresponds
to the device. Usually you do it by looking for the vendor string. If you have
many similar devices, unplug one and compare the two
/sys/kernel/debug/usb/devices outputs. The T-line will have a bus number.
Example::
T: Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 0
D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=0557 ProdID=2004 Rev= 1.00
S: Manufacturer=ATEN
S: Product=UC100KM V2.00
"Bus=03" means it's bus 3. Alternatively, you can look at the output from
"lsusb" and get the bus number from the appropriate line. Example:
Bus 003 Device 002: ID 0557:2004 ATEN UC100KM V2.00
Trace 수집과 종료
76-105한 bus만 들으려면 `cat /sys/kernel/debug/usb/usbmon/3u > /tmp/1.mon.out`처럼 해당 bus의 `u` socket을 읽습니다.
모든 bus를 들으려면 `cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out`을 사용합니다. process는 종료할 때까지 계속 읽으며 output이 매우 길어질 수 있으므로 원하는 file로 redirect하는 편이 좋습니다.
capture가 실행되는 동안 flash key 연결, file 복사, webcam 제어처럼 조사할 USB traffic을 발생시킵니다.
작업이 끝나면 보통 Control-C keyboard interrupt로 `cat`을 종료합니다. `/tmp/1.mon.out` 결과는 저장하거나 email로 보내거나 text editor에서 확인할 수 있지만 editor가 감당할 수 있을 만큼 file이 작은지 확인해야 합니다.
특정 bus 또는 전체 bus의 trace를 수집하는 실제 작업 순서입니다.
3. Start 'cat'
--------------
::
# cat /sys/kernel/debug/usb/usbmon/3u > /tmp/1.mon.out
to listen on a single bus, otherwise, to listen on all buses, type::
# cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out
This process will read until it is killed. Naturally, the output can be
redirected to a desirable location. This is preferred, because it is going
to be quite long.
4. Perform the desired operation on the USB bus
-----------------------------------------------
This is where you do something that creates the traffic: plug in a flash key,
copy files, control a webcam, etc.
5. Kill cat
-----------
Usually it's done with a keyboard interrupt (Control-C).
At this point the output file (/tmp/1.mon.out in this example) can be saved,
sent by e-mail, or inspected with a text editor. In the last case make sure
that the file size is not excessive for your favourite editor.
Raw text format 개요
106-123지원하는 text format은 원래의 `1t`와 `1u`입니다. `1t`는 kernel 2.6.21에서 deprecated되었습니다. `1u`는 ISO frame descriptor, interval 등의 field를 추가해 line이 조금 길지만 그 밖에는 `1t`의 완전한 superset입니다.
program에서 format을 구분하려면 아래의 address word를 봅니다. `1u`는 bus number를 추가하므로 colon이 2개면 `1t`, 그 밖에는 `1u`입니다.
text data는 URB submission, URB callback, submission error 같은 event stream입니다. event 하나가 whitespace로 구분된 word들로 된 한 줄이며 word 수와 위치는 event type에 따라 달라질 수 있지만 공통 word 집합이 있습니다.
1u가 1t에 추가하는 정보와 구분 규칙입니다.
Raw text data format
====================
Two formats are supported currently: the original, or '1t' format, and
the '1u' format. The '1t' format is deprecated in kernel 2.6.21. The '1u'
format adds a few fields, such as ISO frame descriptors, interval, etc.
It produces slightly longer lines, but otherwise is a perfect superset
of '1t' format.
If it is desired to recognize one from the other in a program, look at the
"address" word (see below), where '1u' format adds a bus number. If 2 colons
are present, it's the '1t' format, otherwise '1u'.
Any text format data consists of a stream of events, such as URB submission,
URB callback, submission error. Every event is a text line, which consists
of whitespace separated words. The number or position of words may depend
on the event type, but there is a set of words, common for all types.
URB tag, timestamp, event와 address
124-149첫 word는 `URB Tag`입니다. URB를 식별하며 보통 kernel 안의 URB structure address를 hexadecimal로 표시하지만 sequence number나 합리적인 범위의 다른 unique string도 가능합니다.
두 번째는 microsecond 단위 decimal timestamp입니다. 실제 resolution은 이용 가능한 clock에 좌우되므로 jiffies를 쓰는 구현처럼 microsecond보다 훨씬 나쁠 수 있습니다.
`Event Type`은 URB type이 아니라 event line format을 뜻합니다. `S`는 submission, `C`는 callback, `E`는 submission error입니다.
`Address` word는 과거에 pipe라고 불렸으며 colon으로 구분한 네 field, 즉 URB type/direction, Bus number, Device address, Endpoint number로 구성됩니다. Bus, Device, Endpoint는 decimal이고 사람이 읽기 쉽게 leading zero가 있을 수 있습니다.
두 character로 URB type과 방향을 인코딩합니다.
왼쪽부터 나타나는 핵심 word입니다.
Here is the list of words, from left to right:
- URB Tag. This is used to identify URBs, and is normally an in-kernel address
of the URB structure in hexadecimal, but can be a sequence number or any
other unique string, within reason.
- Timestamp in microseconds, a decimal number. The timestamp's resolution
depends on available clock, and so it can be much worse than a microsecond
(if the implementation uses jiffies, for example).
- Event Type. This type refers to the format of the event, not URB type.
Available types are: S - submission, C - callback, E - submission error.
- "Address" word (formerly a "pipe"). It consists of four fields, separated by
colons: URB type and direction, Bus number, Device address, Endpoint number.
Type and direction are encoded with two bytes in the following manner:
== == =============================
Ci Co Control input and output
Zi Zo Isochronous input and output
Ii Io Interrupt input and output
Bi Bo Bulk input and output
== == =============================
Bus number, Device address, and Endpoint are decimal numbers, but they may
have leading zeros, for the sake of human readers.URB status와 setup packet
150-174`URB Status` word는 letter 하나이거나 colon으로 구분한 `URB status`, `interval`, `start frame`, `error count` 숫자들입니다. status 외 field는 모두 선택 사항입니다.
interval은 interrupt와 isochronous URB에서만, start frame은 isochronous URB에서만, error count는 isochronous callback event에서만 출력합니다.
status는 URB의 status field를 나타내는 decimal number이며 음수일 수 있습니다. submission에서는 의미가 없지만 script parsing을 돕기 위해 존재하고 error가 나면 error code를 담습니다.
Control packet submission에서는 숫자 묶음 대신 Setup Tag가 이 field에 옵니다. Setup Tag는 숫자가 아니므로 쉽게 구분합니다. script가 숫자 묶음을 보면 ISO URB가 아닌 경우 Data Length로 진행하고, letter 같은 다른 값을 보면 Data Length나 ISO descriptor 전에 setup packet을 읽습니다.
setup packet은 USB Specification 2.0의 `bmRequestType`, `bRequest`, `wValue`, `wIndex`, `wLength`에 해당하는 5 word입니다. Setup Tag가 `s`일 때만 안전하게 decode할 수 있습니다. 다른 tag이면 setup packet은 있었지만 capture되지 않아 field에 filler가 들어 있습니다.
URB 종류와 event에 따라 추가되는 값입니다.
- URB Status word. This is either a letter, or several numbers separated
by colons: URB status, interval, start frame, and error count. Unlike the
"address" word, all fields save the status are optional. Interval is printed
only for interrupt and isochronous URBs. Start frame is printed only for
isochronous URBs. Error count is printed only for isochronous callback
events.
The status field is a decimal number, sometimes negative, which represents
a "status" field of the URB. This field makes no sense for submissions, but
is present anyway to help scripts with parsing. When an error occurs, the
field contains the error code.
In case of a submission of a Control packet, this field contains a Setup Tag
instead of an group of numbers. It is easy to tell whether the Setup Tag is
present because it is never a number. Thus if scripts find a set of numbers
in this word, they proceed to read Data Length (except for isochronous URBs).
If they find something else, like a letter, they read the setup packet before
reading the Data Length or isochronous descriptors.
- Setup packet, if present, consists of 5 words: one of each for bmRequestType,
bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0.
These words are safe to decode if Setup Tag was 's'. Otherwise, the setup
packet was present, but not captured, and the fields contain filler.
ISO descriptor와 data
175-197Isochronous transfer event에 descriptor가 있으면 URB의 전체 descriptor 수를 먼저 출력하고 descriptor당 한 word를 최대 5개까지 출력합니다.
descriptor word는 colon으로 구분한 decimal `status`, `offset`, `length` 세 값입니다. submission에서는 initial length를, callback에서는 actual length를 보고합니다.
`Data Length`는 submission이면 요청 길이, callback이면 실제 길이입니다.
usbmon은 길이가 0이 아니어도 data를 항상 capture하지는 않습니다. Data Tag가 `=`일 때만 data word가 존재합니다.
data word는 big-endian hexadecimal 형식입니다. machine word가 아니라 가독성을 위해 word로 나눈 byte stream이므로 마지막 word는 1~4 byte일 수 있습니다. 수집 길이는 제한되어 Data Length보다 작을 수 있습니다.
Isochronous input(`Zi`) completion에서 받은 data가 buffer에 드문드문 있으면 수집 data 길이가 Data Length보다 클 수 있습니다. Data Length는 실제 수신 byte만 세지만 data word에는 전체 transfer buffer가 들어가기 때문입니다.
ISO descriptor와 data word의 길이 의미입니다.
- Number of isochronous frame descriptors and descriptors themselves.
If an Isochronous transfer event has a set of descriptors, a total number
of them in an URB is printed first, then a word per descriptor, up to a
total of 5. The word consists of 3 colon-separated decimal numbers for
status, offset, and length respectively. For submissions, initial length
is reported. For callbacks, actual length is reported.
- Data Length. For submissions, this is the requested length. For callbacks,
this is the actual length.
- Data tag. The usbmon may not always capture data, even if length is nonzero.
The data words are present only if this tag is '='.
- Data words follow, in big endian hexadecimal format. Notice that they are
not machine words, but really just a byte stream split into words to make
it easier to read. Thus, the last word may contain from one to four bytes.
The length of collected data is limited and can be less than the data length
reported in the Data Length word. In the case of an Isochronous input (Zi)
completion where the received data is sparse in the buffer, the length of
the collected data can be greater than the Data Length value (because Data
Length counts only the bytes that were received whereas the Data words
contain the entire transfer buffer).
Text trace 예
198-210첫 예는 port status를 얻는 input control transfer입니다. 같은 URB tag `d5ea89a0`에 submission `S Ci:1:001:0`과 callback `C Ci:1:001:0`이 대응하며 callback은 4 byte `01050000`을 반환합니다.
두 번째 예는 address 5의 storage device에 31-byte Bulk wrapper로 SCSI command `0x28 (READ_10)`을 보내는 output bulk transfer입니다.
submission line `S Bo:1:005:2 -115 31 = ...` 뒤 같은 tag `dd65f0e8`의 callback `C Bo:1:005:2 0 31 >`가 이어집니다. 원문의 hexadecimal payload와 timestamp는 아래 원문 block에 그대로 보존됩니다.
두 예의 transfer·방향·길이입니다.
Examples:
An input control transfer to get a port status::
d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 <
d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000
An output bulk transfer to send a SCSI command 0x28 (READ_10) in a 31-byte
Bulk wrapper to a storage device at address 5::
dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000
dd65f0e8 4128379808 C Bo:1:005:2 0 31 >
Binary format과 usbmon_packet
211-256binary API의 전체 architecture는 text API와 거의 같지만 event를 binary format으로 전달합니다. 각 event는 문서가 참조를 위해 붙인 이름인 `struct usbmon_packet`으로 전송됩니다.
structure는 64 byte입니다. offset 0의 `id`가 submission부터 callback까지 URB를 식별하고, `type`은 text event type과 같으며 확장할 수 있습니다. `xfer_type`은 ISO=0부터 Bulk=3까지, `epnum`은 endpoint와 transfer direction, `devnum`은 device address, `busnum`은 bus number입니다.
`flag_setup`과 `flag_data`는 text format과 같고 `flag_data`에는 binary zero도 유효합니다. timestamp는 `gettimeofday`의 `ts_sec`와 `ts_usec`, 뒤에는 status와 submitted/actual data length, delivered length가 옵니다.
offset 40 union은 Control S-type이면 `setup[SETUP_LEN]`, ISO이면 `error_count`와 `numdesc`를 가진 `iso_rec`입니다. 이어서 Interrupt/ISO의 `interval`, ISO의 `start_frame`, URB `transfer_flags` 복사본, 실제 ISO descriptor 수 `ndesc`가 옵니다.
event는 character device에서 `read(2)`, `ioctl(2)`, mmap buffer access로 받을 수 있습니다. compatibility 때문에 `read(2)`는 첫 48 byte만 반환합니다.
character device 이름은 보통 USB bus N에 대해 `/dev/usbmonN`입니다. `/dev/usbmon0`은 특별히 모든 bus를 뜻하지만 구체적인 naming policy는 distribution이 정합니다.
`/dev/usbmon0`을 수동으로 만들면 owner를 root, mode를 `0600`으로 해야 합니다. 그렇지 않으면 unprivileged user가 keyboard traffic을 엿볼 수 있습니다.
64-byte binary event header의 field와 offset입니다.
Raw binary format and API
=========================
The overall architecture of the API is about the same as the one above,
only the events are delivered in binary format. Each event is sent in
the following structure (its name is made up, so that we can refer to it)::
struct usbmon_packet {
u64 id; /* 0: URB ID - from submission to callback */
unsigned char type; /* 8: Same as text; extensible. */
unsigned char xfer_type; /* ISO (0), Intr, Control, Bulk (3) */
unsigned char epnum; /* Endpoint number and transfer direction */
unsigned char devnum; /* Device address */
u16 busnum; /* 12: Bus number */
char flag_setup; /* 14: Same as text */
char flag_data; /* 15: Same as text; Binary zero is OK. */
s64 ts_sec; /* 16: gettimeofday */
s32 ts_usec; /* 24: gettimeofday */
int status; /* 28: */
unsigned int length; /* 32: Length of data (submitted or actual) */
unsigned int len_cap; /* 36: Delivered length */
union { /* 40: */
unsigned char setup[SETUP_LEN]; /* Only for Control S-type */
struct iso_rec { /* Only for ISO */
int error_count;
int numdesc;
} iso;
} s;
int interval; /* 48: Only for Interrupt and ISO */
int start_frame; /* 52: For ISO */
unsigned int xfer_flags; /* 56: copy of URB's transfer_flags */
unsigned int ndesc; /* 60: Actual number of ISO descriptors */
}; /* 64 total length */
These events can be received from a character device by reading with read(2),
with an ioctl(2), or by accessing the buffer with mmap. However, read(2)
only returns first 48 bytes for compatibility reasons.
The character device is usually called /dev/usbmonN, where N is the USB bus
number. Number zero (/dev/usbmon0) is special and means "all buses".
Note that specific naming policy is set by your Linux distribution.
If you create /dev/usbmon0 by hand, make sure that it is owned by root
and has mode 0600. Otherwise, unprivileged users will be able to snoop
keyboard traffic.
Binary ioctl: URB length와 stats
257-279binary API ioctl의 magic은 `MON_IOC_MAGIC 0x92`입니다.
`MON_IOCQ_URB_LEN = _IO(MON_IOC_MAGIC, 1)`은 다음 event의 data length를 반환합니다. 대부분 event에는 data가 없으므로 0을 반환해도 event가 없다는 뜻은 아닙니다.
`MON_IOCG_STATS = _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats)`는 `queued`와 `dropped`를 가진 structure pointer를 인자로 받습니다.
`queued`는 현재 buffer에 queue된 event 수이며 마지막 reset 이후 처리한 event 수가 아닙니다. `dropped`는 직전 `MON_IOCG_STATS` 호출 이후 잃은 event 수입니다.
다음 event와 queue loss 상태를 조회합니다.
The following ioctl calls are available, with MON_IOC_MAGIC 0x92:
MON_IOCQ_URB_LEN, defined as _IO(MON_IOC_MAGIC, 1)
This call returns the length of data in the next event. Note that majority of
events contain no data, so if this call returns zero, it does not mean that
no events are available.
MON_IOCG_STATS, defined as _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats)
The argument is a pointer to the following structure::
struct mon_bin_stats {
u32 queued;
u32 dropped;
};
The member "queued" refers to the number of events currently queued in the
buffer (and not to the number of events processed since the last reset).
The member "dropped" is the number of events lost since the last call
to MON_IOCG_STATS.
Binary ioctl: ring size와 event 수신
280-309`MON_IOCT_RING_SIZE = _IO(MON_IOC_MAGIC, 4)`는 byte 단위 buffer size를 설정합니다. 요청 값은 다음 chunk 또는 page로 내림될 수 있고 이 kernel의 명시되지 않은 범위를 벗어나면 `-EINVAL`로 실패합니다.
`MON_IOCQ_RING_SIZE = _IO(MON_IOC_MAGIC, 5)`는 현재 buffer size를 byte 단위로 반환합니다.
`MON_IOCX_GET = _IOW(MON_IOC_MAGIC, 6, struct mon_get_arg)`과 `MON_IOCX_GETX = _IOW(MON_IOC_MAGIC, 10, struct mon_get_arg)`은 kernel buffer에 event가 없으면 기다린 뒤 첫 event를 반환합니다.
인자인 `struct mon_get_arg`에는 `struct usbmon_packet *hdr`, `void *data`, data allocation length인 `size_t alloc`가 있습니다. 호출 전 세 field를 채웁니다.
반환 시 `hdr`가 가리키는 영역에는 다음 event structure, data buffer에는 존재하는 경우 data가 들어갑니다. event는 kernel buffer에서 제거됩니다. `MON_IOCX_GET`은 hdr에 48 byte, `MON_IOCX_GETX`는 64 byte를 복사합니다.
buffer 크기와 단일 event fetch 계약입니다.
MON_IOCT_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 4)
This call sets the buffer size. The argument is the size in bytes.
The size may be rounded down to the next chunk (or page). If the requested
size is out of [unspecified] bounds for this kernel, the call fails with
-EINVAL.
MON_IOCQ_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 5)
This call returns the current size of the buffer in bytes.
MON_IOCX_GET, defined as _IOW(MON_IOC_MAGIC, 6, struct mon_get_arg)
MON_IOCX_GETX, defined as _IOW(MON_IOC_MAGIC, 10, struct mon_get_arg)
These calls wait for events to arrive if none were in the kernel buffer,
then return the first event. The argument is a pointer to the following
structure::
struct mon_get_arg {
struct usbmon_packet *hdr;
void *data;
size_t alloc; /* Length of data (can be zero) */
};
Before the call, hdr, data, and alloc should be filled. Upon return, the area
pointed by hdr contains the next event structure, and the data buffer contains
the data, if any. The event is removed from the kernel buffer.
The MON_IOCX_GET copies 48 bytes to hdr area, MON_IOCX_GETX copies 64 bytes.
Binary ioctl: mmap fetch와 flush
310-343`MON_IOCX_MFETCH = _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg)`는 application이 `mmap(2)`으로 buffer에 접근할 때 주로 사용합니다.
`struct mon_mfetch_arg`는 가져온 event offset vector인 `offvec`, 가져올 event 수이며 반환 시 실제 수인 `nfetch`, flush할 event 수인 `nflush`를 가집니다.
ioctl은 세 단계로 동작합니다. 첫째, kernel buffer에서 최대 `nflush` event를 제거해 버리고 실제 제거 수를 `nflush`에 반환합니다.
둘째, pseudo-device가 `O_NONBLOCK`으로 open되지 않았다면 buffer에 event가 생길 때까지 기다립니다.
셋째, mmap buffer 안의 event offset을 최대 `nfetch`개 추출해 `offvec`에 저장하고 실제 offset 수를 `nfetch`에 기록합니다.
`MON_IOCH_MFLUSH = _IO(MON_IOC_MAGIC, 8)`는 인자로 받은 수만큼 kernel buffer event를 제거합니다. event가 더 적으면 존재하는 것을 모두 제거하고 error를 보고하지 않으며 event가 없어도 동작합니다.
`FIONBIO` ioctl은 필요가 생기면 미래에 구현할 수 있다고 문서는 설명합니다.
mmap consumer가 이전 batch를 버리고 다음 offset batch를 받는 과정입니다.
batch fetch와 flush에 쓰는 field·ioctl입니다.
MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg)
This ioctl is primarily used when the application accesses the buffer
with mmap(2). Its argument is a pointer to the following structure::
struct mon_mfetch_arg {
uint32_t *offvec; /* Vector of events fetched */
uint32_t nfetch; /* Number of events to fetch (out: fetched) */
uint32_t nflush; /* Number of events to flush */
};
The ioctl operates in 3 stages.
First, it removes and discards up to nflush events from the kernel buffer.
The actual number of events discarded is returned in nflush.
Second, it waits for an event to be present in the buffer, unless the pseudo-
device is open with O_NONBLOCK.
Third, it extracts up to nfetch offsets into the mmap buffer, and stores
them into the offvec. The actual number of event offsets is stored into
the nfetch.
MON_IOCH_MFLUSH, defined as _IO(MON_IOC_MAGIC, 8)
This call removes a number of events from the kernel buffer. Its argument
is the number of events to remove. If the buffer contains fewer events
than requested, all events present are removed, and no error is reported.
This works when no events are available too.
FIONBIO
The ioctl FIONBIO may be implemented in the future, if there's a need.
Memory-mapped binary buffer 접근
344-375binary API special file은 `ioctl(2)`과 `read(2)` 외에 `select(2)`와 `poll(2)`로 감시할 수 있지만 `lseek(2)`은 동작하지 않습니다.
memory-mapped 접근을 준비하려면 현재 buffer size를 얻고 `mmap(2)`으로 buffer를 map합니다.
loop에서는 N개의 32-bit word를 가진 `vec`를 `fetch.offvec`에, N 이하 값을 `fetch.nfetch`에, 이전 처리 batch 수를 `fetch.nflush`에 넣고 `MON_IOCX_MFETCH`를 한 번 호출합니다. error도 처리해야 합니다.
반환된 `fetch.nfetch`를 다음 호출에서 flush할 수로 저장하고 각 `vec[i]` offset의 header를 읽습니다. type이 `@`이면 filler packet이므로 건너뜁니다. data는 header 위치에서 64 byte 뒤이며 `process_packet(hdr, data)`로 처리합니다.
원문 pseudo-code에는 cast type이 `struct ubsmon_packet`으로 적혀 있으며 이 표기를 원문 block에 그대로 보존했습니다. 번역 설명에서는 정의된 실제 type인 `struct usbmon_packet`을 사용합니다.
핵심은 N개 event마다 ioctl을 한 번만 실행하는 것입니다. buffer는 circular이지만 반환된 header와 data는 buffer 끝을 가로지르지 않으므로 pseudo-code에 gathering logic이 필요하지 않습니다.
N event당 한 ioctl로 header와 data를 처리합니다.
지원되는 readiness와 file-position 동작입니다.
In addition to ioctl(2) and read(2), the special file of binary API can
be polled with select(2) and poll(2). But lseek(2) does not work.
* Memory-mapped access of the kernel buffer for the binary API
The basic idea is simple:
To prepare, map the buffer by getting the current size, then using mmap(2).
Then, execute a loop similar to the one written in pseudo-code below::
struct mon_mfetch_arg fetch;
struct usbmon_packet *hdr;
int nflush = 0;
for (;;) {
fetch.offvec = vec; // Has N 32-bit words
fetch.nfetch = N; // Or less than N
fetch.nflush = nflush;
ioctl(fd, MON_IOCX_MFETCH, &fetch); // Process errors, too
nflush = fetch.nfetch; // This many packets to flush when done
for (i = 0; i < nflush; i++) {
hdr = (struct ubsmon_packet *) &mmap_area[vec[i]];
if (hdr->type == '@') // Filler packet
continue;
caddr_t data = &mmap_area[vec[i]] + 64;
process_packet(hdr, data);
}
}
Thus, the main idea is to execute only one ioctl per N events.
Although the buffer is circular, the returned headers and data do not cross
the end of the buffer, so the above pseudo-code does not need any gathering.
요약·해설
usbmon.rst:1-375usbmon은 peripheral driver가 HCD에 제출한 USB I/O를 관찰하는 kernel trace facility입니다. text API는 사람이 읽기 쉬우나 deprecated이고, `/dev/usbmonN` binary API는 안정된 ABI입니다.
trace에는 keyboard traffic처럼 민감한 data가 들어갈 수 있으므로 수동 생성한 `/dev/usbmon0`은 root 소유와 mode 0600을 유지해야 합니다.
간단한 진단과 고성능 수집의 두 경로입니다.