Documentation/driver-api/driver-model/bus.rst GitHub 원문 ↗

Linux 6.18.37 · Driver API

Bus Types

bus_type 등록, match callback, 목록 순회, sysfs hierarchy와 bus attribute API를 설명합니다.

Source pathDocumentation/driver-api/driver-model/bus.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

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

1. 요약·해설

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

요약과 해설

bus.rst:1-146

각 bus type은 static struct bus_type을 등록하고 bus-specific match로 device와 driver를 연결합니다. core 순회 helper는 lock과 reference lifetime을 관리하며, sysfs의 devices·drivers view와 BUS_ATTR_RW 기반 attribute를 제공합니다.

2. 영어 원문 전체

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

원문 전체 펼치기
1 =========
2 Bus Types
3 =========
4
5 Definition
6 ~~~~~~~~~~
7 See the kerneldoc for the struct bus_type.
8
9 int bus_register(struct bus_type * bus);
10
11
12 Declaration
13 ~~~~~~~~~~~
14
15 Each bus type in the kernel (PCI, USB, etc) should declare one static
16 object of this type. They must initialize the name field, and may
17 optionally initialize the match callback::
18
19 struct bus_type pci_bus_type = {
20 .name = "pci",
21 .match = pci_bus_match,
22 };
23
24 The structure should be exported to drivers in a header file:
25
26 extern struct bus_type pci_bus_type;
27
28
29 Registration
30 ~~~~~~~~~~~~
31
32 When a bus driver is initialized, it calls bus_register. This
33 initializes the rest of the fields in the bus object and inserts it
34 into a global list of bus types. Once the bus object is registered,
35 the fields in it are usable by the bus driver.
36
37
38 Callbacks
39 ~~~~~~~~~
40
41 match(): Attaching Drivers to Devices
42 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
43
44 The format of device ID structures and the semantics for comparing
45 them are inherently bus-specific. Drivers typically declare an array
46 of device IDs of devices they support that reside in a bus-specific
47 driver structure.
48
49 The purpose of the match callback is to give the bus an opportunity to
50 determine if a particular driver supports a particular device by
51 comparing the device IDs the driver supports with the device ID of a
52 particular device, without sacrificing bus-specific functionality or
53 type-safety.
54
55 When a driver is registered with the bus, the bus's list of devices is
56 iterated over, and the match callback is called for each device that
57 does not have a driver associated with it.
58
59
60
61 Device and Driver Lists
62 ~~~~~~~~~~~~~~~~~~~~~~~
63
64 The lists of devices and drivers are intended to replace the local
65 lists that many buses keep. They are lists of struct devices and
66 struct device_drivers, respectively. Bus drivers are free to use the
67 lists as they please, but conversion to the bus-specific type may be
68 necessary.
69
70 The LDM core provides helper functions for iterating over each list::
71
72 int bus_for_each_dev(struct bus_type * bus, struct device * start,
73 void * data,
74 int (*fn)(struct device *, void *));
75
76 int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
77 void * data, int (*fn)(struct device_driver *, void *));
78
79 These helpers iterate over the respective list, and call the callback
80 for each device or driver in the list. All list accesses are
81 synchronized by taking the bus's lock (read currently). The reference
82 count on each object in the list is incremented before the callback is
83 called; it is decremented after the next object has been obtained. The
84 lock is not held when calling the callback.
85
86
87 sysfs
88 ~~~~~~~~
89 There is a top-level directory named 'bus'.
90
91 Each bus gets a directory in the bus directory, along with two default
92 directories::
93
94 /sys/bus/pci/
95 |-- devices
96 `-- drivers
97
98 Drivers registered with the bus get a directory in the bus's drivers
99 directory::
100
101 /sys/bus/pci/
102 |-- devices
103 `-- drivers
104 |-- Intel ICH
105 |-- Intel ICH Joystick
106 |-- agpgart
107 `-- e100
108
109 Each device that is discovered on a bus of that type gets a symlink in
110 the bus's devices directory to the device's directory in the physical
111 hierarchy::
112
113 /sys/bus/pci/
114 |-- devices
115 | |-- 00:00.0 -> ../../../root/pci0/00:00.0
116 | |-- 00:01.0 -> ../../../root/pci0/00:01.0
117 | `-- 00:02.0 -> ../../../root/pci0/00:02.0
118 `-- drivers
119
120
121 Exporting Attributes
122 ~~~~~~~~~~~~~~~~~~~~
123
124 ::
125
126 struct bus_attribute {
127 struct attribute attr;
128 ssize_t (*show)(const struct bus_type *, char * buf);
129 ssize_t (*store)(const struct bus_type *, const char * buf, size_t count);
130 };
131
132 Bus drivers can export attributes using the BUS_ATTR_RW macro that works
133 similarly to the DEVICE_ATTR_RW macro for devices. For example, a
134 definition like this::
135
136 static BUS_ATTR_RW(debug);
137
138 is equivalent to declaring::
139
140 static bus_attribute bus_attr_debug;
141
142 This can then be used to add and remove the attribute from the bus's
143 sysfs directory using::
144
145 int bus_create_file(struct bus_type *, struct bus_attribute *);
146 void bus_remove_file(struct bus_type *, struct bus_attribute *);
147

3. 한국어 전문 번역

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

Bus type 정의

1-11

`struct bus_type`의 상세 정의는 해당 kerneldoc을 참고합니다.

int bus_register(struct bus_type * bus);

Bus type 선언

12-28

kernel의 각 bus type(PCI, USB 등)은 이 type의 static object 하나를 선언해야 합니다. `name` field는 반드시 초기화하고 `match` callback은 선택적으로 초기화할 수 있습니다.

struct bus_type pci_bus_type = {
       .name        = "pci",
       .match        = pci_bus_match,
};

이 구조체는 header file에서 driver에 export해야 합니다.

extern struct bus_type pci_bus_type;

Bus 등록

29-37

bus driver를 초기화할 때 `bus_register`를 호출합니다. 이 함수는 bus object의 나머지 field를 초기화하고 global bus-type 목록에 삽입합니다. bus object가 등록된 뒤에는 bus driver가 그 안의 field를 사용할 수 있습니다.

match(): driver를 device에 attach하기

38-60

device ID 구조체의 형식과 비교 semantics는 본질적으로 bus-specific입니다. driver는 보통 자신이 지원하는 device ID 배열을 bus-specific driver 구조체 안에 선언합니다.

`match` callback은 bus-specific 기능과 type safety를 잃지 않으면서 특정 driver가 지원하는 ID와 특정 device의 ID를 비교해 지원 여부를 판단할 기회를 bus에 제공합니다.

driver가 bus에 등록되면 bus의 device 목록을 순회하고, 아직 driver가 연결되지 않은 각 device에 `match` callback을 호출합니다.

Device와 driver 목록

61-86

bus의 device·driver 목록은 많은 bus가 따로 유지하던 local 목록을 대체하기 위한 것입니다. 각각 `struct device`와 `struct device_driver`의 목록입니다. bus driver는 필요에 따라 목록을 사용할 수 있지만 bus-specific type으로 변환해야 할 수 있습니다.

LDM core는 각 목록을 순회하는 helper function을 제공합니다.

int bus_for_each_dev(struct bus_type * bus, struct device * start,
                     void * data,
                     int (*fn)(struct device *, void *));

int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
                     void * data, int (*fn)(struct device_driver *, void *));

helper는 대응 목록을 순회하며 각 device 또는 driver마다 callback을 호출합니다. 모든 목록 접근은 bus lock(현재는 read lock)을 획득해 동기화합니다. callback 호출 전에 목록 object의 reference count를 늘리고 다음 object를 얻은 뒤 줄입니다. callback을 호출하는 동안에는 lock을 유지하지 않습니다.

bus_for_each_* iteration
bus list read lockcurrent object reference 획득다음 object 위치 확보lock 없이 callback 호출reference 감소 후 반복

목록 잠금과 object reference의 lifetime 순서를 나타냅니다.

Bus sysfs hierarchy

87-120

sysfs에는 top-level `bus` directory가 있습니다. 각 bus는 그 아래에 directory를 가지며 기본적으로 `devices`와 `drivers` 두 directory를 둡니다.

/sys/bus/pci/
|-- devices
`-- drivers

