Roccat Pyra mouse obsolete ABI | Linux 6.18.37

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

1. 요약·해설

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

CPI, active profile과 firmware

sysfs-driver-hid-roccat-pyra:1-49

raw CPI level을 DPI로 변환하고, 구형 active profile·firmware scalar attribute를 binary settings·info로 대체한 관계를 설명합니다.

Profile button과 settings

sysfs-driver-hid-roccat-pyra:51-126

5개 profile의 19-byte button layout, 13-byte resolution·sensitivity·light settings와 3-byte startup settings를 관리합니다.

2. 영어 원문 전체

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

원문 전체 펼치기

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/actual_cpi

2 Date: August 2010

3 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

4 Description: It is possible to switch the cpi setting of the mouse with the

5 press of a button.

6 When read, this file returns the raw number of the actual cpi

7 setting reported by the mouse. This number has to be further

8 processed to receive the real dpi value:

10 ===== ====

11 VALUE DPI

12 ===== ====

13 1 400

14 2 800

15 4 1600

16 ===== ====

18 This file is readonly.

19 Has never been used. If bookkeeping is done, it's done in userland tools.

20 Users: http://roccat.sourceforge.net

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/actual_profile

23 Date: August 2010

24 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

25 Description: When read, this file returns the number of the actual profile in

26 range 0-4.

27 This file is readonly.

28 Please use binary attribute "settings" which provides this information.

29 Users: http://roccat.sourceforge.net

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/firmware_version

32 Date: August 2010

33 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

34 Description: When read, this file returns the raw integer version number of the

35 firmware reported by the mouse. Using the integer value eases

36 further usage in other programs. To receive the real version

37 number the decimal point has to be shifted 2 positions to the

38 left. E.g. a returned value of 138 means 1.38

39 This file is readonly.

40 Please use binary attribute "info" which provides this information.

41 Users: http://roccat.sourceforge.net

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/info

44 Date: November 2012

45 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

46 Description: When read, this file returns general data like firmware version.

47 When written, the device can be reset.

48 The data is 6 bytes long.

49 Users: http://roccat.sourceforge.net

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile_buttons

52 Date: August 2010

53 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

54 Description: The mouse can store 5 profiles which can be switched by the

55 press of a button. A profile is split in settings and buttons.

56 profile_buttons holds information about button layout.

57 When written, this file lets one write the respective profile

58 buttons back to the mouse. The data has to be 19 bytes long.

59 The mouse will reject invalid data.

60 Which profile to write is determined by the profile number

61 contained in the data.

62 Before reading this file, control has to be written to select

63 which profile to read.

64 Users: http://roccat.sourceforge.net

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile[1-5]_buttons

67 Date: August 2010

68 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

69 Description: The mouse can store 5 profiles which can be switched by the

70 press of a button. A profile is split in settings and buttons.

71 profile_buttons holds information about button layout.

72 When read, these files return the respective profile buttons.

73 The returned data is 19 bytes in size.

74 This file is readonly.

75 Write control to select profile and read profile_buttons instead.

76 Users: http://roccat.sourceforge.net

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile_settings

79 Date: August 2010

80 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

81 Description: The mouse can store 5 profiles which can be switched by the

82 press of a button. A profile is split in settings and buttons.

83 profile_settings holds information like resolution, sensitivity

84 and light effects.

85 When written, this file lets one write the respective profile

86 settings back to the mouse. The data has to be 13 bytes long.

87 The mouse will reject invalid data.

88 Which profile to write is determined by the profile number

89 contained in the data.

90 Before reading this file, control has to be written to select

91 which profile to read.

92 Users: http://roccat.sourceforge.net

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile[1-5]_settings

95 Date: August 2010

96 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

97 Description: The mouse can store 5 profiles which can be switched by the

98 press of a button. A profile is split in settings and buttons.

99 profile_settings holds information like resolution, sensitivity

100 and light effects.

101 When read, these files return the respective profile settings.

102 The returned data is 13 bytes in size.

103 This file is readonly.

104 Write control to select profile and read profile_settings instead.

105 Users: http://roccat.sourceforge.net

106

107

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/settings

108 Date: August 2010

109 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

110 Description: When read, this file returns the settings stored in the mouse.

111 The size of the data is 3 bytes and holds information on the

112 startup_profile.

