/* class結構體 */

struct class {
    const char            * name;        /* class的名稱 */
    struct module        * owner;    /* 擁有該class的模組 */
    struct kset            subsys;        /* 該class對應的子系統 */
    struct list_head    children;    /* 該class的class_device列表 */
    struct list_head    devices;    
    struct list_head    interfaces;    
    struct kset            class_dirs;        
    struct semaphore    sem;    /* locks both the children and interfaces lists */
    struct class_attribute            * class_attrs; /* 該class的預設屬性，以NULL結尾 */
    struct class_device_attribute    * class_dev_attrs; /* 新增到class的class_device所擁有的預設屬性 */
    struct device_attribute            * dev_attrs;
    
    /* 該函式提供在產生熱插拔class_device事件時,新增環境變數的能力 */
    int    (*uevent)(struct class_device *dev, struct kobj_uevent_env *env); 
    /* 該函式提供在產生熱插拔device(物理裝置)事件時,新增環境變數的能力 */
    int    (*dev_uevent)(struct device *dev, struct kobj_uevent_env *env);
    /* 新增到class的class_device移除時,呼叫該函式進行必要的清理工作 */
    void (*release)(struct class_device *dev);    
    /* class被移除時,呼叫該函式進行必要的清理工作 */
    void (*class_release)(struct class *class);
    void (*dev_release)(struct device *dev);
    int    (*suspend)(struct device *, pm_message_t state);
    int    (*resume)(struct device *);
};
/* class註冊函式 */
int __must_check class_register(struct class *);
void class_unregister(struct class *);

/* class_create用於建立一個名為name的class,其owner引數一般為THIS_MODULE。class_create內部呼叫了class_register */
struct class *class_create(struct module *owner, const char *name);
/* class_destroy用於刪除一個class,實際上其內部只是簡單呼叫了class_unregister(cls)來登出cls */
void class_destroy(struct class *cls);

/* class屬性結構體 */
struct class_attribute {
    struct attribute    attr;
    /* 當用戶空間讀取該屬性時,呼叫show函式輸出一個"屬性值"給使用者空間 */
    ssize_t (*show)(struct class *, char * buf);
    /* 當用戶空間寫該屬性時,呼叫store函式儲存使用者寫入的"屬性值" */
    ssize_t (*store)(struct class *, const char * buf, size_t count);
};
struct attribute {
    const char        * name;
    struct module    * owner;
    mode_t            mode;
};
/* CLASS_ATTR可以在編譯時建立一個class屬性,該屬性的名稱為class_attr_name */
#define CLASS_ATTR(_name,_mode,_show,_store)            \
struct class_attribute class_attr_##_name = __ATTR(_name,_mode,_show,_store) 
/* class_create_file與class_remove_file用於建立與刪除class預設屬性外的屬性 */
int __must_check class_create_file(struct class *,
                    const struct class_attribute *);
void class_remove_file(struct class *, const struct class_attribute *);

/* class_device結構體 */

struct class_device {
    struct list_head    node;            /* 僅供驅動核心內部使用 */
    struct kobject        kobj;            /* 該class_device相應的kobject,僅供驅動核心內部使用 */
    struct class        * class;        /* 該class_device所屬的class,必須有 */
    dev_t                devt;            /* 該class_device的裝置編號,用於建立其dev屬性檔案,僅供驅動核心內部使用 */
    struct device        * dev;            /* 指向該class_device相關的device結構體(物理裝置),可選.若不為NULL,用於建立一個從class入口到/sys/devices下相應入口的符號連線,以便使用者空間查詢裝置入口 */
    void                * class_data;    /* 該class_device的私有資料指標 */
    struct class_device    *parent;        /* parent of this child device, if there is one */
    struct attribute_group ** groups;    /* optional groups */
    void    (*release)(struct class_device *dev);
    int    (*uevent)(struct class_device *dev, struct kobj_uevent_env *env);
    char    class_id[BUS_ID_SIZE];        /* 該class_device的名稱,在其所屬class中應是唯一的,不可重名 */
};
/* class_devic註冊函式 */
int __must_check class_device_register(struct class_device *);
void class_device_unregister(struct class_device *);

/* class_device_create用於建立一個class_device,其名稱最後兩個引數決定(類似於printf的格式化字串)
 * cls指明瞭其所屬的class,可以是自己填充的class或由class_create返回的class
 * parent指明瞭該class_device的父class_device,若沒有,則為NULL
 * 該class_device的裝置編號,用於建立其dev屬性檔案,必須指明
 * device指明瞭該class_device(邏輯裝置)對應的device(物理裝置),可有可無,無則為NULL
 * 實際上，class_device_create也就是填充一個class_device，然後呼叫了class_device_register註冊該class_device
 */
struct class_device *class_device_create(struct class *cls,
                        struct class_device *parent,
                        dev_t devt,
                        struct device *device,
                        const char *fmt, ...)
                    __attribute__((format(printf,5,6)));
/* class_destroy用於刪除一個class,內部呼叫了class_unregister(cls)來登出cls */
void class_device_destroy(struct class *cls, dev_t devt);

/* class_device屬性,其show和store函式類似於class屬性的show和store函式 */
struct class_device_attribute {
    struct attribute    attr;
    ssize_t (*show)(struct class_device *, char * buf);
    ssize_t (*store)(struct class_device *, const char * buf, size_t count);
};
/* CLASS_DEVICE_ATTR可以在編譯時建立一個class_device屬性,該屬性的名稱為class_device_attr_name */
#define CLASS_DEVICE_ATTR(_name,_mode,_show,_store)        \
struct class_device_attribute class_device_attr_##_name =     \
    __ATTR(_name,_mode,_show,_store)
/* class_device_create_file與class_device_remove_file用於建立與刪除class_device預設屬性外的屬性 */
int __must_check class_device_create_file(struct class_device *,
                 const struct class_device_attribute *);
void class_device_remove_file(struct class_device * class_dev,
             const struct class_device_attribute * attr);