客户端驱动程序 API 文档 ¶

串行集线器通信 ¶

enum ssh_frame_type¶: SSH 帧的帧类型。

常量

SSH_FRAME_TYPE_DATA_SEQ: 指示数据帧，后跟一个有效负载，其长度在 struct ssh_frame.len 字段中指定。此帧是排序的，这意味着需要 ACK。
SSH_FRAME_TYPE_DATA_NSQ: 与 SSH_FRAME_TYPE_DATA_SEQ 相同，但未排序，这意味着消息不必被 ACK。
SSH_FRAME_TYPE_ACK: 指示 ACK 消息。
SSH_FRAME_TYPE_NAK: 指示先前发送的帧的错误响应。一般来说，这意味着帧和/或有效负载格式错误，例如 CRC 错误。对于命令类型有效负载，这也可能意味着该命令无效。

struct ssh_frame¶: SSH 通信帧。

定义:

struct ssh_frame {
    u8 type;
    __le16 len;
    u8 seq;
};

成员

type: 帧的类型。参见 enum ssh_frame_type。
len: 紧随此帧的 CRC 之后的帧有效负载的长度。不包括该有效负载的最终 CRC。
seq: 此消息/交换的序列号。

enum ssh_payload_type¶: SSH 有效负载的类型指示符。

常量

SSH_PLD_TYPE_CMD: 有效负载是带有可选命令有效负载的命令结构。

struct ssh_command¶: 命令类型帧的有效负载。

定义:

struct ssh_command {
    u8 type;
    u8 tc;
    u8 tid;
    u8 sid;
    u8 iid;
    __le16 rqid;
    u8 cid;
};

成员

type: 有效负载的类型。参见 enum ssh_payload_type。对于此结构，应为 SSH_PLD_TYPE_CMD。
tc: 命令目标类别。
tid: 目标 ID。指示消息的目标。
sid: 源 ID。指示消息的来源。
iid: 实例 ID。
rqid: 请求 ID。用于将请求与响应匹配，并区分响应和事件。
cid: 命令 ID。

SSH_MESSAGE_LENGTH¶

SSH_MESSAGE_LENGTH (payload_size)

计算 SSH 消息的长度。

参数

payload_size: SSH 帧内的有效负载的长度。

返回值

返回具有指定大小的有效负载的 SSH 消息的长度。

SSH_COMMAND_MESSAGE_LENGTH¶

SSH_COMMAND_MESSAGE_LENGTH (payload_size)

计算 SSH 命令消息的长度。

参数

payload_size: 命令有效负载的长度。

返回值

返回带有指定大小的命令有效负载的 SSH 命令消息的长度。

SSH_MSGOFFSET_FRAME¶

SSH_MSGOFFSET_FRAME (field)

计算 SSH 消息中到帧中指定字段的偏移量。

参数

field: 应计算偏移量的字段。

返回值

以原始 SSH 消息数据返回指定 struct ssh_frame 字段的偏移量。考虑了帧之前的 SYN 字节 (u16)。

SSH_MSGOFFSET_COMMAND¶

SSH_MSGOFFSET_COMMAND (field)

计算 SSH 消息中到命令中指定字段的偏移量。

参数

field: 应计算偏移量的字段。

返回值

以原始 SSH 消息数据返回指定 struct ssh_command 字段的偏移量。考虑了帧之前的 SYN 字节 (u16) 以及帧和命令之间的帧 CRC (u16)。

u16 ssh_crc(const u8 *buf, size_t len)¶: 计算 SSH 消息的 CRC。

参数

const u8 *buf: 指向应计算 CRC 的数据的指针。
size_t len: 应计算 CRC 的数据的长度。

返回值

返回在提供的数据上计算的 CRC，用于 SSH 消息。

u16 ssh_rqid_next_valid(u16 rqid)¶: 返回下一个有效的请求 ID。

参数

u16 rqid: 当前请求 ID。

返回值

返回下一个有效的请求 ID，遵循提供给此函数的当前请求 ID。此函数跳过为事件保留的任何请求 ID。

u16 ssh_rqid_to_event(u16 rqid)¶: 将请求 ID 转换为其对应的事件 ID。

参数

u16 rqid: 要转换的请求 ID。

bool ssh_rqid_is_event(u16 rqid)¶: 检查给定的请求 ID 是否为有效的事件 ID。

参数

u16 rqid: 要检查的请求 ID。

u16 ssh_tc_to_rqid(u8 tc)¶: 将目标类别转换为其对应的请求 ID。

参数

u8 tc: 要转换的目标类别。

u8 ssh_tid_to_index(u8 tid)¶: 将目标 ID 转换为其对应的目标索引。

参数

u8 tid: 要转换的目标 ID。

bool ssh_tid_is_valid(u8 tid)¶: 检查目标 ID 是否有效/受支持。

参数

u8 tid: 要检查的目标 ID。

struct ssam_span¶: 对缓冲区区域的引用。

定义:

struct ssam_span {
    u8 *ptr;
    size_t len;
};

成员

ptr: 指向缓冲区区域的指针。
len: 缓冲区区域的长度。

描述

对（非拥有的）缓冲区段的引用，由指针和长度组成。使用此结构表示非拥有的数据，即生命周期由另一个指针管理（即，已分配/释放）的数据。

enum ssam_ssh_tid¶: 串行集线器消息的目标/源 ID。

常量

SSAM_SSH_TID_HOST: 我们作为内核串行集线器驱动程序。
SSAM_SSH_TID_SAM: Surface 聚合器 EC。
SSAM_SSH_TID_KIP: 键盘和外围设备控制器。
SSAM_SSH_TID_DEBUG: 调试连接器。
SSAM_SSH_TID_SURFLINK: SurfLink 连接器。

enum ssh_packet_base_priority¶: struct ssh_packet 的基本优先级。

常量

SSH_PACKET_PRIORITY_FLUSH: 刷新数据包的基本优先级。
SSH_PACKET_PRIORITY_DATA: 普通数据包的基本优先级。
SSH_PACKET_PRIORITY_NAK: NAK 数据包的基本优先级。
SSH_PACKET_PRIORITY_ACK: ACK 数据包的基本优先级。

SSH_PACKET_PRIORITY¶

SSH_PACKET_PRIORITY (base, try)

从基本优先级和尝试次数计算数据包优先级。

参数

base: 作为 enum ssh_packet_base_priority 的后缀的基本优先级，例如 FLUSH、DATA、ACK 或 NAK。
try: 尝试次数（必须小于 16）。

描述

计算组合数据包优先级。组合优先级由基本优先级主导，而（重新）尝试次数决定了具有相同基本优先级的数据包的优先级，从而为已经有更多尝试的数据包赋予更高的优先级。

返回值

将计算出的优先级作为适合在 u8 中存储的值返回。数字越大，优先级越高。

u8 ssh_packet_priority_get_try(u8 priority)¶: 从数据包优先级获取尝试次数。

参数

u8 priority: 数据包优先级。

返回值

返回在指定的数据包优先级中编码的尝试次数。

u8 ssh_packet_priority_get_base(u8 priority)¶: 从数据包优先级获取基本优先级。

参数

u8 priority: 数据包优先级。

返回值

返回在给定的数据包优先级中编码的基本优先级。

struct ssh_packet_ops¶: SSH 数据包的回调操作。

定义:

struct ssh_packet_ops {
    void (*release)(struct ssh_packet *p);
    void (*complete)(struct ssh_packet *p, int status);
};

成员

release: 当数据包引用计数达到零时调用的函数。必须依赖此回调来确保数据包已离开传输系统。
complete: 当数据包完成时（成功或失败）调用的函数。如果失败，则失败原因由提供的状态代码参数的值指示。如果成功，此值为零。请注意，调用此回调并不能保证数据包不再被传输系统使用。

struct ssh_packet¶: SSH 传输数据包。

定义:

struct ssh_packet {
    struct ssh_ptl *ptl;
    struct kref refcnt;
    u8 priority;
    struct {
        size_t len;
        u8 *ptr;
    } data;
    unsigned long state;
    ktime_t timestamp;
    struct list_head queue_node;
    struct list_head pending_node;
    const struct ssh_packet_ops *ops;
};

成员

ptl: 指向数据包传输层的指针。如果尚未提交数据包（或封闭的请求），则可能为 NULL。
refcnt: 数据包的引用计数。
priority: 数据包的优先级。必须通过 SSH_PACKET_PRIORITY() 计算。首次提交后，只能在持有队列锁时访问。
data: 原始消息数据。
data.len: 原始消息数据的长度。
data.ptr: 指向原始消息数据缓冲区的指针。
state: 描述当前数据包状态（动态）和类型（静态）的状态和类型标志。有关可能的选项，请参见 enum ssh_packet_flags。
timestamp: 时间戳，指定当前挂起数据包的最新传输何时开始。在传输尝试之前或之间，可能为 KTIME_MAX。用于数据包超时实现。首次提交后，必须在持有 pending 锁的情况下才能访问。
queue_node: 数据包队列的列表节点。
pending_node: 挂起数据包集合的列表节点。
ops: 数据包操作。

