内部 API 文档 ¶

数据包传输层 ¶

struct sshp_buf¶: 用于 SSH 消息的解析器缓冲区。

定义:

struct sshp_buf {
    u8 *ptr;
    size_t len;
    size_t cap;
};

成员

ptr: 指向缓冲区开头的指针。
len: 缓冲区中使用的字节数。
cap: 缓冲区的最大容量。

void sshp_buf_init(struct sshp_buf *buf, u8 *ptr, size_t cap)¶: 初始化 SSH 解析器缓冲区。

参数

struct sshp_buf *buf: 要初始化的缓冲区。
u8 *ptr: 支持缓冲区的内存。
size_t cap: 支持缓冲区的内存长度，即其容量。

描述

使用给定的内存作为后备初始化缓冲区，并将其已用长度设置为零。

int sshp_buf_alloc(struct sshp_buf *buf, size_t cap, gfp_t flags)¶: 分配并初始化 SSH 解析器缓冲区。

参数

struct sshp_buf *buf: 要初始化/分配到的缓冲区。
size_t cap: 缓冲区的所需容量。
gfp_t flags: 用于分配内存的标志。

描述

分配 cap 字节，并使用分配的内存初始化提供的缓冲区结构。

返回

成功返回零，如果分配失败，则返回 -ENOMEM。

void sshp_buf_free(struct sshp_buf *buf)¶: 释放 SSH 解析器缓冲区。

参数

struct sshp_buf *buf: 要释放的缓冲区。

描述

通过释放支持它的内存，然后将其指针重置为 NULL 并将长度和容量重置为零来释放 SSH 解析器缓冲区。旨在释放先前使用 sshp_buf_alloc() 分配的缓冲区。

void sshp_buf_drop(struct sshp_buf *buf, size_t n)¶: 从缓冲区的开头删除数据。

参数

struct sshp_buf *buf: 要从中删除数据的缓冲区。
size_t n: 要删除的字节数。

描述

从缓冲区中删除前 n 个字节。将任何剩余数据重新对齐到缓冲区的开头。

size_t sshp_buf_read_from_fifo(struct sshp_buf *buf, struct kfifo *fifo)¶: 将数据从 fifo 传输到缓冲区。

参数

struct sshp_buf *buf: 要将数据写入的缓冲区。
struct kfifo *fifo: 要从中读取数据的 fifo。

描述

将 fifo 中包含的数据传输到缓冲区，并从 fifo 中删除它。此函数将尝试传输尽可能多的数据，这受到缓冲区中剩余空间或 fifo 中可用字节数的限制。

返回

返回传输的字节数。

void sshp_buf_span_from(struct sshp_buf *buf, size_t offset, struct ssam_span *span)¶: 从给定的缓冲区和偏移量初始化 span。

参数

struct sshp_buf *buf: 要从中创建 span 的缓冲区。
size_t offset: span 应在缓冲区中开始的偏移量。
struct ssam_span *span: 要初始化的 span (输出)。

描述

初始化提供的 span 以指向缓冲区中给定偏移量的内存，span 的长度由偏移量后缓冲区中使用的字节数（即偏移量后剩余的字节数）限制。

警告：此函数不验证 offset 是否小于或等于缓冲区中使用的字节数或缓冲区容量。这必须由调用者保证。

bool sshp_validate_crc(const struct ssam_span *src, const u8 *crc)¶: 验证原始消息数据中的 CRC。

参数

const struct ssam_span *src: 应该计算 CRC 的数据 span。
const u8 *crc: 指向预期 u16 CRC 值的指针。

描述

计算提供的数据 span (src) 的 CRC，将其与存储在给定地址 (crc) 的 CRC 进行比较，并返回此比较的结果，即如果相等则返回 true。此函数旨在对原始输入/消息数据运行。

返回

如果计算的 CRC 与存储的 CRC 匹配，则返回 true，否则返回 false。

bool sshp_starts_with_syn(const struct ssam_span *src)¶: 检查给定的数据是否以 SSH SYN 字节开头。

参数

const struct ssam_span *src: 要检查开头的数据 span。

bool sshp_find_syn(const struct ssam_span *src, struct ssam_span *rem)¶: 在给定的数据 span 中查找 SSH SYN 字节。

参数

const struct ssam_span *src: 要在其中搜索的数据 span。
struct ssam_span *rem: span (输出) 指示剩余数据，如果找到，则以 SSH SYN 字节开头。

描述

在给定的源 span 中搜索 SSH SYN 字节。如果找到，则将 rem span 设置为剩余数据，以第一个 SYN 字节开头，并以源 span 长度为上限，并返回 true。此函数不复制任何数据，而是仅设置指向各自起始地址和长度值的指针。

如果找不到 SSH SYN 字节，则将 rem span 设置为源 span 末尾的零长度 span，并返回 false。

如果在源 span 的末尾找到部分 SSH SYN 字节，则将 rem span 设置为覆盖这些部分 SYN 字节，以源 span 的末尾为上限，并返回 false。一旦更多数据可用，应再次运行此函数。

返回

如果找到完整的 SSH SYN 序列，则返回 true，否则返回 false。

int sshp_parse_frame(const struct device *dev, const struct ssam_span *source, struct ssh_frame **frame, struct ssam_span *payload, size_t maxlen)¶: 解析 SSH 帧。

参数

const struct device *dev: 用于日志记录的设备。
const struct ssam_span *source: 从中解析的源。
struct ssh_frame **frame: 解析的帧（输出）。
struct ssam_span *payload: 解析的有效负载（输出）。
size_t maxlen: 支持的最大消息长度。

描述

从给定的源解析和验证 SSH 帧，包括其有效负载。将提供的 frame 指针设置为帧的开头，并将帧有效负载的限制写入提供的 payload span 指针。

此函数不复制任何数据，而是仅验证消息数据并设置指针（和长度值）以指示各个部分。

如果找不到完整的 SSH 帧，则帧指针将设置为 NULL 指针，有效负载 span 将设置为 null span（起始指针 NULL，大小为零）。

返回

如果帧不完整，则返回零；如果消息的开头无效，则返回 -ENOMSG；如果任何（帧头或有效负载）CRC 无效，则返回 -EBADMSG；如果 SSH 消息大于 maxlen 参数中指定的最大消息长度，则返回 -EMSGSIZE。

int sshp_parse_command(const struct device *dev, const struct ssam_span *source, struct ssh_command **command, struct ssam_span *command_data)¶: 解析 SSH 命令帧有效负载。

参数

const struct device *dev: 用于日志记录的设备。
const struct ssam_span *source: 从中解析的源。
struct ssh_command **command: 解析的命令（输出）。
struct ssam_span *command_data: 解析的命令数据/有效负载（输出）。

描述

解析并验证 SSH 命令帧有效负载。将 command 指针设置为命令头，将 command_data span 设置为命令数据（即命令的有效负载）。如果命令没有任何关联的数据/有效负载，这将导致零长度 span。此函数不检查 frame-payload-type 字段，调用者应在调用此函数之前检查该字段。

source 参数应该是完整的帧有效负载，例如由 sshp_parse_frame() 命令返回的。

此函数不复制任何数据，而是仅验证帧有效负载数据并设置指针（和长度值）以指示各个部分。

返回

如果 source 不表示有效的命令类型帧有效负载，即太短，则返回零；如果 source 不表示有效的命令类型帧有效负载，即太短，则返回 -ENOMSG。

struct msgbuf¶: 用于构造 SSH 消息的缓冲区结构。

定义:

struct msgbuf {
    u8 *begin;
    u8 *end;
    u8 *ptr;
};

成员

begin: 指向已分配缓冲区空间开头的指针。
end: 指向已分配缓冲区空间末尾（最后一个元素之后的一个位置）的指针。
ptr: Pointer

void msgb_init(struct msgbuf *msgb, u8 *ptr, size_t cap)¶: 初始化给定的消息缓冲区结构。

参数

struct msgbuf *msgb: 要初始化的缓冲区结构
u8 *ptr: Pointer
size_t cap: Size

描述

使用提供的内存作为后备初始化给定的消息缓冲区结构。

size_t msgb_bytes_used(const struct msgbuf *msgb)¶: 返回缓冲区中当前使用的字节数。

参数

const struct msgbuf *msgb: 消息缓冲区。

void msgb_push_u16(struct msgbuf *msgb, u16 value)¶: 将 u16 值推送到缓冲区。

参数

struct msgbuf *msgb: 消息缓冲区。
u16 value: 要推送到缓冲区的值。

void msgb_push_syn(struct msgbuf *msgb)¶: 将 SSH SYN 字节推送到缓冲区。

参数

struct msgbuf *msgb: 消息缓冲区。

void msgb_push_buf(struct msgbuf *msgb, const u8 *buf, size_t len)¶: 将原始数据推送到缓冲区。

参数

struct msgbuf *msgb: 消息缓冲区。
const u8 *buf: 要推送到缓冲区的数据。
size_t len: 要推送到缓冲区的数据的长度。