bus에 등록된 driver는 해당 bus의 `drivers` directory 아래에 directory를 얻습니다.

/sys/bus/pci/
|-- devices
`-- drivers
    |-- Intel ICH
    |-- Intel ICH Joystick
    |-- agpgart
    `-- e100

그 bus type에서 발견된 각 device는 bus의 `devices` directory에 symlink를 얻습니다. symlink target은 physical hierarchy에 있는 device directory입니다.

/sys/bus/pci/
|-- devices
|   |-- 00:00.0 -> ../../../root/pci0/00:00.0
|   |-- 00:01.0 -> ../../../root/pci0/00:01.0
|   `-- 00:02.0 -> ../../../root/pci0/00:02.0
`-- drivers
/sys/bus/<type> 구조
PathEntry kindMeaning
/sys/bus/pci/devicesDirectory of symlinksDiscovered PCI devices -> physical hierarchy
/sys/bus/pci/driversDirectoryRegistered PCI drivers
/sys/bus/pci/drivers/<driver>DirectoryOne registered driver and its bound devices
/sys/bus/pci/devices/00:00.0Symlink../../../root/pci0/00:00.0

원문의 ASCII tree를 같은 관계의 구조화 표로 다시 그렸습니다.

Bus attribute export

121-146 
::

  struct bus_attribute {
        struct attribute        attr;
        ssize_t (*show)(const struct bus_type *, char * buf);
        ssize_t (*store)(const struct bus_type *, const char * buf, size_t count);
  };

bus driver는 device의 `DEVICE_ATTR_RW`와 비슷하게 동작하는 `BUS_ATTR_RW` macro로 attribute를 export할 수 있습니다. 다음 정의를 사용합니다.

static BUS_ATTR_RW(debug);

이는 다음 `bus_attribute` 선언과 같습니다.

static bus_attribute bus_attr_debug;

그 다음 아래 함수로 bus의 sysfs directory에 attribute를 추가하거나 제거할 수 있습니다.

int bus_create_file(struct bus_type *, struct bus_attribute *);
void bus_remove_file(struct bus_type *, struct bus_attribute *);