void ssh_packet_set_data(struct ssh_packet *p, u8 *ptr, size_t len)¶: 设置数据包的原始消息数据。

参数

struct ssh_packet *p: 应设置消息数据的数据包。
u8 *ptr: 指向保存消息数据的内存的指针。
size_t len: 消息数据的长度。

描述

将数据包的原始消息数据缓冲区设置为提供的内存。不复制内存。相反，调用者负责内存的管理（即分配和释放）。调用者必须确保提供的内存有效，并包含有效的 SSH 消息，从数据包提交时开始，直到调用 release 回调为止。在此期间，不得以任何方式更改内存。

struct ssh_request_ops¶: SSH 请求的回调操作。

定义:

struct ssh_request_ops {
    void (*release)(struct ssh_request *rqst);
    void (*complete)(struct ssh_request *rqst,const struct ssh_command *cmd, const struct ssam_span *data, int status);
};

成员

release

当请求的引用计数达到零时调用的函数。必须依靠此回调来确保请求已离开传输系统（数据包和请求系统）。

complete

请求完成时调用的函数，无论成功还是失败。请求响应的命令数据通过 struct ssh_command 参数 (cmd) 提供，请求响应的命令有效负载通过 struct ssh_span 参数 (data) 提供。

如果请求没有任何响应或未成功完成，则 cmd 和 data 参数都将为 NULL。如果请求响应没有任何命令有效负载，则 data span 将是一个空的（零长度）span。

如果失败，失败的原因由提供的状态代码参数 (status) 的值指示。成功时此值为零，否则为常规 errno。

请注意，调用此回调并不能保证请求不再被传输系统使用。

struct ssh_request¶: SSH 传输请求。

定义:

struct ssh_request {
    struct ssh_packet packet;
    struct list_head node;
    unsigned long state;
    ktime_t timestamp;
    const struct ssh_request_ops *ops;
};

成员

packet: 底层 SSH 传输数据包。
node: 请求队列和挂起集合的列表节点。
state: 描述当前请求状态（动态）和类型（静态）的状态和类型标志。有关可能的选项，请参见 enum ssh_request_flags。
timestamp: 时间戳，指定我们何时开始等待请求的响应。一旦底层数据包完成，就会设置此时间戳，并且在此之前或当请求不期望响应时，该时间戳可能为 KTIME_MAX。用于请求超时实现。
ops: 请求操作。

struct ssh_request *to_ssh_request(struct ssh_packet *p)¶: 将 SSH 数据包强制转换为其封闭的 SSH 请求。

参数

struct ssh_packet *p: 要强制转换的数据包。

描述

将给定的 struct ssh_packet 强制转换为其封闭的 struct ssh_request。调用者负责确保数据包实际上包含在 struct ssh_request 中。

返回值

返回包装提供的数据包的 struct ssh_request。

struct ssh_request *ssh_request_get(struct ssh_request *r)¶: 增加请求的引用计数。

参数

struct ssh_request *r: 要增加引用计数的请求。

描述

通过增加其中包含的底层 struct ssh_packet 的引用计数，来增加给定请求的引用计数。

另请参见 ssh_request_put()、ssh_packet_get()。

返回值

返回作为输入提供的请求。

void ssh_request_put(struct ssh_request *r)¶: 减少请求的引用计数。

参数

struct ssh_request *r: 要减少引用计数的请求。

描述

通过减少其中包含的底层 struct ssh_packet 的引用计数，来减少给定请求的引用计数。如果引用计数达到零，则会调用请求的 struct ssh_request_ops 中指定的 release 回调，即 r->ops->release。

另请参见 ssh_request_get()、ssh_packet_put()。

void ssh_request_set_data(struct ssh_request *r, u8 *ptr, size_t len)¶: 设置请求的原始消息数据。

参数

struct ssh_request *r: 应设置消息数据的请求。
u8 *ptr: 指向保存消息数据的内存的指针。
size_t len: 消息数据的长度。

描述

将底层数据包的原始消息数据缓冲区设置为指定的缓冲区。不复制实际消息数据，仅设置缓冲区指针和长度。有关更多详细信息，请参见 ssh_packet_set_data()。

struct ssh_packet *ssh_packet_get(struct ssh_packet *packet)¶: 增加数据包的引用计数。

参数

struct ssh_packet *packet: 要增加引用计数的数据包。

描述

增加给定数据包的引用计数。有关此函数的对应部分，请参见 ssh_packet_put()。

返回值

返回作为输入提供的数据包。

void ssh_packet_put(struct ssh_packet *packet)¶: 减少数据包的引用计数。

参数

struct ssh_packet *packet: 要减少引用计数的数据包。

描述

如果引用计数达到零，则会调用数据包的 struct ssh_packet_ops 中指定的 release 回调，即 packet->ops->release。

有关此函数的对应部分，请参见 ssh_packet_get()。

控制器和核心接口 ¶

enum ssam_event_flags¶: 用于启用/禁用 SAM 事件的标志

常量

SSAM_EVENT_SEQUENCED: 该事件将通过排序的数据帧发送。

struct ssam_event¶: 从 EC 发送到主机的 SAM 事件。

定义:

struct ssam_event {
    u8 target_category;
    u8 target_id;
    u8 command_id;
    u8 instance_id;
    u16 length;
    u8 data[] ;
};

成员

target_category: 事件源的目标类别。请参见 enum ssam_ssh_tc。
target_id: 事件源的目标 ID。
command_id: 事件的命令 ID。
instance_id: 事件源的实例 ID。
length: 事件有效负载的长度（以字节为单位）。
data: 事件有效负载数据。

enum ssam_request_flags¶: SAM 请求的标志。

常量

SSAM_REQUEST_HAS_RESPONSE: 指定请求期望得到响应。如果未设置，则在传输其底层数据包后，将直接完成请求。如果设置，则请求传输系统将等待请求的响应。
SSAM_REQUEST_UNSEQUENCED: 指定应通过未排序的数据包传输请求。如果设置，则请求不得有响应，这意味着此标志和 SSAM_REQUEST_HAS_RESPONSE 标志是互斥的。

struct ssam_request¶: SAM 请求描述。

定义:

struct ssam_request {
    u8 target_category;
    u8 target_id;
    u8 command_id;
    u8 instance_id;
    u16 flags;
    u16 length;
    const u8 *payload;
};

成员

target_category: 请求目标类别。请参见 enum ssam_ssh_tc。
target_id: 请求目标的 ID。
command_id: 请求的命令 ID。
instance_id: 请求目标的实例 ID。
flags: 请求的标志。请参见 enum ssam_request_flags。
length: 请求有效负载的长度（以字节为单位）。
payload: 请求有效负载数据。

描述

此结构完整描述了带有有效负载的 SAM 请求。它旨在帮助设置实际的传输结构，例如 struct ssam_request_sync，特别是通过 ssam_request_write_data() 设置其原始消息数据。

struct ssam_response¶: SAM 请求的响应缓冲区。

定义:

struct ssam_response {
    size_t capacity;
    size_t length;
    u8 *pointer;
};

成员

capacity: 缓冲区的容量（以字节为单位）。
length: 实际存储在 pointer 指向的内存中的数据的长度（以字节为单位）。由传输系统设置。
pointer: 指向缓冲区的内存的指针，用于存储响应有效负载数据。

struct ssam_request_sync¶: 同步 SAM 请求结构。

定义:

struct ssam_request_sync {
    struct ssh_request base;
    struct completion comp;
    struct ssam_response *resp;
    int status;
};

成员

base: 底层 SSH 请求。
comp: 用于表示请求完全完成的完成对象。提交请求后，只有在完成对象发出信号后，才能修改或释放此结构。提交请求后，
resp: 用于存储响应的缓冲区。
status: 请求的状态，在基本请求完成或失败后设置。

void ssam_request_sync_set_data(struct ssam_request_sync *rqst, u8 *ptr, size_t len)¶: 设置同步请求的消息数据。

参数

struct ssam_request_sync *rqst: 请求。
u8 *ptr: 指向请求消息数据的指针。
size_t len: 请求消息数据的长度。

描述

设置同步请求的请求消息数据。提供的缓冲区需要在请求完成之前一直存在。

void ssam_request_sync_set_resp(struct ssam_request_sync *rqst, struct ssam_response *resp)¶: 设置同步请求的响应缓冲区。

参数

struct ssam_request_sync *rqst: 请求。
struct ssam_response *resp: 响应缓冲区。

描述

设置同步请求的响应缓冲区。完成请求后，此缓冲区将存储请求的响应。如果不期望任何响应，则可以为 NULL。

int ssam_request_sync_wait(struct ssam_request_sync *rqst)¶: 等待同步请求完成。

参数

struct ssam_request_sync *rqst: 要等待的请求。

描述

等待同步请求完成并释放。此函数终止后，可以保证该请求已离开传输系统。成功提交请求后，必须在访问请求的响应、释放请求或释放与请求关联的任何缓冲区之前调用此函数。

如果尚未提交请求，则不得调用此函数，并且如果后续请求提交在这种情况下失败，可能会导致死锁/无限等待，因为完成对象永远不会触发。

返回值

返回给定请求的状态，该状态在数据包完成后设置。成功时此值为零，失败时为负数。

