USB device stable sysfs ABI | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

USB power management

sysfs-bus-usb:1-77

Persist, autosuspend delay, connected·active duration과 interface driver의 autosuspend 지원 여부를 다룹니다.

Reset quirk, address와 configuration

sysfs-bus-usb:79-119

Mode 전환 device의 reset 금지, USB bus address와 active configuration 변경 규칙을 다룹니다.

Cached descriptor와 speed

sysfs-bus-usb:121-142

Bus-endian descriptor stream의 안전한 순회 기준과 Mbit/s link speed를 다룹니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 What: /sys/bus/usb/devices/.../power/persist

2 Date: May 2007

3 KernelVersion: 2.6.23

4 Contact: Alan Stern <stern@rowland.harvard.edu>

5 Description:

6 USB device directories can contain a file named power/persist.

7 The file holds a boolean value (0 or 1) indicating whether or

8 not the "USB-Persist" facility is enabled for the device. For

9 hubs this facility is always enabled and their device

10 directories will not contain this file.

12 For more information, see Documentation/driver-api/usb/persist.rst.

14 What: /sys/bus/usb/devices/.../power/autosuspend

15 Date: March 2007

16 KernelVersion: 2.6.21

17 Contact: Alan Stern <stern@rowland.harvard.edu>

18 Description:

19 Each USB device directory will contain a file named

20 power/autosuspend. This file holds the time (in seconds)

21 the device must be idle before it will be autosuspended.

22 0 means the device will be autosuspended as soon as

23 possible. Negative values will prevent the device from

24 being autosuspended at all, and writing a negative value

25 will resume the device if it is already suspended.

27 The autosuspend delay for newly-created devices is set to

28 the value of the usbcore.autosuspend module parameter.

30 What: /sys/bus/usb/device/.../power/connected_duration

31 Date: January 2008

32 KernelVersion: 2.6.25

33 Contact: Sarah Sharp <sarah.a.sharp@intel.com>

34 Description:

35 If CONFIG_PM is enabled, then this file is present. When read,

36 it returns the total time (in msec) that the USB device has been

37 connected to the machine. This file is read-only.

38 Users:

39 PowerTOP <powertop@lists.01.org>

40 https://01.org/powertop/

42 What: /sys/bus/usb/device/.../power/active_duration

43 Date: January 2008

44 KernelVersion: 2.6.25

45 Contact: Sarah Sharp <sarah.a.sharp@intel.com>

46 Description:

47 If CONFIG_PM is enabled, then this file is present. When read,

48 it returns the total time (in msec) that the USB device has been

49 active, i.e. not in a suspended state. This file is read-only.

51 Tools can use this file and the connected_duration file to

52 compute the percentage of time that a device has been active.

53 For example::

55 echo $((100 * `cat active_duration` / `cat connected_duration`))

57 will give an integer percentage. Note that this does not

58 account for counter wrap.

59 Users:

60 PowerTOP <powertop@lists.01.org>

61 https://01.org/powertop/

63 What: /sys/bus/usb/devices/<busnum>-<port[.port]>...:<config num>-<interface num>/supports_autosuspend

64 Date: January 2008

65 KernelVersion: 2.6.27

66 Contact: Sarah Sharp <sarah.a.sharp@intel.com>

67 Description:

68 When read, this file returns 1 if the interface driver

69 for this interface supports autosuspend. It also

70 returns 1 if no driver has claimed this interface, as an

71 unclaimed interface will not stop the device from being

72 autosuspended if all other interface drivers are idle.

73 The file returns 0 if autosuspend support has not been

74 added to the driver.

75 Users:

76 USB PM tool

77 git://git.moblin.org/users/sarah/usb-pm-tool/

79 What: /sys/bus/usb/device/.../avoid_reset_quirk

80 Date: December 2009

81 Contact: Oliver Neukum <oliver@neukum.org>

82 Description:

83 Writing 1 to this file tells the kernel that this

84 device will morph into another mode when it is reset.

85 Drivers will not use reset for error handling for

86 such devices.

87 Users:

88 usb_modeswitch

90 What: /sys/bus/usb/devices/.../devnum

91 KernelVersion: since at least 2.6.18

92 Description:

93 Device address on the USB bus.

94 Users:

95 libusb

97 What: /sys/bus/usb/devices/.../bConfigurationValue

98 KernelVersion: since at least 2.6.18

99 Description:

100 bConfigurationValue of the *active* configuration for the

101 device. Writing 0 or -1 to bConfigurationValue will reset the

102 active configuration (unconfigure the device). Writing

103 another value will change the active configuration.

104

105 Note that some devices, in violation of the USB spec, have a

106 configuration with a value equal to 0. Writing 0 to

107 bConfigurationValue for these devices will install that

108 configuration, rather then unconfigure the device.

109

110 Writing -1 will always unconfigure the device.

111 Users:

112 libusb

113

114 What: /sys/bus/usb/devices/.../busnum

115 KernelVersion: 2.6.22

116 Description:

117 Bus-number of the USB-bus the device is connected to.

118 Users:

119 libusb

120

121 What: /sys/bus/usb/devices/.../descriptors

122 KernelVersion: 2.6.26

123 Description:

124 Binary file containing cached descriptors of the device. The

125 binary data consists of the device descriptor followed by the

126 descriptors for each configuration of the device.

127 Note that the wTotalLength of the config descriptors can not

128 be trusted, as the device may have a smaller config descriptor

129 than it advertises. The bLength field of each (sub) descriptor

