管理事件

系统经常需要对用户操作或系统请求之类的条件更改做出响应。例如，设备可能会在某个组件开始过热时发出警告，或者可能在将 DVD 插入驱动器后启动影片播放机。设备驱动程序可以使用称为事件的特殊消息来通知系统发生了状态更改。

事件介绍

事件是指设备驱动程序向相关实体发送的消息，用以指示发生了状态更改。在 Solaris OS 中，事件以用户定义的名称-值对结构的形式实现，这些结构使用 nvlist* 函数进行管理。（请参见 nvlist_alloc(9F) 手册页。）事件由供应商、类以及子类组成。例如，可以定义一个类用于监视环境条件。环境类可以具有子类，用来指示温度、风扇状态以及电源方面的变化。

发生状态更改时，设备将通知驱动程序。驱动程序随后将使用 ddi_log_sysevent(9F) 函数在称为 sysevent 的队列中记录此事件。sysevent 队列会将事件传递到用户级，以便通过 syseventd 守护进程或 syseventconfd 守护进程进行处理。这些守护进程会将通知发送到订阅了指定事件通知的所有应用程序。

用户级应用程序的设计者可以使用以下两种方法处理事件：

• 应用程序可以使用 libsysevent(3LIB) 中的例程向 syseventd 守护进程订阅发生指定事件时的通知。

• 开发者可以编写单独的用户级应用程序来响应事件。此类型应用程序需要通过 syseventadm(1M) 进行注册。syseventconfd 遇到指定事件时，应用程序会根据实际情况运行并处理此事件。

下图对此流程进行了说明。

图 5–1 事件检测

使用 ddi_log_sysevent() 记录事件

设备驱动程序使用 ddi_log_sysevent(9F) 接口生成和记录系统事件。

ddi_log_sysevent() 语法

ddi_log_sysevent() 使用以下语法：

int ddi_log_sysevent(dev_info_t *dip, char *vendor, char *class, 
    char *subclass, nvlist_t *attr-list, sysevent_id_t *eidp, int sleep-flag);

其中：

dip

指向相应驱动程序处理的 dev_info 节点的指针。

vendor

指向定义驱动程序供应商的字符串的指针。第三方驱动程序应使用其公司的股票代号或类似的持久标识符。Sun 提供的驱动程序会使用 DDI_VENDOR_SUNW。

class

指向定义事件类的字符串的指针。class 是特定于驱动程序的值。表示影响设备的一组环境条件的字符串可能即是一个类的示例。事件使用方必须能够理解该值。

subclass

表示 class 参数子集的特定于驱动程序的字符串。例如，在表示环境条件的类中，事件子类可能是指设备的温度。事件使用方必须能够理解该值。

attr-list

指向列出与事件关联的名称-值特性的 nvlist_t 结构的指针。名称-值特性是驱动程序定义的，可以是指设备的特定特性或条件。

例如，可同时读取 CD-ROM 和 DVD 的设备。此设备可能具有一个名称为 disc_type 并且值等于 cd_rom 或 dvd 的特性。

与 class 和 subclass 一样，事件使用方必须能够解释名称-值对。

有关名称-值对以及 nvlist_t 结构的更多信息，请参见定义事件特性以及 nvlist_alloc(9F) 手册页。

如果事件没有任何特性，则此参数应设置为 NULL。

eidp

sysevent_id_t 结构的地址。sysevent_id_t 结构用于提供事件的唯一标识。ddi_log_sysevent (9F) 将向此结构返回系统提供的事件序列号和时间戳。有关 sysevent_id_t 结构的更多信息，请参见 ddi_log_sysevent(9F) 手册页。

sleep-flag

指示调用者如何处理不可用资源可能性的标志。如果 sleep-flag 设置为 DDI_SLEEP，则驱动程序会阻塞，直到资源可用为止。如果设置为 DDI_NOSLEEP，则分配不会休眠且不能保证成功。如果返回了 DDI_ENOMEM，则驱动程序以后需要重试该操作。