ssam_request_do_sync_onstack¶

ssam_request_do_sync_onstack (ctrl, rqst, rsp, payload_len)

在堆栈上执行同步请求。

参数

ctrl: 通过其提交请求的控制器。
rqst: 请求规范。
rsp: 响应缓冲区。
payload_len: （最大）请求有效负载长度。

描述

在堆栈上分配具有指定有效负载长度的同步请求，通过提供的请求规范完全初始化它，提交它，最后等待其完成后再返回其状态。此帮助程序宏基本上在堆栈上分配请求消息缓冲区，然后调用 ssam_request_do_sync_with_buffer()。

请注意

payload_len 参数指定最大有效负载长度，用于缓冲区分配。实际有效负载长度可能更小。

返回值

返回请求的状态或设置期间的任何失败，即成功时为零，失败时为负值。

__ssam_retry¶

__ssam_retry (request, n, args...)

如果出现 I/O 错误或超时，则重试请求。

参数

request: 要执行的请求函数。必须返回一个整数。
n: 尝试次数。
args...: 请求函数的参数。

描述

执行给定的请求函数，即调用 request。如果请求返回 -EREMOTEIO（表示 I/O 错误）或 -ETIMEDOUT（请求或底层数据包超时），request 将再次重新执行，总共最多执行 n 次。

返回值

返回最后一次执行 request 的返回值。

ssam_retry¶

ssam_retry (request, args...)

如果发生 I/O 错误或超时，则重试请求，总共最多三次。

参数

request: 要执行的请求函数。必须返回一个整数。
args...: 请求函数的参数。

描述

执行给定的请求函数，即调用 request。如果请求返回 -EREMOTEIO（表示 I/O 错误）或 -ETIMEDOUT（请求或底层数据包超时），request 将再次重新执行，总共最多三次。

有关此目的的更通用的宏，请参阅 __ssam_retry()。

返回值

返回最后一次执行 request 的返回值。

struct ssam_request_spec¶: SAM 请求的蓝图规范。

定义:

struct ssam_request_spec {
    u8 target_category;
    u8 target_id;
    u8 command_id;
    u8 instance_id;
    u8 flags;
};

成员

target_category: 请求目标类别。请参见 enum ssam_ssh_tc。
target_id: 请求目标的 ID。
command_id: 请求的命令 ID。
instance_id: 请求目标的实例 ID。
flags: 请求的标志。请参见 enum ssam_request_flags。

描述

SAM 请求的蓝图规范。此结构描述了请求的唯一静态参数（即类型），而不指定任何特定于实例的数据（例如，有效负载）。它旨在用作通过 SSAM_DEFINE_SYNC_REQUEST_x() 宏系列定义简单请求函数的基础。

struct ssam_request_spec_md¶: 多设备 SAM 请求的蓝图规范。

定义:

struct ssam_request_spec_md {
    u8 target_category;
    u8 command_id;
    u8 flags;
};

成员

target_category: 请求目标类别。请参见 enum ssam_ssh_tc。
command_id: 请求的命令 ID。
flags: 请求的标志。请参见 enum ssam_request_flags。

描述

多设备 SAM 请求的蓝图规范，即适用于多个设备实例的请求，这些实例由其各自的目标 ID 和实例 ID 描述。此结构描述了请求的唯一静态参数（即类型），而不指定任何特定于实例的数据（例如，有效负载），也不指定任何特定于设备的 ID（即目标 ID 和实例 ID）。它旨在用作通过 SSAM_DEFINE_SYNC_REQUEST_MD_x() 和 SSAM_DEFINE_SYNC_REQUEST_CL_x() 宏系列定义简单多设备请求函数的基础。

SSAM_DEFINE_SYNC_REQUEST_N¶

SSAM_DEFINE_SYNC_REQUEST_N (name, spec...)

定义没有参数也没有返回值的同步 SAM 请求函数。

参数

name: 生成的函数的名称。
spec...: 定义请求的规范（struct ssam_request_spec）。

描述

定义一个函数，该函数执行由 spec 指定的同步 SAM 请求，该请求既没有参数也没有返回值。生成的函数负责设置请求结构和缓冲区分配，以及请求本身的执行，一旦请求完全完成就返回。所需的传输缓冲区将在堆栈上分配。

生成的函数定义为 static int name(struct ssam_controller *ctrl)，返回请求的状态，成功时为零，失败时为负数。ctrl 参数是通过其发送请求的控制器。

有关生成函数行为的更多详细信息，请参阅 ssam_request_do_sync_onstack()。

SSAM_DEFINE_SYNC_REQUEST_W¶

SSAM_DEFINE_SYNC_REQUEST_W (name, atype, spec...)

定义带有参数的同步 SAM 请求函数。

参数

name: 生成的函数的名称。
atype: 请求的参数的类型。
spec...: 定义请求的规范（struct ssam_request_spec）。

描述

定义一个函数，该函数执行由 spec 指定的同步 SAM 请求，该请求采用 atype 类型的参数，并且没有返回值。生成的函数负责设置请求结构、缓冲区分配以及请求本身的执行，一旦请求完全完成就返回。所需的传输缓冲区将在堆栈上分配。

生成的函数定义为 static int name(struct ssam_controller *ctrl, const atype *arg)，返回请求的状态，成功时为零，失败时为负数。ctrl 参数是通过其发送请求的控制器。请求参数通过 arg 指针指定。

有关生成函数行为的更多详细信息，请参阅 ssam_request_do_sync_onstack()。

SSAM_DEFINE_SYNC_REQUEST_R¶

SSAM_DEFINE_SYNC_REQUEST_R (name, rtype, spec...)

定义带有返回值的同步 SAM 请求函数。

参数

name: 生成的函数的名称。
rtype: 请求的返回值的类型。
spec...: 定义请求的规范（struct ssam_request_spec）。

描述

定义一个函数，该函数执行由 spec 指定的同步 SAM 请求，该请求不带参数，但具有 rtype 类型的返回值。生成的函数负责设置请求和响应结构、缓冲区分配以及请求本身的执行，一旦请求完全完成就返回。所需的传输缓冲区将在堆栈上分配。

生成的函数定义为 static int name(struct ssam_controller *ctrl, rtype *ret)，返回请求的状态，成功时为零，失败时为负数。ctrl 参数是通过其发送请求的控制器。请求的返回值写入到 ret 参数指向的内存中。

有关生成函数行为的更多详细信息，请参阅 ssam_request_do_sync_onstack()。

SSAM_DEFINE_SYNC_REQUEST_WR¶

SSAM_DEFINE_SYNC_REQUEST_WR (name, atype, rtype, spec...)

定义既带有参数又带有返回值的同步 SAM 请求函数。

参数

name: 生成的函数的名称。
atype: 请求的参数的类型。
rtype: 请求的返回值的类型。
spec...: 定义请求的规范（struct ssam_request_spec）。

描述

定义一个函数，该函数执行由 spec 指定的同步 SAM 请求，该请求采用 atype 类型的参数，并且具有 rtype 类型的返回值。生成的函数负责设置请求和响应结构、缓冲区分配以及请求本身的执行，一旦请求完全完成就返回。所需的传输缓冲区将在堆栈上分配。

生成的函数定义为 static int name(struct ssam_controller *ctrl, const atype *arg, rtype *ret)，返回请求的状态，成功时为零，失败时为负数。ctrl 参数是通过其发送请求的控制器。请求参数通过 arg 指针指定。请求的返回值写入到 ret 参数指向的内存中。

有关生成函数行为的更多详细信息，请参阅 ssam_request_do_sync_onstack()。

SSAM_DEFINE_SYNC_REQUEST_MD_N¶

SSAM_DEFINE_SYNC_REQUEST_MD_N (name, spec...)

定义没有参数也没有返回值的同步多设备 SAM 请求函数。

参数

name: 生成的函数的名称。
spec...: 定义请求的规范（struct ssam_request_spec_md）。

描述

定义一个函数，该函数执行由 spec 指定的同步 SAM 请求，该请求既没有参数也没有返回值。设备指定参数不是硬编码的，而是必须提供给函数。生成的函数负责设置请求结构、缓冲区分配以及请求本身的执行，一旦请求完全完成就返回。所需的传输缓冲区将在堆栈上分配。

生成的函数定义为 static int name(struct ssam_controller *ctrl, u8 tid, u8 iid)，返回请求的状态，成功时为零，失败时为负数。ctrl 参数是通过其发送请求的控制器，tid 是请求的目标 ID，iid 是实例 ID。

有关生成函数行为的更多详细信息，请参阅 ssam_request_do_sync_onstack()。

SSAM_DEFINE_SYNC_REQUEST_MD_W¶

SSAM_DEFINE_SYNC_REQUEST_MD_W (name, atype, spec...)

定义带有参数的同步多设备 SAM 请求函数。

参数

name: 生成的函数的名称。
atype: 请求的参数的类型。
spec...: 定义请求的规范（struct ssam_request_spec_md）。

描述