130 can be trusted, and can be used to seek forward one (sub)

131 descriptor at a time until the next config descriptor is found.

132 All descriptors read from this file are in bus-endian format

133 Users:

134 libusb

135

136 What: /sys/bus/usb/devices/.../speed

137 KernelVersion: since at least 2.6.18

138 Description:

139 Speed the device is connected with to the usb-host in

140 Mbit / second. IE one of 1.5 / 12 / 480 / 5000.

141 Users:

142 libusb

143

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

USB-Persist와 autosuspend delay

1-28

경로	도입	담당	의미
/sys/bus/usb/devices/.../power/persist	2007년 5월 · kernel 2.6.23	Alan Stern <stern@rowland.harvard.edu>	0 또는 1인 boolean으로 device의 USB-Persist 기능 활성화 여부를 나타낸다. Hub에서는 항상 활성화되므로 hub directory에는 이 file이 없다. 자세한 내용은 Documentation/driver-api/usb/persist.rst를 참조한다.
/sys/bus/usb/devices/.../power/autosuspend	2007년 3월 · kernel 2.6.21	Alan Stern <stern@rowland.harvard.edu>	Device가 autosuspend되기 전에 idle 상태로 있어야 하는 시간을 second로 나타낸다. 0은 가능한 즉시 autosuspend하며 음수는 autosuspend를 완전히 막는다. 이미 suspend된 device에 음수를 쓰면 resume한다.

새로 생성된 device의 autosuspend delay는 usbcore.autosuspend module parameter 값으로 설정된다.

연결 시간과 활성 시간

30-61

두 read-only file은 CONFIG_PM이 활성화된 경우에 존재하고 2008년 1월 kernel 2.6.25에 도입됐다. 담당자는 Sarah Sharp <sarah.a.sharp@intel.com>이며 PowerTOP이 사용한다.

경로	반환 값
/sys/bus/usb/device/.../power/connected_duration	USB device가 machine에 연결돼 있던 전체 시간을 millisecond로 반환한다.
/sys/bus/usb/device/.../power/active_duration	USB device가 suspended 상태가 아니었던 전체 활성 시간을 millisecond로 반환한다.

Tool은 active_duration과 connected_duration으로 device가 활성 상태였던 시간의 비율을 계산할 수 있다.

echo $((100 * `cat active_duration` / `cat connected_duration`))

이 식은 정수 percentage를 출력하지만 counter wrap은 고려하지 않는다. PowerTOP 연락처는 powertop@lists.01.org이고 관련 URL은 https://01.org/powertop/이다.

Interface driver의 autosuspend 지원

63-77

항목	값
What	/sys/bus/usb/devices/<busnum>-<port[.port]>...:<config num>-<interface num>/supports_autosuspend
Date	2008년 1월
KernelVersion	2.6.27
Contact	Sarah Sharp <sarah.a.sharp@intel.com>
Users	USB PM tool

Interface driver가 autosuspend를 지원하면 1을 반환한다. 어떤 driver도 interface를 claim하지 않은 경우에도 1이다. Claim되지 않은 interface는 다른 모든 interface driver가 idle일 때 device autosuspend를 막지 않기 때문이다. Driver에 autosuspend 지원이 추가되지 않았으면 0을 반환한다.

원문에 기록된 USB PM tool repository는 git://git.moblin.org/users/sarah/usb-pm-tool/이다.

Reset quirk와 active configuration

79-112

경로	도입·담당	의미
/sys/bus/usb/device/.../avoid_reset_quirk	2009년 12월 · Oliver Neukum <oliver@neukum.org>	1을 쓰면 reset 시 다른 mode로 변하는 device임을 kernel에 알린다. Driver는 이런 device의 error handling에 reset을 쓰지 않는다. usb_modeswitch가 사용한다.
/sys/bus/usb/devices/.../devnum	적어도 kernel 2.6.18부터	USB bus에서의 device address다. libusb가 사용한다.
/sys/bus/usb/devices/.../bConfigurationValue	적어도 kernel 2.6.18부터	Device의 현재 active configuration에 대한 bConfigurationValue다. libusb가 사용한다.

bConfigurationValue에 0 또는 -1을 쓰면 active configuration을 reset하여 device를 unconfigure한다. 다른 값을 쓰면 active configuration을 바꾼다.

일부 device는 USB specification을 위반하여 값이 0인 configuration을 갖는다. 이런 device에 0을 쓰면 unconfigure하는 대신 그 configuration을 설치한다. -1은 항상 device를 unconfigure한다.

Bus number, descriptor stream과 link speed

114-142

아래 세 attribute는 libusb가 사용한다.

경로	KernelVersion	의미
/sys/bus/usb/devices/.../busnum	2.6.22	Device가 연결된 USB bus의 bus number다.
/sys/bus/usb/devices/.../descriptors	2.6.26	Cache된 device descriptor를 담은 binary file이다. Device descriptor 다음에 device의 각 configuration descriptor가 이어진다. 모든 descriptor는 bus-endian format이다.
/sys/bus/usb/devices/.../speed	적어도 2.6.18부터	Device가 USB host에 연결된 속도를 Mbit/s로 나타낸다. 예시는 1.5, 12, 480, 5000이다.

Device가 광고한 것보다 작은 configuration descriptor를 가질 수 있으므로 config descriptor의 wTotalLength는 신뢰할 수 없다. 각 subdescriptor의 bLength는 신뢰할 수 있으므로 다음 config descriptor를 찾을 때까지 한 descriptor씩 앞으로 이동하는 데 사용한다.