Documentation/translations/zh_TW/filesystems/sysfs.txt

   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      <mochel@osdl.org>
  12                 Mike Murphy <mamurph@cs.clemson.edu>
  13 Chinese maintainer: Fu Wei <tekkamanninja@gmail.com>
  14 ---------------------------------------------------------------------
  15 Documentation/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 <src.res@email.cn>
  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 文檔以獲得更多關於 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.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)(struct bus_type *, char * buf);
 336         ssize_t (*store)(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