1 SPDX-License-Identifier: GPL-2.0
2
3 Chinese translated version of Documentation/fi
4
5 If you have any comment or update to the conte
6 original document maintainer directly. Howeve
7 communicating in English you can also ask the
8 help. Contact the Chinese maintainer if this
9 or if there is a problem with the translation.
10
11 Maintainer: Patrick Mochel <mochel@osdl.or
12 Mike Murphy <mamurph@cs.clemson
13 Chinese maintainer: Fu Wei <tekkamanninja@gmail
14 ----------------------------------------------
15 Documentation/filesystems/sysfs.rst 的中文
16
17 如果想評論或更新本文的內容，請
18 交流有困難的話，也可以向中文版
19 譯存在問題，請聯繫中文版維護者
20 英文版維護者： Patrick Mochel <mochel
21 Mike Murphy <mamurph@cs.clemson
22 中文版維護者： 傅煒 Fu Wei <tekkamanni
23 中文版翻譯者： 傅煒 Fu Wei <tekkamanni
24 中文版校譯者： 傅煒 Fu Wei <tekkamanni
25 繁體中文版校譯者：胡皓文 Hu Haowen<
26
27
28 以下爲正文
29 ----------------------------------------------
30 sysfs - 用於導出內核對象(kobject)的
31
32 Patrick Mochel <mochel@osdl.org>
33 Mike Murphy <mamurph@cs.clemson.edu>
34
35 修訂: 16 August 2011
36 原始版本: 10 January 2003
37
38
39 sysfs 簡介:
40 ~~~~~~~~~~
41
42 sysfs 是一個最初基於 ramfs 且位於內
43 數據結構及其屬性，以及它們之間
44
45 sysfs 始終與 kobject 的底層結構緊密
46 Documentation/core-api/kobject.rst 文檔以
47 信息。
48
49
50 使用 sysfs
51 ~~~~~~~~~~~
52
53 只要內核配置中定義了 CONFIG_SYSFS
54 通過以下命令掛載它:
55
56 mount -t sysfs sysfs /sys
57
58
59 創建目錄
60 ~~~~~~~~
61
62 任何 kobject 在系統中註冊，就會有
63 目錄是作爲該 kobject 的父對象所在
64 內核的對象層次到用戶空間。sysfs
65 共同祖先；例如：某些對象屬於某
66
67 Sysfs 在與其目錄關聯的 kernfs_node 對
68 目錄的 kobject 的指針。以前，這個
69 kobject 文件打開和關閉的引用計數
70 引用計數只能通過 sysfs_schedule_callba
71
72
73 屬性
74 ~~~~
75
76 kobject 的屬性可在文件系統中以普
77 了面向文件 I/O 操作的方法，以提
78
79
80 屬性應爲 ASCII 碼文本文件。以一個
81 文件只包含一個屬性值可能影響效
82 數組也被廣泛地接受。
83
84 混合類型、表達多行數據以及一些
85 很丟臉的,而且其代碼會在未通知作
86
87
88 一個簡單的屬性結構定義如下:
89
90 struct attribute {
91 char * name;
92 struct module *owner;
93 umode_t mode;
94 };
95
96
97 int sysfs_create_file(struct kobject * kobj, c
98 void sysfs_remove_file(struct kobject * kobj,
99
100
101 一個單獨的屬性結構並不包含讀寫
102 對象類型的屬性定義自己的屬性結
103
104 例如:驅動程序模型定義的 device_attr
105
106 struct device_attribute {
107 struct attribute attr;
108 ssize_t (*show)(struct device *dev, st
109 char *buf);
110 ssize_t (*store)(struct device *dev, s
111 const char *buf, size
112 };
113
114 int device_create_file(struct device *, const
115 void device_remove_file(struct device *, const
116
117 爲了定義設備屬性，同時定義了一
118
119 #define DEVICE_ATTR(_name, _mode, _show, _stor
120 struct device_attribute dev_attr_##_name = __A
121
122 例如:聲明
123
124 static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, sho
125
126 等同於如下代碼：
127
128 static struct device_attribute dev_attr_foo =
129 .attr = {
130 .name = "foo",
131 .mode = S_IWUSR | S_IRUGO,
132 .show = show_foo,
133 .store = store_foo,
134 },
135 };
136
137
138 子系統特有的回調函數
139 ~~~~~~~~~~~~~~~~~~~
140
141 當一個子系統定義一個新的屬性類
142 以幫助讀寫調用實現屬性所有者的
143
144 struct sysfs_ops {
145 ssize_t (*show)(struct kobject *, stru
146 ssize_t (*store)(struct kobject *, str
147 };
148
149 [子系統應已經定義了一個 struct kobj
150 描述符，並在此保存 sysfs_ops 的指
151 文檔]
152
153 sysfs 會爲這個類型調用適當的方法
154 將一般的kobject 和 attribute 結構體指
155 調用相關聯的函數。
156
157
158 示例:
159
160 #define to_dev_attr(_attr) container_of(_attr,
161
162 static ssize_t dev_attr_show(struct kobject *k
163 char *buf)
164 {
165 struct device_attribute *dev_attr = to
166 struct device *dev = kobj_to_dev(kobj)
167 ssize_t ret = -EIO;
168
169 if (dev_attr->show)
170 ret = dev_attr->show(dev, dev_
171 if (ret >= (ssize_t)PAGE_SIZE) {
172 printk("dev_attr_show: %pS ret
173 dev_attr->show
174 }
175 return ret;
176 }
177
178
179
180 讀寫屬性數據
181 ~~~~~~~~~~~~
182
183 在聲明屬性時，必須指定 show() 或 s
184 讀或寫。這些方法的類型應該和以
185
186 ssize_t (*show)(struct device *dev, struct dev
187 ssize_t (*store)(struct device *dev, struct de
188 const char *buf, size_t count
189
190 也就是說,他們應只以一個處理對象
191
192 sysfs 會分配一個大小爲 (PAGE_SIZE) 的
193 Sysfs 將會爲每次讀寫操作調用一次
194 會出現以下的行爲:
195
196 - 在讀方面（read(2)），show() 方法應
197 應只導出了一個屬性值或是一個
198 不會不太高。
199
200 這使得用戶空間可以局部地讀和
201 向後搜索到零或使用‘0’偏移執
202 再次被調用，以重新填充緩存。
203
204 - 在寫方面（write(2)），sysfs 希望在
205 之後 Sysfs 傳遞整個緩衝區給 store(
206
207 當要寫 sysfs 文件時，用戶空間進
208 改變的值，然後回寫整個緩衝區
209
210 在讀寫屬性值時，屬性方法的執
211
212 註記:
213
214 - 寫操作導致的 show() 方法重載，會
215
216 - 緩衝區應總是 PAGE_SIZE 大小。對於
217
218 - show() 方法應該返回寫入緩衝區的
219 返回值。
220
221 - show() 方法在將格式化返回值返回
222 如果可以保證不會發生緩衝區溢
223 scnprintf()。
224
225 - store() 應返回緩衝區的已用字節數
226 count 參數。
227
228 - show() 或 store() 可以返回錯誤值。
229 錯誤值。
230
231 - 一個傳遞給方法的對象將會通過 s
232 內存中。儘管如此，對象代表的
233 應該實現一個檢測機制。
234
235 一個簡單的(未經實驗證實的)設備
236
237 static ssize_t show_name(struct device *dev, s
238 char *buf)
239 {
240 return scnprintf(buf, PAGE_SIZE, "%s\n
241 }
242
243 static ssize_t store_name(struct device *dev,
244 const char *buf, siz
245 {
246 snprintf(dev->name, sizeof(dev->name),
247 (int)min(count, sizeof(dev->n
248 return count;
249 }
250
251 static DEVICE_ATTR(name, S_IRUGO, show_name, s
252
253
254 （注意：真正的實現不允許用戶空
255
256 頂層目錄佈局
257 ~~~~~~~~~~~~
258
259 sysfs 目錄的安排顯示了內核數據結
260
261 頂層 sysfs 目錄如下:
262
263 block/
264 bus/
265 class/
266 dev/
267 devices/
268 firmware/
269 net/
270 fs/
271
272 devices/ 包含了一個設備樹的文件系
273 設備樹，反映了設備的層次結構。
274
275 bus/ 包含了內核中各種總線類型的
276 子目錄:
277
278 devices/
279 drivers/
280
281 devices/ 包含了系統中出現的每個設
282 設備目錄。
283
284 drivers/ 包含了每個已爲特定總線上
285 假定驅動沒有跨越多個總線類型)。
286
287 fs/ 包含了一個爲文件系統設立的目
288 在 fs/ 下創建自己的層次結構(參見D
289
290 dev/ 包含兩個子目錄： char/ 和 block/
291 <major>:<minor> 格式命名的符號鏈接。
292 中相應的設備。/sys/dev 提供一個通
293 設備 sysfs 接口快捷的方法。
294
295 更多有關 driver-model 的特性信息可
296 中找到。
297
298
299 TODO: 完成這一節。
300
301
302 當前接口
303 ~~~~~~~~
304
305 以下的接口層普遍存在於當前的sysf
306
307 - 設備 (include/linux/device.h)
308 ----------------------------------
309 結構體:
310
311 struct device_attribute {
312 struct attribute attr;
313 ssize_t (*show)(struct device *dev, st
314 char *buf);
315 ssize_t (*store)(struct device *dev, s
316 const char *buf, size
317 };
318
319 聲明:
320
321 DEVICE_ATTR(_name, _mode, _show, _store);
322
323 增/刪屬性:
324
325 int device_create_file(struct device *dev, con
326 void device_remove_file(struct device *dev, co
327
328
329 - 總線驅動程序 (include/linux/device.h)
330 --------------------------------------
331 結構體:
332
333 struct bus_attribute {
334 struct attribute attr;
335 ssize_t (*show)(const struct bus_type
336 ssize_t (*store)(const struct bus_type
337 };
338
339 聲明:
340
341 BUS_ATTR(_name, _mode, _show, _store)
342
343 增/刪屬性:
344
345 int bus_create_file(struct bus_type *, struct
346 void bus_remove_file(struct bus_type *, struct
347
348
349 - 設備驅動程序 (include/linux/device.h)
350 -----------------------------------------
351
352 結構體:
353
354 struct driver_attribute {
355 struct attribute attr;
356 ssize_t (*show)(struct device_driver *
357 ssize_t (*store)(struct device_driver
358 size_t count);
359 };
360
361 聲明:
362
363 DRIVER_ATTR(_name, _mode, _show, _store)
364
365 增/刪屬性：
366
367 int driver_create_file(struct device_driver *,
368 void driver_remove_file(struct device_driver *
369
370
371 文檔
372 ~~~~
373
374 sysfs 目錄結構以及其中包含的屬性
375 對於任何 ABI，其自身的穩定和適當
376 屬性必須在 Documentation/ABI 中有文檔
377
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.