即使设置为 DDI_SLEEP，此界面也可能返回错误（如系统繁忙），syseventd 守护进程不响应或不尝试在中断上下文中记录事件。

记录事件的样例代码

设备驱动程序可执行以下任务来记录事件：

• 使用 nvlist_alloc(9F) 为特性列表分配内存

• 向特性列表添加名称-值对

• 使用 ddi_log_sysevent(9F) 函数在 sysevent 队列中记录事件

• 不再需要特性列表时调用 nvlist_free(9F)

以下示例说明如何使用 ddi_log_sysevent()。

---

示例 5–1 调用 ddi_log_sysevent()

char *vendor_name = "DDI_VENDOR_JGJG"
char *my_class = "JGJG_event";
char *my_subclass = "JGJG_alert";
nvlist_t *nvl;
/* ... */
nvlist_alloc(&nvl, nvflag, kmflag);
/* ... */
(void) nvlist_add_byte_array(nvl, propname, (uchar_t *)propval, proplen + 1); 
/* ... */
if (ddi_log_sysevent(dip, vendor_name, my_class, 
    my_subclass, nvl, NULL, DDI_SLEEP)!= DDI_SUCCESS)
    cmn_err(CE_WARN, "error logging system event"); 
nvlist_free(nvl);

---

定义事件特性

事件特性定义为名称-值对列表。Solaris DDI 提供了用于在名称-值对中存储信息的例程和结构。名称-值对保留在 nvlist_t 结构中，此结构对于驱动程序是不透明的。名称-值对的值可以是布尔值、int、字节、字符串、nvlist 或这些数据类型的数组。int 可以定义为 16 位、32 位或 64 位，可以带符号，也可不带符号。

下面是创建名称-值对列表的步骤。

1. 使用 nvlist_alloc(9F) 创建 nvlist_t 结构。

   nvlist_alloc() 接口会采用以下三个参数：

   • nvlp－指向 nvlist_t 结构指针的指针

   • nvflag－指示名称-值对的名称唯一性的标志。如果此标志设置为 NV_UNIQUE_NAME_TYPE，则会从列表中删除与新对的名称和类型相匹配的任何现有对。如果标志设置为 NV_UNIQUE_NAME，则会删除任何同名的现有对，而不考虑对的类型。只要对的类型不同，通过指定 NV_UNIQUE_NAME_TYPE，列表即可包含两个或多个同名的对，但如果指定 NV_UNIQUE_NAME，则列表中只能有一个对名称实例。如果未设置标志，则不会执行任何唯一性检查，将由列表的使用方负责处理同名的对。

   • kmflag－指示内核内存分配策略的标志。如果此参数设置为 KM_SLEEP，则驱动程序会阻塞，直到请求的内存可进行分配为止。KM_SLEEP 分配可能会休眠，但是保证会成功。KM_NOSLEEP 分配保证不会休眠，但是可能会在当前无可用内存时返回 NULL。

2. 使用名称-值对填充 nvlist。例如，要添加字符串，请使用 nvlist_add_string(9F)。要添加 32 位整数数组，请使用 nvlist_add_int32_array(9F)。nvlist_add_boolean(9F) 手册页包含用于添加对的可用接口的完整列表。

要取消分配列表，请使用 nvlist_free(9F)。

以下代码样例说明如何创建名称-值对列表。

---

示例 5–2 创建和填充名称-值对列表

nvlist_t*
create_nvlist()
    {
    int err;
    char *str = "child";
    int32_t ints[] = {0, 1, 2};
    nvlist_t *nvl;

    err = nvlist_alloc(&nvl, NV_UNIQUE_NAME, 0);    /* allocate list */
    if (err)
        return (NULL);
    if ((nvlist_add_string(nvl, "name", str) != 0) ||
        (nvlist_add_int32_array(nvl, "prop", ints, 3) != 0)) {
        nvlist_free(nvl);
        return (NULL);
    }
    return (nvl);
}

