요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. include:: <isonum.txt>
===================
The userio Protocol
===================
:Copyright: |copy| 2015 Stephen Chandler Paul <thatslyude@gmail.com>
Sponsored by Red Hat
Introduction
=============
This module is intended to try to make the lives of input driver developers
easier by allowing them to test various serio devices (mainly the various
touchpads found on laptops) without having to have the physical device in front
of them. userio accomplishes this by allowing any privileged userspace program
to directly interact with the kernel's serio driver and control a virtual serio
port from there.
Usage overview
==============
In order to interact with the userio kernel module, one simply opens the
/dev/userio character device in their applications. Commands are sent to the
kernel module by writing to the device, and any data received from the serio
driver is read as-is from the /dev/userio device. All of the structures and
macros you need to interact with the device are defined in <linux/userio.h> and
<linux/serio.h>.
Command Structure
=================
The struct used for sending commands to /dev/userio is as follows::
struct userio_cmd {
__u8 type;
__u8 data;
};
``type`` describes the type of command that is being sent. This can be any one
of the USERIO_CMD macros defined in <linux/userio.h>. ``data`` is the argument
that goes along with the command. In the event that the command doesn't have an
argument, this field can be left untouched and will be ignored by the kernel.
Each command should be sent by writing the struct directly to the character
device. In the event that the command you send is invalid, an error will be
returned by the character device and a more descriptive error will be printed
to the kernel log. Only one command can be sent at a time, any additional data
written to the character device after the initial command will be ignored.
To close the virtual serio port, just close /dev/userio.
Commands
========
USERIO_CMD_REGISTER
~~~~~~~~~~~~~~~~~~~
Registers the port with the serio driver and begins transmitting data back and
forth. Registration can only be performed once a port type is set with
USERIO_CMD_SET_PORT_TYPE. Has no argument.
USERIO_CMD_SET_PORT_TYPE
~~~~~~~~~~~~~~~~~~~~~~~~
Sets the type of port we're emulating, where ``data`` is the port type being
set. Can be any of the macros from <linux/serio.h>. For example: SERIO_8042
would set the port type to be a normal PS/2 port.
USERIO_CMD_SEND_INTERRUPT
~~~~~~~~~~~~~~~~~~~~~~~~~
Sends an interrupt through the virtual serio port to the serio driver, where
``data`` is the interrupt data being sent.
Userspace tools
===============
The userio userspace tools are able to record PS/2 devices using some of the
debugging information from i8042, and play back the devices on /dev/userio. The
latest version of these tools can be found at:
https://github.com/Lyude/ps2emu
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
목적과 사용 개요
1-31이 문서는 2015년 Stephen Chandler Paul이 작성했으며 Red Hat의 후원을 받았습니다.
`userio` module은 input driver 개발자가 실제 serio 장치를 앞에 두지 않고도 여러 serio 장치, 특히 laptop touchpad를 시험할 수 있게 하여 개발을 쉽게 만드는 것이 목적입니다. 권한 있는 사용자 공간 program이 kernel의 serio driver와 직접 상호 작용하고 가상 serio port를 제어하도록 합니다.
application은 `/dev/userio` character device를 열어 module과 상호 작용합니다. device에 기록한 command는 kernel module로 전달되고, serio driver에서 받은 data는 변환하지 않은 그대로 `/dev/userio`에서 읽습니다. 필요한 구조체와 macro는 `<linux/userio.h>`와 `<linux/serio.h>`에 정의되어 있습니다.
같은 character device에서 command와 serio data의 방향이 나뉩니다.
가상 port type을 정한 뒤 등록하고 interrupt data를 교환합니다.
.. include:: <isonum.txt>
===================
The userio Protocol
===================
:Copyright: |copy| 2015 Stephen Chandler Paul <thatslyude@gmail.com>
Sponsored by Red Hat
Introduction
=============
This module is intended to try to make the lives of input driver developers
easier by allowing them to test various serio devices (mainly the various
touchpads found on laptops) without having to have the physical device in front
of them. userio accomplishes this by allowing any privileged userspace program
to directly interact with the kernel's serio driver and control a virtual serio
port from there.
Usage overview
==============
In order to interact with the userio kernel module, one simply opens the
/dev/userio character device in their applications. Commands are sent to the
kernel module by writing to the device, and any data received from the serio
driver is read as-is from the /dev/userio device. All of the structures and
macros you need to interact with the device are defined in <linux/userio.h> and
<linux/serio.h>.명령 구조와 전송 규칙
32-53`/dev/userio`에 command를 보낼 때는 아래 `struct userio_cmd`를 사용합니다. `type`은 `<linux/userio.h>`에 정의된 `USERIO_CMD_*` macro 중 하나이며, `data`는 그 command의 argument입니다. argument가 없는 command에서는 `data`를 건드리지 않아도 kernel이 무시합니다.
command는 두 개의 8-bit field로 이루어집니다.
각 command는 구조체를 character device에 직접 기록하여 한 번에 하나씩 보내야 합니다. 잘못된 command를 보내면 character device가 error를 반환하고 kernel log에는 더 구체적인 error가 기록됩니다. 첫 command 뒤에 함께 기록한 추가 data는 무시됩니다.
write 단위와 오류 처리 규칙입니다.
Command Structure
=================
The struct used for sending commands to /dev/userio is as follows::
struct userio_cmd {
__u8 type;
__u8 data;
};
``type`` describes the type of command that is being sent. This can be any one
of the USERIO_CMD macros defined in <linux/userio.h>. ``data`` is the argument
that goes along with the command. In the event that the command doesn't have an
argument, this field can be left untouched and will be ignored by the kernel.
Each command should be sent by writing the struct directly to the character
device. In the event that the command you send is invalid, an error will be
returned by the character device and a more descriptive error will be printed
to the kernel log. Only one command can be sent at a time, any additional data
written to the character device after the initial command will be ignored.
To close the virtual serio port, just close /dev/userio.지원 명령과 사용자 공간 도구
54-85`USERIO_CMD_REGISTER`는 port를 serio driver에 등록하고 양방향 data 전송을 시작합니다. 이 command는 `USERIO_CMD_SET_PORT_TYPE`으로 port type을 먼저 설정한 뒤 한 번만 수행할 수 있으며 argument는 없습니다.
`USERIO_CMD_SET_PORT_TYPE`은 흉내 낼 port type을 설정합니다. `data`에는 `<linux/serio.h>`의 macro 중 하나를 넣습니다. 예를 들어 `SERIO_8042`는 일반 PS/2 port를 뜻합니다.
`USERIO_CMD_SEND_INTERRUPT`는 가상 serio port를 통해 serio driver로 interrupt를 보냅니다. 전송할 interrupt data는 `data` field에 둡니다.
세 command의 선행 조건과 argument를 비교합니다.
`REGISTER`보다 port type 설정이 먼저 와야 합니다.
userio 사용자 공간 tool은 i8042의 일부 debugging 정보를 사용해 PS/2 장치를 기록하고 `/dev/userio`에서 재생할 수 있습니다. 최신 version은 `https://github.com/Lyude/ps2emu`에서 제공됩니다.
Commands
========
USERIO_CMD_REGISTER
~~~~~~~~~~~~~~~~~~~
Registers the port with the serio driver and begins transmitting data back and
forth. Registration can only be performed once a port type is set with
USERIO_CMD_SET_PORT_TYPE. Has no argument.
USERIO_CMD_SET_PORT_TYPE
~~~~~~~~~~~~~~~~~~~~~~~~
Sets the type of port we're emulating, where ``data`` is the port type being
set. Can be any of the macros from <linux/serio.h>. For example: SERIO_8042
would set the port type to be a normal PS/2 port.
USERIO_CMD_SEND_INTERRUPT
~~~~~~~~~~~~~~~~~~~~~~~~~
Sends an interrupt through the virtual serio port to the serio driver, where
``data`` is the interrupt data being sent.
Userspace tools
===============
The userio userspace tools are able to record PS/2 devices using some of the
debugging information from i8042, and play back the devices on /dev/userio. The
latest version of these tools can be found at:
https://github.com/Lyude/ps2emu
요약·해설
userio.rst:1-85`/dev/userio`는 실제 PS/2·serio hardware 없이 input driver를 시험할 수 있는 privileged interface입니다. 두 byte command로 port type을 정하고 등록한 뒤 interrupt를 전달하며, device를 닫으면 가상 port도 닫힙니다.
설정과 등록 순서를 지키는 것이 핵심입니다.