| 1 |
SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
Chinese translated version of Documentation/filesystems/sysfs.rst |
| 4 |
|
| 5 |
If you have any comment or update to the content, please contact the |
| 6 |
original document maintainer directly. However, if you have a problem |
| 7 |
communicating in English you can also ask the Chinese maintainer for |
| 8 |
help. Contact the Chinese maintainer if this translation is outdated |
| 9 |
or if there is a problem with the translation. |
| 10 |
|
| 11 |
Maintainer: Patrick Mochel <[email protected]> |
| 12 |
Mike Murphy <[email protected]> |
| 13 |
Chinese maintainer: Fu Wei <[email protected]> |
| 14 |
--------------------------------------------------------------------- |
| 15 |
Documentation/filesystems/sysfs.rst 的中文翻譯 |
| 16 |
|
| 17 |
如果想評論或更新本文的內容,請直接聯繫原文檔的維護者。如果你使用英文 |
| 18 |
交流有困難的話,也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 |
| 19 |
譯存在問題,請聯繫中文版維護者。 |
| 20 |
英文版維護者: Patrick Mochel <[email protected]> |
| 21 |
Mike Murphy <[email protected]> |
| 22 |
中文版維護者: 傅煒 Fu Wei <[email protected]> |
| 23 |
中文版翻譯者: 傅煒 Fu Wei <[email protected]> |
| 24 |
中文版校譯者: 傅煒 Fu Wei <[email protected]> |
| 25 |
繁體中文版校譯者:胡皓文 Hu Haowen <[email protected]> |
| 26 |
|
| 27 |
|
| 28 |
以下爲正文 |
| 29 |
--------------------------------------------------------------------- |
| 30 |
sysfs - 用於導出內核對象(kobject)的文件系統 |
| 31 |
|
| 32 |
Patrick Mochel <[email protected]> |
| 33 |
Mike Murphy <[email protected]> |
| 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 文檔以獲得更多關於 kobject 接口的 |
| 47 |
信息。 |
| 48 |
|
| 49 |
|
| 50 |
使用 sysfs |
| 51 |
~~~~~~~~~~~ |
| 52 |
|
| 53 |
只要內核配置中定義了 CONFIG_SYSFS ,sysfs 總是被編譯進內核。你可 |
| 54 |
通過以下命令掛載它: |
| 55 |
|
| 56 |
mount -t sysfs sysfs /sys |
| 57 |
|
| 58 |
|
| 59 |
創建目錄 |
| 60 |
~~~~~~~~ |
| 61 |
|
| 62 |
任何 kobject 在系統中註冊,就會有一個目錄在 sysfs 中被創建。這個 |
| 63 |
目錄是作爲該 kobject 的父對象所在目錄的子目錄創建的,以準確地傳遞 |
| 64 |
內核的對象層次到用戶空間。sysfs 中的頂層目錄代表着內核對象層次的 |
| 65 |
共同祖先;例如:某些對象屬於某個子系統。 |
| 66 |
|
| 67 |
Sysfs 在與其目錄關聯的 kernfs_node 對象中內部保存一個指向實現 |
| 68 |
目錄的 kobject 的指針。以前,這個 kobject 指針被 sysfs 直接用於 |
| 69 |
kobject 文件打開和關閉的引用計數。而現在的 sysfs 實現中,kobject |
| 70 |
引用計數只能通過 sysfs_schedule_callback() 函數直接修改。 |
| 71 |
|
| 72 |
|
| 73 |
屬性 |
| 74 |
~~~~ |
| 75 |
|
| 76 |
kobject 的屬性可在文件系統中以普通文件的形式導出。Sysfs 爲屬性定義 |
| 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, const struct attribute * attr); |
| 98 |
void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr); |
| 99 |
|
| 100 |
|
| 101 |
一個單獨的屬性結構並不包含讀寫其屬性值的方法。子系統最好爲增刪特定 |
| 102 |
對象類型的屬性定義自己的屬性結構體和封裝函數。 |
| 103 |
|
| 104 |
例如:驅動程序模型定義的 device_attribute 結構體如下: |
| 105 |
|
| 106 |
struct device_attribute { |
| 107 |
struct attribute attr; |
| 108 |
ssize_t (*show)(struct device *dev, struct device_attribute *attr, |
| 109 |
char *buf); |
| 110 |
ssize_t (*store)(struct device *dev, struct device_attribute *attr, |
| 111 |
const char *buf, size_t count); |
| 112 |
}; |
| 113 |
|
| 114 |
int device_create_file(struct device *, const struct device_attribute *); |
| 115 |
void device_remove_file(struct device *, const struct device_attribute *); |
| 116 |
|
| 117 |
爲了定義設備屬性,同時定義了一下輔助宏: |
| 118 |
|
| 119 |
#define DEVICE_ATTR(_name, _mode, _show, _store) \ |
| 120 |
struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store) |
| 121 |
|
| 122 |
例如:聲明 |
| 123 |
|
| 124 |
static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo); |
| 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 |
當一個子系統定義一個新的屬性類型時,必須實現一系列的 sysfs 操作, |
| 142 |
以幫助讀寫調用實現屬性所有者的顯示和儲存方法。 |
| 143 |
|
| 144 |
struct sysfs_ops { |
| 145 |
ssize_t (*show)(struct kobject *, struct attribute *, char *); |
| 146 |
ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t); |
| 147 |
}; |
| 148 |
|
| 149 |
[子系統應已經定義了一個 struct kobj_type 結構體作爲這個類型的 |
| 150 |
描述符,並在此保存 sysfs_ops 的指針。更多的信息參見 kobject 的 |
| 151 |
文檔] |
| 152 |
|
| 153 |
sysfs 會爲這個類型調用適當的方法。當一個文件被讀寫時,這個方法會 |
| 154 |
將一般的kobject 和 attribute 結構體指針轉換爲適當的指針類型後 |
| 155 |
調用相關聯的函數。 |
| 156 |
|
| 157 |
|
| 158 |
示例: |
| 159 |
|
| 160 |
#define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr) |
| 161 |
|
| 162 |
static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr, |
| 163 |
char *buf) |
| 164 |
{ |
| 165 |
struct device_attribute *dev_attr = to_dev_attr(attr); |
| 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_attr, buf); |
| 171 |
if (ret >= (ssize_t)PAGE_SIZE) { |
| 172 |
printk("dev_attr_show: %pS returned bad count\n", |
| 173 |
dev_attr->show); |
| 174 |
} |
| 175 |
return ret; |
| 176 |
} |
| 177 |
|
| 178 |
|
| 179 |
|
| 180 |
讀寫屬性數據 |
| 181 |
~~~~~~~~~~~~ |
| 182 |
|
| 183 |
在聲明屬性時,必須指定 show() 或 store() 方法,以實現屬性的 |
| 184 |
讀或寫。這些方法的類型應該和以下的設備屬性定義一樣簡單。 |
| 185 |
|
| 186 |
ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf); |
| 187 |
ssize_t (*store)(struct device *dev, struct device_attribute *attr, |
| 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’偏移執行一個pread(2)操作,show()方法將 |
| 202 |
再次被調用,以重新填充緩存。 |
| 203 |
|
| 204 |
- 在寫方面(write(2)),sysfs 希望在第一次寫操作時得到整個緩衝區。 |
| 205 |
之後 Sysfs 傳遞整個緩衝區給 store() 方法。 |
| 206 |
|
| 207 |
當要寫 sysfs 文件時,用戶空間進程應首先讀取整個文件,修該想要 |
| 208 |
改變的值,然後回寫整個緩衝區。 |
| 209 |
|
| 210 |
在讀寫屬性值時,屬性方法的執行應操作相同的緩衝區。 |
| 211 |
|
| 212 |
註記: |
| 213 |
|
| 214 |
- 寫操作導致的 show() 方法重載,會忽略當前文件位置。 |
| 215 |
|
| 216 |
- 緩衝區應總是 PAGE_SIZE 大小。對於i386,這個值爲4096。 |
| 217 |
|
| 218 |
- show() 方法應該返回寫入緩衝區的字節數,也就是 scnprintf()的 |
| 219 |
返回值。 |
| 220 |
|
| 221 |
- show() 方法在將格式化返回值返回用戶空間的時候,禁止使用snprintf()。 |
| 222 |
如果可以保證不會發生緩衝區溢出,可以使用sprintf(),否則必須使用 |
| 223 |
scnprintf()。 |
| 224 |
|
| 225 |
- store() 應返回緩衝區的已用字節數。如果整個緩存都已填滿,只需返回 |
| 226 |
count 參數。 |
| 227 |
|
| 228 |
- show() 或 store() 可以返回錯誤值。當得到一個非法值,必須返回一個 |
| 229 |
錯誤值。 |
| 230 |
|
| 231 |
- 一個傳遞給方法的對象將會通過 sysfs 調用對象內嵌的引用計數固定在 |
| 232 |
內存中。儘管如此,對象代表的物理實體(如設備)可能已不存在。如有必要, |
| 233 |
應該實現一個檢測機制。 |
| 234 |
|
| 235 |
一個簡單的(未經實驗證實的)設備屬性實現如下: |
| 236 |
|
| 237 |
static ssize_t show_name(struct device *dev, struct device_attribute *attr, |
| 238 |
char *buf) |
| 239 |
{ |
| 240 |
return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name); |
| 241 |
} |
| 242 |
|
| 243 |
static ssize_t store_name(struct device *dev, struct device_attribute *attr, |
| 244 |
const char *buf, size_t count) |
| 245 |
{ |
| 246 |
snprintf(dev->name, sizeof(dev->name), "%.*s", |
| 247 |
(int)min(count, sizeof(dev->name) - 1), buf); |
| 248 |
return count; |
| 249 |
} |
| 250 |
|
| 251 |
static DEVICE_ATTR(name, S_IRUGO, show_name, store_name); |
| 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/ 包含了系統中出現的每個設備的符號鏈接,他們指向 root/ 下的 |
| 282 |
設備目錄。 |
| 283 |
|
| 284 |
drivers/ 包含了每個已爲特定總線上的設備而掛載的驅動程序的目錄(這裏 |
| 285 |
假定驅動沒有跨越多個總線類型)。 |
| 286 |
|
| 287 |
fs/ 包含了一個爲文件系統設立的目錄。現在每個想要導出屬性的文件系統必須 |
| 288 |
在 fs/ 下創建自己的層次結構(參見Documentation/filesystems/fuse/fuse.rst)。 |
| 289 |
|
| 290 |
dev/ 包含兩個子目錄: char/ 和 block/。在這兩個子目錄中,有以 |
| 291 |
<major>:<minor> 格式命名的符號鏈接。這些符號鏈接指向 sysfs 目錄 |
| 292 |
中相應的設備。/sys/dev 提供一個通過一個 stat(2) 操作結果,查找 |
| 293 |
設備 sysfs 接口快捷的方法。 |
| 294 |
|
| 295 |
更多有關 driver-model 的特性信息可以在 Documentation/driver-api/driver-model/ |
| 296 |
中找到。 |
| 297 |
|
| 298 |
|
| 299 |
TODO: 完成這一節。 |
| 300 |
|
| 301 |
|
| 302 |
當前接口 |
| 303 |
~~~~~~~~ |
| 304 |
|
| 305 |
以下的接口層普遍存在於當前的sysfs中: |
| 306 |
|
| 307 |
- 設備 (include/linux/device.h) |
| 308 |
---------------------------------- |
| 309 |
結構體: |
| 310 |
|
| 311 |
struct device_attribute { |
| 312 |
struct attribute attr; |
| 313 |
ssize_t (*show)(struct device *dev, struct device_attribute *attr, |
| 314 |
char *buf); |
| 315 |
ssize_t (*store)(struct device *dev, struct device_attribute *attr, |
| 316 |
const char *buf, size_t count); |
| 317 |
}; |
| 318 |
|
| 319 |
聲明: |
| 320 |
|
| 321 |
DEVICE_ATTR(_name, _mode, _show, _store); |
| 322 |
|
| 323 |
增/刪屬性: |
| 324 |
|
| 325 |
int device_create_file(struct device *dev, const struct device_attribute * attr); |
| 326 |
void device_remove_file(struct device *dev, const struct device_attribute * attr); |
| 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 *, char * buf); |
| 336 |
ssize_t (*store)(const struct bus_type *, const char * buf, size_t count); |
| 337 |
}; |
| 338 |
|
| 339 |
聲明: |
| 340 |
|
| 341 |
BUS_ATTR(_name, _mode, _show, _store) |
| 342 |
|
| 343 |
增/刪屬性: |
| 344 |
|
| 345 |
int bus_create_file(struct bus_type *, struct bus_attribute *); |
| 346 |
void bus_remove_file(struct bus_type *, struct bus_attribute *); |
| 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 *, char * buf); |
| 357 |
ssize_t (*store)(struct device_driver *, const char * buf, |
| 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 *, const struct driver_attribute *); |
| 368 |
void driver_remove_file(struct device_driver *, const struct driver_attribute *); |
| 369 |
|
| 370 |
|
| 371 |
文檔 |
| 372 |
~~~~ |
| 373 |
|
| 374 |
sysfs 目錄結構以及其中包含的屬性定義了一個內核與用戶空間之間的 ABI。 |
| 375 |
對於任何 ABI,其自身的穩定和適當的文檔是非常重要的。所有新的 sysfs |
| 376 |
屬性必須在 Documentation/ABI 中有文檔。詳見 Documentation/ABI/README。 |
| 377 |
|