1SPDX-License-Identifier: GPL-2.0 2 3Chinese translated version of Documentation/filesystems/sysfs.rst 4 5If you have any comment or update to the content, please contact the 6original document maintainer directly. However, if you have a problem 7communicating in English you can also ask the Chinese maintainer for 8help. Contact the Chinese maintainer if this translation is outdated 9or if there is a problem with the translation. 10 11Maintainer: Patrick Mochel <mochel@osdl.org> 12 Mike Murphy <mamurph@cs.clemson.edu> 13Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> 14--------------------------------------------------------------------- 15Documentation/filesystems/sysfs.rst 的中文翻譯 16 17如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 18交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 19譯存在問題，請聯繫中文版維護者。 20英文版維護者： Patrick Mochel <mochel@osdl.org> 21 Mike Murphy <mamurph@cs.clemson.edu> 22中文版維護者： 傅煒 Fu Wei <tekkamanninja@gmail.com> 23中文版翻譯者： 傅煒 Fu Wei <tekkamanninja@gmail.com> 24中文版校譯者： 傅煒 Fu Wei <tekkamanninja@gmail.com> 25繁體中文版校譯者：胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> 26 27 28以下爲正文 29--------------------------------------------------------------------- 30sysfs - 用於導出內核對象(kobject)的文件系統 31 32Patrick Mochel <mochel@osdl.org> 33Mike Murphy <mamurph@cs.clemson.edu> 34 35修訂: 16 August 2011 36原始版本: 10 January 2003 37 38 39sysfs 簡介: 40~~~~~~~~~~ 41 42sysfs 是一個最初基於 ramfs 且位於內存的文件系統。它提供導出內核 43數據結構及其屬性，以及它們之間的關聯到用戶空間的方法。 44 45sysfs 始終與 kobject 的底層結構緊密相關。請閱讀 46Documentation/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 67Sysfs 在與其目錄關聯的 kernfs_node 對象中內部保存一個指向實現 68目錄的 kobject 的指針。以前，這個 kobject 指針被 sysfs 直接用於 69kobject 文件打開和關閉的引用計數。而現在的 sysfs 實現中，kobject 70引用計數只能通過 sysfs_schedule_callback() 函數直接修改。 71 72 73屬性 74~~~~ 75 76kobject 的屬性可在文件系統中以普通文件的形式導出。Sysfs 爲屬性定義 77了面向文件 I/O 操作的方法，以提供對內核屬性的讀寫。 78 79 80屬性應爲 ASCII 碼文本文件。以一個文件只存儲一個屬性值爲宜。但一個 81文件只包含一個屬性值可能影響效率，所以一個包含相同數據類型的屬性值 82數組也被廣泛地接受。 83 84混合類型、表達多行數據以及一些怪異的數據格式會遭到強烈反對。這樣做是 85很丟臉的,而且其代碼會在未通知作者的情況下被重寫。 86 87 88一個簡單的屬性結構定義如下: 89 90struct attribute { 91 char * name; 92 struct module *owner; 93 umode_t mode; 94}; 95 96 97int sysfs_create_file(struct kobject * kobj, const struct attribute * attr); 98void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr); 99 100 101一個單獨的屬性結構並不包含讀寫其屬性值的方法。子系統最好爲增刪特定 102對象類型的屬性定義自己的屬性結構體和封裝函數。 103 104例如:驅動程序模型定義的 device_attribute 結構體如下: 105 106struct 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 114int device_create_file(struct device *, const struct device_attribute *); 115void device_remove_file(struct device *, const struct device_attribute *); 116 117爲了定義設備屬性，同時定義了一下輔助宏: 118 119#define DEVICE_ATTR(_name, _mode, _show, _store) \ 120struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store) 121 122例如:聲明 123 124static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo); 125 126等同於如下代碼： 127 128static 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 144struct 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 153sysfs 會爲這個類型調用適當的方法。當一個文件被讀寫時，這個方法會 154將一般的kobject 和 attribute 結構體指針轉換爲適當的指針類型後 155調用相關聯的函數。 156 157 158示例: 159 160#define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr) 161 162static 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 186ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf); 187ssize_t (*store)(struct device *dev, struct device_attribute *attr, 188 const char *buf, size_t count); 189 190也就是說,他們應只以一個處理對象、一個屬性和一個緩衝指針作爲參數。 191 192sysfs 會分配一個大小爲 (PAGE_SIZE) 的緩衝區並傳遞給這個方法。 193Sysfs 將會爲每次讀寫操作調用一次這個方法。這使得這些方法在執行時 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 237static 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 243static 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 251static DEVICE_ATTR(name, S_IRUGO, show_name, store_name); 252 253 254（注意：真正的實現不允許用戶空間設置設備名。） 255 256頂層目錄佈局 257~~~~~~~~~~~~ 258 259sysfs 目錄的安排顯示了內核數據結構之間的關係。 260 261頂層 sysfs 目錄如下: 262 263block/ 264bus/ 265class/ 266dev/ 267devices/ 268firmware/ 269net/ 270fs/ 271 272devices/ 包含了一個設備樹的文件系統表示。他直接映射了內部的內核 273設備樹，反映了設備的層次結構。 274 275bus/ 包含了內核中各種總線類型的平面目錄佈局。每個總線目錄包含兩個 276子目錄: 277 278 devices/ 279 drivers/ 280 281devices/ 包含了系統中出現的每個設備的符號鏈接，他們指向 root/ 下的 282設備目錄。 283 284drivers/ 包含了每個已爲特定總線上的設備而掛載的驅動程序的目錄(這裏 285假定驅動沒有跨越多個總線類型)。 286 287fs/ 包含了一個爲文件系統設立的目錄。現在每個想要導出屬性的文件系統必須 288在 fs/ 下創建自己的層次結構(參見Documentation/filesystems/fuse.rst)。 289 290dev/ 包含兩個子目錄： 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 299TODO: 完成這一節。 300 301 302當前接口 303~~~~~~~~ 304 305以下的接口層普遍存在於當前的sysfs中: 306 307- 設備 (include/linux/device.h) 308---------------------------------- 309結構體: 310 311struct 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 321DEVICE_ATTR(_name, _mode, _show, _store); 322 323增/刪屬性: 324 325int device_create_file(struct device *dev, const struct device_attribute * attr); 326void device_remove_file(struct device *dev, const struct device_attribute * attr); 327 328 329- 總線驅動程序 (include/linux/device.h) 330-------------------------------------- 331結構體: 332 333struct 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 341BUS_ATTR(_name, _mode, _show, _store) 342 343增/刪屬性: 344 345int bus_create_file(struct bus_type *, struct bus_attribute *); 346void bus_remove_file(struct bus_type *, struct bus_attribute *); 347 348 349- 設備驅動程序 (include/linux/device.h) 350----------------------------------------- 351 352結構體: 353 354struct 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 363DRIVER_ATTR(_name, _mode, _show, _store) 364 365增/刪屬性： 366 367int driver_create_file(struct device_driver *, const struct driver_attribute *); 368void driver_remove_file(struct device_driver *, const struct driver_attribute *); 369 370 371文檔 372~~~~ 373 374sysfs 目錄結構以及其中包含的屬性定義了一個內核與用戶空間之間的 ABI。 375對於任何 ABI，其自身的穩定和適當的文檔是非常重要的。所有新的 sysfs 376屬性必須在 Documentation/ABI 中有文檔。詳見 Documentation/ABI/README。 377 378