void msgb_push_crc(struct msgbuf *msgb, const u8 *buf, size_t len)¶: 计算 CRC 并将其推送到缓冲区。

参数

struct msgbuf *msgb: 消息缓冲区。
const u8 *buf: Const
size_t len: The

void msgb_push_frame(struct msgbuf *msgb, u8 ty, u16 len, u8 seq)¶: 将 SSH 消息帧头推送到缓冲区。

参数

struct msgbuf *msgb: The
u8 ty: 帧的类型。
u16 len: 帧的有效负载的长度。
u8 seq: 帧/数据包的序列 ID。

void msgb_push_ack(struct msgbuf *msgb, u8 seq)¶: 将 SSH ACK 帧推送到缓冲区。

参数

struct msgbuf *msgb: The
u8 seq: 要 ACK 的帧/数据包的序列 ID。

void msgb_push_nak(struct msgbuf *msgb)¶: 将 SSH NAK 帧推送到缓冲区。

参数

struct msgbuf *msgb: The

void msgb_push_cmd(struct msgbuf *msgb, u8 seq, u16 rqid, const struct ssam_request *rqst)¶: 将带有有效负载的 SSH 命令帧推送到缓冲区。

参数

struct msgbuf *msgb: 消息缓冲区。
u8 seq: 帧/数据包的序列 ID (SEQ)。
u16 rqid: 帧中包含的请求的请求 ID (RQID)。
const struct ssam_request *rqst: 要包装在帧中的请求。

enum ssh_ptl_state_flags¶: struct ssh_ptl 的状态标志。

常量

SSH_PTL_SF_SHUTDOWN_BIT: 指示数据包传输层已关闭或正在关闭，不应接受任何新数据包/数据。

struct ssh_ptl_ops¶: 数据包传输层的回调操作。

定义:

struct ssh_ptl_ops {
    void (*data_received)(struct ssh_ptl *p, const struct ssam_span *data);
};

成员

data_received: 在收到数据包时调用的函数。接收数据包的数据包层和数据包的有效负载数据都提供给此函数。

struct ssh_ptl¶: SSH 数据包传输层。

定义:

struct ssh_ptl {
    struct serdev_device *serdev;
    unsigned long state;
    struct {
        spinlock_t lock;
        struct list_head head;
    } queue;
    struct {
        spinlock_t lock;
        struct list_head head;
        atomic_t count;
    } pending;
    struct {
        atomic_t running;
        struct task_struct *thread;
        struct completion thread_cplt_tx;
        struct completion thread_cplt_pkt;
        struct wait_queue_head packet_wq;
    } tx;
    struct {
        struct task_struct *thread;
        struct wait_queue_head wq;
        struct kfifo fifo;
        struct sshp_buf buf;
        struct {
            u16 seqs[8];
            u16 offset;
        } blocked;
    } rx;
    struct {
        spinlock_t lock;
        ktime_t timeout;
        ktime_t expires;
        struct delayed_work reaper;
    } rtx_timeout;
    struct ssh_ptl_ops ops;
};

成员

serdev: 提供底层数据传输的串行设备。
state: 传输层的状态（标志）。
queue: 数据包提交队列。
queue.lock: 用于修改数据包提交队列的锁。
queue.head: 数据包提交队列的列表头。
pending: 挂起数据包的集合/列表。
pending.lock: 用于修改挂起集合的锁。
pending.head: 待处理集合/列表的列表头。
pending.count: 当前待处理数据包的数量。
tx: 发送器子系统。
tx.running: 指示（期望的）发送器线程状态的标志。
tx.thread: 发送器线程。
tx.thread_cplt_tx: 用于等待传输的发送器线程的完成。
tx.thread_cplt_pkt: 用于等待数据包的发送器线程的完成。
tx.packet_wq: 数据包传输完成的等待队列头。
rx: 接收器子系统。
rx.thread: 接收器线程。
rx.wq: 接收器线程的等待队列头。
rx.fifo: 用于接收数据/将数据推送到接收器线程的缓冲区。
rx.buf: 用于评估接收器线程上的数据的缓冲区。
rx.blocked: 用于检测重传的最近/阻塞序列 ID 的列表。
rx.blocked.seqs: 阻塞序列 ID 的数组。
rx.blocked.offset: 指示应插入新 ID 的偏移量。
rtx_timeout: 重传超时子系统。
rtx_timeout.lock: 用于修改重传超时 Reaper 的锁。
rtx_timeout.timeout: 重传的超时时间间隔。
rtx_timeout.expires: 指定下次安排 Reaper 工作的时间。
rtx_timeout.reaper: 执行超时检查和后续操作的工作。
ops: 数据包层操作。

struct device *ssh_ptl_get_device(struct ssh_ptl *ptl)¶: 获取与数据包传输层关联的设备。

参数

struct ssh_ptl *ptl: 数据包传输层。

返回

返回给定的数据包传输层构建于其上的设备。

void ssh_ptl_tx_wakeup_transfer(struct ssh_ptl *ptl)¶: 唤醒用于传输的数据包发送器线程。

参数

struct ssh_ptl *ptl: 数据包传输层。

描述

唤醒数据包发送器线程，通知它底层传输有更多空间可用于传输数据。如果数据包传输层已关闭，则对此函数的调用将被忽略。

bool ssh_ptl_should_drop_ack_packet(void)¶: 错误注入挂钩以丢弃 ACK 数据包。

参数

void: 没有参数

描述

有助于测试 EC 的自动重传的检测和处理。具体来说，是 EC 认为未 ACK 的数据包，但驱动程序已经认为是 ACKed 的数据包（由于丢弃的 ACK）。在这种情况下，EC 会重新传输要 ACK 的数据包，驱动程序应将其检测为重复/已处理。请注意，驱动程序仍应为重新传输的数据包发送 ACK。

bool ssh_ptl_should_drop_nak_packet(void)¶: 错误注入挂钩以丢弃 NAK 数据包。

参数

void: 没有参数

描述

有助于测试/强制 EC 的自动（基于超时）重传。具体来说，数据包尚未完全到达驱动程序/具有有效的校验和。仅在与接收（注入的）错误数据结合使用时才有用。

bool ssh_ptl_should_drop_dsq_packet(void)¶: 错误注入挂钩以丢弃排序数据包。

参数

void: 没有参数

描述

有助于测试驱动程序的重传超时。如果在一定时间后未 ACK 数据包，驱动程序应重新传输该数据包，最多传输 SSH_PTL_MAX_PACKET_TRIES 中定义的次数。

int ssh_ptl_should_fail_write(void)¶: 错误注入挂钩以使 serdev_device_write() 失败。

参数

void: 没有参数

描述

用于模拟传输数据包时 serdev_device_write 中的错误的挂钩。

bool ssh_ptl_should_corrupt_tx_data(void)¶: 错误注入挂钩以模拟发送到 EC 的无效数据。

参数

void: 没有参数

描述

用于模拟从主机（驱动程序）发送到 EC 的损坏/无效数据的挂钩。导致数据包数据被主动损坏，方法是用预定义的值覆盖它，使其变为无效，导致 EC 以 NAK 数据包响应。有助于测试驱动程序接收到的 NAK 数据包的处理。

bool ssh_ptl_should_corrupt_rx_syn(void)¶: 错误注入挂钩以模拟 EC 发送的无效数据。

参数

void: 没有参数

描述

用于模拟无效 SYN 字节的挂钩，即无效的消息开头，并测试驱动程序中的处理方式。

bool ssh_ptl_should_corrupt_rx_data(void)¶: 错误注入挂钩以模拟 EC 发送的无效数据。

参数

void: 没有参数

描述

用于模拟消息帧的无效数据/校验和并测试驱动程序中的处理方式的挂钩。

void ssh_packet_init(struct ssh_packet *packet, unsigned long type, u8 priority, const struct ssh_packet_ops *ops)¶: 初始化 SSH 数据包。

参数

struct ssh_packet *packet: 要初始化的数据包。
unsigned long type: 数据包的类型标志。
u8 priority: 数据包的优先级。有关详细信息，请参阅 SSH_PACKET_PRIORITY()。
const struct ssh_packet_ops *ops: 数据包操作。

描述

初始化给定的 SSH 数据包。将传输缓冲区指针设置为 NULL，并将传输缓冲区长度设置为零。对于数据类型的数据包，必须在提交之前通过 ssh_packet_set_data() 单独设置此缓冲区，并且必须包含有效的 SSH 消息，即具有任何类型的可选负载的帧。

int ssh_ctrl_packet_cache_init(void)¶: 初始化控制数据包缓存。

参数

void: 没有参数

void ssh_ctrl_packet_cache_destroy(void)¶: 取消初始化控制数据包缓存。

参数

void: 没有参数

int ssh_ctrl_packet_alloc(struct ssh_packet **packet, struct ssam_span *buffer, gfp_t flags)¶: 从控制数据包缓存分配数据包。

参数

struct ssh_packet **packet: 应存储新分配的数据包的指针的位置。
struct ssam_span *buffer: 与此数据包对应的缓冲区。
gfp_t flags: 用于分配的标志。

描述