定义一个函数，该函数执行由 spec 指定的同步 SAM 请求，该请求采用 atype 类型的参数，并且没有返回值。设备指定参数不是硬编码的，而是必须提供给函数。生成的函数负责设置请求结构、缓冲区分配以及请求本身的执行，一旦请求完全完成就返回。所需的传输缓冲区将在堆栈上分配。

生成的函数定义为 static int name(struct ssam_controller *ctrl, u8 tid, u8 iid, const atype *arg)，返回请求的状态，成功时为零，失败时为负数。ctrl 参数是通过其发送请求的控制器，tid 是请求的目标 ID，iid 是实例 ID。请求参数通过 arg 指针指定。

有关生成函数行为的更多详细信息，请参阅 ssam_request_do_sync_onstack()。

SSAM_DEFINE_SYNC_REQUEST_MD_R¶

SSAM_DEFINE_SYNC_REQUEST_MD_R (name, rtype, spec...)

定义带有返回值的同步多设备 SAM 请求函数。

参数

name: 生成的函数的名称。
rtype: 请求的返回值的类型。
spec...: 定义请求的规范（struct ssam_request_spec_md）。

描述

定义一个函数，该函数执行由 spec 指定的同步 SAM 请求，该请求不带参数，但具有 rtype 类型的返回值。设备指定参数不是硬编码的，而是必须提供给函数。生成的函数负责设置请求和响应结构、缓冲区分配以及请求本身的执行，一旦请求完全完成就返回。所需的传输缓冲区将在堆栈上分配。

生成的函数定义为 static int name(struct ssam_controller *ctrl, u8 tid, u8 iid, rtype *ret)，返回请求的状态，成功时为零，失败时为负数。ctrl 参数是通过其发送请求的控制器，tid 是请求的目标 ID，iid 是实例 ID。请求的返回值写入到 ret 参数指向的内存中。

有关生成函数行为的更多详细信息，请参阅 ssam_request_do_sync_onstack()。

SSAM_DEFINE_SYNC_REQUEST_MD_WR¶

SSAM_DEFINE_SYNC_REQUEST_MD_WR (name, atype, rtype, spec...)

定义既带有参数又带有返回值的同步多设备 SAM 请求函数。

参数

name: 生成的函数的名称。
atype: 请求的参数的类型。
rtype: 请求的返回值的类型。
spec...: 定义请求的规范（struct ssam_request_spec_md）。

描述

定义一个函数，该函数执行由 spec 指定的同步 SAM 请求，该请求采用 atype 类型的参数，并且具有 rtype 类型的返回值。设备指定参数不是硬编码的，而是必须提供给函数。生成的函数负责设置请求和响应结构、缓冲区分配以及请求本身的执行，一旦请求完全完成就返回。所需的传输缓冲区将在堆栈上分配。

生成的函数定义为 static int name(struct ssam_controller *ctrl, u8 tid, u8 iid, const atype *arg, rtype *ret)，返回请求的状态，成功时为零，失败时为负数。ctrl 参数是通过其发送请求的控制器，tid 是请求的目标 ID，iid 是实例 ID。请求参数通过 arg 指针指定。请求的返回值写入到 ret 参数指向的内存中。

有关生成函数行为的更多详细信息，请参阅 ssam_request_do_sync_onstack()。

enum ssam_notif_flags¶: SSAM 通知器回调函数中的返回值中使用的标志。

常量

SSAM_NOTIF_HANDLED

表示通知已处理。如果处理程序可以作用/已经作用于提供给它的事件，则处理程序应设置此标志。如果处理程序不是 intended 适用于所提供事件的主处理程序，则不应设置此标志。

如果在遍历通知程序链后，任何处理程序都未设置此标志，则会发出警告，指出该事件未处理。

SSAM_NOTIF_STOP

表示通知程序遍历应停止。如果从此通知程序回调返回此标志，则通知程序链遍历将立即停止，并且不会调用任何剩余的通知程序。当使用负错误值调用 ssam_notifier_from_errno() 时，将自动设置此标志。

struct ssam_notifier_block¶: SSAM 事件通知的基本通知程序块。

定义:

struct ssam_notifier_block {
    struct list_head node;
    ssam_notifier_fn_t fn;
    int priority;
};

成员

node: 通知程序列表的节点。
fn: 此通知程序的回调函数。此函数将各自的通知程序块和事件作为输入，并应返回一个通知程序值，该值可以从 enum ssam_notif_flags 中提供的标志获得，通过 ssam_notifier_from_errno() 从标准错误值转换，或两者的组合（例如，ssam_notifier_from_errno(e) | SSAM_NOTIF_HANDLED）。
priority: 优先级值，用于确定调用通知程序回调的顺序。值越高表示优先级越高，即关联的回调将比其他（较低优先级）回调更早执行。

u32 ssam_notifier_from_errno(int err)¶: 将标准错误值转换为通知程序返回值。

参数

int err: 要转换的错误代码，如果失败则必须为负数，如果成功则必须为零。

返回值

返回通过转换指定的 err 值获得的通知程序返回值。如果 err 为负数，则将设置 SSAM_NOTIF_STOP 标志，导致通知程序调用链遍历中止。

int ssam_notifier_to_errno(u32 ret)¶: 将通知程序返回值转换为标准错误值。

参数

u32 ret: 要转换的通知程序返回值。

返回值

返回 ret 中编码的负错误值，如果 ret 表示成功，则返回零。

struct ssam_event_registry¶: 用于启用事件的注册表规范。

定义:

struct ssam_event_registry {
    u8 target_category;
    u8 target_id;
    u8 cid_enable;
    u8 cid_disable;
};

成员

target_category: 事件注册表请求的目标类别。
target_id: 事件注册表请求的目标 ID。
cid_enable: 用于事件启用请求的命令 ID。
cid_disable: 用于事件禁用请求的命令 ID。

描述

此结构通过指定用于启用和禁用事件的请求的最小 SAM ID 集合来描述 SAM 事件注册表。要启用/禁用的单个事件本身通过 struct ssam_event_id 指定。

struct ssam_event_id¶: 用于启用事件的唯一事件 ID。

定义:

struct ssam_event_id {
    u8 target_category;
    u8 instance;
};

成员

target_category: 事件源的目标类别。
instance: 事件源的实例 ID。

描述

此结构通过外部提供的注册表指定要启用/禁用的事件。它不指定要使用的注册表本身，这通过 struct ssam_event_registry 完成。

enum ssam_event_mask¶: 指定如何将事件与通知程序匹配的标志。

常量

SSAM_EVENT_MASK_TARGET: 除了按目标类别过滤外，仅为目标 ID 与用于启用/禁用事件的注册表的 ID 匹配的事件执行通知程序回调。
SSAM_EVENT_MASK_INSTANCE: 除了按目标类别过滤外，仅为实例 ID 与启用事件时使用的实例 ID 匹配的事件执行通知程序回调。
SSAM_EVENT_MASK_NONE: 为具有匹配目标类别的任何事件运行回调。不执行任何其他过滤。
SSAM_EVENT_MASK_STRICT: 执行以上所有过滤。

SSAM_EVENT_REGISTRY¶

SSAM_EVENT_REGISTRY (tc, tid, cid_en, cid_dis)

定义新的事件注册表。

参数

tc: 事件注册表请求的目标类别。
tid: 事件注册表请求的目标 ID。
cid_en: 用于事件启用请求的命令 ID。
cid_dis: 用于事件禁用请求的命令 ID。

返回值

返回由给定参数指定的 struct ssam_event_registry。

enum ssam_event_notifier_flags¶: 事件通知程序的标志。

常量

SSAM_EVENT_NOTIFIER_OBSERVER: 相应的通知程序充当观察者。注册设置了此标志的通知程序不会尝试启用任何事件。同样，取消注册不会尝试禁用任何事件。请注意，带有此标志的通知程序甚至可能根本不对应于某个特定事件，仅对应于某个特定事件目标类别。事件匹配不会受此标志的影响。

struct ssam_event_notifier¶: SSAM 事件的通知程序块。

定义:

struct ssam_event_notifier {
    struct ssam_notifier_block base;
    struct {
        struct ssam_event_registry reg;
        struct ssam_event_id id;
        enum ssam_event_mask mask;
        u8 flags;
    } event;
    unsigned long flags;
};

成员

base: 具有回调函数和优先级的基本通知程序块。
event: 此块将接收通知的事件。
event.reg: 将通过其启用/禁用事件的注册表。
event.id: 指定事件的 ID。
event.mask: 确定如何将事件与通知程序匹配的标志。
event.flags: 用于启用事件的标志。
flags: 通知程序标志（请参阅 enum ssam_event_notifier_flags）。

int ssam_notifier_unregister(struct ssam_controller *ctrl, struct ssam_event_notifier *n)¶: 注销事件通知器。

参数

struct ssam_controller *ctrl: 已注册通知器的控制器。
struct ssam_event_notifier *n: 要注销的事件通知器。

描述

注销事件通知器。如果通知器未标记为观察者，则递减关联 SAM 事件的使用计数器。如果使用计数器达到零，则将禁用该事件。

返回值

成功时返回零，如果给定的通知器块尚未在控制器上注册，则返回 -ENOENT。如果给定的通知器块是与其特定事件关联的最后一个通知器块，则返回事件禁用 EC 命令的状态。