---

驱动程序可通过相应类型的查找函数（如 nvlist_lookup_int32_array(9F)）来检索 nvlist 中的元素，此类查找函数将要搜索的名称-值对的名称作为参数。

---

注 –

仅当在调用 nvlist_alloc(9F) 时指定了 NV_UNIQUE_NAME 或 NV_UNIQUE_NAME_TYPE 的情况下，这些接口才会正常工作。否则，将返回 ENOTSUP，因为此列表不能包含多个同名的对。

---

可以将名称-值列表中的各对放在连续内存中。此方法有助于将列表传递给已订阅了通知的实体。第一步是使用 nvlist_size(9F) 获取列表所需的内存块的大小。第二步是使用 nvlist_pack(9F) 将列表压缩到缓冲区中。收到缓冲区内容的使用方可使用 nvlist_unpack(9F) 解压缩缓冲区。

用户级开发者和内核级开发者均可使用用于处理名称-值对的函数。可以在《man pages section 3: Library Interfaces and Headers》和《man pages section 9: DDI and DKI Kernel Functions》中找到这些函数的相同手册页。有关针对名称-值对执行操作的函数的列表，请参见下表。

表 5–1 使用名称-值对的函数

手册页	用途/函数
nvlist_add_boolean(9F)	向列表中添加名称-值对。函数包括：  nvlist_add_boolean()、nvlist_add_boolean_value ()、nvlist_add_byte()、nvlist_add_int8()、 nvlist_add_uint8()、nvlist_add_int16()、nvlist_add_uint16 ()、nvlist_add_int32()、nvlist_add_uint32()、 nvlist_add_int64()、nvlist_add_uint64()、nvlist_add_string ()、nvlist_add_nvlist()、nvlist_add_nvpair()、 nvlist_add_boolean_array()、nvlist_add_int8_array、nvlist_add_uint8_array ()、nvlist_add_nvlist_array()、nvlist_add_byte_array ()、nvlist_add_int16_array()、nvlist_add_uint16_array ()、nvlist_add_int32_array()、nvlist_add_uint32_array ()、nvlist_add_int64_array()、nvlist_add_uint64_array ()、nvlist_add_string_array()
nvlist_alloc(9F)	处理名称-值列表缓冲区。函数包括：  nvlist_alloc()、nvlist_free()、 nvlist_size()、nvlist_pack()、nvlist_unpack ()、nvlist_dup()、nvlist_merge()
nvlist_lookup_boolean(9F)	搜索名称-值对。函数包括：  nvlist_lookup_boolean()、nvlist_lookup_boolean_value ()、nvlist_lookup_byte()、nvlist_lookup_int8 ()、nvlist_lookup_int16()、nvlist_lookup_int32 ()、nvlist_lookup_int64()、nvlist_lookup_uint8 ()、nvlist_lookup_uint16()、nvlist_lookup_uint32 ()、nvlist_lookup_uint64()、nvlist_lookup_string ()、nvlist_lookup_nvlist()、nvlist_lookup_boolean_array、nvlist_lookup_byte_array()、nvlist_lookup_int8_array()、 nvlist_lookup_int16_array()、nvlist_lookup_int32_array()、 nvlist_lookup_int64_array()、nvlist_lookup_uint8_array()、 nvlist_lookup_uint16_array()、nvlist_lookup_uint32_array()、 nvlist_lookup_uint64_array()、nvlist_lookup_string_array()、 nvlist_lookup_nvlist_array()、nvlist_lookup_pairs()
nvlist_next_nvpair(9F)	获取名称-值对数据。函数包括：  nvlist_next_nvpair()、nvpair_name()、 nvpair_type()
nvlist_remove(9F)	删除名称-值对。函数包括：  nv_remove()、nv_remove_all()