从控制数据包缓存分配数据包和相应的传输缓冲区。将数据包的缓冲区引用设置为已分配的缓冲区。必须通过 ssh_ctrl_packet_free() 释放该数据包，这还将释放相应的缓冲区。不得单独释放相应的缓冲区。旨在与 ssh_ptl_ctrl_packet_ops 作为数据包操作一起使用。

返回

成功时返回零，如果分配失败，则返回 -ENOMEM。

void ssh_ctrl_packet_free(struct ssh_packet *p)¶: 释放从控制数据包缓存分配的数据包。

参数

struct ssh_packet *p: 要释放的数据包。

void ssh_ptl_tx_wakeup_packet(struct ssh_ptl *ptl)¶: 唤醒用于新数据包的数据包发送器线程。

参数

struct ssh_ptl *ptl: 数据包传输层。

描述

唤醒数据包发送器线程，通知它新数据包已到达并准备好传输。如果数据包传输层已关闭，则对此函数的调用将被忽略。

int ssh_ptl_tx_start(struct ssh_ptl *ptl)¶: 启动数据包发送器线程。

参数

struct ssh_ptl *ptl: 数据包传输层。

返回

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

int ssh_ptl_tx_stop(struct ssh_ptl *ptl)¶: 停止数据包发送器线程。

参数

struct ssh_ptl *ptl: 数据包传输层。

返回

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

int ssh_ptl_submit(struct ssh_ptl *ptl, struct ssh_packet *p)¶: 将数据包提交到传输层。

参数

struct ssh_ptl *ptl: 要将数据包提交到的数据包传输层。
struct ssh_packet *p: 要提交的数据包。

描述

将新数据包提交到传输层，将其排队以进行发送。此函数不应用于重新提交。

返回

成功时返回零，如果数据包字段无效或数据包在提交之前已被取消，则返回 -EINVAL，如果数据包已被提交，则返回 -EALREADY，如果数据包传输层已关闭，则返回 -ESHUTDOWN。

void ssh_ptl_cancel(struct ssh_packet *p)¶: 取消数据包。

参数

struct ssh_packet *p: 要取消的数据包。

描述

取消数据包。无法保证何时将调用完成和释放回调。这可能在此函数执行期间发生，也可能在稍后的任何时间点发生。

请注意，如果另一个进程并发完成该数据包，则不能保证实际取消该数据包。此函数的唯一保证是数据包将在合理的时间范围内完成（成功、失败或取消）并从传输层释放。

可以在提交数据包之前调用，在这种情况下，任何稍后的数据包提交都会失败。

int ssh_ptl_rx_start(struct ssh_ptl *ptl)¶: 启动数据包传输层接收器线程。

参数

struct ssh_ptl *ptl: 数据包传输层。

返回

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

int ssh_ptl_rx_stop(struct ssh_ptl *ptl)¶: 停止数据包传输层接收器线程。

参数

struct ssh_ptl *ptl: 数据包传输层。

返回

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

ssize_t ssh_ptl_rx_rcvbuf(struct ssh_ptl *ptl, const u8 *buf, size_t n)¶: 将来自下层传输的数据推送到数据包层。

参数

struct ssh_ptl *ptl: 数据包传输层。
const u8 *buf: 指向要推送到层的数据的指针。
size_t n: 要推送到层的数据大小（以字节为单位）。

描述

将来自下层传输的数据推送到数据包层的接收器 FIFO 缓冲区，并通知接收器线程。一旦数据包层已关闭，对此函数的调用将被忽略。

返回

成功时返回传输的字节数（正数或零）。如果数据包层已关闭，则返回 -ESHUTDOWN。

void ssh_ptl_shutdown(struct ssh_ptl *ptl)¶: 关闭数据包传输层。

参数

struct ssh_ptl *ptl: 数据包传输层。

描述

关闭数据包传输层，删除和取消所有排队和待处理的数据包。由此操作取消的数据包将以 -ESHUTDOWN 作为状态完成。将停止接收器和发送器线程。

作为此函数的结果，传输层将被标记为已关闭。在传输层已关闭后提交数据包将失败并显示 -ESHUTDOWN。

int ssh_ptl_init(struct ssh_ptl *ptl, struct serdev_device *serdev, struct ssh_ptl_ops *ops)¶: 初始化数据包传输层。

参数

struct ssh_ptl *ptl: 要初始化的数据包传输层。
struct serdev_device *serdev: 底层串行设备，即下层传输。
struct ssh_ptl_ops *ops: 数据包层操作。

描述

初始化给定的数据包传输层。在初始化数据包层并设置了下层传输层之后，必须通过 ssh_ptl_tx_start() 和 ssh_ptl_rx_start() 单独启动发送器和接收器线程。

返回

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

void ssh_ptl_destroy(struct ssh_ptl *ptl)¶: 取消初始化数据包传输层。

参数

struct ssh_ptl *ptl: 要取消初始化的数据包传输层。

描述

取消初始化给定的数据包传输层并释放与之关联的资源。如果已启动接收器和/或发送器线程，则必须先通过 ssh_ptl_shutdown() 关闭该层，然后才能调用此函数。

请求传输层 ¶

enum ssh_rtl_state_flags¶: struct ssh_rtl 的状态标志。

常量

SSH_RTL_SF_SHUTDOWN_BIT: 指示请求传输层已关闭或正在关闭，并且不应接受任何新请求。

struct ssh_rtl_ops¶: 请求传输层的回调操作。

定义:

struct ssh_rtl_ops {
    void (*handle_event)(struct ssh_rtl *rtl, const struct ssh_command *cmd, const struct ssam_span *data);
};

成员

handle_event: 收到 SSH 事件时调用的函数。指定的函数将请求层、收到的命令结构和相应的负载作为参数。如果事件没有负载，则负载跨度为空（不是 NULL）。

struct ssh_rtl¶: SSH 请求传输层。

定义:

struct ssh_rtl {
    struct ssh_ptl ptl;
    unsigned long state;
    struct {
        spinlock_t lock;
        struct list_head head;
    } queue;
    struct {
        spinlock_t lock;
        struct list_head head;
        atomic_t count;
    } pending;
    struct {
        struct work_struct work;
    } tx;
    struct {
        spinlock_t lock;
        ktime_t timeout;
        ktime_t expires;
        struct delayed_work reaper;
    } rtx_timeout;
    struct ssh_rtl_ops ops;
};

成员

ptl: 底层数据包传输层。
state: 传输层的状态（标志）。
queue: 请求提交队列。
queue.lock: 用于修改请求提交队列的锁。
queue.head: 请求提交队列的列表头。
pending: 待处理请求的集合/列表。
pending.lock: 用于修改请求集的锁。
pending.head: 待处理集合/列表的列表头。
pending.count: 当前待处理的请求数。
tx: 发送器子系统。
tx.work: 发送器工作项。
rtx_timeout: 重传超时子系统。
rtx_timeout.lock: 用于修改重传超时 Reaper 的锁。
rtx_timeout.timeout: 重传的超时时间间隔。
rtx_timeout.expires: 指定下次安排 Reaper 工作的时间。
rtx_timeout.reaper: 执行超时检查和后续操作的工作。
ops: 请求层操作。

struct device *ssh_rtl_get_device(struct ssh_rtl *rtl)¶: 获取与请求传输层关联的设备。

参数

struct ssh_rtl *rtl: 请求传输层。

返回

返回给定的请求传输层构建于其上的设备。

struct ssh_rtl *ssh_request_rtl(struct ssh_request *rqst)¶: 获取与请求关联的请求传输层。

参数

struct ssh_request *rqst: 要获取请求传输层引用的请求。

返回

返回与给定的 SSH 请求关联的 struct ssh_rtl。

bool ssh_rtl_should_drop_response(void)¶: 错误注入挂钩以丢弃请求响应。

参数

void: 没有参数

描述

有助于通过丢弃对请求的响应来导致驱动程序中的请求传输超时。

int ssh_rtl_submit(struct ssh_rtl *rtl, struct ssh_request *rqst)¶: 将请求提交到传输层。

参数

struct ssh_rtl *rtl: 请求传输层。
struct ssh_request *rqst: 要提交的请求。

描述

将请求提交到传输层。未经重新初始化，单个请求可能不会多次提交。

返回

成功时返回零，如果请求类型无效或者请求在提交之前已被取消，则返回 -EINVAL，如果请求已被提交，则返回 -EALREADY，如果请求传输层已关闭，则返回 -ESHUTDOWN。

bool ssh_rtl_cancel(struct ssh_request *rqst, bool pending)¶: 取消请求。

参数

struct ssh_request *rqst: 要取消的请求。
bool pending: 是否也取消待处理的请求。

描述

取消给定的请求。如果 pending 为 false，则这不会取消待处理的请求，即已经提交到数据包层但尚未完成的请求。如果 pending 为 true，则无论给定请求处于何种状态，都会取消该请求。

如果已通过调用此函数取消请求，则请求的完成和释放回调都会在合理的时间范围内执行。这可能在此函数执行期间发生，但是，不能保证这一点。例如，当前正在传输的请求只有在传输完成后才会取消/完成，并且相应的回调将在发送器线程上执行，这可能在取消函数执行期间发生，也可能在取消函数执行后的一段时间发生。