struct device *ssam_controller_device(struct ssam_controller *c)¶: 获取与此控制器关联的 struct device。

参数

struct ssam_controller *c: 要获取设备的控制器。

返回值

返回与此控制器关联的 struct device，提供其较低级别的传输。

struct ssam_controller *ssam_controller_get(struct ssam_controller *c)¶: 递增控制器的引用计数。

参数

struct ssam_controller *c: 控制器。

返回值

返回作为输入提供的控制器。

void ssam_controller_put(struct ssam_controller *c)¶: 递减控制器的引用计数。

参数

struct ssam_controller *c: 控制器。

void ssam_controller_statelock(struct ssam_controller *c)¶: 锁定控制器以防止状态转换。

参数

struct ssam_controller *c: 要锁定的控制器。

描述

锁定控制器以防止状态转换。持有此锁可保证控制器不会在状态之间转换，即，如果控制器处于“已启动”状态，则在获取此锁后，它将至少保持在此状态，直到释放该锁为止。

多个客户端可以同时持有此锁。换句话说：statelock 函数表示 r/w 信号量的读锁部分。导致控制器状态转换的操作必须在持有此 r/w 信号量的写锁部分时执行（有关此，请参见 ssam_controller_lock() 和 ssam_controller_unlock()）。

有关相应的解锁函数，请参见 ssam_controller_stateunlock()。

void ssam_controller_stateunlock(struct ssam_controller *c)¶: 解锁控制器状态转换。

参数

struct ssam_controller *c: 要解锁的控制器。

描述

有关相应的锁定函数，请参见 ssam_controller_statelock()。

ssize_t ssam_request_write_data(struct ssam_span *buf, struct ssam_controller *ctrl, const struct ssam_request *spec)¶: 构造 SAM 请求消息并将其写入缓冲区。

参数

struct ssam_span *buf: 要将数据写入的缓冲区。
struct ssam_controller *ctrl: 将通过其发送请求的控制器。
const struct ssam_request *spec: 请求数据和规范。

描述

构造 SAM/SSH 请求消息并将其写入提供的缓冲区。请求和传输计数器，特别是 RQID 和 SEQ，将在此调用中设置。这些计数器是从控制器获得的。因此，仅通过此处指定的控制器发送生成的消息才有效。

有关所需缓冲区大小的计算，请参阅 SSH_COMMAND_MESSAGE_LENGTH() 宏。

返回值

成功时返回缓冲区中使用的字节数。如果请求规范中提供的有效负载长度太大（大于 SSH_COMMAND_MAX_PAYLOAD_SIZE），或者如果提供的缓冲区太小，则返回 -EINVAL。

int ssam_request_sync_alloc(size_t payload_len, gfp_t flags, struct ssam_request_sync **rqst, struct ssam_span *buffer)¶: 分配一个同步请求。

参数

size_t payload_len: 请求有效负载的长度。
gfp_t flags: 用于分配的标志。
struct ssam_request_sync **rqst: 存储指向已分配请求的指针的位置。
struct ssam_span *buffer: 存储请求消息缓冲区的缓冲区描述符的位置。

描述

分配一个带有相应消息缓冲区的同步请求。在提交之前，仍然需要使用 ssam_request_sync_init() 初始化该请求，并且在填充消息缓冲区数据后，仍然必须通过 ssam_request_sync_set_data() 将其设置为返回的缓冲区（如果需要调整消息长度）。

使用后，应通过 ssam_request_sync_free() 释放该请求及其相应的消息缓冲区。不得单独释放缓冲区。

返回值

成功时返回零，如果无法分配请求，则返回 -ENOMEM。

void ssam_request_sync_free(struct ssam_request_sync *rqst)¶: 释放一个同步请求。

参数

struct ssam_request_sync *rqst: 要释放的请求。

描述

释放一个同步请求及其使用 ssam_request_sync_alloc() 分配的相应缓冲区。不要用于在堆栈上或通过任何其他函数分配的请求。

警告：调用者必须确保该请求不再使用。即，调用者必须确保它拥有对该请求的唯一引用，并且该请求当前未挂起。这意味着调用者要么从未提交该请求，请求提交失败，要么调用者已等到提交的请求通过 ssam_request_sync_wait() 完成。

int ssam_request_sync_init(struct ssam_request_sync *rqst, enum ssam_request_flags flags)¶: 初始化同步请求结构。

参数

struct ssam_request_sync *rqst: 要初始化的请求。
enum ssam_request_flags flags: 请求标志。

描述

初始化给定的请求结构。不初始化请求消息数据。在此调用之后，必须通过 ssam_request_sync_set_data() 显式执行此操作，并且必须通过 ssam_request_write_data() 写入实际消息数据。

返回值

成功时返回零，如果给定的标志无效，则返回 -EINVAL。

int ssam_request_sync_submit(struct ssam_controller *ctrl, struct ssam_request_sync *rqst)¶: 提交一个同步请求。

参数

struct ssam_controller *ctrl: 提交请求的控制器。
struct ssam_request_sync *rqst: 要提交的请求。

描述

提交一个同步请求。必须初始化并正确设置请求，包括响应缓冲区（如果不需要响应，则可以为 NULL）和命令消息数据。此函数不等待请求完成。

如果此函数成功，则必须使用 ssam_request_sync_wait() 来确保在可以访问响应数据和/或释放请求之前，请求已完成。如果失败，则可以立即释放该请求。

仅当控制器处于活动状态（即已初始化且未暂停）时，才能使用此函数。

int ssam_request_do_sync(struct ssam_controller *ctrl, const struct ssam_request *spec, struct ssam_response *rsp)¶: 执行一个同步请求。

参数

struct ssam_controller *ctrl: 将通过其提交请求的控制器。
const struct ssam_request *spec: 请求规范和有效负载。
struct ssam_response *rsp: 响应缓冲区。

描述

通过 ssam_request_sync_alloc() 在堆上分配一个带有其消息数据缓冲区的同步请求，通过提供的请求规范完全初始化它，提交它，并在释放它并返回其状态之前，最后等待其完成。

返回值

返回请求的状态或设置期间的任何故障。

int ssam_request_do_sync_with_buffer(struct ssam_controller *ctrl, const struct ssam_request *spec, struct ssam_response *rsp, struct ssam_span *buf)¶: 执行一个同步请求，并将提供的缓冲区用作消息缓冲区的后端。

参数

struct ssam_controller *ctrl: 将通过其提交请求的控制器。
const struct ssam_request *spec: 请求规范和有效负载。
struct ssam_response *rsp: 响应缓冲区。
struct ssam_span *buf: 请求消息数据的缓冲区。

描述

在堆栈上分配一个同步请求结构，使用提供的缓冲区作为消息数据缓冲区完全初始化它，提交它，然后在返回其状态之前等待其完成。可以使用 SSH_COMMAND_MESSAGE_LENGTH() 宏来计算所需的消息缓冲区大小。

此函数本质上与 ssam_request_do_sync() 相同，但它不是动态分配请求和消息数据缓冲区，而是使用提供的消息数据缓冲区并将（小）请求结构存储在堆上。

返回值

返回请求的状态或设置期间的任何故障。

int ssam_notifier_register(struct ssam_controller *ctrl, struct ssam_event_notifier *n)¶: 注册事件通知器。

参数

struct ssam_controller *ctrl: 要在其上注册通知器的控制器。
struct ssam_event_notifier *n: 要注册的事件通知器。

描述

注册事件通知器。如果通知器未标记为观察者，则递增关联 SAM 事件的使用计数器。如果事件未标记为观察者，并且当前未启用，则将在本次调用期间启用它。如果通知器被标记为观察者，则不会尝试启用任何事件，也不会修改任何引用计数。

标记为观察者的通知器不需要与一个特定的事件相关联，即，只要不执行任何事件匹配，则只需要设置事件目标类别。

返回值

成功时返回零，如果已为与注册的通知器块关联的事件 ID/类型存在 INT_MAX 个通知器，则返回 -ENOSPC，如果无法分配相应的事件条目，则返回 -ENOMEM。如果这是第一次为特定的关联事件注册通知器块，则返回事件启用 EC 命令的状态。

int __ssam_notifier_unregister(struct ssam_controller *ctrl, struct ssam_event_notifier *n, bool disable)¶: 注销事件通知器。

参数

struct ssam_controller *ctrl: 已注册通知器的控制器。
struct ssam_event_notifier *n: 要注销的事件通知器。
bool disable: 是否在 EC 上禁用相应的事件。

描述

注销事件通知器。如果通知器未标记为观察者，则递减关联 SAM 事件的使用计数器。如果使用计数器达到零并且 disable 等于 true，则将禁用该事件。

对于热插拔设备很有用，一旦设备已物理移除，通信可能会失败。在这种情况下，指定 disable 为 false 可避免与 EC 通信。

返回值

成功时返回零，如果给定的通知器块尚未在控制器上注册，则返回 -ENOENT。如果给定的通知器块是与其特定事件关联的最后一个通知器块，则返回事件禁用 EC 命令的状态。

int ssam_controller_event_enable(struct ssam_controller *ctrl, struct ssam_event_registry reg, struct ssam_event_id id, u8 flags)¶: 启用指定的事件。

