요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
USB core callbacks
~~~~~~~~~~~~~~~~~~
What callbacks will usbcore do?
===============================
Usbcore will call into a driver through callbacks defined in the driver
structure and through the completion handler of URBs a driver submits.
Only the former are in the scope of this document. These two kinds of
callbacks are completely independent of each other. Information on the
completion callback can be found in :ref:`usb-urb`.
The callbacks defined in the driver structure are:
1. Hotplugging callbacks:
- @probe:
Called to see if the driver is willing to manage a particular
interface on a device.
- @disconnect:
Called when the interface is no longer accessible, usually
because its device has been (or is being) disconnected or the
driver module is being unloaded.
2. Odd backdoor through usbfs:
- @ioctl:
Used for drivers that want to talk to userspace through
the "usbfs" filesystem. This lets devices provide ways to
expose information to user space regardless of where they
do (or don't) show up otherwise in the filesystem.
3. Power management (PM) callbacks:
- @suspend:
Called when the device is going to be suspended.
- @resume:
Called when the device is being resumed.
- @reset_resume:
Called when the suspended device has been reset instead
of being resumed.
4. Device level operations:
- @pre_reset:
Called when the device is about to be reset.
- @post_reset:
Called after the device has been reset
The ioctl interface (2) should be used only if you have a very good
reason. Sysfs is preferred these days. The PM callbacks are covered
separately in :ref:`usb-power-management`.
Calling conventions
===================
All callbacks are mutually exclusive. There's no need for locking
against other USB callbacks. All callbacks are called from a task
context. You may sleep. However, it is important that all sleeps have a
small fixed upper limit in time. In particular you must not call out to
user space and await results.
Hotplugging callbacks
=====================
These callbacks are intended to associate and disassociate a driver with
an interface. A driver's bond to an interface is exclusive.
The probe() callback
--------------------
::
int (*probe) (struct usb_interface *intf,
const struct usb_device_id *id);
Accept or decline an interface. If you accept the device return 0,
otherwise -ENODEV or -ENXIO. Other error codes should be used only if a
genuine error occurred during initialisation which prevented a driver
from accepting a device that would else have been accepted.
You are strongly encouraged to use usbcore's facility,
usb_set_intfdata(), to associate a data structure with an interface, so
that you know which internal state and identity you associate with a
particular interface. The device will not be suspended and you may do IO
to the interface you are called for and endpoint 0 of the device. Device
initialisation that doesn't take too long is a good idea here.
The disconnect() callback
-------------------------
::
void (*disconnect) (struct usb_interface *intf);
This callback is a signal to break any connection with an interface.
You are not allowed any IO to a device after returning from this
callback. You also may not do any other operation that may interfere
with another driver bound to the interface, eg. a power management
operation. Outstanding operations on the device must be completed or
aborted before this callback may return.
If you are called due to a physical disconnection, all your URBs will be
killed by usbcore. Note that in this case disconnect will be called some
time after the physical disconnection. Thus your driver must be prepared
to deal with failing IO even prior to the callback.
Device level callbacks
======================
pre_reset
---------
::
int (*pre_reset)(struct usb_interface *intf);
A driver or user space is triggering a reset on the device which
contains the interface passed as an argument. Cease IO, wait for all
outstanding URBs to complete, and save any device state you need to
restore. No more URBs may be submitted until the post_reset method
is called.
If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you
are in atomic context.
post_reset
----------
::
int (*post_reset)(struct usb_interface *intf);
The reset has completed. Restore any saved device state and begin
using the device again.
If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you
are in atomic context.
Call sequences
==============
No callbacks other than probe will be invoked for an interface
that isn't bound to your driver.
Probe will never be called for an interface bound to a driver.
Hence following a successful probe, disconnect will be called
before there is another probe for the same interface.
Once your driver is bound to an interface, disconnect can be
called at any time except in between pre_reset and post_reset.
pre_reset is always followed by post_reset, even if the reset
failed or the device has been unplugged.
suspend is always followed by one of: resume, reset_resume, or
disconnect.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Usbcore callback 종류
1-56Usbcore는 driver structure에 정의된 callback과 driver가 제출한 URB의 completion handler를 통해 driver를 호출합니다. 이 문서는 driver structure callback만 다루며 두 callback 종류는 서로 완전히 독립적입니다. Completion callback 정보는 `usb-urb` reference를 참조합니다.
Hotplug callback의 `probe`는 driver가 특정 device interface를 관리할 의사가 있는지 확인할 때 호출됩니다. `disconnect`는 device가 분리 중이거나 이미 분리됐거나 driver module이 unload되어 interface에 더 이상 접근할 수 없을 때 호출됩니다.
Usbfs backdoor인 `ioctl`은 `usbfs` filesystem을 통해 userspace와 통신하려는 driver가 사용합니다. Device가 filesystem의 다른 위치에 나타나는지와 관계없이 userspace에 정보를 노출할 수 있습니다.
Power management callback은 suspend 직전의 `suspend`, resume 중의 `resume`, 일반 resume 대신 suspended device가 reset됐을 때의 `reset_resume`입니다.
Device-level operation은 reset 직전의 `pre_reset`과 reset 뒤의 `post_reset`입니다. `ioctl` interface는 매우 타당한 이유가 있을 때만 사용해야 하며 현재는 sysfs가 선호됩니다. PM callback은 `usb-power-management` reference에서 별도로 설명합니다.
USB core callbacks
~~~~~~~~~~~~~~~~~~
What callbacks will usbcore do?
===============================
Usbcore will call into a driver through callbacks defined in the driver
structure and through the completion handler of URBs a driver submits.
Only the former are in the scope of this document. These two kinds of
callbacks are completely independent of each other. Information on the
completion callback can be found in :ref:`usb-urb`.
The callbacks defined in the driver structure are:
1. Hotplugging callbacks:
- @probe:
Called to see if the driver is willing to manage a particular
interface on a device.
- @disconnect:
Called when the interface is no longer accessible, usually
because its device has been (or is being) disconnected or the
driver module is being unloaded.
2. Odd backdoor through usbfs:
- @ioctl:
Used for drivers that want to talk to userspace through
the "usbfs" filesystem. This lets devices provide ways to
expose information to user space regardless of where they
do (or don't) show up otherwise in the filesystem.
3. Power management (PM) callbacks:
- @suspend:
Called when the device is going to be suspended.
- @resume:
Called when the device is being resumed.
- @reset_resume:
Called when the suspended device has been reset instead
of being resumed.
4. Device level operations:
- @pre_reset:
Called when the device is about to be reset.
- @post_reset:
Called after the device has been reset
The ioctl interface (2) should be used only if you have a very good
reason. Sysfs is preferred these days. The PM callbacks are covered
separately in :ref:`usb-power-management`.공통 호출 규약
57-66모든 USB callback은 서로 배타적으로 실행되므로 다른 USB callback과의 locking은 필요하지 않습니다. 모든 callback은 task context에서 호출되어 sleep할 수 있습니다.
다만 모든 sleep에는 짧고 고정된 최대 시간이 있어야 합니다. 특히 userspace를 호출한 뒤 결과를 기다리면 안 됩니다.
Calling conventions
===================
All callbacks are mutually exclusive. There's no need for locking
against other USB callbacks. All callbacks are called from a task
context. You may sleep. However, it is important that all sleeps have a
small fixed upper limit in time. In particular you must not call out to
user space and await results.
Hotplug와 `probe()` callback
67-91Hotplug callback은 driver와 interface를 연결하거나 분리하기 위한 것이며 한 interface에 대한 driver의 bind는 exclusive입니다.
`probe(struct usb_interface *intf, const struct usb_device_id *id)`는 interface를 수락하거나 거절합니다. Device를 수락하면 0, 거절하면 `-ENODEV` 또는 `-ENXIO`를 반환합니다. 원래 수락했어야 할 device를 initialization error 때문에 수락하지 못한 경우에만 다른 error code를 사용합니다.
`usb_set_intfdata()`로 data structure를 interface와 연결하는 방식을 강하게 권장합니다. 이를 통해 특정 interface에 대응하는 internal state와 identity를 알 수 있습니다.
`probe()` 중에는 device가 suspend되지 않으며 전달된 interface와 device endpoint 0에 I/O를 수행할 수 있습니다. 너무 오래 걸리지 않는 device initialization을 여기서 수행하는 것이 좋습니다.
Interface 지원 여부와 initialization 결과에 따라 반환값을 선택합니다.
Hotplugging callbacks
=====================
These callbacks are intended to associate and disassociate a driver with
an interface. A driver's bond to an interface is exclusive.
The probe() callback
--------------------
::
int (*probe) (struct usb_interface *intf,
const struct usb_device_id *id);
Accept or decline an interface. If you accept the device return 0,
otherwise -ENODEV or -ENXIO. Other error codes should be used only if a
genuine error occurred during initialisation which prevented a driver
from accepting a device that would else have been accepted.
You are strongly encouraged to use usbcore's facility,
usb_set_intfdata(), to associate a data structure with an interface, so
that you know which internal state and identity you associate with a
particular interface. The device will not be suspended and you may do IO
to the interface you are called for and endpoint 0 of the device. Device
initialisation that doesn't take too long is a good idea here.
`disconnect()` callback
92-110`disconnect(struct usb_interface *intf)`는 interface와의 모든 연결을 끊으라는 신호입니다. Callback이 반환한 뒤에는 device에 어떤 I/O도 할 수 없고, power management operation처럼 이후 interface에 bind될 다른 driver를 방해할 수 있는 operation도 수행하면 안 됩니다.
Device에서 진행 중인 모든 operation은 callback이 반환하기 전에 완료하거나 abort해야 합니다.
Physical disconnection 때문에 호출된 경우 usbcore가 모든 URB를 kill합니다. `disconnect`는 실제 물리 분리보다 나중에 호출될 수 있으므로 driver는 callback 전부터 I/O 실패를 처리할 준비가 되어 있어야 합니다.
Callback 반환 시점까지 I/O와 outstanding operation을 완전히 정리합니다.
The disconnect() callback
-------------------------
::
void (*disconnect) (struct usb_interface *intf);
This callback is a signal to break any connection with an interface.
You are not allowed any IO to a device after returning from this
callback. You also may not do any other operation that may interfere
with another driver bound to the interface, eg. a power management
operation. Outstanding operations on the device must be completed or
aborted before this callback may return.
If you are called due to a physical disconnection, all your URBs will be
killed by usbcore. Note that in this case disconnect will be called some
time after the physical disconnection. Thus your driver must be prepared
to deal with failing IO even prior to the callback.
`pre_reset`과 `post_reset`
111-142Driver 또는 userspace가 전달된 interface를 포함한 device reset을 시작하면 `pre_reset(struct usb_interface *intf)`가 호출됩니다. I/O를 중단하고 모든 outstanding URB가 완료될 때까지 기다린 뒤 복원에 필요한 device state를 저장합니다.
`post_reset`이 호출될 때까지 새 URB를 제출하면 안 됩니다. 여기서 memory가 필요하면 `GFP_NOIO`를 사용하고 atomic context라면 `GFP_ATOMIC`을 사용합니다.
Reset이 끝나면 `post_reset(struct usb_interface *intf)`가 호출됩니다. 저장한 device state를 복원하고 device 사용을 다시 시작합니다. 이 callback에서 allocation이 필요할 때도 `GFP_NOIO` 또는 atomic context의 `GFP_ATOMIC`을 사용합니다.
Reset 전후에 I/O를 멈추고 state를 보존·복원합니다.
Device level callbacks
======================
pre_reset
---------
::
int (*pre_reset)(struct usb_interface *intf);
A driver or user space is triggering a reset on the device which
contains the interface passed as an argument. Cease IO, wait for all
outstanding URBs to complete, and save any device state you need to
restore. No more URBs may be submitted until the post_reset method
is called.
If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you
are in atomic context.
post_reset
----------
::
int (*post_reset)(struct usb_interface *intf);
The reset has completed. Restore any saved device state and begin
using the device again.
If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you
are in atomic context.
Callback 호출 순서 보장
143-159Driver에 bind되지 않은 interface에는 `probe` 외의 callback이 호출되지 않습니다. 이미 driver에 bind된 interface에는 `probe`가 호출되지 않으므로 성공한 `probe` 뒤 같은 interface에 다음 `probe`가 오기 전에 반드시 `disconnect`가 호출됩니다.
Driver가 interface에 bind된 뒤 `disconnect`는 `pre_reset`과 `post_reset` 사이를 제외하면 언제든 호출될 수 있습니다. Reset 실패나 device unplug이 발생해도 `pre_reset` 뒤에는 항상 `post_reset`이 호출됩니다.
`suspend` 뒤에는 항상 `resume`, `reset_resume`, `disconnect` 중 하나가 호출됩니다.
Call sequences
==============
No callbacks other than probe will be invoked for an interface
that isn't bound to your driver.
Probe will never be called for an interface bound to a driver.
Hence following a successful probe, disconnect will be called
before there is another probe for the same interface.
Once your driver is bound to an interface, disconnect can be
called at any time except in between pre_reset and post_reset.
pre_reset is always followed by post_reset, even if the reset
failed or the device has been unplugged.
suspend is always followed by one of: resume, reset_resume, or
disconnect.
요약·해설
callbacks.rst:1-159Usbcore callback은 interface bind·disconnect, power management와 device reset의 lifecycle을 직렬화합니다. Driver는 callback별 I/O 허용 범위와 outstanding URB 정리, 보장된 후속 callback을 지켜야 합니다.