返回

如果给定的请求已被此函数或在调用此函数之前取消或完成，则返回 true，否则返回 false。如果 pending 为 true，则此函数将始终返回 true。

int ssh_request_init(struct ssh_request *rqst, enum ssam_request_flags flags, const struct ssh_request_ops *ops)¶: 初始化 SSH 请求。

参数

struct ssh_request *rqst: 要初始化的请求。
enum ssam_request_flags flags: 请求标志，确定请求的类型。
const struct ssh_request_ops *ops: 请求操作。

描述

初始化给定的 SSH 请求和底层数据包。将消息缓冲区指针设置为 NULL，并将消息缓冲区长度设置为零。必须在提交之前通过 ssh_request_set_data() 单独设置此缓冲区，并且必须包含有效的 SSH 请求消息。

返回

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

int ssh_rtl_init(struct ssh_rtl *rtl, struct serdev_device *serdev, const struct ssh_rtl_ops *ops)¶: 初始化请求传输层。

参数

struct ssh_rtl *rtl: 要初始化的请求传输层。
struct serdev_device *serdev: 底层串行设备，即下层传输。
const struct ssh_rtl_ops *ops: 请求传输层操作。

描述

初始化给定的请求传输层和关联的数据包传输层。在请求层初始化并且底层串行设备层已设置完成后，必须通过 ssh_rtl_start() 单独启动发送器和接收器线程。

返回

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

void ssh_rtl_destroy(struct ssh_rtl *rtl)¶: 取消初始化请求传输层。

参数

struct ssh_rtl *rtl: 要取消初始化的请求传输层。

描述

取消初始化给定的请求传输层并释放与其关联的资源。如果接收器和/或发送器线程已启动，则必须先通过 ssh_rtl_shutdown() 关闭该层，然后才能调用此函数。

int ssh_rtl_start(struct ssh_rtl *rtl)¶: 启动请求发送器和接收器。

参数

struct ssh_rtl *rtl: 请求传输层。

返回

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

int ssh_rtl_flush(struct ssh_rtl *rtl, unsigned long timeout)¶: 刷新请求传输层。

参数

struct ssh_rtl *rtl: 请求传输层
unsigned long timeout: 刷新操作的超时时间（单位为 jiffies）

描述

将特殊的刷新请求排队并等待其完成。此请求将在所有其他当前排队和挂起的请求完成后完成。此请求不是提交正常的数据包，而是提交特殊的刷新包，这意味着完成时，也会刷新底层的数据包传输层。

刷新请求层可确保在此调用返回之前，所有先前提交的请求都已完全完成。此外，刷新会阻止所有稍后提交的请求的执行，直到刷新完成为止。

如果调用方确保在此函数调用之后不提交新请求，则保证在此调用返回时，请求传输层没有剩余请求。相同的保证不适用于数据包层，在此调用之后，控制数据包可能仍在排队。

返回

成功时返回零，如果刷新超时并由于超时而取消，则返回 -ETIMEDOUT，如果在此调用之前数据包和/或请求传输层已关闭，则返回 -ESHUTDOWN。如果底层数据包传输已中断，也可能返回 -EINTR。

void ssh_rtl_shutdown(struct ssh_rtl *rtl)¶: 关闭请求传输层。

参数

struct ssh_rtl *rtl: 请求传输层。

描述

关闭请求传输层，删除和取消所有排队和挂起的请求。通过此操作取消的请求将以 -ESHUTDOWN 作为状态完成。接收器和发送器线程将停止，底层数据包层将关闭。

此函数的结果是，传输层将被标记为已关闭。在传输层关闭后提交请求将失败，并显示 -ESHUTDOWN。

控制器 ¶

struct ssh_seq_counter¶: 用于 SSH 序列 ID 的安全计数器。

定义:

struct ssh_seq_counter {
    u8 value;
};

成员

值: 当前计数器值。

struct ssh_rqid_counter¶: 用于 SSH 请求 ID 的安全计数器。

定义:

struct ssh_rqid_counter {
    u16 value;
};

成员

值: 当前计数器值。

struct ssam_nf_head¶: SSAM 事件的通知器头部。

定义:

struct ssam_nf_head {
    struct srcu_struct srcu;
    struct list_head head;
};

成员

srcu: 用于同步的 SRCU 结构。
头部: 在此头部下注册的通知器块的列表头部。

struct ssam_nf¶: SSAM 事件的通知器回调和激活注册表。

定义:

struct ssam_nf {
    struct mutex lock;
    struct rb_root refcount;
    struct ssam_nf_head head[SSH_NUM_EVENTS];
};

成员

锁: 用于保护通知器块的（取消）注册的锁。注意：此锁不需要用于通知器调用，仅用于注册和取消注册。
引用计数: 用于引用计数启用事件/通知的 RB 树的根。
头部: 用于事件/通知回调的通知器头部列表。

struct ssam_event_item¶: 用于事件排队和完成的结构。

定义:

struct ssam_event_item {
    struct list_head node;
    u16 rqid;
    struct {
        void (*free)(struct ssam_event_item *event);
    } ops;
    struct ssam_event event;
};

成员

节点: 队列中的节点。
rqid: 事件的请求 ID。
ops: 实例特定函数。
ops.free: 用于释放此事件项的回调。
事件: 实际事件数据。

struct ssam_event_queue¶: 用于完成接收到的事件的队列。

定义:

struct ssam_event_queue {
    struct ssam_cplt *cplt;
    spinlock_t lock;
    struct list_head head;
    struct work_struct work;
};

成员

cplt: 对此队列处于活动状态的完成系统的引用。
锁: 队列上任何操作的锁。
头部: 队列的列表头部。
工作: 执行此队列的完成工作的 struct work_struct。

struct ssam_event_target¶: 单个 SSH 目标 ID 的队列集。

定义:

struct ssam_event_target {
    struct ssam_event_queue queue[SSH_NUM_EVENTS];
};

成员

queue: 队列数组，每个事件 ID 一个队列。

struct ssam_cplt¶: SSAM 事件/异步请求完成系统。

定义:

struct ssam_cplt {
    struct device *dev;
    struct workqueue_struct *wq;
    struct {
        struct ssam_event_target target[SSH_NUM_TARGETS];
        struct ssam_nf notif;
    } event;
};

成员

开发: 与此系统关联的设备。仅用于日志记录。
wq: 所有完成工作项都排队的 struct workqueue_struct。
事件: 事件完成管理。
event.target: struct ssam_event_target 数组，每个目标一个。
event.notif: 通知器回调和事件激活引用计数。

enum ssam_controller_state¶: struct ssam_controller 的状态值。

常量

SSAM_CONTROLLER_UNINITIALIZED: 控制器尚未初始化或已取消初始化。
SSAM_CONTROLLER_INITIALIZED: 控制器已初始化，但尚未启动。
SSAM_CONTROLLER_STARTED: 控制器已启动并可以使用。
SSAM_CONTROLLER_STOPPED: 控制器已停止。
SSAM_CONTROLLER_SUSPENDED: 控制器已挂起。

struct ssam_controller_caps¶: 控制器设备功能。

定义:

struct ssam_controller_caps {
    u32 ssh_power_profile;
    u32 ssh_buffer_size;
    u32 screen_on_sleep_idle_timeout;
    u32 screen_off_sleep_idle_timeout;
    u32 d3_closes_handle:1;
};

成员

ssh_power_profile: SSH 电源配置文件。
ssh_buffer_size: SSH 驱动程序 UART 缓冲区大小。
screen_on_sleep_idle_timeout: SAM UART 屏幕开启睡眠空闲超时。
screen_off_sleep_idle_timeout: SAM UART 屏幕关闭睡眠空闲超时。
d3_closes_handle: SAM 在 D3 中关闭 UART 句柄。

描述

在 ACPI 中找到的控制器和 SSH 设备功能。

struct ssam_controller¶: SSAM 控制器设备。

定义:

struct ssam_controller {
    struct kref kref;
    struct rw_semaphore lock;
    enum ssam_controller_state state;
    struct ssh_rtl rtl;
    struct ssam_cplt cplt;
    struct {
        struct ssh_seq_counter seq;
        struct ssh_rqid_counter rqid;
    } counter;
    struct {
        int num;
        bool wakeup_enabled;
    } irq;
    struct ssam_controller_caps caps;
};

成员

kref: 控制器的引用计数。
锁: 控制器的主要锁，用于保护状态更改。
state: 控制器状态。
rtl: 用于 SSH I/O 的请求传输层。
cplt: 用于 SSH/SSAM 事件和异步请求的完成系统。
计数器: 安全 SSH 消息 ID 计数器。
counter.seq: 序列 ID 计数器。
counter.rqid: 请求 ID 计数器。
irq: 唤醒 IRQ 资源。
irq.num: 唤醒 IRQ 编号。
irq.wakeup_enabled: 挂起期间是否启用通过 IRQ 唤醒。
caps: 控制器设备功能。