参数

struct ssam_controller *ctrl: 要为其启用事件的控制器。
struct ssam_event_registry reg: 用于启用事件的事件注册表。
struct ssam_event_id id: 指定要启用的事件的事件 ID。
u8 flags: 用于启用事件的 SAM 事件标志。

描述

递增指定事件的事件引用计数。如果该事件之前未被启用，则将通过此调用启用它。

请注意

通常，对于启用/禁用事件，应优先使用带有非观察者通知器的 ssam_notifier_register()，因为这将保证在事件启用/禁用期间发生错误时能够正确排序和转发事件。

返回值

成功时返回零，如果指定事件的引用计数已达到其最大值，则返回 -ENOSPC，如果无法分配相应的事件条目，则返回 -ENOMEM。如果这是第一次启用此事件（即，此调用将引用计数从零递增到一），则返回事件启用 EC 命令的状态。

int ssam_controller_event_disable(struct ssam_controller *ctrl, struct ssam_event_registry reg, struct ssam_event_id id, u8 flags)¶: 禁用指定的事件。

参数

struct ssam_controller *ctrl: 要为其禁用事件的控制器。
struct ssam_event_registry reg: 用于禁用事件的事件注册表。
struct ssam_event_id id: 指定要禁用的事件的事件 ID。
u8 flags: 启用事件时使用的标志。

描述

递减指定事件的引用计数。如果引用计数达到零，则将禁用该事件。

请注意

通常，对于启用/禁用事件，应优先使用带有非观察者通知器的 ssam_notifier_register()/ssam_notifier_unregister()，因为这将保证在事件启用/禁用期间发生错误时能够正确排序和转发事件。

返回值

成功时返回零，如果给定的事件未在控制器上启用，则返回 -ENOENT。如果在调用期间事件的引用计数达到零，则返回事件禁用 EC 命令的状态。

struct ssam_controller *ssam_get_controller(void)¶: 获取对 SSAM 控制器的引用。

参数

void: 无参数

描述

返回对系统 SSAM 控制器的引用；如果不存在，尚未设置或已被注销，则返回 NULL。此函数自动递增控制器的引用计数，因此调用方必须确保在不再需要控制器时调用 ssam_controller_put()。

int ssam_client_link(struct ssam_controller *c, struct device *client)¶: 将任意客户端设备链接到控制器。

参数

struct ssam_controller *c: 要链接到的控制器。
struct device *client: 客户端设备。

描述

通过在其作为消费者和控制器设备作为提供者之间创建设备链接，将任意客户端设备链接到控制器。此函数可用于非 SSAM 设备（或未注册为控制器下的子设备的 SSAM 设备），以保证只要客户端设备的驱动程序已绑定，控制器就有效，并且保证了正确的挂起和恢复顺序。

设备链接不必手动销毁。一旦客户端设备的驱动程序解除绑定，它就会自动删除。

返回值

成功时返回零，如果控制器未准备好或即将被删除，则返回 -ENODEV，如果由于其他原因无法创建设备链接，则返回 -ENOMEM。

struct ssam_controller *ssam_client_bind(struct device *client)¶: 将任意客户端设备绑定到控制器。

参数

struct device *client: 客户端设备。

描述

通过在其作为消费者和主控制器设备作为提供者之间创建设备链接，将任意客户端设备链接到控制器。此函数可用于非 SSAM 设备，以保证只要客户端设备的驱动程序已绑定，由此函数返回的控制器就有效，并且保证了正确的挂起和恢复顺序。

此函数基本上与 ssam_client_link() 相同，除了它首先获取主控制器引用，然后创建链接，最后返回此引用。请注意，此函数不会递增控制器的引用计数，因为由于链接，只要客户端设备的驱动程序已绑定，就可以保证控制器的生命周期。

如果不首先通过 ssam_controller_get() 递增控制器的引用计数，则使用此方法获得的控制器引用在驱动程序绑定到调用此函数时所绑定的客户端设备之外无效。即使这样做之后，也必须注意，只有当控制器处于活动状态且未挂起时，才能提交请求和（取消）注册通知器。换句话说：设备链接仅在客户端驱动程序绑定时存在，并且此链接强制执行的任何保证（例如，活动控制器状态）只能在此链接存在时依赖，并且之后可能需要以其他方式强制执行。

创建的设备链接不必手动销毁。一旦客户端设备的驱动程序解除绑定，它就会自动删除。

返回值

成功时返回控制器，如果控制器不存在、未准备好或即将被删除，则返回带有 -ENODEV 的错误指针，如果由于其他原因无法创建设备链接，则返回 -ENOMEM。

客户端总线和客户端设备 API ¶

enum ssam_device_domain¶: SAM 设备域。

常量

SSAM_DOMAIN_VIRTUAL: 虚拟设备。
SSAM_DOMAIN_SERIALHUB: 通过 Surface Serial Hub 连接的物理设备。

enum ssam_virtual_tc¶: 虚拟 SAM 域的目标类别。

常量

SSAM_VIRTUAL_TC_HUB: 设备集线器类别。

struct ssam_device_uid¶: SSAM 设备的唯一标识符。

定义:

struct ssam_device_uid {
    u8 domain;
    u8 category;
    u8 target;
    u8 instance;
    u8 function;
};

成员

domain: 设备的域。
category: 设备的目标类别。
target: 设备的目标 ID。
instance: 设备的实例 ID。
function: 设备的子功能。此字段可用于将单个 SAM 设备拆分为多个虚拟子设备，以分离该设备的不同功能，并允许每个功能使用一个驱动程序。

SSAM_DEVICE¶

SSAM_DEVICE (d, cat, tid, iid, fun)

使用给定的参数初始化 struct ssam_device_id。

参数

d: 设备的域。
cat: 设备的目标类别。
tid: 设备的目标 ID。
iid: 设备的实例 ID。
fun: 设备的子功能。

描述

使用给定的参数初始化 struct ssam_device_id。有关参数的详细信息，请参阅 struct ssam_device_uid。特殊值 SSAM_SSH_TID_ANY、SSAM_SSH_IID_ANY 和 SSAM_SSH_FUN_ANY 可用于指定匹配应分别忽略目标 ID、实例 ID 和/或子功能。此宏基于给定的参数初始化 match_flags 字段。

请注意

参数 d 和 cat 必须是有效的 u8 值，参数 tid、iid 和 fun 必须是有效的 u8 值或 SSAM_SSH_TID_ANY、SSAM_SSH_IID_ANY 或 SSAM_SSH_FUN_ANY。不允许使用其他非 u8 值。

SSAM_VDEV¶

SSAM_VDEV (cat, tid, iid, fun)

使用给定的参数将 struct ssam_device_id 初始化为虚拟设备。

参数

cat: 设备的目标类别。
tid: 设备的目标 ID。
iid: 设备的实例 ID。
fun: 设备的子功能。

描述

使用虚拟域中给定的参数初始化 struct ssam_device_id。有关参数的详细信息，请参阅 struct ssam_device_uid。特殊值 SSAM_SSH_TID_ANY、SSAM_SSH_IID_ANY 和 SSAM_SSH_FUN_ANY 可用于指定匹配应分别忽略目标 ID、实例 ID 和/或子功能。此宏基于给定的参数初始化 match_flags 字段。

请注意

参数 cat 必须是有效的 u8 值，参数 tid、iid 和 fun 必须是有效的 u8 值或 SSAM_SSH_TID_ANY、SSAM_SSH_IID_ANY 或 SSAM_SSH_FUN_ANY。不允许使用其他非 u8 值。

SSAM_SDEV¶

SSAM_SDEV (cat, tid, iid, fun)

使用给定的参数将 struct ssam_device_id 初始化为物理 SSH 设备。

参数

cat: 设备的目标类别。
tid: 设备的目标 ID。
iid: 设备的实例 ID。
fun: 设备的子功能。

描述

使用 SSH 域中给定的参数初始化 struct ssam_device_id。有关参数的详细信息，请参阅 struct ssam_device_uid。特殊值 SSAM_SSH_TID_ANY、SSAM_SSH_IID_ANY 和 SSAM_SSH_FUN_ANY 可用于指定匹配应分别忽略目标 ID、实例 ID 和/或子功能。此宏基于给定的参数初始化 match_flags 字段。

请注意

参数 cat 必须是有效的 u8 值，参数 tid、iid 和 fun 必须是有效的 u8 值或 SSAM_SSH_TID_ANY、SSAM_SSH_IID_ANY 或 SSAM_SSH_FUN_ANY。不允许使用其他非 u8 值。

struct ssam_device¶: SSAM 客户端设备。

定义:

struct ssam_device {
    struct device dev;
    struct ssam_controller *ctrl;
    struct ssam_device_uid uid;
    unsigned long flags;
};

成员

dev: 设备的驱动程序模型表示。
ctrl: SSAM 控制器管理此设备。
uid: 标识设备的 UID。
flags: 设备状态标志，请参阅 enum ssam_device_flags。

struct ssam_device_driver¶: SSAM 客户端设备驱动程序。

定义:

