요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
===============================
rfkill - RF kill switch support
===============================
.. contents::
:depth: 2
Introduction
============
The rfkill subsystem provides a generic interface for disabling any radio
transmitter in the system. When a transmitter is blocked, it shall not
radiate any power.
The subsystem also provides the ability to react on button presses and
disable all transmitters of a certain type (or all). This is intended for
situations where transmitters need to be turned off, for example on
aircraft.
The rfkill subsystem has a concept of "hard" and "soft" block, which
differ little in their meaning (block == transmitters off) but rather in
whether they can be changed or not:
- hard block
read-only radio block that cannot be overridden by software
- soft block
writable radio block (need not be readable) that is set by
the system software.
The rfkill subsystem has two parameters, rfkill.default_state and
rfkill.master_switch_mode, which are documented in
admin-guide/kernel-parameters.rst.
Implementation details
======================
The rfkill subsystem is composed of three main components:
* the rfkill core,
* the deprecated rfkill-input module (an input layer handler, being
replaced by userspace policy code) and
* the rfkill drivers.
The rfkill core provides API for kernel drivers to register their radio
transmitter with the kernel, methods for turning it on and off, and letting
the system know about hardware-disabled states that may be implemented on
the device.
The rfkill core code also notifies userspace of state changes, and provides
ways for userspace to query the current states. See the "Userspace support"
section below.
When the device is hard-blocked (either by a call to rfkill_set_hw_state()
or from query_hw_block), set_block() will be invoked for additional software
block, but drivers can ignore the method call since they can use the return
value of the function rfkill_set_hw_state() to sync the software state
instead of keeping track of calls to set_block(). In fact, drivers should
use the return value of rfkill_set_hw_state() unless the hardware actually
keeps track of soft and hard block separately.
Kernel API
==========
Drivers for radio transmitters normally implement an rfkill driver.
Platform drivers might implement input devices if the rfkill button is just
that, a button. If that button influences the hardware then you need to
implement an rfkill driver instead. This also applies if the platform provides
a way to turn on/off the transmitter(s).
For some platforms, it is possible that the hardware state changes during
suspend/hibernation, in which case it will be necessary to update the rfkill
core with the current state at resume time.
To create an rfkill driver, driver's Kconfig needs to have::
depends on RFKILL || !RFKILL
to ensure the driver cannot be built-in when rfkill is modular. The !RFKILL
case allows the driver to be built when rfkill is not configured, in which
case all rfkill API can still be used but will be provided by static inlines
which compile to almost nothing.
Calling rfkill_set_hw_state() when a state change happens is required from
rfkill drivers that control devices that can be hard-blocked unless they also
assign the poll_hw_block() callback (then the rfkill core will poll the
device). Don't do this unless you cannot get the event in any other way.
rfkill provides per-switch LED triggers, which can be used to drive LEDs
according to the switch state (LED_FULL when blocked, LED_OFF otherwise).
Userspace support
=================
The recommended userspace interface to use is /dev/rfkill, which is a misc
character device that allows userspace to obtain and set the state of rfkill
devices and sets of devices. It also notifies userspace about device addition
and removal. The API is a simple read/write API that is defined in
linux/rfkill.h, with one ioctl that allows turning off the deprecated input
handler in the kernel for the transition period.
Except for the one ioctl, communication with the kernel is done via read()
and write() of instances of 'struct rfkill_event'. In this structure, the
soft and hard block are properly separated (unlike sysfs, see below) and
userspace is able to get a consistent snapshot of all rfkill devices in the
system. Also, it is possible to switch all rfkill drivers (or all drivers of
a specified type) into a state which also updates the default state for
hotplugged devices.
After an application opens /dev/rfkill, it can read the current state of all
devices. Changes can be obtained by either polling the descriptor for
hotplug or state change events or by listening for uevents emitted by the
rfkill core framework.
Additionally, each rfkill device is registered in sysfs and emits uevents.
rfkill devices issue uevents (with an action of "change"), with the following
environment variables set::
RFKILL_NAME
RFKILL_STATE
RFKILL_TYPE
The content of these variables corresponds to the "name", "state" and
"type" sysfs files explained above.
For further details consult Documentation/ABI/stable/sysfs-class-rfkill.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
rfkill 문서 정보와 목차
1-8이 문서는 RF transmitter 차단 switch를 지원하는 rfkill subsystem을 설명하며, 목차는 depth 2까지 생성합니다.
===============================
rfkill - RF kill switch support
===============================
.. contents::
:depth: 2
rfkill 목적과 hard·soft block
9-35Rfkill subsystem은 system 안의 모든 radio transmitter를 disable하는 generic interface를 제공합니다. Transmitter가 block된 동안에는 어떤 power도 방사해서는 안 됩니다.
Button press에 반응해 특정 type의 transmitter 전체 또는 모든 transmitter를 끄는 기능도 제공합니다. 이는 aircraft 안처럼 transmitter를 꺼야 하는 상황을 위한 것입니다.
Hard block과 soft block은 모두 transmitter를 끈다는 의미이지만 변경 가능성이 다릅니다. Hard block은 software가 override할 수 없는 read-only radio block이고, soft block은 system software가 설정하는 writable radio block이며 반드시 읽을 수 있을 필요는 없습니다.
Subsystem parameter `rfkill.default_state`와 `rfkill.master_switch_mode`는 `admin-guide/kernel-parameters.rst`에 문서화되어 있습니다.
두 상태 모두 transmitter off를 뜻하지만 누가 변경할 수 있는지가 다릅니다.
Introduction
============
The rfkill subsystem provides a generic interface for disabling any radio
transmitter in the system. When a transmitter is blocked, it shall not
radiate any power.
The subsystem also provides the ability to react on button presses and
disable all transmitters of a certain type (or all). This is intended for
situations where transmitters need to be turned off, for example on
aircraft.
The rfkill subsystem has a concept of "hard" and "soft" block, which
differ little in their meaning (block == transmitters off) but rather in
whether they can be changed or not:
- hard block
read-only radio block that cannot be overridden by software
- soft block
writable radio block (need not be readable) that is set by
the system software.
The rfkill subsystem has two parameters, rfkill.default_state and
rfkill.master_switch_mode, which are documented in
admin-guide/kernel-parameters.rst.
rfkill subsystem 구성요소
36-45Rfkill subsystem은 rfkill core, deprecated된 `rfkill-input` module, rfkill driver의 세 주요 component로 구성됩니다.
`rfkill-input`은 input layer handler이며 userspace policy code로 대체되는 중입니다.
Core를 중심으로 driver와 legacy input handler가 상태 제어 경로를 구성합니다.
Implementation details
======================
The rfkill subsystem is composed of three main components:
* the rfkill core,
* the deprecated rfkill-input module (an input layer handler, being
replaced by userspace policy code) and
* the rfkill drivers.Core 등록·제어·userspace 통지
46-54Rfkill core는 kernel driver가 radio transmitter를 kernel에 등록하고 transmitter를 켜거나 끄며, device가 구현한 hardware-disabled 상태를 system에 알리는 API를 제공합니다.
Core는 상태 변경을 userspace에 알리고 현재 상태를 조회하는 방법도 제공합니다. 자세한 userspace 경로는 뒤의 Userspace support 절에서 설명합니다.
Driver 등록과 hardware 상태를 받아 제어 API와 userspace 관찰 경로를 제공합니다.
The rfkill core provides API for kernel drivers to register their radio
transmitter with the kernel, methods for turning it on and off, and letting
the system know about hardware-disabled states that may be implemented on
the device.
The rfkill core code also notifies userspace of state changes, and provides
ways for userspace to query the current states. See the "Userspace support"
section below.Hard block 중 software state 동기화
55-63Device가 `rfkill_set_hw_state()` 호출이나 `query_hw_block` 결과로 hard-blocked 상태일 때 추가 software block을 위한 `set_block()`도 호출됩니다.
Driver는 `set_block()` 호출을 따로 추적하지 않고 `rfkill_set_hw_state()` 반환값으로 software state를 동기화할 수 있으므로 이 method call을 무시해도 됩니다.
Hardware가 soft block과 hard block을 실제로 별도 추적하는 경우가 아니라면 driver는 `rfkill_set_hw_state()`의 반환값을 사용해야 합니다.
Hardware state update의 반환값이 별도 set_block 추적 없이 software state를 맞춥니다.
When the device is hard-blocked (either by a call to rfkill_set_hw_state()
or from query_hw_block), set_block() will be invoked for additional software
block, but drivers can ignore the method call since they can use the return
value of the function rfkill_set_hw_state() to sync the software state
instead of keeping track of calls to set_block(). In fact, drivers should
use the return value of rfkill_set_hw_state() unless the hardware actually
keeps track of soft and hard block separately.
Kernel driver와 platform 경계
64-78Radio transmitter driver는 보통 rfkill driver를 구현합니다.
Platform의 rfkill control이 단순 button일 뿐이면 platform driver가 input device를 구현할 수 있습니다. 그러나 button이 hardware에 영향을 주거나 platform이 transmitter를 켜고 끄는 방법을 제공하면 rfkill driver를 구현해야 합니다.
일부 platform에서는 suspend 또는 hibernation 중 hardware state가 바뀔 수 있습니다. 이 경우 resume 시점에 현재 상태로 rfkill core를 갱신해야 합니다.
Kernel API
==========
Drivers for radio transmitters normally implement an rfkill driver.
Platform drivers might implement input devices if the rfkill button is just
that, a button. If that button influences the hardware then you need to
implement an rfkill driver instead. This also applies if the platform provides
a way to turn on/off the transmitter(s).
For some platforms, it is possible that the hardware state changes during
suspend/hibernation, in which case it will be necessary to update the rfkill
core with the current state at resume time.
Kconfig dependency와 stub API
79-87Rfkill driver의 Kconfig에는 `depends on RFKILL || !RFKILL`이 필요합니다. 이는 rfkill이 module일 때 driver가 built-in으로 구성되는 일을 막습니다.
`!RFKILL` 조건은 rfkill이 설정되지 않은 경우에도 driver build를 허용합니다. 이때 모든 rfkill API는 거의 아무 code도 생성하지 않는 static inline으로 제공되므로 같은 call site를 유지할 수 있습니다.
Dependency 식이 modular ordering을 지키면서 RFKILL 미설정 build도 허용합니다.
To create an rfkill driver, driver's Kconfig needs to have::
depends on RFKILL || !RFKILL
to ensure the driver cannot be built-in when rfkill is modular. The !RFKILL
case allows the driver to be built when rfkill is not configured, in which
case all rfkill API can still be used but will be provided by static inlines
which compile to almost nothing.
Hardware 상태 보고와 LED trigger
88-96Hard-block 가능한 device를 제어하는 rfkill driver는 state change가 생길 때 `rfkill_set_hw_state()`를 호출해야 합니다.
대신 `poll_hw_block()` callback을 지정하면 rfkill core가 device를 poll합니다. 다른 어떤 방법으로도 event를 받을 수 없을 때만 polling을 사용해야 합니다.
Rfkill은 switch별 LED trigger를 제공합니다. Switch가 block 상태이면 `LED_FULL`, 그렇지 않으면 `LED_OFF`로 LED를 구동할 수 있습니다.
Calling rfkill_set_hw_state() when a state change happens is required from
rfkill drivers that control devices that can be hard-blocked unless they also
assign the poll_hw_block() callback (then the rfkill core will poll the
device). Don't do this unless you cannot get the event in any other way.
rfkill provides per-switch LED triggers, which can be used to drive LEDs
according to the switch state (LED_FULL when blocked, LED_OFF otherwise).
/dev/rfkill userspace interface
97-106권장 userspace interface는 misc character device인 `/dev/rfkill`입니다. Userspace는 개별 rfkill device와 device 집합의 상태를 읽고 설정할 수 있으며 device 추가·제거 통지도 받습니다.
API는 `linux/rfkill.h`에 정의된 단순 read/write interface입니다. 전환 기간 동안 kernel의 deprecated input handler를 끌 수 있는 ioctl 하나도 제공합니다.
Misc character device가 상태 query·set과 device lifecycle notification을 한 interface로 제공합니다.
Userspace support
=================
The recommended userspace interface to use is /dev/rfkill, which is a misc
character device that allows userspace to obtain and set the state of rfkill
devices and sets of devices. It also notifies userspace about device addition
and removal. The API is a simple read/write API that is defined in
linux/rfkill.h, with one ioctl that allows turning off the deprecated input
handler in the kernel for the transition period.
rfkill_event snapshot과 default state
107-114단 하나의 ioctl을 제외하면 kernel과의 통신은 `struct rfkill_event` instance를 `read()`하고 `write()`하는 방식입니다.
이 구조체에서는 sysfs와 달리 soft block과 hard block이 올바르게 분리되며, userspace는 system의 모든 rfkill device에 대한 일관된 snapshot을 얻을 수 있습니다.
모든 rfkill driver 또는 지정 type의 모든 driver를 한 상태로 전환할 수 있고, 이 operation은 이후 hotplug되는 device의 default state도 갱신합니다.
Except for the one ioctl, communication with the kernel is done via read()
and write() of instances of 'struct rfkill_event'. In this structure, the
soft and hard block are properly separated (unlike sysfs, see below) and
userspace is able to get a consistent snapshot of all rfkill devices in the
system. Also, it is possible to switch all rfkill drivers (or all drivers of
a specified type) into a state which also updates the default state for
hotplugged devices.
상태 변화 감지와 sysfs
115-121Application이 `/dev/rfkill`을 열면 모든 device의 현재 상태를 읽을 수 있습니다.
이후 변화는 descriptor를 polling해 hotplug 또는 state-change event를 받거나 rfkill core framework가 내보내는 uevent를 listen하는 방법으로 얻습니다.
각 rfkill device는 sysfs에도 등록되고 uevent를 발생시킵니다.
초기 snapshot 이후 descriptor event 또는 uevent로 변화분을 추적합니다.
After an application opens /dev/rfkill, it can read the current state of all
devices. Changes can be obtained by either polling the descriptor for
hotplug or state change events or by listening for uevents emitted by the
rfkill core framework.
Additionally, each rfkill device is registered in sysfs and emits uevents.
Uevent 환경 변수와 ABI
122-132Rfkill device는 action이 `change`인 uevent를 발생시키며 `RFKILL_NAME`, `RFKILL_STATE`, `RFKILL_TYPE` 환경 변수를 설정합니다.
각 변수의 내용은 앞에서 설명한 sysfs의 `name`, `state`, `type` file에 대응합니다. 자세한 내용은 `Documentation/ABI/stable/sysfs-class-rfkill`을 참조합니다.
Action은 `change`이며 ABI 세부사항은 stable sysfs-class-rfkill 문서에 정의됩니다.
rfkill devices issue uevents (with an action of "change"), with the following
environment variables set::
RFKILL_NAME
RFKILL_STATE
RFKILL_TYPE
The content of these variables corresponds to the "name", "state" and
"type" sysfs files explained above.
For further details consult Documentation/ABI/stable/sysfs-class-rfkill.
요약과 해설
rfkill.rst:1-132Rfkill core는 radio transmitter를 hard·soft block으로 제어하고 driver의 hardware 상태를 userspace에 전달합니다. Driver는 event 기반 `rfkill_set_hw_state()`를 우선 사용하며, userspace는 `/dev/rfkill`의 `struct rfkill_event`, descriptor polling, uevent와 sysfs ABI로 일관된 상태를 관찰하고 변경합니다.