ssize_t ssam_controller_receive_buf(struct ssam_controller *ctrl, const u8 *buf, size_t n)¶: 向控制器提供输入数据。

参数

struct ssam_controller *ctrl: 控制器。
const u8 *buf: 输入缓冲区。
size_t n: 输入缓冲区中的字节数。

描述

提供要由控制器评估的输入数据，这些数据已通过底层传输接收。

返回

返回消耗的字节数，或者，如果控制器的包传输层已关闭，则返回 -ESHUTDOWN。

void ssam_controller_write_wakeup(struct ssam_controller *ctrl)¶: 通知控制器底层设备有可用于写入数据的空间。

参数

struct ssam_controller *ctrl: 控制器。

void ssh_seq_reset(struct ssh_seq_counter *c)¶: 重置/初始化序列 ID 计数器。

参数

struct ssh_seq_counter *c: 要重置的计数器。

u8 ssh_seq_next(struct ssh_seq_counter *c)¶: 获取下一个序列 ID。

参数

struct ssh_seq_counter *c: 提供序列 ID 的计数器。

返回

返回计数器的下一个序列 ID。

void ssh_rqid_reset(struct ssh_rqid_counter *c)¶: 重置/初始化请求 ID 计数器。

参数

struct ssh_rqid_counter *c: 要重置的计数器。

u16 ssh_rqid_next(struct ssh_rqid_counter *c)¶: 获取下一个请求 ID。

参数

struct ssh_rqid_counter *c: 提供请求 ID 的计数器。

返回

返回计数器的下一个请求 ID，跳过任何保留的请求 ID。

bool ssam_event_matches_notifier(const struct ssam_event_notifier *n, const struct ssam_event *event)¶: 测试事件是否与通知器匹配。

参数

const struct ssam_event_notifier *n: 要测试的事件通知器。
const struct ssam_event *event: 要测试的事件。

返回

如果给定的事件根据通知器的事件掩码中设置的规则与给定的通知器匹配，则返回 true，否则返回 false。

int ssam_nfblk_call_chain(struct ssam_nf_head *nh, struct ssam_event *event)¶: 调用给定链的事件通知器回调。

参数

struct ssam_nf_head *nh: 应为其调用通知器回调的通知器头部。
struct ssam_event *event: 提供给回调的事件数据。

描述

按优先级顺序调用所有已注册的通知器回调，直到没有剩余通知器或通知器返回设置了 SSAM_NOTIF_STOP 位的返回值。请注意，此位通过 ssam_notifier_from_errno() 在任何非零错误值上自动设置。

返回

返回通知器状态值，其中包含通知器状态位（SSAM_NOTIF_HANDLED 和 SSAM_NOTIF_STOP）以及从上次执行的通知器回调返回的潜在错误值。使用 ssam_notifier_to_errno() 将此值转换为原始错误值。

int ssam_nfblk_insert(struct ssam_nf_head *nh, struct ssam_notifier_block *nb)¶: 将新的通知器块插入到给定的通知器列表中。

参数

struct ssam_nf_head *nh: 应将块插入到的通知器头部。
struct ssam_notifier_block *nb: 要添加的通知器块。

注意

对于其他插入、查找和/或删除调用，调用方必须通过持有 struct ssam_nf.lock 来同步此函数。

返回

成功时返回零，如果已注册通知器块，则返回 -EEXIST。

bool ssam_nfblk_find(struct ssam_nf_head *nh, struct ssam_notifier_block *nb)¶: 检查通知器块是否已在给定的通知器头部上注册。列表。

参数

struct ssam_nf_head *nh: 要在其上搜索的通知器头部。
struct ssam_notifier_block *nb: 要搜索的通知器块。

注意

对于其他插入、查找和/或删除调用，调用方必须通过持有 struct ssam_nf.lock 来同步此函数。

返回

如果给定的通知器块已在给定的通知器头部上注册，则返回 true，否则返回 false。

void ssam_nfblk_remove(struct ssam_notifier_block *nb)¶: 从通知器列表中删除通知器块。

参数

struct ssam_notifier_block *nb: 要删除的通知器块。

注意

对于其他插入、查找和/或删除调用，调用方必须通过持有 struct ssam_nf.lock 来同步此函数。此外，调用方_必须_通过在离开临界区后使用 nh->srcu 调用 synchronize_srcu() 来确保 SRCU 同步，以确保不再使用已删除的通知器块。

int ssam_nf_head_init(struct ssam_nf_head *nh)¶: 初始化给定的通知器头部。

参数

struct ssam_nf_head *nh: 要初始化的通知器头部。

void ssam_nf_head_destroy(struct ssam_nf_head *nh)¶: 取消初始化给定的通知器头部。

参数

struct ssam_nf_head *nh: 要取消初始化的通知器头部。

struct ssam_nf_refcount_key¶: 用于事件激活引用计数的键。

定义:

struct ssam_nf_refcount_key {
    struct ssam_event_registry reg;
    struct ssam_event_id id;
};

成员

reg: 事件通过其启用/禁用的注册表。
id: 唯一描述事件的 ID。

struct ssam_nf_refcount_entry¶: 用于引用计数事件激活的 RB 树条目。

定义:

struct ssam_nf_refcount_entry {
    struct rb_node node;
    struct ssam_nf_refcount_key key;
    int refcount;
    u8 flags;
};

成员

节点: 节点
此条目在 rb 树中的节点。: key
引用计数: 引用计数
flags: 启用事件时使用的标志。

struct ssam_nf_refcount_entry *ssam_nf_refcount_inc(struct ssam_nf *nf, struct ssam_event_registry reg, struct ssam_event_id id)¶: 增加给定事件的引用计数/激活计数。

参数

struct ssam_nf *nf: 通知器系统引用。
struct ssam_event_registry reg: 用于启用/禁用事件的注册表。
struct ssam_event_id id: 事件 ID。

描述

增加与指定的事件类型/ID 关联的引用计数/激活计数，必要时为此事件 ID 分配新条目。新分配的条目的引用计数为 1。

注意

调用此函数时必须持有 nf->lock。

返回

成功时返回引用计数条目。如果已注册指定 ID 和类型的 INT_MAX 个事件，则返回带有 -ENOSPC 的错误指针，如果无法分配条目，则返回 -ENOMEM。

struct ssam_nf_refcount_entry *ssam_nf_refcount_dec(struct ssam_nf *nf, struct ssam_event_registry reg, struct ssam_event_id id)¶: 减少给定事件的引用/激活计数。

参数

struct ssam_nf *nf: 通知器系统引用。
struct ssam_event_registry reg: 用于启用/禁用事件的注册表。
struct ssam_event_id id: 事件 ID。

描述

减少指定事件的引用/激活计数，并返回其条目。如果返回的条目的引用计数为零，则调用者负责使用 kfree() 释放它。

注意

调用此函数时必须持有 nf->lock。

返回

成功时返回引用计数条目，如果未找到该条目，则返回 NULL。

void ssam_nf_refcount_dec_free(struct ssam_nf *nf, struct ssam_event_registry reg, struct ssam_event_id id)¶: 减少给定事件的引用/激活计数，如果引用计数达到零，则释放其条目。

参数

struct ssam_nf *nf: 通知器系统引用。
struct ssam_event_registry reg: 用于启用/禁用事件的注册表。
struct ssam_event_id id: 事件 ID。

描述

减少指定事件的引用/激活计数，如果达到零，则释放其条目。

注意

调用此函数时必须持有 nf->lock。

bool ssam_nf_refcount_empty(struct ssam_nf *nf)¶: 测试通知系统是否具有任何已启用/激活的事件。

参数

struct ssam_nf *nf: 通知系统。

void ssam_nf_call(struct ssam_nf *nf, struct device *dev, u16 rqid, struct ssam_event *event)¶: 为提供的事件调用通知回调。

参数

struct ssam_nf *nf: 通知器系统
struct device *dev: 关联的设备，仅用于日志记录。
u16 rqid: 事件的请求 ID。
struct ssam_event *event: 提供给回调的事件。

描述

按照其优先级顺序执行注册的回调，直到没有回调剩余或回调返回一个设置了 SSAM_NOTIF_STOP 位的返回值。请注意，当通过 ssam_notifier_from_errno() 将非零错误值转换为通知器值时，会自动设置此位。

另请注意，任何可以处理事件的回调都应返回一个设置了位 SSAM_NOTIF_HANDLED 的值，指示该事件不会未经处理/忽略。如果未注册的回调可以处理事件，此函数将发出警告。

如果回调失败，此函数将发出错误消息。

int ssam_nf_init(struct ssam_nf *nf)¶: 初始化通知器系统。

参数

struct ssam_nf *nf: 要初始化的通知器系统。

void ssam_nf_destroy(struct ssam_nf *nf)¶: 取消初始化通知器系统。

参数

struct ssam_nf *nf: 要取消初始化的通知器系统。

int ssam_event_item_cache_init(void)¶: 初始化事件项缓存。

参数

void: 没有参数