struct ssam_device_driver {
    struct device_driver driver;
    const struct ssam_device_id *match_table;
    int (*probe)(struct ssam_device *sdev);
    void (*remove)(struct ssam_device *sdev);
};

成员

driver: 基本驱动程序模型结构。
match_table: 匹配表，指定驱动程序应绑定到哪些设备。
probe: 当驱动程序绑定到设备时调用。
remove: 当驱动程序从设备解除绑定时调用。

bool is_ssam_device(struct device *d)¶: 检查给定的设备是否为 SSAM 客户端设备。

参数

struct device *d: 要测试其类型的设备。

返回值

如果指定的设备类型为 struct ssam_device，即设备类型指向 ssam_device_type，则返回 true，否则返回 false。

to_ssam_device¶

to_ssam_device (d)

将给定的设备强制转换为 SSAM 客户端设备。

参数

d: 要强制转换的设备。

描述

将给定的 struct device 强制转换为 struct ssam_device。调用方必须确保给定的设备实际上包含在 struct ssam_device 中，例如，通过调用 is_ssam_device()。

返回值

返回指向包装给定设备 d 的 struct ssam_device 的指针。

to_ssam_device_driver¶

to_ssam_device_driver (d)

将给定的设备驱动程序强制转换为 SSAM 客户端设备驱动程序。

参数

d: 要强制转换的驱动程序。

描述

将给定的 struct device_driver 强制转换为 struct ssam_device_driver。调用方必须确保给定的驱动程序实际上包含在 struct ssam_device_driver 中。

返回值

返回指向包装给定设备驱动程序 d 的 struct ssam_device_driver 的指针。

void ssam_device_mark_hot_removed(struct ssam_device *sdev)¶: 将给定的设备标记为热移除。

参数

struct ssam_device *sdev: 要标记为热移除的设备。

描述

将设备标记为已热移除。这会向使用该设备的驱动程序发出信号，表明应避免与该设备通信，并且可能会导致超时。

bool ssam_device_is_hot_removed(struct ssam_device *sdev)¶: 检查给定的设备是否已热移除。

参数

struct ssam_device *sdev: 要检查的设备。

描述

检查给定的设备是否已被标记为热移除。详情请参阅 ssam_device_mark_hot_removed()。

返回值

如果设备已被标记为热移除，则返回 true。

struct ssam_device *ssam_device_get(struct ssam_device *sdev)¶: 增加 SSAM 客户端设备的引用计数。

参数

struct ssam_device *sdev: 要增加引用计数的设备。

描述

通过使用 get_device() 增加所包含的 struct device 的引用计数，从而增加给定 SSAM 客户端设备的引用计数。

此函数的对应部分请参阅 ssam_device_put()。

返回值

返回作为输入提供的设备。

void ssam_device_put(struct ssam_device *sdev)¶: 减少 SSAM 客户端设备的引用计数。

参数

struct ssam_device *sdev: 要减少引用计数的设备。

描述

通过使用 put_device() 减少所包含的 struct device 的引用计数，从而减少给定 SSAM 客户端设备的引用计数。

此函数的对应部分请参阅 ssam_device_get()。

void *ssam_device_get_drvdata(struct ssam_device *sdev)¶: 获取 SSAM 客户端设备的驱动程序数据。

参数

struct ssam_device *sdev: 要从中获取驱动程序数据的设备。

返回值

返回给定设备的驱动程序数据，该数据之前通过 ssam_device_set_drvdata() 设置。

void ssam_device_set_drvdata(struct ssam_device *sdev, void *data)¶: 设置 SSAM 客户端设备的驱动程序数据。

参数

struct ssam_device *sdev: 要设置驱动程序数据的设备。
void *data: 要将设备的驱动程序数据指针设置为的数据。

ssam_device_driver_register¶

ssam_device_driver_register (drv)

注册 SSAM 客户端设备驱动程序。

参数

drv: 要注册的驱动程序。

module_ssam_device_driver¶

module_ssam_device_driver (drv)

用于 SSAM 设备驱动程序注册的辅助宏。

参数

drv: 由此模块管理的驱动程序。

描述

辅助宏，用于通过 module_init() 和 module_exit() 注册 SSAM 设备驱动程序。此宏每个模块只能使用一次，并取代上述定义。

int ssam_register_clients(struct device *dev, struct ssam_controller *ctrl)¶: 注册在给定父设备下定义的所有客户端设备。

参数

struct device *dev: 应在其下注册客户端的父设备。
struct ssam_controller *ctrl: 客户端应注册到的控制器。

描述

注册所有已通过固件节点定义为给定（父）设备的子设备的客户端。各个子固件节点将与相应创建的子设备相关联。

给定的控制器将用于实例化新设备。详情请参阅 ssam_device_add()。

返回值

成功时返回零，失败时返回非零值。

int ssam_device_register_clients(struct ssam_device *sdev)¶: 注册在给定 SSAM 父设备下定义的所有客户端设备。

参数

struct ssam_device *sdev: 应在其下注册客户端的父设备。

描述

注册所有已通过固件节点定义为给定（父）设备的子设备的客户端。各个子固件节点将与相应创建的子设备相关联。

父设备使用的控制器将用于实例化新设备。详情请参阅 ssam_device_add()。

返回值

成功时返回零，失败时返回非零值。

SSAM_DEFINE_SYNC_REQUEST_CL_N¶

SSAM_DEFINE_SYNC_REQUEST_CL_N (name, spec...)

定义不带参数且不带返回值的同步客户端设备 SAM 请求函数。

参数

name: 生成的函数的名称。
spec...: 定义请求的规范（struct ssam_request_spec_md）。

描述

定义一个函数，用于执行由 spec 指定的同步 SAM 请求，该请求不带参数且不带返回值。设备指定参数不是硬编码的，而是通过客户端设备提供的，特别是它的 UID，该 UID 在调用此函数时提供。生成的函数负责设置请求结构、缓冲区分配以及请求本身的执行，并在请求完全完成后返回。所需的传输缓冲区将在堆栈上分配。

生成的函数定义为 static int name(struct ssam_device *sdev)，返回请求的状态，成功时为零，失败时为负数。 sdev 参数同时指定请求的目标设备，并通过关联指定发送请求的控制器。

有关生成函数行为的更多详细信息，请参阅 ssam_request_do_sync_onstack()。

SSAM_DEFINE_SYNC_REQUEST_CL_W¶

SSAM_DEFINE_SYNC_REQUEST_CL_W (name, atype, spec...)

定义带参数的同步客户端设备 SAM 请求函数。

参数

name: 生成的函数的名称。
atype: 请求的参数的类型。
spec...: 定义请求的规范（struct ssam_request_spec_md）。

描述

定义一个函数，用于执行由 spec 指定的同步 SAM 请求，该请求采用 atype 类型的参数且不带返回值。设备指定参数不是硬编码的，而是通过客户端设备提供的，特别是它的 UID，该 UID 在调用此函数时提供。生成的函数负责设置请求结构、缓冲区分配以及请求本身的执行，并在请求完全完成后返回。所需的传输缓冲区将在堆栈上分配。

生成的函数定义为 static int name(struct ssam_device *sdev, const atype *arg)，返回请求的状态，成功时为零，失败时为负数。 sdev 参数同时指定请求的目标设备，并通过关联指定发送请求的控制器。请求的参数通过 arg 指针指定。

有关生成函数行为的更多详细信息，请参阅 ssam_request_do_sync_onstack()。

SSAM_DEFINE_SYNC_REQUEST_CL_R¶

SSAM_DEFINE_SYNC_REQUEST_CL_R (name, rtype, spec...)

定义带返回值的同步客户端设备 SAM 请求函数。

参数

name: 生成的函数的名称。
rtype: 请求的返回值的类型。
spec...: 定义请求的规范（struct ssam_request_spec_md）。

描述

定义一个函数，用于执行由 spec 指定的同步 SAM 请求，该请求不带参数但具有 rtype 类型的返回值。设备指定参数不是硬编码的，而是通过客户端设备提供的，特别是它的 UID，该 UID 在调用此函数时提供。生成的函数负责设置请求结构、缓冲区分配以及请求本身的执行，并在请求完全完成后返回。所需的传输缓冲区将在堆栈上分配。

生成的函数定义为 static int name(struct ssam_device *sdev, rtype *ret)，返回请求的状态，成功时为零，失败时为负数。 sdev 参数同时指定请求的目标设备，并通过关联指定发送请求的控制器。请求的返回值写入到 ret 参数指向的内存中。

有关生成函数行为的更多详细信息，请参阅 ssam_request_do_sync_onstack()。

SSAM_DEFINE_SYNC_REQUEST_CL_WR¶

SSAM_DEFINE_SYNC_REQUEST_CL_WR (name, atype, rtype, spec...)

定义带参数和返回值的同步客户端设备 SAM 请求函数。

参数

name: 生成的函数的名称。
atype: 请求的参数的类型。
rtype: 请求的返回值的类型。
spec...: 定义请求的规范（struct ssam_request_spec_md）。

描述