113 When written, this file lets write settings back to the mouse.

114 The data has to be 3 bytes long. The mouse will reject invalid

115 data.

116 Users: http://roccat.sourceforge.net

117

118

What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/startup_profile

119 Date: August 2010

120 Contact: Stefan Achatz <erazor_de@users.sourceforge.net>

121 Description: The integer value of this attribute ranges from 0-4.

122 When read, this attribute returns the number of the profile

123 that's active when the mouse is powered on.

124 This file is readonly.

125 Please use binary attribute "settings" which provides this information.

126 Users: http://roccat.sourceforge.net

127

3. 한국어 전문 번역

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

CPI와 active profile

1-29

BASE=/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>

$BASE/actual_cpi
$BASE/actual_profile

별도 표시가 없는 항목의 Date는 2010년 8월, contact는 Stefan Achatz <erazor_de@users.sourceforge.net>, user는 http://roccat.sourceforge.net다.

mouse button으로 CPI 설정을 바꿀 수 있다. actual_cpi를 읽으면 mouse가 보고한 현재 CPI setting의 raw 번호를 반환한다. 실제 DPI는 다음 표로 변환한다.

raw VALUE	DPI
1	400
2	800
4	1600

actual_cpi는 read-only이며 실제로 사용된 적이 없다. CPI bookkeeping은 userland tool에서 수행한다.

actual_profile은 0-4 범위의 현재 profile 번호를 반환하는 read-only file이다. 같은 정보를 제공하는 binary settings attribute를 사용해야 한다.

Firmware version과 info

31-49

$BASE/firmware_version
$BASE/info

attribute	Date	payload	access
firmware_version	2010년 8월	raw integer	read-only
info	2012년 11월	6 byte	read/write

firmware_version은 mouse가 보고한 raw integer version을 반환한다. 실제 version은 decimal point를 왼쪽으로 두 자리 옮겨 구하며 138은 1.38이다. 같은 정보를 제공하는 binary info attribute를 사용해야 한다.

info를 읽으면 firmware version 같은 일반 data 6 byte를 반환한다. 6-byte data를 쓰면 device를 reset할 수 있다.

Profile button과 settings

51-105

$BASE/profile_buttons
$BASE/profile[1-5]_buttons
$BASE/profile_settings
$BASE/profile[1-5]_settings

attribute	payload	access	내용
profile_buttons	19 byte	read/write	선택 profile의 button layout
profile[1-5]_buttons	19 byte	read-only	번호별 profile button layout
profile_settings	13 byte	read/write	선택 profile의 resolution·sensitivity·light effect
profile[1-5]_settings	13 byte	read-only	번호별 profile settings

mouse는 button press로 전환할 수 있는 profile 다섯 개를 저장하며 각 profile은 settings와 buttons로 나뉜다.

profile_buttons에 19 byte를 쓰면 payload 안의 profile 번호가 지정하는 button layout을 기록한다. invalid data는 mouse가 거부한다. 읽기 전에는 control에 써서 profile을 선택해야 한다.

profile1_buttons부터 profile5_buttons까지는 번호별 button data 19 byte를 직접 읽는 기존 file이다. control로 선택한 뒤 profile_buttons를 읽는 방식으로 대체되었다.

profile_settings에 13 byte를 쓰면 payload 안의 profile 번호가 지정하는 resolution, sensitivity, light effect를 기록한다. invalid data는 거부되고 read 전에는 control selector가 필요하다.

profile1_settings부터 profile5_settings까지는 번호별 settings 13 byte를 직접 읽는 기존 file이다. control과 profile_settings 조합을 사용해야 한다.

Global settings와 startup profile

107-126

$BASE/settings
$BASE/startup_profile

attribute	payload·범위	access	의미
settings	3 byte	read/write	mouse에 저장된 startup_profile 포함 settings
startup_profile	integer 0-4	read-only	power-on 때 활성화할 profile 번호

settings를 읽으면 mouse에 저장된 3-byte settings를 반환하며 그 안에 startup_profile 정보가 들어 있다. 3-byte settings를 다시 쓸 수 있고 invalid data는 mouse가 거부한다.

startup_profile은 mouse power-on 때 활성화되는 profile 번호를 반환하는 구형 read-only scalar interface다. 같은 정보를 포함하는 binary settings를 사용해야 한다.