void ssam_event_item_cache_destroy(void)¶: 取消初始化事件项缓存。

参数

void: 没有参数

void ssam_event_item_free(struct ssam_event_item *item)¶: 释放提供的事件项。

参数

struct ssam_event_item *item: 要释放的事件项。

struct ssam_event_item *ssam_event_item_alloc(size_t len, gfp_t flags)¶: 分配具有给定有效负载大小的事件项。

参数

size_t len: 事件有效负载长度。
gfp_t flags: 用于分配的标志。

描述

分配具有给定有效负载大小的事件项，如果有效负载足够小（即小于 SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN），则优先从事件项缓存中分配。设置项操作和有效负载长度值。在此调用之后，不应覆盖项释放回调（ops.free）。

返回

返回新分配的事件项。

void ssam_event_queue_push(struct ssam_event_queue *q, struct ssam_event_item *item)¶: 将事件项推送到事件队列。

参数

struct ssam_event_queue *q: 事件队列。
struct ssam_event_item *item: 要添加的项。

struct ssam_event_item *ssam_event_queue_pop(struct ssam_event_queue *q)¶: 从事件队列中弹出下一个事件项。

参数

struct ssam_event_queue *q: 事件队列。

描述

从队列中返回并删除下一个事件项。如果剩余事件项，则返回 NULL。

bool ssam_event_queue_is_empty(struct ssam_event_queue *q)¶: 检查事件队列是否为空。

参数

struct ssam_event_queue *q: 事件队列。

struct ssam_event_queue *ssam_cplt_get_event_queue(struct ssam_cplt *cplt, u8 tid, u16 rqid)¶: 获取给定参数的事件队列。

参数

struct ssam_cplt *cplt: 在其上查找队列的完成系统。
u8 tid: 队列的目标 ID。
u16 rqid: 请求 ID，表示要获取队列的事件 ID。

返回

返回对应于给定参数描述的事件类型的事件队列。如果请求 ID 不表示事件，则此函数返回 NULL。如果不支持目标 ID，则此函数将回退到默认目标 ID（tid = 1）。

bool ssam_cplt_submit(struct ssam_cplt *cplt, struct work_struct *work)¶: 将工作项提交到完成系统工作队列。

参数

struct ssam_cplt *cplt: 完成系统。
struct work_struct *work: 要提交的工作项。

int ssam_cplt_submit_event(struct ssam_cplt *cplt, struct ssam_event_item *item)¶: 将事件提交到完成系统。

参数

struct ssam_cplt *cplt: 完成系统。
struct ssam_event_item *item: 要提交的事件项。

描述

通过将其排队到事件项队列并将相应的事件队列工作项排队到完成工作队列，将事件提交到完成系统，最终完成该事件。

返回

成功时返回零，如果没有可以处理给定事件项的事件队列，则返回 -EINVAL。

void ssam_cplt_flush(struct ssam_cplt *cplt)¶: 刷新完成系统。

参数

struct ssam_cplt *cplt: 完成系统。

描述

通过等待直到所有当前提交的工作项都已完成，来刷新完成系统。

此操作仅用于在关闭之前的正常操作期间，尝试完成大多数事件和请求，以便在系统仍在完全运行的情况下将其从系统中删除。它并不旨在提供任何保证，即所有事件和请求都已处理。

注意

此函数不能保证在此调用终止后所有事件都将被处理。如果存在大量要完成的事件，事件队列工作函数可能会重新安排其工作项，此刷新操作将忽略该工作项。

void ssam_event_queue_init(struct ssam_cplt *cplt, struct ssam_event_queue *evq)¶: 初始化事件队列。

参数

struct ssam_cplt *cplt: 队列所在的完成系统。
struct ssam_event_queue *evq: 要初始化的事件队列。

int ssam_cplt_init(struct ssam_cplt *cplt, struct device *dev)¶: 初始化完成系统。

参数

struct ssam_cplt *cplt: 要初始化的完成系统。
struct device *dev: 用于日志记录的设备。

void ssam_cplt_destroy(struct ssam_cplt *cplt)¶: 取消初始化完成系统。

参数

struct ssam_cplt *cplt: 要取消初始化的完成系统。

描述

取消初始化给定的完成系统，并确保已处理所有挂起的，即尚未完成的事件项和请求。

void ssam_controller_lock(struct ssam_controller *c)¶: 获取主控制器锁。

参数

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

描述

对于任何状态转换，包括转换到挂起/恢复状态以及关闭期间，都必须持有此锁。有关控制器锁定的更多详细信息，请参见 ssam_controller_statelock()。

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

int ssam_controller_caps_load_from_acpi(acpi_handle handle, struct ssam_controller_caps *caps)¶: 从 ACPI _DSM 加载控制器功能。

参数

acpi_handle handle: ACPI 控制器/SSH 设备的句柄。
struct ssam_controller_caps *caps: 在何处存储功能。

描述

使用默认值初始化给定的控制器功能，然后检查，如果相应的 _DSM 功能可用，则从 _DSM 加载实际功能。

返回

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

int ssam_controller_caps_load_from_of(struct device *dev, struct ssam_controller_caps *caps)¶: 从 OF/DT 加载控制器功能。

参数

struct device *dev: 指向控制器设备的指针
struct ssam_controller_caps *caps: 在何处存储功能。

返回

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

int ssam_controller_caps_load(struct device *dev, struct ssam_controller_caps *caps)¶: 加载控制器功能

参数

struct device *dev: 指向控制器设备的指针
struct ssam_controller_caps *caps: 在何处存储功能。

返回

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

int ssam_controller_init(struct ssam_controller *ctrl, struct serdev_device *serdev)¶: 初始化 SSAM 控制器。

参数

struct ssam_controller *ctrl: 要初始化的控制器。
struct serdev_device *serdev: 表示底层数据传输的串行设备。

描述

初始化给定的控制器。既不启动接收器线程也不启动发送器线程。在此调用之后，必须通过 struct serdev_device_ops 将控制器单独连接到 serdev 核心，将调用中继到 ssam_controller_receive_buf() 和 ssam_controller_write_wakeup()。连接控制器后，可以通过 ssam_controller_start() 启动发送器线程和接收器线程。这些设置步骤需要在控制器可用于请求之前完成。

int ssam_controller_start(struct ssam_controller *ctrl)¶: 启动控制器的接收器线程和发送器线程。

参数

struct ssam_controller *ctrl: 控制器。

注意

调用此函数时，应通过 struct serdev_device_ops 将控制器正确连接到 serdev 核心。有关控制器初始化的更多详细信息，请参见 ssam_controller_init()。

描述

必须在持有主控制器锁的情况下调用此函数（即通过调用 ssam_controller_lock()）。

void ssam_controller_shutdown(struct ssam_controller *ctrl)¶: 关闭控制器。

参数

struct ssam_controller *ctrl: 控制器。

描述

通过刷新所有挂起的请求并停止发送器线程和接收器线程来关闭控制器。在此调用之后提交的所有请求都将失败，并显示 -ESHUTDOWN。虽然不建议这样做，但此函数可以安全地与正在进行的请求提交并行使用。

在此关闭过程中，所有当前注册的通知器都将被取消注册。但是，强烈建议不要依赖此行为，而是注册通知器的一方应在控制器关闭之前取消注册它，例如，通过 SSAM 总线，该总线保证在关闭之前删除客户端设备。

请注意，在此调用之后可能仍有挂起的事件，但是由于通知器已取消注册，因此当控制器随后通过 ssam_controller_destroy() 销毁时，这些事件将被丢弃。

必须在持有主控制器锁的情况下调用此函数（即通过调用 ssam_controller_lock()）。

void ssam_controller_destroy(struct ssam_controller *ctrl)¶: 销毁控制器并释放其资源。

参数

struct ssam_controller *ctrl: 控制器。

描述

确保释放与控制器关联的所有资源。仅应在通过 ssam_controller_shutdown() 停止控制器后调用此函数。通常，不应直接调用此函数。直接调用此函数的唯一有效位置是在初始化期间，在控制器已完全初始化并传递给其他进程之前。当控制器的引用计数达到零时，将自动调用此函数。

必须在持有主控制器锁的情况下调用此函数（即通过调用 ssam_controller_lock()）。

int ssam_controller_suspend(struct ssam_controller *ctrl)¶: 挂起控制器。

参数

struct ssam_controller *ctrl: 要挂起的控制器。

描述

将控制器标记为已挂起。请注意，必须先手动发送显示关闭和 D0-exit 通知，然后才能通过此函数将控制器转换到挂起状态。

有关相应的恢复函数，请参见 ssam_controller_resume()。

返回

如果控制器当前未处于“已启动”状态，则返回 -EINVAL。

int ssam_controller_resume(struct ssam_controller *ctrl)¶: 从挂起状态恢复控制器。

参数

struct ssam_controller *ctrl: 要恢复的控制器。

描述

从通过 ssam_controller_suspend() 置于挂起状态的控制器恢复。此函数不会发出显示开启和 D0-entry 通知。如果需要，必须在此调用后手动发送这些通知。

返回

如果控制器当前未挂起，则返回 -EINVAL。

