客户端驱动程序 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 Aggregator 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。用于数据包超时实现。在首次提交后持有挂起锁时才能访问。
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 传输数据包。
节点: 请求队列和待处理集合的列表节点。
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）。它旨在用作通过 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

表示通知已被处理。如果处理程序可以或已经对提供给它的事件采取了行动，则应由处理程序设置此标志。如果处理程序不是为提供的事件设计的主要处理程序，则不应设置此标志。

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

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;
};

成员

节点: 通知程序列表的节点。
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: 事件源的目标类别。
实例: 事件源的实例 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 函数代表读/写信号量的读锁部分。导致控制器状态转换的操作必须在持有此读/写信号量的写锁部分时执行（请参阅 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;
};

成员

域: 设备的域。
类别: 设备的目标类别。
目标: 设备的目标 ID。
实例: 设备的实例 ID。
功能: 设备的子功能。此字段可用于将单个 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，在调用此函数时提供。生成的函数负责设置请求结构、缓冲区分配以及请求本身的执行，在请求完全完成后返回。所需的传输缓冲区将在堆栈上分配。

生成的函数定义为 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，在调用此函数时提供。生成的函数负责设置请求结构、缓冲区分配以及请求本身的执行，在请求完全完成后返回。所需的传输缓冲区将在堆栈上分配。

生成的函数定义为 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，在调用此函数时提供。生成的函数负责设置请求结构、缓冲区分配以及请求本身的执行，在请求完全完成后返回。所需的传输缓冲区将在堆栈上分配。

生成的函数定义为 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，在调用此函数时提供。生成的函数负责设置请求结构、缓冲区分配以及请求本身的执行，在请求完全完成后返回。所需的传输缓冲区将在堆栈上分配。

生成的函数定义为 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 ¶