定义一个函数，用于执行由 spec 指定的同步 SAM 请求，该请求采用 atype 类型的参数且具有 rtype 类型的返回值。设备指定参数不是硬编码的，而是通过客户端设备提供的，特别是它的 UID，该 UID 在调用此函数时提供。生成的函数负责设置请求结构、缓冲区分配以及请求本身的执行，并在请求完全完成后返回。所需的传输缓冲区将在堆栈上分配。

生成的函数定义为 static int name(struct ssam_device *sdev, const atype *arg, rtype *ret)，返回请求的状态，成功时为零，失败时为负数。 sdev 参数同时指定请求的目标设备，并通过关联指定发送请求的控制器。请求的参数通过 arg 指针指定。请求的返回值写入到 ret 参数指向的内存中。

有关生成函数行为的更多详细信息，请参阅 ssam_request_do_sync_onstack()。

int ssam_device_notifier_register(struct ssam_device *sdev, struct ssam_event_notifier *n)¶: 为指定的客户端设备注册事件通知程序。

参数

struct ssam_device *sdev: 通知程序应注册到的设备。
struct ssam_event_notifier *n: 要注册的事件通知器。

描述

注册事件通知器。如果通知器未标记为观察者，则递增关联 SAM 事件的使用计数器。如果事件未标记为观察者，并且当前未启用，则将在本次调用期间启用它。如果通知器被标记为观察者，则不会尝试启用任何事件，也不会修改任何引用计数。

标记为观察者的通知器不需要与一个特定的事件相关联，即，只要不执行任何事件匹配，则只需要设置事件目标类别。

返回值

成功时返回零，如果与注册的通知程序块关联的事件 ID/类型已经有 INT_MAX 个通知程序，则返回 -ENOSPC，如果无法分配相应的事件条目，则返回 -ENOMEM，如果设备被标记为热移除，则返回 -ENODEV。如果这是第一次为特定关联的事件注册通知程序块，则返回事件启用 EC 命令的状态。

int ssam_device_notifier_unregister(struct ssam_device *sdev, struct ssam_event_notifier *n)¶: 取消注册指定客户端设备的事件通知程序。

参数

struct ssam_device *sdev: 通知程序已注册到的设备。
struct ssam_event_notifier *n: 要注销的事件通知器。

描述

注销事件通知器。如果通知器未标记为观察者，则递减关联 SAM 事件的使用计数器。如果使用计数器达到零，则将禁用该事件。

如果设备已被标记为热移除，则不会在 EC 上禁用事件，因为在这些情况下，任何执行此操作的尝试都可能超时。

返回值

成功时返回零，如果给定的通知器块尚未在控制器上注册，则返回 -ENOENT。如果给定的通知器块是与其特定事件关联的最后一个通知器块，则返回事件禁用 EC 命令的状态。

struct ssam_device *ssam_device_alloc(struct ssam_controller *ctrl, struct ssam_device_uid uid)¶: 分配并初始化 SSAM 客户端设备。

参数

struct ssam_controller *ctrl: 应在其下添加设备的控制器。
struct ssam_device_uid uid: 要添加的设备的 UID。

描述

分配并初始化新的客户端设备。设备的父设备将设置为控制器设备，名称将基于 UID 设置。请注意，仍然必须通过 ssam_device_add() 添加该设备。有关更多详细信息，请参阅该函数。

返回值

返回新分配和初始化的 SSAM 客户端设备，如果无法分配，则返回 NULL。

int ssam_device_add(struct ssam_device *sdev)¶: 添加 SSAM 客户端设备。

参数

struct ssam_device *sdev: 要添加的 SSAM 客户端设备。

描述

必须保证添加的客户端设备始终具有有效的且处于活动状态的控制器。因此，如果设备的控制器尚未初始化、已挂起或已关闭，则此函数将失败并返回 -ENODEV。

此函数的调用方应确保在控制器关闭之前发出对 ssam_device_remove() 的相应调用。如果添加的设备是控制器设备的直接子设备（默认），则会在控制器关闭时自动删除该设备。

默认情况下，控制器设备将成为新创建的客户端设备的父设备。可以在调用 ssam_device_add 之前更改父设备，但必须注意 a) 保证正确的挂起/恢复顺序，并且 b) 客户端设备的生存期不会超过控制器，即在关闭控制器之前删除设备。如果必须手动强制执行这些保证，请参阅 ssam_client_link() 和 ssam_client_bind() 函数，这些函数旨在为此目的设置设备链接。

返回值

成功时返回零，失败时返回负错误代码。

void ssam_device_remove(struct ssam_device *sdev)¶: 删除 SSAM 客户端设备。

参数

struct ssam_device *sdev: 要删除的设备。

描述

删除并取消注册提供的 SSAM 客户端设备。

const struct ssam_device_id *ssam_device_id_match(const struct ssam_device_id *table, const struct ssam_device_uid uid)¶: 查找给定 UID 的匹配 ID 表条目。

参数

const struct ssam_device_id *table: 要在其中搜索的表。
const struct ssam_device_uid uid: 要与各个表条目匹配的 UID。

描述

在提供的 ID 表中查找提供的设备 UID 的第一个匹配项并返回它。如果找不到匹配项，则返回 NULL。

const struct ssam_device_id *ssam_device_get_match(const struct ssam_device *dev)¶: 查找并返回已绑定驱动程序的 ID 表中与设备匹配的 ID。

参数

const struct ssam_device *dev: 用于获取匹配 ID 表项的设备。

描述

在当前绑定的驱动程序的 ID 表中查找设备的 UID 的第一个匹配项并返回它。如果设备没有绑定驱动程序，驱动程序没有 match_table（即它是 NULL），或者驱动程序的 match_table 中没有匹配项，则返回 NULL。

此函数本质上使用绑定设备驱动程序的 ID 表和设备的 UID 调用 ssam_device_id_match()。

返回值

返回设备驱动程序的匹配表中设备 UID 的第一个匹配项，如果找不到这样的匹配项，则返回 NULL。

const void *ssam_device_get_match_data(const struct ssam_device *dev)¶: 在绑定驱动程序的 ID 表中查找与设备匹配的 ID，并返回其 driver_data 成员。

参数

const struct ssam_device *dev: 用于获取匹配数据的设备。

描述

在相应驱动程序的 ID 表中查找设备 UID 的第一个匹配项，并返回其 driver_data。如果设备没有绑定驱动程序，驱动程序没有 match_table（即它是 NULL），驱动程序的 match_table 中没有匹配项，或者匹配项没有任何 driver_data，则返回 NULL。

此函数本质上调用 ssam_device_get_match()，如果找到任何匹配项，则返回其 struct ssam_device_id.driver_data 成员。

返回值

返回与设备驱动程序的匹配表中设备 UID 的第一个匹配项关联的驱动程序数据，如果找不到这样的匹配项，则返回 NULL。

int __ssam_device_driver_register(struct ssam_device_driver *sdrv, struct module *owner)¶: 注册 SSAM 客户端设备驱动程序。

参数

struct ssam_device_driver *sdrv: 要注册的驱动程序。
struct module *owner: 拥有提供的驱动程序的模块。

描述

请参阅 ssam_device_driver_register() 宏，了解从其所属模块内部注册驱动程序的常用方法。

void ssam_device_driver_unregister(struct ssam_device_driver *sdrv)¶: 注销 SSAM 设备驱动程序。

参数

struct ssam_device_driver *sdrv: 要注销的驱动程序。

int __ssam_register_clients(struct device *parent, struct ssam_controller *ctrl, struct fwnode_handle *node)¶: 将给定固件节点下定义的客户端设备注册为给定设备的子设备。

参数

struct device *parent: 应在其下注册客户端的父设备。
struct ssam_controller *ctrl: 客户端应注册到的控制器。
struct fwnode_handle *node: 保存要添加的设备定义的固件节点。

描述

将所有已定义为给定根固件节点的子节点的客户端注册为给定父设备的子设备。相应的子固件节点将与相应创建的子设备相关联。

给定的控制器将用于实例化新设备。详情请参阅 ssam_device_add()。

请注意，通常应首选使用 ssam_device_register_clients() 或 ssam_register_clients()，因为它们直接使用与给定设备关联的固件节点和/或控制器。此函数仅用于需要组合不同的设备规范（例如 ACPI 和固件节点）时（就像在设备注册表的平台中心中完成的那样）。

返回值

成功时返回零，失败时返回非零值。

void ssam_remove_clients(struct device *dev)¶: 删除注册为给定父设备下直接子设备的 SSAM 客户端设备。

参数

struct device *dev: 要删除所有直接客户端的（父）设备。

描述

删除注册为给定设备下直接子设备的所有 SSAM 客户端设备。请注意，这仅适用于设备的直接子设备。有关更多详细信息，请参阅 ssam_device_add()/ssam_device_remove()。

Linux 内核

目录

本页

客户端驱动程序 API 文档 ¶

串行集线器通信 ¶

控制器和核心接口 ¶

客户端总线和客户端设备 API ¶

客户端驱动程序 API 文档¶

串行集线器通信¶

控制器和核心接口¶

客户端总线和客户端设备 API¶

客户端驱动程序 API 文档 ¶

串行集线器通信 ¶

控制器和核心接口 ¶

客户端总线和客户端设备 API ¶