struct ssh_notification_params¶: 启用/禁用 SSH 通知的命令有效负载。

定义:

struct ssh_notification_params {
    u8 target_category;
    u8 flags;
    __le16 request_id;
    u8 instance_id;
};

成员

target_category: 应为其启用/禁用通知的目标类别。
flags: 标志，确定如何发送通知。
request_id: 用于发送这些通知的请求 ID。
instance_id: 应为其启用通知的给定目标类别中的特定实例。

int ssam_ssh_event_enable(struct ssam_controller *ctrl, struct ssam_event_registry reg, struct ssam_event_id id, u8 flags)¶: 启用 SSH 事件。

参数

struct ssam_controller *ctrl: 为其启用事件的控制器。
struct ssam_event_registry reg: 事件注册表，描述用于启用和禁用事件的请求。
struct ssam_event_id id: 事件标识符。
u8 flags: 事件标志。

描述

在 EC 上启用指定的事件。此函数不管理已启用事件的引用计数，并且基本上只是原始 EC 请求的包装器。如果指定的事件已经启用，EC 将忽略此请求。

返回

如果请求响应指示失败，则返回执行的 SAM 请求的状态（成功时为零，直接失败时为负数）或 -EPROTO。

int ssam_ssh_event_disable(struct ssam_controller *ctrl, struct ssam_event_registry reg, struct ssam_event_id id, u8 flags)¶: 禁用 SSH 事件。

参数

struct ssam_controller *ctrl: 为其禁用事件的控制器。
struct ssam_event_registry reg: 事件注册表，描述用于启用和禁用事件的请求（必须与启用事件时使用的相同）。
struct ssam_event_id id: 事件标识符。
u8 flags: 事件标志（很可能在禁用事件时被忽略）。

描述

在 EC 上禁用指定的事件。此函数不管理已启用事件的引用计数，并且基本上只是原始 EC 请求的包装器。如果指定的事件已经禁用，EC 将忽略此请求。

返回

如果请求响应指示失败，则返回执行的 SAM 请求的状态（成功时为零，直接失败时为负数）或 -EPROTO。

int ssam_get_firmware_version(struct ssam_controller *ctrl, u32 *version)¶: 获取 SAM/EC 固件版本。

参数

struct ssam_controller *ctrl: 控制器。
u32 *version: 存储版本号的位置。

返回

成功时返回零，如果执行的 SAM 请求失败，则返回该请求的状态。

int ssam_ctrl_notif_display_off(struct ssam_controller *ctrl)¶: 通知 EC 显示器已关闭。

参数

struct ssam_controller *ctrl: 控制器。

描述

通知 EC 显示器已关闭，驱动程序可能会进入低功耗状态。这将阻止直接发送事件。相反，EC 通过将唤醒 GPIO 拉高来发出事件信号，只要有挂起的事件。然后需要通过 GPIO 回调请求手动逐个释放事件。通过发出显示打开通知（例如通过 ssam_ctrl_notif_display_on()）也可以释放在此状态期间累积的所有挂起事件，这也将重置 GPIO。

在某些设备上，特别是具有集成键盘的设备，键盘背光将通过此调用关闭。

仅当 EC 支持显示通知时，此函数才会发送显示关闭通知命令。目前，所有已知的设备都支持这些通知。

使用 ssam_ctrl_notif_display_on() 来反转此函数的效果。

返回

成功时返回零或如果未执行任何请求，则返回执行的 SAM 请求的状态（如果该请求失败），或者如果收到意外响应，则返回 -EPROTO。

int ssam_ctrl_notif_display_on(struct ssam_controller *ctrl)¶: 通知 EC 显示器已打开。

参数

struct ssam_controller *ctrl: 控制器。

描述

通知 EC 显示器已重新打开，并且驱动程序已退出其低功耗状态。此通知是经由 ssam_ctrl_notif_display_off() 发送的显示关闭通知的对应方，并且将反转其效果，包括将事件重置为其默认行为。

仅当 EC 支持显示通知时，此函数才会发送显示打开通知命令。目前，所有已知的设备都支持这些通知。

有关更多详细信息，请参见 ssam_ctrl_notif_display_off()。

返回

成功时返回零或如果未执行任何请求，则返回执行的 SAM 请求的状态（如果该请求失败），或者如果收到意外响应，则返回 -EPROTO。

int ssam_ctrl_notif_d0_exit(struct ssam_controller *ctrl)¶: 通知 EC 驱动程序/设备退出 D0 电源状态。

参数

struct ssam_controller *ctrl: 控制器

描述

通知 EC 驱动程序准备退出 D0 电源状态，以支持较低功耗的状态。目前尚不清楚此函数与 EC 相关的确切效果。

仅当 EC 支持 D0 状态通知时，此函数才会发送 D0 退出通知命令。只有较新的 Surface 代支持这些通知。

使用 ssam_ctrl_notif_d0_entry() 来反转此函数的效果。

返回

成功时返回零或如果未执行任何请求，则返回执行的 SAM 请求的状态（如果该请求失败），或者如果收到意外响应，则返回 -EPROTO。

int ssam_ctrl_notif_d0_entry(struct ssam_controller *ctrl)¶: 通知 EC 驱动程序/设备进入 D0 电源状态。

参数

struct ssam_controller *ctrl: 控制器

描述

通知 EC 驱动程序已退出较低功耗状态并进入 D0 电源状态。目前尚不清楚此函数与 EC 相关的确切效果。

仅当 EC 支持 D0 进入通知时，此函数才会发送 D0 进入通知命令。只有较新的 Surface 代支持这些通知。

有关更多详细信息，请参见 ssam_ctrl_notif_d0_exit()。

返回

成功时返回零或如果未执行任何请求，则返回执行的 SAM 请求的状态（如果该请求失败），或者如果收到意外响应，则返回 -EPROTO。

int ssam_nf_refcount_enable(struct ssam_controller *ctrl, struct ssam_nf_refcount_entry *entry, u8 flags)¶: 如果尚未启用，则为引用计数条目启用事件。

参数

struct ssam_controller *ctrl: 要在其上启用事件的控制器。
struct ssam_nf_refcount_entry *entry: 要启用的事件的引用计数条目。
u8 flags: 用于在 EC 上启用事件的标志。

描述

如果引用计数等于 1，则启用与给定引用计数条目关联的事件，即，之前未启用该事件。如果该事件已被启用（即，引用计数不等于 1），请检查用于启用的标志是否匹配，如果不匹配，则发出警告。

这不会修改引用计数本身，引用计数本身通过 ssam_nf_refcount_inc() / ssam_nf_refcount_dec() 完成。

注意

调用此函数时必须持有 nf->lock。

返回

成功时返回零。如果事件由此调用启用，则返回事件启用 EC 命令的状态。

int ssam_nf_refcount_disable_free(struct ssam_controller *ctrl, struct ssam_nf_refcount_entry *entry, u8 flags, bool ec)¶: 如果引用计数条目不再使用，则禁用该条目的事件，并释放相应的条目。

参数

struct ssam_controller *ctrl: 要在其上禁用事件的控制器。
struct ssam_nf_refcount_entry *entry: 要禁用的事件的引用计数条目。
u8 flags: 用于在 EC 上启用事件的标志。
bool ec: 一个标志，用于指定是否应实际在 EC 上禁用事件。

描述

如果 ec 等于 true 并且引用计数等于 0（即，任何客户端都不再请求该事件），则将通过相应的请求在 EC 上禁用指定的事件。

如果 ec 等于 false，则不会向 EC 发送任何请求，并且该事件可以被视为处于分离状态（即，不再使用但仍启用）。对于热插拔设备，可能需要通过此方法禁用事件，在这种情况下，设备被物理移除后，事件禁用请求可能会超时。

在这两种情况下，如果引用计数等于 0，则将释放相应的引用计数条目。在调用此函数后，不得再使用该引用计数条目。

此外，还会检查用于禁用事件的标志是否与用于启用事件的标志匹配，如果不匹配，则发出警告（无论引用计数如何）。

这不会修改引用计数本身，引用计数本身通过 ssam_nf_refcount_inc() / ssam_nf_refcount_dec() 完成。

注意

调用此函数时必须持有 nf->lock。

返回

成功时返回零。如果事件由此调用禁用，则返回事件启用 EC 命令的状态。

int ssam_notifier_disable_registered(struct ssam_controller *ctrl)¶: 禁用所有已注册通知程序的事件。

参数

struct ssam_controller *ctrl: 要禁用通知程序/事件的控制器。

描述

禁用所有当前已注册通知程序的事件。如果发生错误（EC 命令失败），则将恢复所有先前禁用的事件，并返回错误代码。

此函数旨在休眠条目之前禁用所有事件。有关更多信息，请参见 ssam_notifier_restore_registered() 以还原/重新启用使用此函数禁用的所有事件。

请注意，此函数不会禁用在此函数调用之后注册的通知程序的事件。因此，应确保在此调用之后和对 ssam_notifier_restore_registered() 的相应调用之前，不会添加任何新的通知程序。

返回

成功时返回零。如果失败，则返回禁用事件的失败 EC 命令返回的错误代码。

void ssam_notifier_restore_registered(struct ssam_controller *ctrl)¶: 还原/重新启用所有已注册通知程序的事件。

参数

struct ssam_controller *ctrl: 要还原通知程序/事件的控制器。

描述

还原/重新启用在给定控制器上已注册通知程序的所有事件。如果发生故障，则会记录该错误，并且该函数会继续尝试启用剩余的事件。

此函数旨在在休眠后还原/重新启用所有已注册的事件。有关禁用事件的对应部分以及更多详细信息，请参见 ssam_notifier_disable_registered()。

bool ssam_notifier_is_empty(struct ssam_controller *ctrl)¶: 检查是否有任何已注册的通知程序。

参数

struct ssam_controller *ctrl: 要检查的控制器。

返回

如果当前没有在控制器上注册任何通知程序，则返回 true，否则返回 false。

void ssam_notifier_unregister_all(struct ssam_controller *ctrl)¶: 取消注册所有当前已注册的通知程序。

参数

struct ssam_controller *ctrl: 要在其上取消注册通知程序的控制器。

描述

取消注册所有当前已注册的通知程序。当控制器正在关闭时，此函数用于确保取消注册所有通知程序并释放关联的条目/资源。

int ssam_irq_setup(struct ssam_controller *ctrl)¶: 设置 SAM EC 唤醒 GPIO 中断。

参数

struct ssam_controller *ctrl: 应为其设置 IRQ 的控制器。

描述

为 SAM EC 的唤醒 GPIO 引脚设置 IRQ。此 IRQ 可用于将设备从低功耗状态唤醒。

请注意，只有当 EC 处于显示关闭状态时，才能触发此 IRQ。在这种状态下，事件不会以通常的方式发送到主机。相反，只要有挂起的事件，唤醒 GPIO 就会被拉至“高电平”，并且这些事件需要通过 GPIO 回调请求逐个释放，直到没有剩余事件且 GPIO 重置，或者通过将 EC 转换为显示关闭状态来一次性释放所有事件，这也将清除 GPIO。

但是，并非所有事件都应触发完整的系统唤醒。相反，驱动程序应在必要时检查每个事件并将其转发到相应的子系统，而子系统又应决定是否需要唤醒系统。此逻辑尚未实现，因此默认情况下应禁用此 IRQ 的唤醒，以避免出现假唤醒，例如，由剩余电池百分比变化引起的唤醒。有关如何实现此功能的更多详细信息，请参见此函数中的注释以及相应 IRQ 处理程序中的注释。

另请参见 ssam_ctrl_notif_display_off() 和 ssam_ctrl_notif_display_off()，以了解将 EC 转换为显示关闭状态以及退出显示关闭状态的函数以及有关它的更多详细信息。

默认情况下禁用 IRQ，并且必须先启用 IRQ，然后才能通过 ssam_irq_arm_for_wakeup() 将设备从挂起状态唤醒。在拆卸时，应通过 ssam_irq_free() 释放 IRQ。

void ssam_irq_free(struct ssam_controller *ctrl)¶: 释放 SAM EC 唤醒 GPIO 中断。

参数

struct ssam_controller *ctrl: 应为其释放 IRQ 的控制器。

描述

释放先前通过 ssam_irq_setup() 设置的唤醒 GPIO IRQ。

int ssam_irq_arm_for_wakeup(struct ssam_controller *ctrl)¶: 如果已启用，则准备 EC IRQ 以进行唤醒。

参数

struct ssam_controller *ctrl: 应准备 IRQ 的控制器。

描述

设置 IRQ，使其可用于唤醒设备。具体来说，此函数会启用 irq，然后，如果允许设备唤醒系统，则调用 enable_irq_wake()。有关禁用 IRQ 的相应函数，请参见 ssam_irq_disarm_wakeup()。

此函数旨在在进入 S2idle 挂起之前准备 IRQ。

注意

必须平衡对 ssam_irq_arm_for_wakeup() 和 ssam_irq_disarm_wakeup() 的调用。

void ssam_irq_disarm_wakeup(struct ssam_controller *ctrl)¶: 解除唤醒 IRQ 的准备。

参数

struct ssam_controller *ctrl: 应解除 IRQ 准备的控制器。

描述

解除先前通过 ssam_irq_arm_for_wakeup() 设置的唤醒 IRQ 的准备。

此函数旨在退出 S2idle 挂起后解除 IRQ 的准备。

注意

必须平衡对 ssam_irq_arm_for_wakeup() 和 ssam_irq_disarm_wakeup() 的调用。

客户端设备总线 ¶

bool ssam_device_id_compatible(const struct ssam_device_id *id, struct ssam_device_uid uid)¶: 检查设备 ID 是否与 UID 匹配。

参数

const struct ssam_device_id *id: 作为潜在匹配项的设备 ID。
struct ssam_device_uid uid: 用于匹配的设备 UID。

描述

检查给定的 ID 是否与给定的 UID 匹配，即，具有提供的 UID 的设备是否与给定的 ID 兼容，遵循其 ssam_device_id.match_flags 成员中描述的匹配规则。

返回

如果给定的 UID 与给定的 ID 描述的匹配规则兼容，则返回 true，否则返回 false。

bool ssam_device_id_is_null(const struct ssam_device_id *id)¶: 检查设备 ID 是否为空。

参数

const struct ssam_device_id *id: 要检查的设备 ID。

描述

检查给定的设备 ID 是否为空，即，是否全部为零。用于检查 MODULE_DEVICE_TABLE(ssam, ...) 或类似列表的结尾。

返回

如果给定的 ID 表示空 ID，则返回 true，否则返回 false。

int ssam_bus_register(void)¶: 注册并设置 SSAM 客户端设备总线。

参数

void: 没有参数

void ssam_bus_unregister(void)¶: 取消注册 SSAM 客户端设备总线。

参数

void: 没有参数

核心 ¶

int ssam_try_set_controller(struct ssam_controller *ctrl)¶: 尝试设置主控制器引用。

参数

struct ssam_controller *ctrl: 引用应指向的控制器。

描述

如果尚未设置引用，则将主控制器引用设置为给定的指针。

返回

成功时返回零，如果已设置引用，则返回 -EEXIST。

void ssam_clear_controller(void)¶: 删除/清除主控制器引用。

参数

void: 没有参数

描述

清除主控制器引用，即，将其设置为 NULL。在关闭控制器之前应调用此函数。

跟踪帮助器 ¶

void ssam_trace_ptr_uid(const void *ptr, char *uid_str)¶: 将指针转换为非指针 UID 字符串。

参数

const void *ptr: 要转换的指针。
char *uid_str: 长度为 SSAM_PTR_UID_LEN 的缓冲区，UID 将存储在该缓冲区中。

描述

将给定的指针转换为 UID 字符串，该字符串可以安全地与用户空间和日志共享，即，不会泄露实际的内存位置。

u16 ssam_trace_get_packet_seq(const struct ssh_packet *p)¶: 读取数据包的序列 ID。

参数

const struct ssh_packet *p: 数据包。

返回

如果存在，则返回数据包的序列 ID (SEQ) 字段，如果不存在（例如，刷新数据包），则返回 SSAM_SEQ_NOT_APPLICABLE。

u32 ssam_trace_get_request_id(const struct ssh_packet *p)¶: 读取数据包的请求 ID。

参数

const struct ssh_packet *p: 数据包。

返回

如果数据包表示带有命令数据的请求，则返回数据包的请求 ID (RQID) 字段，如果不是（例如，刷新请求、控制数据包），则返回 SSAM_RQID_NOT_APPLICABLE。

u32 ssam_trace_get_request_tid(const struct ssh_packet *p)¶: 读取数据包的请求目标 ID。

参数

const struct ssh_packet *p: 数据包。

返回

如果数据包表示带有命令数据的请求，则返回数据包的请求目标 ID (TID) 字段，如果不是（例如，刷新请求、控制数据包），则返回 SSAM_SSH_TID_NOT_APPLICABLE。

u32 ssam_trace_get_request_sid(const struct ssh_packet *p)¶: 读取数据包的请求源 ID。

参数

const struct ssh_packet *p: 数据包。

返回

如果数据包表示带有命令数据的请求，则返回数据包的请求源 ID (SID) 字段，如果不是（例如，刷新请求、控制数据包），则返回 SSAM_SSH_TID_NOT_APPLICABLE。

u32 ssam_trace_get_request_tc(const struct ssh_packet *p)¶: 读取数据包的请求目标类别。

参数

const struct ssh_packet *p: 数据包。

返回

如果数据包表示带有命令数据的请求，则返回数据包的请求目标类别 (TC) 字段，如果不是（例如，刷新请求、控制数据包），则返回 SSAM_SSH_TC_NOT_APPLICABLE。

Linux 内核

目录

本页

内部 API 文档 ¶

数据包传输层 ¶

请求传输层 ¶

控制器 ¶

客户端设备总线 ¶

核心 ¶

跟踪帮助器 ¶