1.功能约束类型,即DA类的FC成员

ST (Status) 状态信息
MX (MesuredExtensed) 测量值
CO (Control) 控制
SP (StaticParam) 参数
SV (SubstitueValue) 取代
CF (Config) 配置
DC (Describe) 描述
SG (StaticGrop) 定值组
SE (StaticEdit) 可编辑定值组
EX (Extra) 扩充定义
BR (BufferReport)缓存报告
RP (Report)非缓存报告
LG (Log)日志
GO(Goose)Goose控制
GS(Gsse)gsse控制
MS （MutiSample）多路广播采样值控制
US （UniqueSample）单路创博采样值控制
XX 作为所有DA服务参数

2.通用数据类型,即DA类的CDC成员

Quality(品质)
Analogue value(模拟值)
Configration of analoge value(模拟值的配置)
Range configration(范围配置)
Pulse configration(脉冲配置)
Originator(原发者)
Unit(单位定义)
Vector(向量定义)
Point(点定义)
CtlModels(控制模式定义)
sboClass(操作前选择定义)

3.数据对象类,即DO类的name成员

SPC(单点状态信息)
DPS(双点状态信息)
INS(整数状态信息)
ACT(保护激活信息)
ACD(方向保护激活信息)
SEC(安全违例计数)
BCR(二进制计数器读数)
MV(测量值)
CMV(复数测量值)
SAV(采样值)
WYE(三相系统中相对地相关测量值)
SEQ(顺序值)
HMV(谐波值)
WYE/HWYE(谐波值)
SPC(可控的单点)
DPC(可控的双点)
INC(可控的整数状态)
BSC(二进制受控步位置信息)
ISC(整数受控步位置信息)
APC(可控模拟设点信息)
SPG(单点定值)
ING(整数状态定值)
ASG(模拟定值)
CURVE(定值曲线)
DPL(设备铭牌)
LPL(逻辑节点铭牌)
CSD(曲线形状描述)

4.逻辑节点类,即LN类的name成员

LPHD(物理装置信息)
LLN0（逻辑节点零）
PDIF(差动)
PDIR(方向比较)
PDIS(距离保护)
PDOP(过功率方向)
PDUP(欠功率方向)
PFRC(频率变化率)
PHAR(谐波制动)
PHIZ(接地检测)
PIOC(瞬时过流)
PMRI(禁止电动机重新启动)
PMSS(电动机启动时间监视)
POPF(过功率因素)
PPAM（相角测量）
PSCH(保护配置)
PSDE(灵敏方向接地故障)
PIEF(瞬时接地故障)
PTOC(带时限过电流)
PTOF(高周频率)
PTOV(过压电)
PTRC(保护跳闸条件)
PTTR(过热)
PTUC(欠电流)
PTUV(欠电压)
PTPF(欠功率因数)
PTUF(低周)
PVOC(电压控制限时过流电)
PVPH(电压频率)
PZSU(零速或欠速保护)
RDRE(扰动记录功能)
RADR(扰动记录模拟通道)
RBDR(扰动记录状态量通道)
RDRS(扰动记录处理)
RBRF(断路器失灵)
RDIR(方向元件)
RFLO(故障定位)
RPSB(电网振荡检测/闭锁)
RREC(自动重合闸)
RSYN(同期检测或同期)
CALH(告警处理)
CCGR(冷却成组控制)
CILO(联锁)
CPOW(定点分合)
CSWI(开关控制器)
GAPC(通用自动勾过程控制)
GGIO(通用过程I/O)
GSAL(通用安全应用)
IARC(存档)
IHMI(人机接口)
ITCI(遥控接口)
ITMI(远方监视接口)
ANCR(中性点电流调节)
ARCO(无功控制)
ATCC(自动调分接头控制)
AVCO(电压控制)
MDIF(差动测量)
MHAI(谐波和间谐波)
MHAN(相别无关谐波和间谐波)
MMTR(计量)
MMXN(相别无关测量)
MMXU(测量)
MSQI(相序和不平衡)
MSTA(计量统计)
SARC(电弧监视和诊断)
SIMG(绝缘介质监视气体)
SIML(绝缘介质监视液体)
SPDC(局部放电监视和诊断)
XCBR(断路器)
XSWI(隔离开关)
TCTR(电流互感器)
TVTR(电压互感器)
YEFN(接地故障中性点补偿消弧线圈)
YLTC(分接头)
YPSH(功率分流)
YPTR(电力变压器)
ZAXN(辅助网络)
ZBAT(电池)
ZBSH(套管)
ZCAB(电力电缆)
ZCAP(电容器组)
ZCON(转换器)
ZGEN(发电机)
ZGIL(气体绝缘线路)
ZLIN(电力架空线)
ZMOT(电动机)
ZREA(电抗器)
ZRRC(旋转无功元件)
ZSAR(浪涌抑制器)
ZTCF(晶闸管控制频率转换器)
ZTCR(晶闸管控制无功元件)

5.其他的常用语

MMS：Manufacturing Message Specification 制造报文规范
GOOSE:Generic Object Oriented Substation Event 面向通用对象变电站事件
LD:Logical Device 逻辑设备,代表典型变电站功能集的实体
LN:Logical Node 逻辑节点,代表典型变电站功能的实体
DO:Data Object class or instance 数据对象类型
DA:Data Attribute 数据属性
FC:Functional Constraint 功能约束
FCDA:Functionall Constrained Data Attribute 功能约束数据属性
BDA:Basic Data Attribute,that is not structre 非结构化的基本数据属性
DOI:Data Object Instantiated 实例化数据对象
DAI:Data Attribute Instantiated 实例化数据属性
ICD:IED Capability Description 智能电子设备能力描述文件
SSD:System Specification Description 系统规范描述文件
SCD:Sustation Configuration Description 变电站配置描述文件
CID:Configured IED Description 配置过的智能电子设备描述
IID:Instantiated IED Description 实例化的智能电子设备描述文件
SED:System Exchange Description 系统交换描述文件
CDC:Commmon Data Class(DL/T860.73)公用数据类
XML:Extensible Markup Language 拓展标志语言
SCL:Substation Configuration description Language 变电站配置描述语言
RCB:Report Control Block 报告控制块
IED:Intelligent Electronic Device 智能电子设备
XSD:XML Schema Definition xml语法定义

原文：https://blog.csdn.net/yuan1164345228/article/details/134669201

本文组合翻译了以下两篇文章的干货部分，作为 io_uring 相关的入门参考：

• How io_uring and eBPF Will Revolutionize Programming in Linux, ScyllaDB, 2020
• An Introduction to the io_uring Asynchronous I/O Framework, Oracle, 2020

io_uring 是 2019 年 Linux 5.1 内核首次引入的高性能 异步 I/O 框架，能显著加速 I/O 密集型应用的性能。 但如果你的应用已经在使用 传统 Linux AIO 了，并且使用方式恰当， 那 io_uring 并不会带来太大的性能提升 —— 根据原文测试（以及我们 自己的复现），即便打开高级特性，也只有 5%。除非你真的需要这 5% 的额外性能，否则 切换成 io_uring 代价可能也挺大，因为要 重写应用来适配 io_uring（或者让依赖的平台或框架去适配，总之需要改代码）。

既然性能跟传统 AIO 差不多，那为什么还称 io_uring 为革命性技术呢？

它首先和最大的贡献在于：统一了 Linux 异步 I/O 框架，

• Linux AIO 只支持 direct I/O 模式的存储文件 （storage file），而且主要用在数据库这一细分领域；
• io_uring 支持存储文件和网络文件（network sockets），也支持更多的异步系统调用 （accept/openat/stat/...），而非仅限于 read/write 系统调用。

在设计上是真正的异步 I/O，作为对比，Linux AIO 虽然也 是异步的，但仍然可能会阻塞，某些情况下的行为也无法预测；

似乎之前 Windows 在这块反而是领先的，更多参考：

• 浅析开源项目之 io_uring，“分步试存储”专栏，知乎
• Is there really no asynchronous block I/O on Linux?，stackoverflow

1. 灵活性和可扩展性非常好，甚至能基于 io_uring 重写所有系统调用，而 Linux AIO 设计时就没考虑扩展性。

eBPF 也算是异步框架（事件驱动），但与 io_uring 没有本质联系，二者属于不同子系统， 并且在模型上有一个本质区别：

1. eBPF 对用户是透明的，只需升级内核（到合适的版本），应用程序无需任何改造；
2. io_uring 提供了新的系统调用和用户空间 API，因此需要应用程序做改造。

eBPF 作为动态跟踪工具，能够更方便地排查和观测 io_uring 等模块在执行层面的具体问题。

本文介绍 Linux 异步 I/O 的发展历史，io_uring 的原理和功能， 并给出了一些程序示例和性能压测结果（我们在 5.10 内核做了类似测试，结论与原文差不多）。

Ceph 代码上已经支持了 io_uring，但发行版在编译时没有打开这个配置，判断是否支持 io_uring 直接返回的 false， 因此想测试得自己重新编译。测试时的参考配置：

$ cat /etc/ceph/ceph.conf
[osd]
bluestore_ioring = true
...

确认配置生效（这是只是随便挑一个 OSD）：

$ ceph config show osd.16 | grep ioring
bluestore_ioring                       true                                            file

还要去看下日志，是否因为检测 io_uring 失败而 fallback 回了 libaio。

由于译者水平有限，本文不免存在遗漏或错误之处。如有疑问，请查阅原文。

以下是译文。

• 译者序
• 1 Linux I/O 系统调用演进
• 1.1 基于 fd 的阻塞式 I/O：read()/write()
• 1.2 非阻塞式 I/O：select()/poll()/epoll()
• 1.3 线程池方式
• 1.4 Direct I/O（数据库软件）：绕过 page cache
• 1.5 异步 IO（AIO）
• 1.6 小结
• 2 io_uring
• 2.1 与 Linux AIO 的不同
• 2.2 原理及核心数据结构：SQ/CQ/SQE/CQE
• 2.3 带来的好处
• 2.4 三种工作模式
• 2.5 io_uring 系统调用 API
• 2.5.1 io_uring_setup()
• 2.5.2 io_uring_register()
• 注册的缓冲区（buffer）性质
• 通过 eventfd() 订阅 completion 事件
• 2.5.3 io_uring_enter()
• 2.6 高级特性
• 2.7 用户空间库 liburing
• 3 基于 liburing 的示例应用
• 3.1 io_uring-test
• 源码及注释
• 其他说明
• 3.2 link-cp
• I/O chain
• 源码及注释
• 其他说明
• 4 io_uring 性能压测（基于 fio）
• 4.1 测试环境
• 4.2 场景一：direct I/O 1KB 随机读（绕过 page cache）
• 4.2 场景二：buffered I/O 1KB 随机读（数据提前加载到内存，100% hot cache）
• 4.3 性能测试小结
• 4.4 ScyllaDB 与 io_uring
• 5 eBPF
• 6 结束语
• 参考资料

很多人可能还没意识到，Linux 内核在过去几年已经发生了一场革命。这场革命源于 两个激动人心的新接口的引入：eBPF 和 io_uring。 我们认为，二者将会完全改变应用与内核交互的方式，以及 应用开发者思考和看待内核的方式。

本文介绍 io_uring（我们在 ScyllaDB 中有 io_uring 的深入使用经验），并略微提及一下 eBPF。

1 Linux I/O 系统调用演进

1.1 基于 fd 的阻塞式 I/O：read()/write()

作为大家最熟悉的读写方式，Linux 内核提供了基于文件描述符的系统调用， 这些描述符指向的可能是存储文件（storage file），也可能是 network sockets：

ssize_t read(int fd, void *buf, size_t count);
ssize_t write(int fd, const void *buf, size_t count);

二者称为阻塞式系统调用（blocking system calls），因为程序调用 这些函数时会进入 sleep 状态，然后被调度出去（让出处理器），直到 I/O 操作完成：

• 如果数据在文件中，并且文件内容已经缓存在 page cache 中，调用会立即返回；
• 如果数据在另一台机器上，就需要通过网络（例如 TCP）获取，会阻塞一段时间；
• 如果数据在硬盘上，也会阻塞一段时间。

但很容易想到，随着存储设备越来越快，程序越来越复杂， 阻塞式（blocking）已经这种最简单的方式已经不适用了。

1.2 非阻塞式 I/O：select()/poll()/epoll()

阻塞式之后，出现了一些新的、非阻塞的系统调用，例如 select()、poll() 以及更新的 epoll()。 应用程序在调用这些函数读写时不会阻塞，而是立即返回，返回的是一个 已经 ready 的文件描述符列表。

但这种方式存在一个致命缺点：只支持 network sockets 和 pipes —— epoll() 甚至连 storage files 都不支持。

1.3 线程池方式

对于 storage I/O，经典的解决思路是 thread pool： 主线程将 I/O 分发给 worker 线程，后者代替主线程进行阻塞式读写，主线程不会阻塞。

这种方式的问题是线程上下文切换开销可能非常大，后面性能压测会看到。

1.4 Direct I/O（数据库软件）：绕过 page cache

随后出现了更加灵活和强大的方式：数据库软件（database software） 有时 并不想使用操作系统的 page cache， 而是希望打开一个文件后，直接从设备读写这个文件（direct access to the device）。 这种方式称为直接访问（direct access）或直接 I/O（direct I/O），

• 需要指定 O_DIRECT flag；
• 需要应用自己管理自己的缓存 —— 这正是数据库软件所希望的；
• 是 zero-copy I/O，因为应用的缓冲数据直接发送到设备，或者直接从设备读取。

1.5 异步 IO（AIO）

前面提到，随着存储设备越来越快，主线程和 worker 线性之间的上下文切换开销占比越来越高。 现在市场上的一些设备，例如 Intel Optane ，延迟已经低到和上下文切换一个量级（微秒 us）。换个方式描述， 更能让我们感受到这种开销： 上下文每切换一次，我们就少一次 dispatch I/O 的机会。

因此，Linux 2.6 内核引入了异步 I/O（asynchronous I/O）接口， 方便起见，本文简写为 linux-aio。AIO 原理是很简单的：

• 用户通过 io_submit() 提交 I/O 请求，
• 过一会再调用 io_getevents() 来检查哪些 events 已经 ready 了。
• 使程序员能编写完全异步的代码。

近期，Linux AIO 甚至支持了 epoll()：也就是说 不仅能提交 storage I/O 请求，还能提交网络 I/O 请求。照这样发展下去，linux-aio 似乎能成为一个王者。但由于它糟糕的演进之路，这个愿望几乎不可能实现了。 我们从 Linus 标志性的激烈言辞中就能略窥一斑：

Reply to: to support opening files asynchronously

So I think this is ridiculously ugly.

AIO is a horrible ad-hoc design, with the main excuse being “other, less gifted people, made that design, and we are implementing it for compatibility because database people — who seldom have any shred of taste — actually use it”.

— Linus Torvalds (on lwn.net)

首先，作为数据库从业人员，我们想借此机会为我们的没品（lack of taste）向 Linus 道歉。 但更重要的是，我们要进一步解释一下为什么 Linus 是对的：Linux AIO 确实问题缠身，

1. 只支持 O_DIRECT 文件，因此对常规的非数据库应用 （normal, non-database applications）几乎是无用的；
2. 接口在设计时并未考虑扩展性。虽然可以扩展 —— 我们也确实这么做了 —— 但每加一个东西都相当复杂；
3. 虽然从技术上说接口是非阻塞的，但实际上有 很多可能的原因都会导致它阻塞，而且引发的方式难以预料。

1.6 小结

以上可以清晰地看出 Linux I/O 的演进：

• 最开始是同步（阻塞式）系统调用；
• 然后随着实际需求和具体场景，不断加入新的异步接口，还要保持与老接口的兼容和协同工作。

另外也看到，在非阻塞式读写的问题上并没有形成统一方案：

1. Network socket 领域：添加一个异步接口，然后去轮询（poll）请求是否完成（readiness）；
2. Storage I/O 领域：只针对某一细分领域（数据库）在某一特定时期的需求，添加了一个定制版的异步接口。

这就是 Linux I/O 的演进历史 —— 只着眼当前，出现一个问题就引入一种设计，而并没有多少前瞻性 —— 直到 io_uring 的出现。

2 io_uring

io_uring 来自资深内核开发者 Jens Axboe 的想法，他在 Linux I/O stack 领域颇有研究。 从最早的 patch aio: support for IO polling 可以看出，这项工作始于一个很简单的观察：随着设备越来越快， 中断驱动（interrupt-driven）模式效率已经低于轮询模式 （polling for completions） —— 这也是高性能领域最常见的主题之一。

• io_uring 的基本逻辑与 linux-aio 是类似的：提供两个接口，一个将 I/O 请求提交到内核，一个从内核接收完成事件。
• 但随着开发深入，它逐渐变成了一个完全不同的接口：设计者开始从源头思考 如何支持完全异步的操作。

2.1 与 Linux AIO 的不同

io_uring 与 linux-aio 有着本质的不同：

1. 在设计上是真正异步的（truly asynchronous）。只要 设置了合适的 flag，它在系统调用上下文中就只是将请求放入队列， 不会做其他任何额外的事情，保证了应用永远不会阻塞。

支持任何类型的 I/O：cached files、direct-access files 甚至 blocking sockets。

由于设计上就是异步的（async-by-design nature），因此无需 poll+read/write 来处理 sockets。 只需提交一个阻塞式读（blocking read），请求完成之后，就会出现在 completion ring。

1. 灵活、可扩展：基于 io_uring 甚至能重写（re-implement）Linux 的每个系统调用。

2.2 原理及核心数据结构：SQ/CQ/SQE/CQE

每个 io_uring 实例都有两个环形队列（ring），在内核和应用程序之间共享：

• 提交队列：submission queue (SQ)
• 完成队列：completion queue (CQ)

这两个队列：

• 都是单生产者、单消费者，size 是 2 的幂次；
• 提供无锁接口（lock-less access interface），内部使用 内存屏障做同步（coordinated with memory barriers）。

使用方式：

请求

• 应用创建 SQ entries (SQE)，更新 SQ tail；
• 内核消费 SQE，更新 SQ head。

完成

• 内核为完成的一个或多个请求创建 CQ entries (CQE)，更新 CQ tail；
• 应用消费 CQE，更新 CQ head。
• 完成事件（completion events）可能以任意顺序到达，到总是与特定的 SQE 相关联的。
• 消费 CQE 过程无需切换到内核态。

2.3 带来的好处

io_uring 这种请求方式还有一个好处是：原来需要多次系统调用（读或写），现在变成批处理一次提交。

还记得 Meltdown 漏洞吗？当时我还写了一篇文章 解释为什么我们的 Scylla NoSQL 数据库受影响很小：aio 已经将我们的 I/O 系统调用批处理化了。

io_uring 将这种批处理能力带给了 storage I/O 系统调用之外的 其他一些系统调用，包括：

• read
• write
• send
• recv
• accept
• openat
• stat
• 专用的一些系统调用，例如 fallocate

此外，io_uring 使异步 I/O 的使用场景也不再仅限于数据库应用，普通的 非数据库应用也能用。这一点值得重复一遍：

虽然 io_uring 与 aio 有一些相似之处，但它的扩展性和架构是革命性的： 它将异步操作的强大能力带给了所有应用（及其开发者），而 不再仅限于是数据库应用这一细分领域。

我们的 CTO Avi Kivity 在 the Core C++ 2019 event 上 有一次关于 async 的分享。 核心点包括：从延迟上来说，

1. 现代多核、多 CPU 设备，其内部本身就是一个基础网络；
2. CPU 之间是另一个网络；
3. CPU 和磁盘 I/O 之间又是一个网络。

因此网络编程采用异步是明智的，而现在开发自己的应用也应该考虑异步。 这从根本上改变了 Linux 应用的设计方式：

• 之前都是一段顺序代码流，需要系统调用时才执行系统调用，
• 现在需要思考一个文件是否 ready，因而自然地引入 event-loop，不断通过共享 buffer 提交请求和接收结果。

2.4 三种工作模式

io_uring 实例可工作在三种模式：

中断驱动模式（interrupt driven）

默认模式。可通过 io_uring_enter() 提交 I/O 请求，然后直接检查 CQ 状态判断是否完成。

轮询模式（polled）

Busy-waiting for an I/O completion，而不是通过异步 IRQ（Interrupt Request）接收通知。

这种模式需要文件系统（如果有）和块设备（block device）支持轮询功能。 相比中断驱动方式，这种方式延迟更低（连系统调用都省了）， 但可能会消耗更多 CPU 资源。

目前，只有指定了 O_DIRECT flag 打开的文件描述符，才能使用这种模式。当一个读 或写请求提交给轮询上下文（polled context）之后，应用（application）必须调用 io_uring_enter() 来轮询 CQ 队列，判断请求是否已经完成。

对一个 io_uring 实例来说，不支持混合使用轮询和非轮询模式。

内核轮询模式（kernel polled）

这种模式中，会 创建一个内核线程（kernel thread）来执行 SQ 的轮询工作。

使用这种模式的 io_uring 实例， 应用无需切到到内核态 就能触发（issue）I/O 操作。 通过 SQ 来提交 SQE，以及监控 CQ 的完成状态，应用无需任何系统调用，就能提交和收割 I/O（submit and reap I/Os）。

如果内核线程的空闲时间超过了用户的配置值，它会通知应用，然后进入 idle 状态。 这种情况下，应用必须调用 io_uring_enter() 来唤醒内核线程。如果 I/O 一直很繁忙，内核线性是不会 sleep 的。

2.5 io_uring 系统调用 API

有三个：

• io_uring_setup(2)
• io_uring_register(2)
• io_uring_enter(2)

下面展开介绍。完整文档见 manpage。

2.5.1 io_uring_setup()

执行异步 I/O 需要先设置上下文：

int io_uring_setup(u32 entries, struct io_uring_params *p);

这个系统调用

• 创建一个 SQ 和一个 CQ，
• queue size 至少 entries 个元素，
• 返回一个文件描述符，随后用于在这个 io_uring 实例上执行操作。

SQ 和 CQ 在应用和内核之间共享，避免了在初始化和完成 I/O 时（initiating and completing I/O）拷贝数据。

参数 p：

• 应用用来配置 io_uring，
• 内核返回的 SQ/CQ 配置信息也通过它带回来。

io_uring_setup() 成功时返回一个文件描述符（fd）。应用随后可以将这个 fd 传给 mmap(2) 系统调用，来 map the submission and completion queues 或者传给 to the io_uring_register() or io_uring_enter() system calls.

2.5.2 io_uring_register()

注册用于异步 I/O 的文件或用户缓冲区（files or user buffers）：

int io_uring_register(unsigned int fd, unsigned int opcode, void *arg, unsigned int nr_args);

注册文件或用户缓冲区，使内核能长时间持有对该文件在内核内部的数据结构引用（internal kernel data structures associated with the files）， 或创建应用内存的长期映射（long term mappings of application memory associated with the buffers）， 这个操作只会在注册时执行一次，而不是每个 I/O 请求都会处理，因此减少了 per-I/O overhead。

注册的缓冲区（buffer）性质

• Registered buffers 将会被锁定在内存中（be locked in memory），并计入用户的 RLIMIT_MEMLOCK 资源限制。
• 此外，每个 buffer 有 1GB 的大小限制。
• 当前，buffers 必须是匿名、非文件后端的内存（anonymous, non-file-backed memory），例如 malloc(3) or mmap(2) with the MAP_ANONYMOUS flag set 返回的内存。
• Huge pages 也是支持的。整个 huge page 都会被 pin 到内核，即使只用到了其中一部分。
• 已经注册的 buffer 无法调整大小，想调整只能先 unregister，再重新 register 一个新的。

通过 eventfd() 订阅 completion 事件

可以用 eventfd(2) 订阅 io_uring 实例的 completion events。 将 eventfd 描述符通过这个系统调用注册就行了。

The credentials of the running application can be registered with io_uring which returns an id associated with those credentials. Applications wishing to share a ring between separate users/processes can pass in this credential id in the SQE personality field. If set, that particular SQE will be issued with these credentials.

2.5.3 io_uring_enter()

int io_uring_enter(unsigned int fd, unsigned int to_submit, unsigned int min_complete, unsigned int flags, sigset_t *sig);

这个系统调用用于初始化和完成（initiate and complete）I/O，使用共享的 SQ 和 CQ。 单次调用同时执行：

1. 提交新的 I/O 请求
2. 等待 I/O 完成

参数：

1. fd 是 io_uring_setup() 返回的文件描述符；
2. to_submit 指定了 SQ 中提交的 I/O 数量；

依据不同模式：

• 默认模式，如果指定了 min_complete，会等待这个数量的 I/O 事件完成再返回；

如果 io_uring 是 polling 模式，这个参数表示：

1. 0：要求内核返回当前以及完成的所有 events，无阻塞；
2. 非零：如果有事件完成，内核仍然立即返回；如果没有完成事件，内核会 poll，等待指定的次数完成，或者这个进程的时间片用完。

注意：对于 interrupt driven I/O，应用无需进入内核就能检查 CQ 的 event completions。

io_uring_enter() 支持很多操作，包括：

• Open, close, and stat files
• Read and write into multiple buffers or pre-mapped buffers
• Socket I/O operations
• Synchronize file state
• Asynchronously monitor a set of file descriptors
• Create a timeout linked to a specific operation in the ring
• Attempt to cancel an operation that is currently in flight
• Create I/O chains
• Ordered execution within a chain
• Parallel execution of multiple chains

当这个系统调用返回时，表示一定数量的 SEQ 已经被消费和提交了，此时可以安全的重用队列中的 SEQ。 此时 IO 提交有可能还停留在异步上下文中，即实际上 SQE 可能还没有被提交 —— 不过 用户不用关心这些细节 —— 当随后内核需要使用某个特定的 SQE 时，它已经复制了一份。

2.6 高级特性

io_uring 提供了一些用于特殊场景的高级特性：

1. File registration（文件注册）：每次发起一个指定文件描述的操 作，内核都需要花费一些时钟周期（cycles）将文件描述符映射到内部表示。 对于那些针对同一文件进行重复操作的场景，io_uring 支持提前注册这些文件，后面直接查找就行了。
2. Buffer registration（缓冲区注册）：与 file registration 类 似，direct I/O 场景中，内核需要 map/unmap memory areas。io_uring 支持提前 注册这些缓冲区（buffers）。
3. Poll ring（轮询环形缓冲区）：对于非常快是设备，处理中断的开 销是比较大的。io_uring 允许用户关闭中断，使用轮询模式。前面“三种工作模式”小节 也介绍到了这一点。
4. Linked operations（链接操作）：允许用户发送串联的请求。这两 个请求同时提交，但后面的会等前面的处理完才开始执行。

2.7 用户空间库 liburing

liburing 提供了一个简单的高层 API， 可用于一些基本场景，应用程序避免了直接使用更底层的系统调用。 此外，这个 API 还避免了一些重复操作的代码，如设置 io_uring 实例。

举个例子，在 io_uring_setup() 的 manpage 描述中，调用这个系统调用获得一个 ring 文 件描述符之后，应用必须调用 mmap() 来这样的逻辑需要一段略长的代码，而用 liburing 的话，下面的函数已经将上述流程封装好了：

int io_uring_queue_init(unsigned entries, struct io_uring *ring, unsigned flags);

下一节来看两个例子基于 liburing 的例子。

3 基于 liburing 的示例应用

编译：

$ git clone https://github.com/axboe/liburing.git
$ git co -b liburing-2.0 tags/liburing-2.0

$ cd liburing
$ ls examples/
io_uring-cp  io_uring-cp.c  io_uring-test  io_uring-test.c  link-cp  link-cp.c  Makefile  ucontext-cp  ucontext-cp.c

$ make -j4

$ ./examples/io_uring-test <file>
Submitted=4, completed=4, bytes=16384

$ ./examples/link-cp <in-file> <out-file>

3.1 io_uring-test

这个程序使用 4 个 SQE，从输入文件中读取最多 16KB 数据。

源码及注释

为方便看清主要逻辑，忽略了一些错误处理代码，完整代码见 io_uring-test.c。

/* SPDX-License-Identifier: MIT */
/*
 * Simple app that demonstrates how to setup an io_uring interface,
 * submit and complete IO against it, and then tear it down.
 *
 * gcc -Wall -O2 -D_GNU_SOURCE -o io_uring-test io_uring-test.c -luring
 */
#include "liburing.h"

#define QD    4 // io_uring 队列长度

int main(int argc, char *argv[]) {
    int i, fd, pending, done;
    void *buf;

    // 1. 初始化一个 io_uring 实例
    struct io_uring ring;
    ret = io_uring_queue_init(QD,    // 队列长度
                              &ring, // io_uring 实例
                              0);    // flags，0 表示默认配置，例如使用中断驱动模式

    // 2. 打开输入文件，注意这里指定了 O_DIRECT flag，内核轮询模式需要这个 flag，见前面介绍
    fd = open(argv[1], O_RDONLY | O_DIRECT);
    struct stat sb;
    fstat(fd, &sb); // 获取文件信息，例如文件长度，后面会用到

    // 3. 初始化 4 个读缓冲区
    ssize_t fsize = 0;             // 程序的最大读取长度
    struct iovec *iovecs = calloc(QD, sizeof(struct iovec));
    for (i = 0; i < QD; i++) {
        if (posix_memalign(&buf, 4096, 4096))
            return 1;
        iovecs[i].iov_base = buf;  // 起始地址
        iovecs[i].iov_len = 4096;  // 缓冲区大小
        fsize += 4096;
    }

    // 4. 依次准备 4 个 SQE 读请求，指定将随后读入的数据写入 iovecs 
    struct io_uring_sqe *sqe;
    offset = 0;
    i = 0;
    do {
        sqe = io_uring_get_sqe(&ring);  // 获取可用 SQE
        io_uring_prep_readv(sqe,        // 用这个 SQE 准备一个待提交的 read 操作
                            fd,         // 从 fd 打开的文件中读取数据
                            &iovecs[i], // iovec 地址，读到的数据写入 iovec 缓冲区
                            1,          // iovec 数量
                            offset);    // 读取操作的起始地址偏移量
        offset += iovecs[i].iov_len;    // 更新偏移量，下次使用
        i++;

        if (offset > sb.st_size)        // 如果超出了文件大小，停止准备后面的 SQE
            break;
    } while (1);

    // 5. 提交 SQE 读请求
    ret = io_uring_submit(&ring);       // 4 个 SQE 一次提交，返回提交成功的 SQE 数量
    if (ret < 0) {
        fprintf(stderr, "io_uring_submit: %s\n", strerror(-ret));
        return 1;
    } else if (ret != i) {
        fprintf(stderr, "io_uring_submit submitted less %d\n", ret);
        return 1;
    }

    // 6. 等待读请求完成（CQE）
    struct io_uring_cqe *cqe;
    done = 0;
    pending = ret;
    fsize = 0;
    for (i = 0; i < pending; i++) {
        io_uring_wait_cqe(&ring, &cqe);  // 等待系统返回一个读完成事件
        done++;

        if (cqe->res != 4096 && cqe->res + fsize != sb.st_size) {
            fprintf(stderr, "ret=%d, wanted 4096\n", cqe->res);
        }

        fsize += cqe->res;
        io_uring_cqe_seen(&ring, cqe);   // 更新 io_uring 实例的完成队列
    }

    // 7. 打印统计信息
    printf("Submitted=%d, completed=%d, bytes=%lu\n", pending, done, (unsigned long) fsize);

    // 8. 清理工作
    close(fd);
    io_uring_queue_exit(&ring);
    return 0;
}

其他说明

代码中已经添加了注释，这里再解释几点：

• 每个 SQE 都执行一个 allocated buffer，后者是用 iovec 结构描述的；
• 第 3 & 4 步：初始化所有 SQE，用于接下来的 IORING_OP_READV 操作，后者 提供了 readv(2) 系统调用的异步接口。
• 操作完成之后，这个 SQE iovec buffer 中存放的是相关 readv 操作的结果；
• 接下来调用 io_uring_wait_cqe() 来 reap CQE，并通过 cqe->res 字段验证读取的字节数；
• io_uring_cqe_seen() 通知内核这个 CQE 已经被消费了。

3.2 link-cp

link-cp 使用 io_uring 高级特性 SQE chaining 特性来复制文件。

I/O chain

io_uring 支持创建 I/O chain。一个 chain 内的 I/O 是顺序执行的，多个 I/O chain 可以并行执行。

io_uring_enter() manpage 中对 IOSQE_IO_LINK 有 详细解释：

When this flag is specified, it forms a link with the next SQE in the submission ring. That next SQE will not be started before this one completes. This, in effect, forms a chain of SQEs, which can be arbitrarily long. The tail of the chain is denoted by the first SQE that does not have this flag set. This flag has no effect on previous SQE submissions, nor does it impact SQEs that are outside of the chain tail. This means that multiple chains can be executing in parallel, or chains and individual SQEs. Only members inside the chain are serialized. A chain of SQEs will be broken, if any request in that chain ends in error. io_uring considers any unexpected result an error. This means that, eg, a short read will also terminate the remainder of the chain. If a chain of SQE links is broken, the remaining unstarted part of the chain will be terminated and completed with -ECANCELED as the error code. Available since 5.3.

为实现复制文件功能，link-cp 创建一个长度为 2 的 SQE chain。

• 第一个 SQE 是一个读请求，将数据从输入文件读到 buffer；
• 第二个请求，与第一个请求是 linked，是一个写请求，将数据从 buffer 写入输出文件。

源码及注释

/* SPDX-License-Identifier: MIT */
/*
 * Very basic proof-of-concept for doing a copy with linked SQEs. Needs a
 * bit of error handling and short read love.
 */
#include "liburing.h"

#define QD    64         // io_uring 队列长度
#define BS    (32*1024)

struct io_data {
    size_t offset;
    int index;
    struct iovec iov;
};

static int infd, outfd;
static unsigned inflight;

// 创建一个 read->write SQE chain
static void queue_rw_pair(struct io_uring *ring, off_t size, off_t offset) {
    struct io_uring_sqe *sqe;
    struct io_data *data;
    void *ptr;

    ptr = malloc(size + sizeof(*data));
    data = ptr + size;
    data->index = 0;
    data->offset = offset;
    data->iov.iov_base = ptr;
    data->iov.iov_len = size;

    sqe = io_uring_get_sqe(ring);                            // 获取可用 SQE
    io_uring_prep_readv(sqe, infd, &data->iov, 1, offset);   // 准备 read 请求
    sqe->flags |= IOSQE_IO_LINK;                             // 设置为 LINK 模式
    io_uring_sqe_set_data(sqe, data);                        // 设置 data

    sqe = io_uring_get_sqe(ring);                            // 获取另一个可用 SQE
    io_uring_prep_writev(sqe, outfd, &data->iov, 1, offset); // 准备 write 请求
    io_uring_sqe_set_data(sqe, data);                        // 设置 data
}

// 处理完成（completion）事件：释放 SQE 的内存缓冲区，通知内核已经消费了 CQE。
static int handle_cqe(struct io_uring *ring, struct io_uring_cqe *cqe) {
    struct io_data *data = io_uring_cqe_get_data(cqe);       // 获取 CQE
    data->index++;

    if (cqe->res < 0) {
        if (cqe->res == -ECANCELED) {
            queue_rw_pair(ring, BS, data->offset);
            inflight += 2;
        } else {
            printf("cqe error: %s\n", strerror(cqe->res));
            ret = 1;
        }
    }

    if (data->index == 2) {        // read->write chain 完成，释放缓冲区内存
        void *ptr = (void *) data - data->iov.iov_len;
        free(ptr);
    }

    io_uring_cqe_seen(ring, cqe);  // 通知内核已经消费了 CQE 事件
    return ret;
}

static int copy_file(struct io_uring *ring, off_t insize) {
    struct io_uring_cqe *cqe;
    size_t this_size;
    off_t offset;

    offset = 0;
    while (insize) {                      // 数据还没处理完
        int has_inflight = inflight;      // 当前正在进行中的 SQE 数量
        int depth;  // SQE 阈值，当前进行中的 SQE 数量（inflight）超过这个值之后，需要阻塞等待 CQE 完成

        while (insize && inflight < QD) { // 数据还没处理完，io_uring 队列也还没用完
            this_size = BS;
            if (this_size > insize)       // 最后一段数据不足 BS 大小
                this_size = insize;

            queue_rw_pair(ring, this_size, offset); // 创建一个 read->write chain，占用两个 SQE
            offset += this_size;
            insize -= this_size;
            inflight += 2;                // 正在进行中的 SQE 数量 +2
        }

        if (has_inflight != inflight)     // 如果有新创建的 SQE，
            io_uring_submit(ring);        // 就提交给内核

        if (insize)                       // 如果还有 data 等待处理，
            depth = QD;                   // 阈值设置 SQ 的队列长度，即 SQ 队列用完才开始阻塞等待 CQE；
        else                              // data 处理已经全部提交，
            depth = 1;                    // 阈值设置为 1，即只要还有 SQE 未完成，就阻塞等待 CQE

        // 下面这个 while 只有 SQ 队列用完或 data 全部提交之后才会执行到
        while (inflight >= depth) {       // 如果所有 SQE 都已经用完，或者所有 data read->write 请求都已经提交
            io_uring_wait_cqe(ring, &cqe);// 等待内核 completion 事件
            handle_cqe(ring, cqe);        // 处理 completion 事件：释放 SQE 内存缓冲区，通知内核 CQE 已消费
            inflight--;                   // 正在进行中的 SQE 数量 -1
        }
    }

    return 0;
}

static int setup_context(unsigned entries, struct io_uring *ring) {
    io_uring_queue_init(entries, ring, 0);
    return 0;
}

static int get_file_size(int fd, off_t *size) {
    struct stat st;

    if (fstat(fd, &st) < 0)
        return -1;
    if (S_ISREG(st.st_mode)) {
        *size = st.st_size;
        return 0;
    } else if (S_ISBLK(st.st_mode)) {
        unsigned long long bytes;

        if (ioctl(fd, BLKGETSIZE64, &bytes) != 0)
            return -1;

        *size = bytes;
        return 0;
    }

    return -1;
}

int main(int argc, char *argv[]) {
    struct io_uring ring;
    off_t insize;
    int ret;

    infd = open(argv[1], O_RDONLY);
    outfd = open(argv[2], O_WRONLY | O_CREAT | O_TRUNC, 0644);

    if (setup_context(QD, &ring))
        return 1;
    if (get_file_size(infd, &insize))
        return 1;

    ret = copy_file(&ring, insize);

    close(infd);
    close(outfd);
    io_uring_queue_exit(&ring);
    return ret;
}

其他说明

代码中实现了三个函数：

copy_file()：高层复制循环逻辑；它会调用 queue_rw_pair(ring, this_size, offset) 来构造 SQE pair； 并通过一次 io_uring_submit() 调用将所有构建的 SQE pair 提交。

这个函数维护了一个最大 DQ 数量的 inflight SQE，只要数据 copy 还在进行中；否则，即数据已经全部读取完成，就开始等待和收割所有的 CQE。

queue_rw_pair() 构造一个 read-write SQE pair.

read SQE 的 IOSQE_IO_LINK flag 表示开始一个 chain，write SQE 不用设置这个 flag，标志着这个 chain 的结束。 用户 data 字段设置为同一个 data 描述符，并且在随后的 completion 处理中会用到。

handle_cqe() 从 CQE 中提取之前由 queue_rw_pair() 保存的 data 描述符，并在描述符中记录处理进展（index）。

如果之前请求被取消，它还会重新提交 read-write pair。

一个 CQE pair 的两个 member 都处理完成之后（index==2），释放共享的 data descriptor。 最后通知内核这个 CQE 已经被消费。

4 io_uring 性能压测（基于 fio）

对于已经在使用 linux-aio 的应用，例如 ScyllaDB， 不要期望换成 io_uring 之后能获得大幅的性能提升，这是因为： io_uring 性能相关的底层机制与 linux-aio 并无本质不同（都是异步提交，轮询结果）。

在此，本文也希望使读者明白：io_uring 首先和最重要的贡献在于： 将 linux-aio 的所有优良特性带给了普罗大众（而非局限于数据库这样的细分领域）。

4.1 测试环境

本节使用 fio 测试 4 种模式：

1. synchronous reads
2. posix-aio (implemented as a thread pool)
3. linux-aio
4. io_uring

硬件：

• NVMe 存储设备，物理极限能打到 3.5M IOPS。
• 8 核处理器

4.2 场景一：direct I/O 1KB 随机读（绕过 page cache）

第一组测试中，我们希望所有的读请求都能命中存储设备（all reads to hit the storage），完全绕开操作系统的页缓存（page cache）。

测试配置：

• 8 个 CPU 执行 72 fio job，
• 每个 job 随机读取 4 个文件，
• iodepth=8（number of I/O units to keep in flight against the file.）。

这种配置保证了 CPU 处于饱和状态，便于观察 I/O 性能。 如果 CPU 数量足够多，那每组测试都可能会打满设备带宽，结果对 I/O 压测就没意义了。

表 1. Direct I/O（绕过系统页缓存）：1KB 随机读，CPU 100% 下的 I/O 性能

几点分析：

1. io_uring 相比 linux-aio 确实有一定提升，但并非革命性的。
2. 开启高级特性，例如 buffer & file registration 之后性能有进一步提升 —— 但也还 没有到为了这些性能而重写整个应用的地步，除非你是搞数据库研发，想榨取硬件的最后一分性能。

io_uring and linux-aio 都比同步 read 接口快 2 倍，而后者又比 posix-aio 快 2 倍 —— 初看有点差异。但看看上下文切换次数，就不难理解为什么 posix-aio 这么慢了。

• 同步 read 性能差是因为：在这种没有 page cache 的情况下， 每次 read 系统调用都会阻塞，因此就会涉及一次上下文切换。
• posix-aio 性能更差是因为：不仅内核和应用程序之间要频繁上下文切换，线程池的多个线程之间也在频繁切换。

4.2 场景二：buffered I/O 1KB 随机读（数据提前加载到内存，100% hot cache）

第二组测试 buffered I/O：

将文件数据提前加载到内存，然后再测随机读。

• 由于数据全部在 page cache，因此同步 read 永远不会阻塞。
• 这种场景下，我们预期同步读和 io_uring 的性能差距不大（都是最好的）。

1. 其他测试条件不变。

表 2. Buffered I/O（数据全部来自 page cache，100% hot cache）：1KB 随机读，100% CPU 下的 I/O 性能

结果分析：

同步读和 io_uring 性能差距确实很小，二者都是最好的。

但注意，实际的应用不可能一直 100% 时间执行 IO 操作，因此 基于同步读的真实应用性能还是要比基于 io_uring 要差的，因为 io_uring 会将多个系统调用批处理化。

1. posix-aio 性能最差，直接原因是上下文切换次数太多，这也和场景相关： 在这种 CPU 饱和的情况下，它的线程池反而是累赘，会完全拖慢性能。
2. linux-aio 并不是针对 buffered I/O 设计的，在这种 page cache 直接返回的场景， 它的异步接口反而会造成性能损失 —— 将操作分 为 dispatch 和 consume 两步不但没有性能收益，反而有额外开销。

4.3 性能测试小结

最后再次提醒，本节是极端应用/场景（100% CPU + 100% cache miss/hit）测试， 真实应用的行为通常处于同步读和异步读之间：时而一些阻塞操作，时而一些非阻塞操作。 但不管怎么说，用了 io_uring 之后，用户就无需担心同步和异步各占多少比例了，因为它在任何场景下都表现良好。

1. 如果操作是非阻塞的，io_uring 不会有额外开销；
2. 如果操作是阻塞式的，也没关系，io_uring 是完全异步的，并且不依赖线程池或昂贵的上下文切换来实现这种异步能力；

本文测试的都是随机读，但对其他类型的操作，io_uring 表现也是非常良好的。例如：

1. 打开/关闭文件
2. 设置定时器
3. 通过 network sockets 传输数据

而且使用的是同一套 io_uring 接口。

4.4 ScyllaDB 与 io_uring

Scylla 重度依赖 direct I/O，从一开始就使用 linux-aio。 在我们转向 io_uring 的过程中，最开始测试显示对某些 workloads，能取得 50% 以上的性能提升。 但深入研究之后发现，这是因为我们之前的 linux-aio 用的不够好。 这也揭示了一个经常被忽视的事实：获得高性能没有那么难（前提是你得弄对了）。 在对比 io_uring 和 linux-aio 应用之后，我们很快改进了一版，二者的性能差距就消失了。 但坦率地说，解决这个问题需要一些工作量，因为要改动一个已经使用 了很多年的基于 linux-aio 的接口。而对 io_uring 应用来说，做类似的改动是轻而 易举的。

以上只是一个场景，io_uring 相比 linux-aio 的优势是能应用于 file I/O 之外的场景。 此外，它还自带了特殊的 高性能 接口，例如 buffer registration、file registration、轮询模式等等。

启用 io_uring 高级特性之后，我们看到性能确实有提升：Intel Optane 设备，单个 CPU 读取 512 字节，观察到 5% 的性能提升。与 表 1 & 2 对得上。虽然 5% 的提升 看上去不是太大，但对于希望压榨出硬件所有性能的数据库来说，还是非常宝贵的。

5 eBPF

eBPF 也是一个事件驱动框架（因此也是异步的），允许用户空间程序动态向内核注入字节码，主要有两个使用场景：

1. Networking：本站 已经有相当多的文章
2. Tracing & Observability：例如 bcc 等工具

eBPF 在内核 4.9 首次引入，4.19 以后功能已经很强大。更多关于 eBPF 的演进信息，可参考： （译）大规模微服务利器：eBPF + Kubernetes（KubeCon, 2020）。

谈到与 io_uring 的结合，就是用 bcc 之类的工具跟踪一些 I/O 相关的内核函数，例如：

1. Trace how much time an application spends sleeping, and what led to those sleeps. (wakeuptime)
2. Find all programs in the system that reached a particular place in the code (trace)
3. Analyze network TCP throughput aggregated by subnet (tcpsubnet)
4. Measure how much time the kernel spent processing softirqs (softirqs)
5. Capture information about all short-lived files, where they come from, and for how long they were opened (filelife)

6 结束语

io_uring 和 eBPF 这两大特性将给 Linux 编程带来革命性的变化。 有了这两个特性的加持，开发者就能更充分地利用 Amazon i3en meganode systems 之类的多核/多处理器系统，以及 Intel Optane 持久存储 之类的 us 级延迟存储设备。

参考资料

• Efficient IO with io_uring, pdf
• Ringing in a new asynchronous I/O API, lwn.net
• The rapid growth of io_uring, lwn.net
• System call API, manpage

原文:https://arthurchiao.art/blog/intro-to-io-uring-zh/

makefile 不会写，cmake 虽然常用，但文档太烂了，真不好用。前一段有同事说 xmake 不错，试试

安装

官方网站有脚本可以直接下载安装，这里是 github 下载的安装包

./xmake-v2.8.1.gz.run

测试

不会写makefile？没关系，直接在源码目录运行以下命令即可直接编译:

xmake
xmake -P .

xmake f -m release
xmake f -p cross --cross=arm-linux-gnueabihf- -m release

xmake build -j4
xmake install -o install/armhf
xmake uninstall
xmake clean

xmake会自动扫描在当前目录下的源码结构，生成一个xmake.lua工程描述文件，然后尝试直接编译。

想要直接运行编译后的可执行程序，简单，直接敲:

xmake run

创建项目

xmake create -l c++ -t qt.quickapp test
xmake create -l c -t test
xmake project -k vs2017 -m "debug,release"
xmake project -k makefile

静态库

xmake create -l c -t static test

动态库

xmake create -l c -t shared test

手工填写 xmake.lua

target("test")
    set_kind("binary") 
    add_files("src/*.c")
    
target("test") 
    set_kind("static") 
    add_files("src/*.c")
    add_files("lib/libxxx.a", "obj/bbb.o")
    
target("test")
    set_kind("binary") 
    add_files("src/*.c") 
    if is_mode("debug") then 
        add_cxflags("-DDEBUG") 
    end
    
target("test") 
    set_kind("binary") 
    add_files("src/*.c") 
    after_build(function (target) 
        os.exec("file %s", target:targetfile()) 
    end)

添加依赖

target("test") 
    set_kind("static") 
    add_files("src/test/*.c") 
target("hello") 
    add_deps("test") --添加依赖 
    set_kind("binary") 
    add_files("src/hello/*.c")

直接运行

xmake run

如果有多个target目标，你可以指定需要运行的target名，例如:

xmake run test

想要快速调试程序？加上-d参数即可

xmake run -d test

界面

xmake f --menu

可以显示指定 target 配置信息，可以看到各种配置来源于哪个配置文件和具体的行数。

xmake show -t <target>

检查工程配置和代码。

xmake check

xrepo项目

xmake create -l c++ test

xmake.lua 文件

add_rules("mode.debug", "mode.release")
add_requires("cereal")
target("test")
    set_kind("binary")
    add_files("src/*.cpp")
    add_packages("cereal")

github 无法下载，手工下载

mkdir lib && cd lib
wget -O cereal-1.3.2.tar.gz https://ghproxy.com/https://github.com/USCiLab/cereal/archive/refs/tags/v1.3.2.tar.gz

设置搜索库绝对路径

xmake --pkg_searchdirs="/mnt/d/Download/test/lib/"

编译

xmake

看起来可以，不过本地没有头文件，看起来也不太舒服

语义版本设置

Xmake 的依赖包管理是完全支持语义版本选择的，例如：”~1.6.1”，对于语义版本的具体描述见：https://semver.org/

比如下面一些语义版本写法：

add_requires("tbox 1.6.*", "pcre 1.3.x", "libpng ^1.18") 
add_requires("libpng ~1.16", "zlib 1.1.2 || >=1.2.11 <1.3.0")

当然，如果我们对当前的依赖包的版本没有特殊要求，那么可以直接这么写：

add_requires("tbox", "libpng", "zlib")

这会使用已知的最新版本包，或者是master分支的源码编译的包，如果当前包有git repo地址，我们也能指定特定分支版本：

add_requires("tbox master") 
add_requires("tbox dev")

Xmake 的语义版本支持，在几年前就已经很好的支持，而 vcpkg 也仅仅在最近一年才通过清单模式勉强支持它。

即使现在，vcpkg 对版本语义的支持也很受限，只能支持 >=1.0, 1.0 等几种版本模式，想要选择任意版本的包，比如 >=1.0 <1.5 等复杂版本条件的包，vcpkg 还是无法支持。

可选包设置

如果指定的依赖包当前平台不支持，或者编译安装失败了，那么 Xmake 会编译报错，这对于有些必须要依赖某些包才能工作的项目，这是合理的。 但是如果有些包是可选的依赖，即使没有也可以正常编译使用的话，可以设置为可选包：

add_requires("tbox", {optional = true})

使用系统库

默认的设置，Xmake 会去优先检测系统库是否存在（如果没设置版本要求），如果用户完全不想使用系统库以及第三方包管理提供的库，那么可以设置：

add_requires("tbox", {system = false})

而如果配置成：

add_requires("tbox", {system = true})

就是仅仅查找使用系统库，不会去远程下载安装它，这类似于 CMake 的 find_package，但是集成方式更加简单一致。

使用调试版本的包

如果我们想同时源码调试依赖包，那么可以设置为使用debug版本的包（当然前提是这个包支持debug编译）：

add_requires("tbox", {debug = true})

启用包的可选特性

我们也可以安装带有指定特性的包，比如安装开启了 zlib 和 libx265 的 ffmpeg 包。

add_requires("ffmpeg", {configs = {zlib = true, libx265 = true}})

传递额外的编译选项

我们也可以传递额外的编译选项给包：

add_requires("spdlog", {configs = {cxflags = "-Dxxx"}})

独立的包管理命令 Xrepo

Xrepo 是一个基于 Xmake 的跨平台 C/C++ 包管理器。

它是一个独立于 Xmake 的命令程序，用于辅助用户去管理依赖包，类似 vcpkg/conan，但相比它们，有额外多了一些实用的特性，我们会简单介绍一些。

多仓库管理

除了可以直接从官方仓库：xmake-repo 检索安装包之外， 我们还可以添加任意多个自建的仓库，甚至可以完全隔离外网，仅仅在公司内部网络维护私有包的安装集成。

只需要通过下面的命令，添加上自己的仓库地址：

xrepo add-repo myrepo https://github.com/mygroup/myrepo

基本使用

xrepo install zlib tbox

安装指定版本包

完整支持 Semantic Versioning (语义版本)。

xrepo install "zlib 1.2.x" 
xrepo install "zlib >=1.2.0"

安装指定平台包

xrepo install -p iphoneos -a arm64 zlib 
xrepo install -p android [--ndk=/xxx] zlib 
xrepo install -p mingw [--mingw=/xxx] zlib 
xrepo install -p cross --sdk=/xxx/arm-linux-musleabi-cross zlib

安装调试版本包

xrepo install -m debug zlib

安装动态库版本包

xrepo install -k shared zlib

安装指定配置包

xrepo install -f "vs_runtime=MD" zlib 
xrepo install -f "regex=true,thread=true" boost

安装第三方包管理器的包

xrepo install brew::zlib 
xrepo install vcpkg::zlib 
xrepo install conan::zlib/1.2.11

查看包的库使用信息

xrepo fetch pcre2 { { linkdirs = { "/usr/local/Cellar/pcre2/10.33/lib" }, links = { "pcre2-8" }, defines = { "PCRE2_CODE_UNIT_WIDTH=8" }, includedirs = "/usr/local/Cellar/pcre2/10.33/include" } }

导入导出安装后的包

xrepo 可以快速导出已经安装后的包，包括对应的库文件，头文件等等。

xrepo export -o /tmp/output zlib

也可以在其他机器上导入之前导出的安装包，实现包的迁移。

xrepo import -i /xxx/packagedir zlib

搜索支持的包

xrepo search zlib "pcr*" 
    zlib: 
      -> zlib: A Massively Spiffy Yet Delicately Unobtrusive Compression Library (in xmake-repo) 
    pcr*:
      -> pcre2: A Perl Compatible Regular Expressions Library (in xmake-repo) 
      -> pcre: A Perl Compatible Regular Expressions Library (in xmake-repo)

另外，现在还可以从 vcpkg, conan, conda 以及 apt 等第三方包管理器中搜索它们的包，只需要加上对应的包命名空间就行，例如：

xrepo search vcpkg::pcre 
The package names: 
    vcpkg::pcre: 
      -> vcpkg::pcre-8.44
      #8: Perl Compatible Regular Expressions -> vcpkg::pcre2-10.35
      #2: PCRE2 is a re-working of the original Perl Compatible Regular Expressions library

包虚拟环境管理

我们可以通过在当前目录下，添加 xmake.lua 文件，定制化一些包配置，然后进入特定的包 shell 环境。

add_requires("zlib 1.2.11") 
add_requires("python 3.x", "luajit")

进行虚拟环境：

xrepo env shell 
python --version 
luajit --version

在 Xmake 中集成第三方构建系统

在 Xmake 中集成 Cmake 项目

Xmake 并不打算分裂 C/C++ 生态，它能很好和兼容复用现有 cmake/autoconf/meson 维护的项目，比如可以将一些其他使用 CMake 维护的代码库，直接本地集成进来，参与混合编译。

也就是说，Xmake 不会强制用户将所有的项目重新 port 到 xmake.lua，现有的 CMake 项目，一样可以快速集成到 Xmake 项目中去。

例如，我们有如下项目结构：

.
├── foo 
│ ├── CMakeLists.txt 
│ └── src 
│ ├── foo.c 
│ └── foo.h 
├── src 
│ └── main.c 
├── test.lua 
└── xmake.lua

foo 目录下是一个使用 CMake 维护的静态库，而根目录下使用了 Xmake 来维护，我们可以在 xmake.lua 中通过定义 package("foo") 包来描述如何构建 foo 代码库。

add_rules("mode.debug", "mode.release") 

package("foo") 
add_deps("cmake") 
set_sourcedir(path.join(os.scriptdir(), "foo")) 
on_install(function (package) 
local configs = {} 
table.insert(configs, "-DCMAKE_BUILD_TYPE=" .. (package:debug() and "Debug" or "Release")) 
table.insert(configs, "-DBUILD_SHARED_LIBS=" .. (package:config("shared") and "ON" or "OFF")) 
import("package.tools.cmake").install(package, configs) 
end) 

on_test(function (package) 
assert(package:has_cfuncs("add", {includes = "foo.h"})) 
end) 
package_end() 

add_requires("foo") 
target("demo") 
set_kind("binary") 
add_files("src/main.c") 
add_packages("foo")

其中，我们通过 set_sourcedir() 来设置 foo 包的代码目录位置，然后通过 import 导入 package.tools.cmake 辅助模块来调用 cmake 构建代码，xmake 会自动获取生成的 libfoo.a 和对应的头文件。

如果仅仅本地源码集成，我们不需要额外设置 add_urls 和 add_versions。

定义完包后，我们就可以通过 add_requires("foo") 和 add_packages("foo") 来集成使用它了，就跟集成远程包一样的使用方式。

另外，on_test 是可选的，如果想要严格检测包的编译安装是否成功，可以在里面做一些测试。

在 Xmake 中集成 Autoconf 项目

我们也可以使用 package.tools.autoconf 来本地集成带有 autoconf 维护的第三方代码库。

package("libev") 
set_sourcedir(path.join(os.scriptdir(), "3rd/libev")) 

on_install(function (package) 
import("package.tools.autoconf").install(package) 
end)

package.tools.autoconf 和 package.tools.cmake 模块都是可以支持 mingw/cross/iphoneos/android 等交叉编译平台和工具链的，xmake 会自动传递对应的工具链进去，用户不需要做任何其他事情。

在 Xmake 中集成 Gn 项目

我们也可以使用 package.tools.gn 来本地集成带有 GN 维护的第三方代码库。

package("skia") 
set_sourcedir(path.join(os.scriptdir(), "3rd/skia")) 
add_deps("gn", "ninja") 

on_install(function (package) 
import("package.tools.gn").install(package) 
end)

在 Xmake 中查找使用 CMake/C++ 包

现在 CMake 已经是事实上的标准，所以 CMake 提供的 find_package 已经可以查找大量的系统库和模块，我们也可以完全复用 CMake 的这部分生态来扩充 xmake 对包的集成。

只需要像集成 vcpkg/conan 包那样，将包命名空间改成 cmake:: 就可以了。

add_requires("cmake::ZLIB", {alias = "zlib", system = true}) 

target("test") 
set_kind("binary") 
add_files("src/*.c") 
add_packages("zlib")

我们指定 system = true 告诉 xmake 强制从系统中调用 cmake 查找包，如果找不到，不再走安装逻辑，因为 cmake 没有提供类似 vcpkg/conan 等包管理器的安装功能，只提供了包查找特性。

指定版本

add_requires("cmake::OpenCV 4.1.1", {system = true})

指定组件

add_requires("cmake::Boost", {system = true, configs = {components = {"regex", "system"}})}

预设开关

add_requires("cmake::Boost", {system = true, configs = {components = {"regex", "system"}, presets = {Boost_USE_STATIC_LIB = true}}})

相当于内部调用 find_package 查找包之前，在 CMakeLists.txt 中预定义一些配置，控制 find_package 的查找策略和状态。

set(Boost_USE_STATIC_LIB ON) 
-- will be used in FindBoost.cmake find_package(Boost REQUIRED COMPONENTS regex system)

设置环境变量

add_requires("cmake::OpenCV", {system = true, configs = {envs = {CMAKE_PREFIX_PATH = "xxx"}}})

指定自定义 FindFoo.cmake 模块脚本目录
mydir/cmake_modules/FindFoo.cmake

add_requires("cmake::Foo", {system = true, configs = {moduledirs = "mydir/cmake_modules"}})

在 Cmake 中集成 Xrepo 依赖包

除了可以在 Xmake 中集成 CMake 项目，我们也可以在 CMake 中直接集成 Xmake/Xrepo 提供的包，只需要使用 xrepo-cmake 提供的 CMake Wrapper。

例如：

cmake_minimum_required(VERSION 3.13.0) 
project(foo)

# Download xrepo.cmake if not exists in build directory. 
if(NOT EXISTS "${CMAKE_BINARY_DIR}/xrepo.cmake") 
    message(STATUS "Downloading xrepo.cmake from https://github.com/xmake-io/xrepo-cmake/") 

    # mirror https://cdn.jsdelivr.net/gh/xmake-io/xrepo-cmake@main/xrepo.cmake 
    file(DOWNLOAD "https://raw.githubusercontent.com/xmake-io/xrepo-cmake/main/xrepo.cmake" "${CMAKE_BINARY_DIR}/xrepo.cmake" TLS_VERIFY ON) 
endif() 

# Include xrepo.cmake so we can use xrepo_package function. 
include(${CMAKE_BINARY_DIR}/xrepo.cmake) 
xrepo_package("zlib") 
add_executable(example-bin "") 
target_sources(example-bin PRIVATE src/main.cpp ) 
xrepo_target_packages(example-bin zlib)

添加带有配置的包

我们，也可以跟在 Xmake 中一样，定制包的可选特性。

xrepo_package("gflags 2.2.2" CONFIGS "shared=true,mt=true") 
add_executable(example-bin "") 
target_sources(example-bin PRIVATE src/main.cpp ) 
xrepo_target_packages(example-bin gflags)

使用来自第三个存储库的包

除了从 Xmake 官方维护的存储库安装软件包之外，我们也可以直接在 CMake 中使用它来安装来自第三方仓库的包，只需将仓库名称添加为命名空间即可。

例如：vcpkg::zlib, conan::pcre2。

xrepo_package("conan::gflags/2.2.2") 
xrepo_package("conda::gflags 2.2.2") 
xrepo_package("vcpkg::gflags")
xrepo_package("brew::gflags")

通过这种方式，我们将在 CMake 中集成使用 vcpkg/conan 包的方式进行了统一，并且额外提供了自动包安装特性，以及对 homebrew/conda 等其他包仓库的支持。

xmake-vscode 插件

我们之前的所有实验，都是使用 xmake 的命令行程序在终端下操作完成的，这对于一些初学者来说还是有不少门槛的，并且操作起来也不能够像其它 IDE 等带有可视化界面的开发环境那样顺手，尤其是代码的编辑、编译和断点调试都需要不停的切换各种终端、编辑器环境才能完成。

为了方便我们的日常开发，xmake 官方提供了可以快速无缝集成到 Visual Studio Code 编辑器的 xmake-vscode 插件，使用这个插件我们可以通过 vscode 编辑器环境来一站式进行 C/C++ 程序开发，内置 xmake 编译、断点调试、编译错误分析定位、编译配置的快速切换等各种实用功能。

而 Visual Studio Code 编辑器是微软推出的一款轻量级跨平台的编辑器，具有非常好的跨平台性、可扩展性，我们在实验环境的桌面上，就能找到带有 Visual Studio Code 字样的图标，双击运行就可以打开它。

安装 xmake-vscode 插件

首先在环境中安装 xmake，执行如下命令：

bash <(curl -kfsSL https://labfile.oss.aliyuncs.com/courses/2764/shget.text) v2.3.7
source ~/.xmake/profile

检查版本，验证安装成功

xmake --version

在使用 xmake-vscode 插件之前，我们需要安装它，安装过程很简单，只需要切换到 vscode 的插件扩展 tab 页，然后输入 xmake 搜索相关插件。

如果看到下图所示内容，说明我们已经成功找到了 xmake-vscode 插件，然后点击旁边的 Install 字样按钮就可以完成安装了。

创建和打开 C/C++ 工程

插件安装完成后，我们可以先来创建一个空的 C 工程，之前介绍过可以使用 xmake create 命令来创建工程。但是这里我们打算直接使用 xmake-vscode 插件提供的工程创建功能来完成 C/C++ 工程的创建。

在创建之前，需要先准备一个空目录用来存放工程文件，例如将工程放置在 ~/Code/vscode_test 目录下，如果还不存在此目录，可以先手动创建下。

然后，我们直接在 vscode 里面打开这个空目录，只需要通过点击下图红框位置的按钮。

点击后，我们进入刚刚创建的 vscode_test 目录，选中并打开它。

打开目录后，我们就可以开始创建工程文件了，继续进入菜单的 view 子菜单打开 vscode 里面的命令面板，如下图。

命令面板打开后，我们输入 xmake 字符串，就会看到一系列跟 xmake 插件相关的命令，然后从其中找到带 Create Project 字样的命令。

这个时候，由于当前还没有 xmake.lua 文件，会在底下弹出一个提示框，继续点击里面的蓝色按钮。
接着就会弹出编程语言的选择列表，这里选择第二项，也就是 C++ 语言。

选择完语言后，还会提示选择工程类型，这里选择 console 终端程序类型。

选择完成后，整个项目就创建好了，下图左边就是新创建的工程文件，根目录下有 xmake.lua，而图最底下的工具栏就是 xmake 插件的操作面板了，我们的大部分操作都可以通过这个面板快速完成，包括：编译、运行、调试以及配置切换等等。

工具栏面板介绍

创建完成工程后，我们会看到 vscode 底部工具链出现了一排跟 xmake 相关的操作面板，xmake 的大部分操作都可以通过这个面板上的工具按钮来快速完成。

另外，不仅仅是创建工程，如果安装 xmake-vscode 插件后，使用 vscode 打开一个带有 xmake.lua 文件的 C/C++ 工程根目录，那么 vscode 底部的 xmake 工具栏面板也会被自动激活。

通过上图，我们大概能知道每个按钮的具体功能，具体更进一步的使用方式，我们会接下来会挨个讲解。

编译 C/C++ 程序

刚刚我们通过 vscode 创建的一个 C++ 项目工程，其内部就是执行了 xmake 的 xmake create vscode_test 命令来完成的，整个工程文件结构如下。

.
├── src
│   └── main.cpp
└── xmake.lua

在编译之前，先调整下生成的 xmake.lua 文件，修改成如下配置。

add_rules("mode.debug", "mode.release")

target("test")
set_kind("binary")
add_files("src/*.cpp")

其实，也就是将程序目标名改成 test，然后点击 vscode 底下的 xmake 工具栏里面的 Build 按钮，来编译我们新创建的 C++ 工程。

运行程序

编译完成后就可以尝试运行程序了，还是使用底下的工具栏按钮，点击运行图标。
如果运行成功，就会看到实际的运行输出信息：Hello world!。

调试程序

接下来，我们重点讲解如何通过 vscode 配合 xmake-vscode 插件来实现断点调试 C/C++ 程序。

不过在调试前还需要做一些准备工作，由于默认 xmake 采用 release 模式编译的目标程序，是不带调试符号信息的，因此我们需要先将编译模式切换到 debug 调式编译模式去重新编译它，使其带上调试符号信息。

具体如何切换到 debug 模式，可以参考下图的操作，点击底下 release 文本所在的按钮，然后在上面列出的列表中，选择 debug 项即可。

完成切换后可以看到底下的 release 按钮已经变成了 debug 字样，然后点击 build 按钮，就可以重新编译带有调试符号的目标程序了。

调试版本程序编译完成后，还需要额外做一件事，那就是安装 vscode 的 C/C++ 插件，因为 xmake-vscode 插件的调试功能是基于这个插件的，我们仅仅只需要首次使用时安装它即可。

重新切到插件市场页面，搜索 C/C++，显示出来的第一项就是，点击 Install 安装即可。

安装好 C/C++ 插件，就可以开始调试操作了。首先点击 main.cpp 打开源文件，然后在需要下断点的代码行左侧位置点击下断点，如果出现小红点，说明已经成功下好了调试断点。

断点下好后，就可以点击底下的调试按钮，开启断点调试了，如果一切顺利，程序运行起来后就会命中刚刚设置的断点。

目标程序切换

接下来再来详细讲解编译，之前我们已经使用过 build 按钮来编译工程，但如果一个项目中存在多个目标程序又不想全部编译，我们就需要指定编译哪个目标程序。

在命令行中，我们可以通过 xmake build test 命令来显示的指定编译哪个目标，而在 vscode 中，xmake 插件也提供了很方便的目标切换操作，来快速切换编译。

首先修改 xmake.lua 文件，新增一个名为 test2 的目标程序，用于之后的目标切换测试，例如。

add_rules("mode.debug", "mode.release")

target("test")
set_kind("binary")
add_files("src/*.cpp")

target("test2")
set_kind("binary")
add_files("src/*.cpp")

然后点击底下 default 字样的按钮，之后会在顶部显示整个项目所有目标程序名的列表，我们点击其中的 test2 目标程序，就可以完成切换。

如果切换成功，底下的 default 文本就会变成 test2，由于默认编译 xmake 会自动编译所有目标程序，所以最初显示的是 default 文本。

这个时候，我们再执行编译，就能看到实际仅仅只编译了我们指定的 test2 目标程序。

编译错误信息

如果我们的工程代码没写对导致编译出错，可以直接从编译输出中看到错误信息。

而 xmake-vscode 插件还会自动解析编译错误输出信息，分类每个编译错误，并可通过双击指定错误，跳转定位到指定的错误代码位置，也就是下图所示位置。

查看编译详细信息

在命令行中，我们可以通过 xmake -v 来查看编译过程中的详细命令参数信息，而在 vscode 中同样可以通过配置开启详细输出。

首先打开菜单，点击 File -> Preferences -> Settings 子菜单。

然后在打开的 Setting 配置页面，输入 xmake 找到所有跟 xmake 插件相关的配置项，其中有一项是 BuildLevel，它就是用于设置编译过程中的输出信息级别。

默认是 warnings 级别，仅仅输出编译警告信息以及正常信息，我们把它改为 verbose 级别，就可以输出完整的编译命令行参数了。

至于 debug 级别对应的就是 xmake -vD 的诊断信息，还会进一步打印出错的栈信息。

我们这里将配置切换成 verbose 级别后，再重新构建下程序，看看实际的输出是怎样的。不过由于底部只提供了 build 按钮，没有 rebuild 按钮，为了执行重新编译，我们需要从菜单里面的命令面板中，找到 xmake 的 Rebuild 命令，点击执行才行。

从下图的红色箭头位置找到对应的命令面板。

然后再打开的命令面板中输入 xmake 过滤出所有跟 xmake 相关的命令列表，找到 Rebuild 命令后点击编译即可，如下图。

开启 verbose 级别后，我们就能看到编译输出中完整的命令参数了。

xmake.lua 编辑和自动补全

xmake-vscode 插件还内置了对 xmake.lua 文件编写时的自动提示和补全支持，我们只需要输入 add_、set_ 等字样的文本，就会自动列举出与其相关的所有 api 供我们使用，来方便快速配置 xmake.lua。

我们可以通过编辑 xmake.lua 文件对里面 test2 目标程序添加一个 add_defines("TEST2") 来体验下自动补全功能。

最终的完整配置内容如下。

add_rules("mode.debug", "mode.release")

target("test")
set_kind("binary")
add_files("src/*.cpp")

target("test2")
set_kind("binary")
add_files("src/*.cpp")
add_defines("TEST2")

而我们输入时的补全特性可以通过下面的图片体会到。

完成配置后，我们再来点击底下的 Build 按钮执行编译，看下详细命令输出，应该能够正常看到新加上的 -DTEST2 宏定义了。

简单使用还挺不错，以后尽量不用 cmake 了。
后面那些都是来自官网，我也没看完，备用吧。

原来笔记本上买的 UOS 家庭版系统，用着还可以，不过这一年多没用了，最近进去升了下级，结果启动不了了。。没办法，Linux 目前还是这熊样。

折腾过程如下

升级系统，结果开机进不去系统，显示 i8042-present:0，硬盘灯不亮了

grub 选安全模式进去，没法上网。。。这 TM 怎么想的。
uos 的软件包还不能在系统外下载，坑爹的货。。。

重启 grub 按 e 进入编辑模式，ro 开始改成

rw single init=/bin/bash

ctrl+x 重新引导，单用户模式，卡在 random: crng init done

估计是更新的内核太新，不兼容老机器。

deepin 官网上下载 livecd 的 iso，u 盘制作启动盘。重启 F12 选择，可以引导进去，可以网线上网。。。还好

重新挂载系统盘

df -h
sudo umount /dev/sda2
sudo mount /dev/sda2 /mnt 

chroot 进系统盘

sudo chroot /mnt

apt 安装老版本内核

sudo apt install linux-headers-5.4.50-amd64-desktop
sudo apt install linux-image-5.4.50-amd64-desktop

各种报错。貌似需要先 mount 一些系统目录

sudo mount -t proc proc /mnt/proc
sudo mount -t sysfs sys /mnt/sys
sudo mount -o bind /dev /mnt/dev
sudo chroot /mnt

能安装内核和生成 initramfs，但更新不了 grub。

重启 grub 按 e，把内核版本改成新安装的老版本内核
ctrl+x。。。终于进去系统了

赶紧把刚才乱安装的包，该删的删，没装好的装上，更新 grub

sudo update_grub2

重启测下没问题，系统引导正常。

MSDK V5 发布了

MSDK V5 支持的产品：

• DJI Mavic 3 Enterprise Series
• M30 Series
• M300 RTK

DJI Mobile SDK V4 Android 最新版本 4.16.4

这是什么？

DJI Mobile SDK 使您能够自动化您的 DJI 产品。你可以控制飞行，以及产品的许多子系统，包括相机和万向节。使用移动 SDK，创建一个定制的移动应用程序，以释放您的 DJI 空中平台的全部潜力。

整合

通过 Maven 声明依赖关系：

<dependency>
    <groupId>com.dji</groupId>
    <artifactId>dji-sdk</artifactId>
    <version>4.16.4</version>
</dependency>

<dependency>
    <groupId>com.dji</groupId>
    <artifactId>dji-sdk-provided</artifactId>
    <version>4.16.4</version>
</dependency>

或者 Gradle:

compile 'com.dji:dji-sdk:4.16.4'
provided 'com.dji:dji-sdk-provided:4.16.4'

有关如何将 DJI Android SDK 集成到您的 Android Studio 项目中的更多详细信息，请查看将 SDK 集成到应用程序中教程。

运行 SDK 示例代码

开发人员可以运行示例应用程序来立即运行代码，并查看如何使用 DJI Mobile SDK。

需要 一架 DJI 飞机或手持摄像机才能运行示例应用程序。

开发工作流

从注册为开发人员到部署应用程序，以下内容将带您完成完整的 Mobile SDK 应用程序开发过程：

• 前置条件
• 注册成为大疆开发者并下载 SDK
• 将 SDK 集成到应用程序中
• 运行应用程序
• 测试、分析和调试
• 部署

示例项目和教程

提供了几个 Android 教程作为示例，介绍如何使用 Mobile SDK 的不同功能，调试工具包括：

• 应用程序激活和飞机绑定
• UX SDK 入门
• 相机应用程序
• MapView 和 Waypoint 应用程序（高德地图）
• MapView 和航路点应用程序（GoogleMap）
• TapFly 和 ActiveTrack 应用程序
• 模拟器应用程序
• GEO 系统应用

了解有关 DJI 产品和移动 SDK 的更多信息

请访问 DJI Mobile SDK 文档了解更多详细信息。

DJI Mobile UX SDK

DJI Mobile UX SDK 是一套与产品无关的 UI 对象，可使用 DJI Mobile SDK 快速跟踪 iOS 应用程序的开发。有关更多详细信息，请查看此处。

设备运行状况信息 Json 文件

您可以在该 repo 的根文件夹中找到 hms.json 和 hms_match_sdkerror.json 文件。

它包含错误代码和设备组件的详细说明。仅由 Matrice 300 RTK 和 Zenmuse H20 系列的某些组件支持。

建议使用设备健康信息来替换飞行控制器和 RTK 的旧诊断。Matrice 300 RTK 上的万向节、电池、感知模块会有一些重复的组件错误。

重复性错误请参阅下表：

ProGuard

如果您计划使用 ProGuard 优化您的应用程序，您可以将以下规则添加到应用程序的 proguard.cfg 文件中：

• 对于 AAR 文件，请使用以下规则：

"-libraryjars ./PATH_TO_THIS_FILE/dji_android_sdk.aar"

• 对于 API 库文件夹，请使用 proguard-project 中的规则文件。

注：DJI Android SDK 有两种类型：AAR 和 API 库文件夹，您可以从 DJI 开发者网站下载：http://developer.dji.com/mobile-sdk/downloads/。

SDK 密钥

SDK 密钥可以用作访问产品的替代接口。

SDK 密钥的详细介绍在这里.

任务重构器

任务是 SDK 的重要组成部分，因为它们允许开发人员使用简单的高级界面来自动化 DJI 的产品。在 4.0 中，任务被重构为更健壮、更易于管理。

任务的详细介绍如下此处.

安卓桥接应用程序

请查看此链接下载安卓桥应用程序的 apk 文件。

SDK API 参考

Android SDK API 文档

许可证

DJI Android SDK 与基于 LGPLv2.1 发布的 FFmpeg 的未修改库动态链接。这些 FFmpeg 库的源代码、编译说明和 LGPLv2.1 许可证在 Github 提供。

根据 LGPLv2.1，DJI Android SDK 与 JTS 拓扑套件的未修改库动态链接。

支持

您可以通过以下方法获得 DJI 的支持：

• 在大疆开发者论坛发布问题：
  中文论坛
  , 英文论坛

加入我们

DJI 招软件工程师啦，based在深圳，如果你想和我们一起把 DJI 产品做得更好，请发送简历到 software-sz@dji.com. 或者在这里提交您的简历：https://we.dji.com/zh-CN/position/detail?positionId=1382258951346253824 更多岗位详情请浏览 https://we.dji.com/zh-CN/social.

五一有点空，继续折腾下 llama.cpp。

本来应该优先折腾这个的，毕竟更出名，不过同事折腾过 gpt4all，也是 llama，但似乎中文支持不怎么样的，觉得不行就没看。顺便网上找找，看看融合 Chinese-LLaMA-Alpaca 的中文怎么样

操作环境：Windows 11 Python 3.10

下载并生成 llama.cpp

下载代码

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp

生成

mkdir build
cd build
cmake ..
cmake --build . --config Release

试运行

cd bin\Release
./main -h

下载 llama 7b 模型

下载 llama 半精度模型

$env:GIT_LFS_SKIP_SMUDGE=1
git lfs install
git clone https://huggingface.co/decapoda-research/llama-7b-hf
git lfs pull

下载 Chinese-LLaMA-Alpaca

git clone https://ghproxy.com/github.com/ymcui/Chinese-LLaMA-Alpaca.git

下载 chinese alpaca lora-7b 模型

$env:GIT_LFS_SKIP_SMUDGE=1
git lfs install
https://huggingface.co/ziqingyang/chinese-alpaca-lora-7b
git lfs pull

模型融合

使用 ymcui/Chinese-LLaMA-Alpaca 里面的 scripts/merge_llama_with_chinese_lora.py 脚本对原版 LLaMA 模型（HF格式）扩充中文词表，并与 LoRA 权重进行合并，生成全量模型权重 consolidated.*.pth（建议检查生成模型的 SHA256 值）和配置文件 params.json

cd Chinese-LLaMA-Alpaca
python scripts/merge_llama_with_chinese_lora.py --base_model D:\test\ai\llama\llama-7b-hf --lora_model D:\test\ai\llama\chinese-alpaca-lora-7b --output_dir ./ggml-model-chinese-alpaca-lora-7b/

把生成的 tokenizer.model 文件放入 llama.cpp/models 目录下，其他小文件放入 llama.cpp/models/7B 目录下。

转换为 ggml fp16 模型

cd llama.cpp
python convert.py D:\test\ai\llama\Chinese-LLaMA-Alpaca\ggml-model-chinese-alpaca-lora-7b

量化为 4bit

cd build/bin/Release
./quantize  D:\test\ai\llama\Chinese-LLaMA-Alpaca\ggml-model-chinese-alpaca-lora-7b/ggml-model-f16.bin ../../../models/7B/ggml-model-q4_0.bin q4_0 4

删除临时文件

rm -R D:\test\ai\llama\Chinese-LLaMA-Alpaca\ggml-model-chinese-alpaca-lora-7b

运行

./main -m ../../../models/7B/ggml-model-q4_0.bin --color -f ../../../prompts/alpaca.txt -ins -c 2048 --temp 0.2 --repeat_penalty 1 -n 4096

速度倒是很快。不过这中文理解能力有问题啊。。前面问小说，后面不问了也是回答小说。。。

写一段 c 操作串口的代码，还是不行。。

既然玩了 ai 聊天的东西，顺便折腾下画画的东西。搜了下，发现了 Stable Diffusion。

操作环境：Windows 11 Python 3.10

下载代码

在适当的地方，新建文件夹，准备获取代码。不带其他任何模型的默认版本大概 7G。模型也是 GB 级别，所以空间可以适当留大一点。另外，目录的路径中不要带中文。

打开命令行，进入待安装的目录下，执行指令获取代码。

git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui.git

运行和下载部件

获取完代码后，运行获取到的 webui.bat 。因为我们没有显卡，因此需要加上参数，运行：

./webui --skip-torch-cuda-test --no-half

这两个参数是跳过 CUDA（依赖于显卡的加速算法）以及禁用半精度运算，规避报错。

脚本首先会获取依赖项，随后会获取依赖项目，然后会获取默认模型。最终启动WebUI服务器。直到提示

Running on local URL: http://127.0.0.1:7860

这时候，Web 服务就启动成功了。接下来打开浏览器，就可以开始画起来了。

输入描述来画图。只能用英文描述关键词。

cpu 占用不是很大，不影响打开一个 vscode。

不过还是慢。我的笔记本 512x512 的需要 5 分钟。。1000x600 的 20 分钟。。

点 save 保存，文件默认在 stable-diffusion-webui\outputs\txt2img-images

老鹰抓小鸡。。

画出来的人脸全是花的。。。吓人。

部件下载问题

无法下载 gfpgan 就手工下载

git clone https://ghproxy.com/github.com/TencentARC/GFPGAN.git

算了，直接改 launch.py 中的链接

中文提示词

提示词只支持英文也是无奈，国内的太乙还不支持 cpu

安装个 Prompt Translator，输入中文自动用百度翻译

本地化界面

另一个界面库 invokeai 里面有本地化文件，下载后在 invokeai\frontend\web\dist\locales 能找到，复制到
stable-diffusion-webui\localizations 中。

然后再界面配置中选择 zh_CN，重启服务。

面部修复

在配置界面上选择面部修复。似乎没什么用。

用 lora 模型似乎没问题。。可能是提示词的问题

ChatGLM 本地挺慢的，在它的 readme 中找到一个 cpp 实现的，试试

操作环境：windows 11 python 3.10

经折腾发现，比 python 的还慢。

编译 mnn

git clone https://github.com/alibaba/MNN.git
cd MNN
mkdir build && cd build
cmake ..
cmake --build . -j4

cp -r ../include /path/to/ChatGLM-MNN/
cp libMNN.so /path/to/ChatGLM-MNN/libs
cp express/libMNN_Express.so /path/to/ChatGLM-MNN/libs

下载模型

cd ChatGLM-MNN/resource/models

后面两个一样，不用重复下载

int4

mkdir in4 && cd in4

wget https://github.com/wangzhaode/ChatGLM-MNN/releases/download/v0.3/glm_block_0.mnn
... 
wget https://github.com/wangzhaode/ChatGLM-MNN/releases/download/v0.3/glm_block_27.mnn 

wget https://github.com/wangzhaode/ChatGLM-MNN/releases/download/v0.1/lm.mnn 
wget https://github.com/wangzhaode/ChatGLM-MNN/releases/download/v0.1/slim_word_embeddings.bin

int8

mkdir in8 && cd in8

wget https://github.com/wangzhaode/ChatGLM-MNN/releases/download/v0.2/glm_block_0.mnn
...
wget https://github.com/wangzhaode/ChatGLM-MNN/releases/download/v0.2/glm_block_27.mnn

wget https://github.com/wangzhaode/ChatGLM-MNN/releases/download/v0.1/lm.mnn
wget https://github.com/wangzhaode/ChatGLM-MNN/releases/download/v0.1/slim_word_embeddings.bin

fp16

mkdir fp16 && cd fp16

wget https://github.com/wangzhaode/ChatGLM-MNN/releases/download/v0.1/glm_block_0.mnn
... 
wget https://github.com/wangzhaode/ChatGLM-MNN/releases/download/v0.1/glm_block_27.mnn 

wget https://github.com/wangzhaode/ChatGLM-MNN/releases/download/v0.1/lm.mnn
wget https://github.com/wangzhaode/ChatGLM-MNN/releases/download/v0.1/slim_word_embeddings.bin

编译运行

本地 msvc 编译

cd ChatGLM-MNN
mkdir build && cd build
cmake ..
cmake --build . -j4
./cli_demo # cli demo
./web_demo # web ui demo

msvc 编译需要 CMakeLists 添加

add_compile_options("$<$<CXX_COMPILER_ID:MSVC>:/source-charset:utf-8>")
add_compile_options("$<$<C_COMPILER_ID:MSVC>:/source-charset:utf-8>")

web_demo 引用了 pthread，需要 mingw 编译。。依赖的 mnn 库也要编译。。。

cmake .. -G "MinGW Makefiles"
cmake --build . -j4

生成不了 express 库

无法运行。。禁用掉 gpu

./cli_demo -g0

还是不行。。

wsl 编译

直接 wsl 中编译运行吧

mkdir build && cd build
cmake ..
cmake --build . -j4

运行

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:../libs
./web_demo -g0 -m "../resource/models/int4"

虚拟机内内存不足。。已杀死。。需要的内存真多。。大概需要 25G

添加配置，增加 wsl 虚拟内存。%UserProfile%/.wslconfig 内容

[wsl2]
swap=20480MB

占的 C 盘空间。。用完得去掉。。

慢得不得了。。。

mingw 编译

注释掉对 mnn-express 的依赖，再用 mingw 编译

出错：undefined reference to `__imp_setsockopt'
少 ws2_32 库

        target_link_libraries(web_demo chat pthread)

改成

if(WIN32)
        target_link_libraries(web_demo chat ws2_32)
else()
        target_link_libraries(web_demo chat pthread)
endif()

把 libMNN.dll 复制过来，运行

./web_demo -g0 -m "../resource/models/int4"

还是太慢了，比 ptyhon 还慢。而且 web 输进去控制台显示乱码，程序无法识别。程序输出的也是乱码。毕竟里面编码 utf8

算了，不折腾了。没用，删除。。。还是直接用网上能用的吧。

同事在玩 gpt4all，不过对中文不怎么支持。回来搜了下，发现国内清华出的 ChatGLM-6B 对中文支持不错。本地部署下，用纯 cpu 玩玩。

操作环境：windows 11 python 3.10

没有多余精力研究，就当感受感受高科技吧

可用量化模型

ChatGLM-6B-INT4

ChatGLM-6B-INT4 是 ChatGLM-6B 量化后的模型权重。具体的，ChatGLM-6B-INT4 对 ChatGLM-6B 中的 28 个 GLM Block 进行了 INT4 量化，没有对 Embedding 和 LM Head 进行量化。量化后的模型理论上 6G 显存（使用 CPU 即内存） 即可推理，具有在 嵌入式设备（如树莓派）上运行的可能。

此外，如果需要在 cpu 上运行量化后的模型，还需要安装 gcc 与 openmp。多数 Linux 发行版默认已安装。对于 Windows ，可在安装 TDM-GCC 时勾选 openmp（components/gcc/opemp）。 Windows 测试环境 gcc 版本为 TDM-GCC 10.3.0， Linux 为 gcc 11.3.0。

chatglm-6b-int8

chatglm-6b-int8 是基于 64 位浮点数的指令集，而 chatglm-6b-int4 是基于 32 位浮点数的指令集。

试了下，chatglm-6b-int8 还是很慢，而且需要更大的内存。。

chatglm-6b-int4-slim

ChatGLM-6B-INT4-Slim 是在 ChatGLM-6B-INT4 的基础上通过裁剪词表构建的。因为 ChatGLM-6B 使用了 icetk，在其词表中，前 20000 个 token 是预留给图片的，在文本模型中没有用到这些图片 token，但是在 infer 和微调的时候，这些 token 对应的 embedding 依然需要被加载，并且在解码每一个 token 的时候需要多计算 20K 个 logits，会占用不少显存。因此将这一部分 token 裁剪掉以节省显存。

除了词表外，ChatGLM-6B-INT4-Slim 的其他结构与 ChatGLM-6B-INT4 完全一致，性能也完全一样，可以认为是 ChatGLM-6B-INT4 的一个低显存版等价平替。

chatglm-6b-int4-slim 经测试似乎完全不能用，删掉。

各模型内存使用

随着对话轮数的增多，对应消耗显存也随之增长

下载代码

git clone https://github.com/THUDM/ChatGLM-6B
cd ChatGLM-6B

下载模型

cd ChatGLM-6B

$Env:GIT_LFS_SKIP_SMUDGE=1

git lfs install
git clone https://huggingface.co/THUDM/chatglm-6b
git lfs pull

git lfs install
git clone https://huggingface.co/THUDM/chatglm-6b-int4
git lfs pull

git lfs install
git clone https://huggingface.co/THUDM/chatglm-6b-int8
git lfs pull

配置环境

如果没有 6G 显存，需要使用 CPU 运行，模型会根据硬件自动编译 CPU Kernel ，请确保已安装 GCC 和 OpenMP （Linux 一般已安装，Windows 则需手动安装），以获得最佳并行计算能力。

如果有 6G 显存，则需要安装与显卡版本对应的 cuda，之后再安装与 cuda 版本对应的 pytorch。

安装相关依赖，在 ChatGLM-6B 目录下打开命令行终端，输入

pip install -r requirements.txt 

按回车后，pip 就自动下载和安装相关依赖库了。

启动 demo 程序

在 ChatGLM-6B 目录下有两个 demo 代码：

• cli_demo.py，直接在命令行中输入进行问答；
• web_demo.py，利用 gradio 库生成问答网页。

启动 cli_demo.py

修改模型路径。编辑 cli_demo.py 代码，修改 5、6 行的模型文件夹路径，将原始的 “THUDM/ChatGLM-6B” 替换为 “chatglm-6b-int4” 即可。

修改量化版本。如果你的显存大于 14G，则无需量化可以跳过此步骤。如果你的显存只有 6G 或 10G，则需要在第 6 行代码上添加 quantize(4) 或 quantize(8) ，如下：

6G 显存可以 4 bit 量化

model = AutoModel.from_pretrained("chatglm-6b-int4", trust_remote_code=True).half().quantize(4).cuda() 

10G 显存可以 8 bit 量化

model = AutoModel.from_pretrained("chatglm-6b-int4", trust_remote_code=True).half().quantize(8).cuda()

这里用的 cpu，.half().quantize(8).cuda() 改为.float()

执行 python 文件即可，可以在命令行终端输入：

python cli_demo.py 

即可启动 demo

出错，说需要 icetk：

pip install icetk

回答后，如果不输入内容，直接回车，它只再补充内容。

界面如下：

启动 web_demo.py

安装 gradio 库，在 ChatGLM 目录下打开命令行终端，输入：

pip install gradio 

即可安装 demo 所需要的库。

同上，修改 web_demo.py 中的模型路径和纯 cpu 方法。

可以在命令行终端输入：

python web_demo.py 

即可启动 demo。

程序会运行一个 Web Server，并输出地址。在浏览器中打开输出的地址即可使用。

界面如下：

比 llama 的中文智障强多了，就算加了 vicuna 的 llama 7B 模型都一样。一用中文就垃圾得不行。

lib60870：基于 IEC 60870-5 协议的 C 语言库

当前的实现包含 IEC 60870-5-101（应用层和串行链路层）和 IEC 60870-5-104（TCP/IP 协议库）规范的代码。

特性:

• 支持所有应用层消息类型
• 主站和从站
• 平衡和不平衡链路层（用于 CS 101 串行通信）
• 用于 CS 104 TCP/IP 通信的客户端/服务器
• CS 104 冗余组支持
• 可移植的 C99 代码

还请考虑用户指南和 API 参考文档 (https://support.mz-automation.de/doc/lib60870/latest/)

编译和运行示例:

在 lib60870-C 文件夹，使用如下命令构建库

make

转到 examples 文件夹，在每个示例文件夹使用如下命令构建示例

make

该库和示例也可以使用 CMake 来构建。

要在单独的文件夹中构建库，请创建一个新文件夹作为项目文件夹的子目录，并运行 cmake 来创建构建文件：

mkdir build
cd build
cmake ..

构建不带通用代码和 HAL 的版本

该库包含一些公共代码和与 MZ Automation 的其他协议库（例如 libiec61850）共享的平台抽象层（HAL）。如果要简化使用所有这些协议库，可以在没有公共部分的情况下编译库。

这可以通过在调用 make 时使用 WITHOUT_HAL 和 WITHOUT_COMMON 定义来实现：

make WITHOUT_HAL=1 WITHOUT_COMMON=1

构建支持 TLS 的版本

该库可以构建支持 TLS。为了做到这一点，您必须下载 2.16.12 版本 mbedtls。

解压缩 dependencies 文件夹中的 mbedtls tar 包，保证以下文件存在

dependencies/mbedtls-2.16.12

cmake 构建系统将自动检测 mbedtls 源，并构建包含 TLS 支持和 mbedtls 的库

使用 make 时，需要带 WITH_MBEDTLS=1 选项调用 make

make WITH_MBEDTLS=1

库配置

有不同的运行时和编译时配置选项。

编译时配置选项可用于在小型嵌入式系统中缩小库大小。可以通过修改文件 _config/lib60870_config.h 来更改编译时配置。

内存分配

该库使用动态内存分配（malloc/caloc 由自己的函数包装，这些函数可以在需要时替换）。

CS104 从机仅在启动时使用动态内存分配（当调用函数 CS104_slave_create 和 CS104_Slave_start/CS104_Slave_startThreadless_)。

有关详细信息，请参阅 User Guide。

联系方式:

该库是由我的 MZ Automation GmbH 开发和支持的。

有关错误报告、提示或支持，请联系 info@mz-automation.de

许可证

此软件可在 GPLv3 (https://www.gnu.org/licenses/gpl-3.0.en.html)以及商业许可协议下获得双重许可。

在商业和非 GPL 应用程序中使用库时，您应该购买商业许可证。

商业许可证和支持

MZ Automation GmbH 提供支持和商业许可选项。请联系 info@mz-automation.de 了解更多详细信息。

贡献

如果你想为库的改进和开发做出贡献，请给我发评论、功能请求、错误报告或补丁。

对于不是微不足道的贡献，我要求您签署一份贡献者许可协议。请联系 info@mz-automation.de。

英文原文：https://github.com/mz-automation/lib60870
API参考：https://support.mz-automation.de/doc/lib60870/latest/index.html

lib60870 - IEC 60870-5-101/104 C 源代码库用户指南 - 版本 2.3.0

版权 2020 MZ Automation GmbH

介绍

lib60870 是针对客户端（主站）和服务器（从站或受控站）的 IEC 60870-5-101/104 协议的功能丰富且经过现场验证的实现。该库实现了 IEC 60870-5-101/104 规范的所有数据类型。lib60870 以标准 C 实现，并与 C99 标准兼容。它被设计成尽可能易于使用。

客户端/服务器 API 是严格异步的。使用非阻塞函数发送请求，并且必须在回调函数中处理响应和其他事件。

以下是支持的功能列表：

• CS 101 (IEC 60870-5-101) 平衡和非平衡串行模式
• CS 104 (IEC 60870-5-104) 客户端和服务端 TCP/IP 通信
• CS 104 支持加密和授权的 TLS 通信
• CS 104 使用 CS 101 应用层
• CS 104 从机：支持冗余组
• 主站/客户端支持反向发送系统命令、过程命令、参数命令和数据消息。
• 从机/服务器支持在监控方向发送数据消息，并支持在相反方向发送命令
• 支持的 ASDU 类型列表可在附件中找到
• 库支持用户定义的专用 ASDU 类型
• 库扩展插件接口

注： CS 代表“配套标准”，规定了 IEC 60870-5 标准系列中定义的通信协议和服务的变体。

该库使用“面向对象”的编程风格。它基于抽象数据类型（ADT）和操作这些数据类型的函数。通常，数据类型（保存数据的数据结构）的实际实现对 API 用户是隐藏的。在几乎所有情况下，API 用户不需要（也不建议）直接访问这些数据结构。

应用层消息

此编程风格将通过 CS101_ASDU ADT 的示例进行解释，后者是库 API 的最重要部分。该数据类型表示 CS101/C104 协议的应用层消息。缩写 ASDU 代表“应用服务数据单元”。要创建新的 ASDU 对象，必须使用 CS101_ASDU_create 函数作为对象的构造函数。

CS101_ASDU newAsdu = CS101_ASDU_create(alParams, false, CS101_COT_INTERROGATED_BY_STATION,
        0, 1, false, false);

此函数具有多个参数，以反映 ASDU 的不同属性。以下是 CS101_ASDU_create 函数的签名：

CS101_ASDU
CS101_ASDU_create(CS101_AppLayerParameters parameters, bool isSequence, CS101_CauseOfTransmission cot,
                  int oa, int ca, bool isTest, bool isNegative);

第一个参数是另一个 CS101_AppLayerParameters 类型的对象，该对象表示主设备和从设备之间根据协议共享的应用层参数。如果双方没有相同的参数，他们将无法理解对方的 ASDU。

第二个参数 isSequence 指示 ASDU 包含连续信息对象序列（如果 true）或一个或多个独立信息对象（如果 false）。连续信息对象的序列意味着 ASDU 仅包含单个信息对象地址（IOA）。然后，连续的信息对象具有地址 IOA、IOA+1、IOA+2。。。

第三个参数表示传输原因（COT）。这是为了告诉对方发送信息的原因。对于周期性消息，可能的值为 CS101_COT_PERIODIC，对于自发消息，可能为 CS101_COT_SPONTANEOUS。

其他参数为，oa 表示始发方地址，ca 表示 ASDU 的公共地址，isTest 表示消息是测试消息，isNegative 表示消息为另一消息的否定确认。

有了新的 ASDU 对象的句柄（在我们的例子中为 newAsdu），我们可以调用多种函数来获取或设置 ASDU 数据。例如，您可以使用 CS101_ASDU_isTest 或 CS101_ASDU_setTest 函数获取或设置测试标志值。这些函数的第一个参数始终是 ASDU 对象的句柄。

bool isTest = CS101_ASDU_isTest(newAsdu);

创建可用 ASDU 对象的一个重要函数是 CS101_ASDU_addInformation Object 函数。使用函数可以将信息对象实例添加到 ASDU 中。

InformationObject io = (InformationObject) MeasuredValueScaled_create(NULL, 100, -1,
                       IEC60870_QUALITY_GOOD);

CS101_ASDU_addInformationObject(newAsdu, io);

可以多次调用此函数，以便向 ASDU 对象添加更多信息对象。它有一个布尔返回值，指示信息对象是否已成功添加（返回值 true）。当 ASDU 有效负载已满时，添加信息对象可能会失败。在这种情况下，函数将返回 false。

最后，当应用程序创建了一个 ASDU 对象，并且不再需要它时，必须使用 CS101_ASDU_destroy 函数来释放它。

CS101_ASDU_destroy(newAsdu);

主站 (客户端) 侧编程

对于主站端编程，可以使用以下抽象数据类型和 API：

• CS101_Master 适用于符合 CS 101 的平衡模式和非平衡模式串行连接。
• CS104_Connection 用于符合 CS 104 的 TCP/IP 连接。

创建一个到 CS 104 服务端的连接

由于 IEC 60870-5-104 连接基于 TCP 客户端/服务器连接，因此该连接将由客户端（主机）建立。服务器（从站或分站）通常被动等待连接。

通过调用 CS104_connection 类型的 CS104_connection_create 函数，可以简单地创建新连接：

CS104_Connection con = CS104_Connection_create("127.0.0.1", 2404);

这将创建一个新的 CS104_Connection 对象，该对象已准备好连接到服务器。参数是服务器的主机名或 IP 地址以及 TCP/IP 端口（通常为 2404）。对于端口参数，您也可以设置 -1 以使用默认端口。

创建连接对象后，现在只需调用 CS104_connection_connect 函数即可连接到服务器：

CS104_Connection_connect(con);

参数 con 是对上面创建的连接对象的引用。

正确建立连接后，可以使用连接对象发送命令和接收数据。

当您使用完连接对象时，您必须调用

CS104_Connection_destroy(con);

释放对象分配的所有资源。使用 destroy 函数后，不能对 con 引用使用任何函数！

准备连接到一个或多个从机的 CS 101

CS 101 为主/从连接提供了两种链路层模式。

平衡模式支持使用专用串行线在单个主设备和单个从设备之间进行通信。这种模式是“平衡的”，因为两端可以随时自发地发送消息。

不平衡模式支持串行总线上单个主设备和多个从设备之间的通信。每个从设备都通过其唯一的链路层地址进行寻址。从机是不允许自发发送信息的。他们只会根据主站的请求做出回应。主设备可以通过使用广播地址同时寻址多个从设备。

配置串口

对于这两种模式，首先必须配置和初始化串行端口。以下代码显示了如何准备串行端口以便与库一起使用的示例：

SerialPort port = SerialPort_create("/dev/ttsS0", 9600, 8, 'E', 1);

创建并使用新的非平衡主实例

对于平衡和不平衡通信模式，必须使用 CS101_Master 类型。

以下代码使用上面定义的串行端口创建一个新的不平衡主站实例。CS101_Master_setASDUReceivedHandler 函数为接收到的 ASDU 提供回调处理程序。CS101_Master_addSlave 函数将创建一个新的从机专用的状态机，以处理与链路层地址为 1 的从机的所有通信。

CS101_Master master = CS101_Master_create(port, NULL, NULL, IEC60870_LINK_LAYER_UNBALANCED);

CS101_Master_setASDUReceivedHandler(master, asduReceivedHandler, NULL);

CS101_Master_addSlave(master, 1);

链路层参数和应用层参数是可选参数。如果未设置，则会创建和使用参数对象的默认实例。以后也可以修改这些参数。

在向特定从机发送任何命令或其他请求之前，必须使用 CS101_Master_useSlaveAddress 函数设置从机地址。

CS101_Master_useSlaveAddress(master, 1);
CS101_Master_sendProcessCommand(master, CS101_COT_ACTIVATION, 1, sc);

平衡主站

平衡主站也是以同样的方式创建的。只是链接层模式参数不同。CS101_Master_useSlaveAddress 用于设置从机地址。在平衡主站情况下，只需设置一次，因为只有

CS101_Master master = CS101_Master_create(port, NULL, NULL, IEC60870_LINK_LAYER_BALANCED);

CS101_Master_useSlaveAddress(master, 3);
CS101_Master_setASDUReceivedHandler(master, asduReceivedHandler, NULL);

设置链路层参数

设置链接层参数是一个可选步骤。如果未明确设置，则将为新的主站实例使用一组默认参数。参数可以通过构造函数 CS101_Master_create 给出，也可以稍后修改。

示例：禁用单字符 ACK 的用法

LinkLayerParameters llParams = CS101_Master_getLinkLayerParameters(master);
llParams->useSingleCharACK = false;

向从机发送请求并接收响应

一般来说，应用程序专注于向从机发送应用层消息（ASDU）。主机 API 包含向从机发送消息的通用和专用函数。发送系统命令或过程命令时，建议使用专用函数，因为它们有助于创建符合标准的 ASDU。以下各节将对这些专门函数进行解释。它们通常存在于 CS101 和 CS104 的两种变体中。

对于一般情况，可以使用 CS101_Master_sendASDU 或 CS104_Connection_sendASDU 函数发送任意 ASDU。

为了接收应用层消息，应用程序必须实现 CS101_ASDUReceivedHandler 回调。

在 CS101_ASDUReceivedHandler 中处理接收到的 ASDU 的示例

static bool
asduReceivedHandler (void* parameter, int address, CS101_ASDU asdu)
{
    printf("RECVD ASDU type: %s(%i) elements: %i\n",
            TypeID_toString(CS101_ASDU_getTypeID(asdu)),
            CS101_ASDU_getTypeID(asdu),
            CS101_ASDU_getNumberOfElements(asdu));

    if (CS101_ASDU_getTypeID(asdu) == M_ME_TE_1) {

        printf("  measured scaled values with CP56Time2a timestamp:\n");

        int i;

        for (i = 0; i < CS101_ASDU_getNumberOfElements(asdu); i++) {

            MeasuredValueScaledWithCP56Time2a io =
                    (MeasuredValueScaledWithCP56Time2a) CS101_ASDU_getElement(asdu, i);

            printf("    IOA: %i value: %i\n",
                    InformationObject_getObjectAddress((InformationObject) io),
                    MeasuredValueScaled_getValue((MeasuredValueScaled) io)
            );

            MeasuredValueScaledWithCP56Time2a_destroy(io);
        }
    }
    else if (CS101_ASDU_getTypeID(asdu) == M_SP_NA_1) {
        printf("  single point information:\n");

        int i;

        for (i = 0; i < CS101_ASDU_getNumberOfElements(asdu); i++) {

            SinglePointInformation io =
                    (SinglePointInformation) CS101_ASDU_getElement(asdu, i);

            printf("    IOA: %i value: %i\n",
                    InformationObject_getObjectAddress((InformationObject) io),
                    SinglePointInformation_getValue((SinglePointInformation) io)
            );

            SinglePointInformation_destroy(io);
        }
    }

    return true;
}

此回调处理程序必须使用 CS104_Connection_setASDUReceivedHandler 或 _CS101_Master_setASDURLeceivedHandler 函数安装。

CS101_Master_setASDUReceivedHandler(master, asduReceivedHandler, NULL);

所有回调处理程序的函数签名中都有一个名为 “parameter” 的通用引用参数。用户可以使用此参数向回调处理程序提供特定于应用程序的上下文信息。此参数通过回调处理程序的安装函数进行设置（如上例中的 CS101_Master_setASDUReceivedHandler）。如果不使用此参数，则可以将其设置为 NULL。

主站侧回调处理程序类型

发送读请求

IEC 60870 文档不建议使用此服务（周期性数据请求或轮询），但这是获取所需数据的一种简单方法。您只需要知道公共地址（CA）和信息对象地址（IOA）就可以创建正确的请求。

  CS104_Connection_sendReadCommand(con, 1 /* CA */, 2001 /* IOA */);

此调用是非阻塞的。您必须在 CS101_ASDUReceivedHandler 回调函数中评估响应。

通常情况下，服务器响应只包含没有时间戳的基本数据类型（即使用不包含时间戳的特定数据类型的消息类型）！

召唤

也可以通过单个请求向从机请求一组数据项。在主站（客户端）端，您可以简单地使用 Connection 对象的 sendInterrogationCommand 函数：

CS104_Connection_sendInterrogationCommand (con, CS101_COT_ACTIVATION, /* CA */ 1, /* QOI */ 20);

客户端/主机端方法签名如下所示：

bool
CS104_Connection_sendInterrogationCommand(CS104_Connection self, CS101_CauseOfTransmission cot, int ca, QualifierOfInterrogation qoi)

与其他方法一样，参数 ca 是公共地址（ca）。参数 qoi 是“询问限定符”（qoi）。QOI 的值 “20”（表示“站询问”）表示它是对所有数据点的请求。QOI 的其他值将指示客户端（主机）只想从特定询问组接收数据。

时钟同步过程

对于时钟同步过程，控制站（主站）向受控站（从站）发送 C_CS_NA_1 ACT 消息，该消息包含作为 CP56Time2a 类型的时间值的当前有效时间信息。受控站必须更新其内部时间，并在发送了所有排队的时间标记 PDU 之后用 C_CS_NAME_1 ACT_CON 消息进行响应。

受控站的时钟同步可以通过 CS104 的 CS104_Connection_sendClockSyncCommand 函数或 CS101 的 CS101_Master_sendClockSyncCommand 来完成。

首先，必须创建并初始化 CP56Time2a 时间戳：

struct sCP56Time2a currentTime;
CP56Time2a_createFromMsTimestamp(&currentTime, Hal_getTimeInMs());
CS104_Connection_sendClockSyncCommand(con, 1 /* CA */, &currentTime);

或者当使用动态内存分配和 CS 101 时：

CP56Time2a currentTime = CP56Time2a_createFromMsTimestamp(NULL, Hal_getTimeInMs());
CS101_Master_sendClockSyncCommand(master, 1 /* CA */, currentTime);

注：Hal_getTimeInMs 函数是一种独立于平台的方法，用于获取自 1970 年 1 月 UTC 00:00:00 1 以来的当前时间（以毫秒为单位）。您也可以使用自己的函数来获取时间。

指令执行过程

命令用于在受控站设置设定点、参数或触发一些动作。

以下命令类型（数据类型可用于命令）：

• C_SC (单点命令) - 控制二进制数据（开关…）
• C_DC (双点命令) - 用转换状态控制二进制数据（移动开关…）
• S_RC (步进位置命令) - 控制步进位置
• S_SE (设定值命令) - 控制设定值（缩放值、归一化值、浮点值）-也可用于设置参数、报警限值等。

这些命令类型同样有带时间标签的版本（CP56TIme2a）。

有两种不同的命令过程可用。直接操作命令程序和操作前选择命令程序。

要发送直接操作命令过程的命令，你必须向受控站发送 ACTIVATION APDU。

向受控站发送处理命令

InformationObject sc = (InformationObject)
      SingleCommand_create(NULL, 5000, true, false, 0);

CS101_Master_sendProcessCommand(master, CS101_COT_ACTIVATION, 1, sc);

InformationObject_destroy(sc);

SingleCommand 数据类型的构造器具有以下签名：

SingleCommand
SingleCommand_create(SingleCommand self, int ioa, bool command, bool selectCommand, int qu);

要发送直接操作命令，selectCommand 参数应为 false。限定符（qu）通常应设置为 0。

对于操作前选择，发送命令时必须将 selectCommand 参数设置为 true，以选择控制输出。在下一步中，必须发送一个 selectCommand 设置为 false 的附加命令，才能执行实际的命令。

如果命令成功，则分站将以未设置 negative flag 的 ACT_CON 响应消息进行应答。如果分站无法执行该命令，它也将使用 ACT_CON 响应进行应答，但设置 negative flag 。您可以对接收到的 CS101_ASDU 实例使用 CS101_ASDU_isNegative 函数，检查此标志是否设置。

对于 CS 104 主机，可以使用 CS104_master_sendProcessCommandEx 函数以相同的方式发送命令。

从机 (服务端) 侧编程

CS104（TCP/IP）服务器配置和设置

要配置和设置 IEC 60870-5-104 服务器/从机，需要一个 CS104_slave 数据类型的实例。

CS104_Slave slave = CS104_Slave_create(100, 100);

创建服务器实例后，可以对其进行配置

CS104 服务端模式

服务器提供了三种不同的模式，涉及对冗余连接和事件队列处理的支持：

默认模式（CS104_mode_SINGLE_REDUNDANCY_GROUP）仅允许单个活动客户端连接。活动客户端连接是发送 ASDU（应用程序数据单元）的连接。所有其他连接都只是不发送应用层数据的备用连接。
事件只有一个队列。当没有客户端连接或没有连接处于活动状态时，也会存储事件。

第二种模式（CS104_mode_CONNECTION_IS_REDUNDANCY_GROUP）允许多个活动客户端连接。每个连接都有自己的事件队列。
当客户端连接关闭时，事件队列将被删除。当有多个客户端需要访问应用程序数据时，可以使用此模式。这种模式很容易使用，但它的缺点是，当没有客户端连接时，事件会丢失。

第三种模式（CS104_mode_MULTIPLE_REDUNDANCY_GROUPS）允许多个活动客户端连接，同时在没有客户端连接时保留事件。在这种模式下，客户端可以被分配到特定的冗余组。分配基于客户端的 IP 地址。一个冗余组可以同时具有多个连接，但这些连接中只有一个可以处于活动状态。激活的连接数量受冗余组数量的限制。每个冗余组都有一个专用的事件队列。

可以使用 CS104_Slave_setServerMode 功能设置服务器模式：

CS104_Slave_setServerMode(slave, CS104_MODE_MULTIPLE_REDUNDANCY_GROUPS);

CS104：定义多个冗余组

只有在使用服务器模式 CS104_MODE_MULTIPLE_Redundancy_groups 时，才需要显式创建冗余组。您可以将多个 IP 地址分配给一个冗余组。来自其中一个 IP 地址的传入连接将自动分配给该特定的冗余组。

当一个冗余组没有分配 IP 地址时，它作为一个“包罗万象”的组工作。这意味着所有未分配给其他组的传入连接都将最终在此组中。

如何定义多个冗余组的示例

CS104_Slave_setServerMode(slave, CS104_MODE_MULTIPLE_REDUNDANCY_GROUPS);

CS104_RedundancyGroup redGroup1 = CS104_RedundancyGroup_create("red-group-1");
CS104_RedundancyGroup_addAllowedClient(redGroup1, "192.168.2.9");

CS104_RedundancyGroup redGroup2 = CS104_RedundancyGroup_create("red-group-2");
CS104_RedundancyGroup_addAllowedClient(redGroup2, "192.168.2.223");
CS104_RedundancyGroup_addAllowedClient(redGroup2, "192.168.2.222");

CS104_RedundancyGroup redGroup3 = CS104_RedundancyGroup_create("catch-all");

CS104_Slave_addRedundancyGroup(slave, redGroup1);
CS104_Slave_addRedundancyGroup(slave, redGroup2);
CS104_Slave_addRedundancyGroup(slave, redGroup3);

CS101（串行）从机配置和设置

与主站侧类似，CS101 从站侧也可以被配置用于两种链路层模式之一（平衡 或 非平衡）。CS101 从机由 CS101_slave 对象表示。

在创建 CS101_Slave 对象之前，需要一个 SerialPort 对象。SerialPort 对象表示串行接口及其配置。

SerialPort port = SerialPort_create(serialPort, 9600, 8, 'E', 1);

创建的 SerialPort 对象是 CS101_Slave_create 函数所必需的：

CS101_Slave slave = CS101_Slave_create(port, NULL, NULL, IEC60870_LINK_LAYER_UNBALANCED);

此函数具有以下签名：

CS101_Slave
CS101_Slave_create(SerialPort serialPort, LinkLayerParameters llParameters, CS101_AppLayerParameters alParameters, IEC60870_LinkLayerMode linkLayerMode)

可以选择指定链路层参数和应用层参数。如果应该使用默认值，则可以跳过这些参数（设置为 NULL）。最后一个参数指定是使用 平衡 模式还是使用 非平衡 模式。

对于串行从机，还需要设置链路层地址：

CS101_Slave_setLinkLayerAddress(slave, 1);

设置回调处理函数

在启动或运行服务器前，建议设置回调函数来处理从站事件。以下回调处理程序类型可用（有关函数签名的详细信息，请参阅 API 参考手册）。其中一些仅适用于 CS 104 服务器，而另一些则仅适用于 CS101 从站。

从机侧回调函数类型

为 CS101 从机设置一些回调函数

/* set the callback handler for the clock synchronization command */
CS101_Slave_setClockSyncHandler(slave, clockSyncHandler, NULL);

/* set the callback handler for the interrogation command */
CS101_Slave_setInterrogationHandler(slave, interrogationHandler, NULL);

/* set handler for other message types */
CS101_Slave_setASDUHandler(slave, asduHandler, NULL);

/* set handler for reset CU (reset communication unit) message */
CS101_Slave_setResetCUHandler(slave, resetCUHandler, (void*) slave);

CS104 启动/停止服务端

配置服务器后，可以使用 CS104_Slave_start 函数启动服务器。此函数启动一个新的后台线程，以侦听传入的客户端连接。

CS104_Slave_start(slave);

要停用 IEC 60870-5-104 服务，可以使用 CS104_Slave_stop 函数停止服务器。

CS104_Slave_stop(slave);

自发或周期性的信息传输

对于服务器/从站的自发或周期性消息传输，API 用户必须分配一个代表单个 ASDU 的 CS101_ASDU 对象，将信息对象添加到 ASDU，并最终将 ASDU 放入传输队列。传输队列是一个 FIFO（先进先出）列表。如果队列已满，则最旧的消息将被删除，并由新添加的消息替换。只有当存在活动的客户端连接或工作的链接层连接时，才会发送消息。否则，消息将保留在队列中，直到连接被激活。

CS 104: 在 CS 104 从机中，队列大小由 CS104_slave_create 函数的 maxLowPrioQueueSize 参数确定。如果 maxLowPrioQueueSize 参数设置为零，则队列的大小将始终由 CONFIG_SLAVE_MESSAGE_queue_size 定义。第二个参数 maxHighPrioQueueSize 确定高优先级数据队列的大小。放入此队列的消息会绕过低优先级队列的消息。高优先级队列用于库回调处理程序中的请求响应。

要发送自发或周期性消息，必须执行以下步骤：

1. Step: 创建一个新的 CS101_ASDU 实例（对周期性数据使用 CS101_COT_PERIODIC，对自发数据使用 CS101_COT_SPONTANEOUS）

CS101_ASDU newAsdu = CS101_ASDU_create(alParameters, false, CS101_COT_PERIODIC, 0, 1, false, false);

2. Step: 创建包含要发送的数据的新信息对象实例

InformationObject io = (InformationObject) MeasuredValueScaled_create(NULL, 110, scaledValue, IEC60870_QUALITY_GOOD);

3. Step: 将新的信息对象添加到 ASDU

CS101_ASDU_addInformationObject(newAsdu, io);

4. Step: 释放信息对象内存

InformationObject_destroy(io);

5. Step: 将 ASDU 放入 2 类数据队列进行传输

CS101_Slave_enqueueUserDataClass2(slave, newAsdu);

6. Step: 释放 ASDU 内存

CS101_ASDU_destroy(newAsdu);

注： 对于 CS 104，您必须在步骤 5 中使用 CS104_Slave_enqueueASDU 函数：

CS104_Slave_enqueueASDU(slave, newAsdu);

召唤请求处理

在服务器端，您应该使用 InterrogationHandler 回调函数来处理召唤请求。根据 QOI（Qualifier of question 问题限定符）值，您可以返回不同的信息对象。对于一个简单的系统来说，只处理站召唤请求（QOI=20）就足够了。QOI 值 21-36 用于召唤组（1-16）。由从机实现者将信息对象分配给召唤组。

根据该规范，服务器必须用 ACT_CON 响应来响应来自客户端的 ACTIVATION 请求，然后是包含信息对象的 ASDU，该信息对象具有用于站召唤的 CS101_COT_INTERROGATED_by_STATION 或表示相应召唤组的 COT（例如，用于召唤组 1 的 CS101-COT_INTERROGATED_by_group_1）。在发送所有信息对象之后，服务器必须发送具有 COT＝_CS101_COT_ACTIVATION_TERMINATION_ 的初始召唤命令消息，以指示召唤数据的传输完成。

如何实现召唤处理程序的示例

static bool
interrogationHandler(void* parameter, IMasterConnection connection, CS101_ASDU asdu, uint8_t qoi)
{
    if (qoi == 20) { /* only handle station interrogation */

        CS101_AppLayerParameters alParams = IMasterConnection_getApplicationLayerParameters(connection);

        IMasterConnection_sendACT_CON(connection, asdu, false);

        CS101_ASDU newAsdu = CS101_ASDU_create(alParams, false, CS101_COT_INTERROGATED_BY_STATION,
                0, 1, false, false);

        InformationObject io = (InformationObject) MeasuredValueScaled_create(NULL, 100, -1, IEC60870_QUALITY_GOOD);

        CS101_ASDU_addInformationObject(newAsdu, io);

        CS101_ASDU_addInformationObject(newAsdu, (InformationObject)
            MeasuredValueScaled_create((MeasuredValueScaled) io, 101, 23, IEC60870_QUALITY_GOOD));

        CS101_ASDU_addInformationObject(newAsdu, (InformationObject)
            MeasuredValueScaled_create((MeasuredValueScaled) io, 102, 2300, IEC60870_QUALITY_GOOD));

        InformationObject_destroy(io);

        IMasterConnection_sendASDU(connection, newAsdu);

        CS101_ASDU_destroy(newAsdu);

        IMasterConnection_sendACT_TERM(connection, asdu);
    }
    else {
        IMasterConnection_sendACT_CON(connection, asdu, true);
    }

    return true;
}

在召唤处理程序内部，IMasterConnection 接口可用于将召唤的数据发送回客户端/主机。在召唤处理程序中创建的 CS101_ASDU 和 InformationObject 实例由用户负责，如果之前动态分配，则必须使用适当的函数（CS101_ASDU_destroy 和 InformationObject_destroy）进行释放。

读数据指令 (C_RD_NA_1) 处理

客户端/主机可以使用读取命令 C_RD_NAME_1（102）来读取监控方向上的特定数据点的值。

在服务器/从端处理读取命令最方便的方法是实现回调函数类型 CS101_ReadHandler。读取处理程序可以通过用于 CS 104 服务器或 CS 101 从机的 CS104_Slave_setReadHandler 或 CS101_Slave_setReadHandler 函数安装。

在读取处理程序中，您必须发送相同的读取命令，但带有指示错误的 COT。或者，您必须为数据点创建正确类型的 ASDU，并将其发送回客户端/主机。当执行后者时，您必须使用 COT_CS101_COT_REQUEST 来指示消息是由读取请求引起的。

读取处理程序的简单实现（伪代码）

static bool
readHandler(void* parameter, IMasterConnection connection, CS101_ASDU asdu, int ioa)
{
	if (request failed) {
	   /* send error reponse- e.g. unknown */
	   CS101_ASDU_setCOT(asdu, CS101_COT_UNKNOWN_CA);
	   CS101_ASDU_setNegative(asdu, true);
	   IMasterConnection_sendASDU(connection, asdu);
	}
	else {
	
		CS101_AppLayerParameters alParams = CS104_Slave_getAppLayerParameters(cs104Slave);
		
		sCS101_StaticASDU _asdu;
		CS101_ADSU newAsdu = CS101_ASDU_initializeStatic(_asdu, alParams, false, CS101_COT_REQUEST,
		        0, 1, false, false);
		
		CS101_ASDU_addInformationObject(newAsdu, io);
		
		IMasterConnection_sendASDU(connection, newAsdu);
	}

   /* return true to indicate that the request ASDU is handled here */
	return true;   
}

CS104（TCP/IP）特定问题

服务端模式

服务器提供三种不同的模式：

默认模式（CS104_mode_SINGLE_REDUNDANCY_GROUP）仅允许单个活动客户端连接。活动客户端连接是发送 ASDU 的连接。所有其他连接都是备用连接。事件只有一个队列。当没有客户端连接或没有连接处于活动状态时，也会存储事件。

第二种模式（CS104_mode_CONNECTION_IS_REDUNDANCY_GROUP）允许多个活动客户端连接。每个连接都有自己的事件队列。当客户端连接关闭时，事件队列将被删除。当多个客户端访问应用程序数据时，必须使用此模式。

第三种模式（CS104_mode_MULTIPLE_REDUNDANCY_GROUPS）是最灵活的模式，允许定义特定的 REDUNDANCY 组。这些冗余组是共享同一事件队列的客户端组。对于每个冗余组，都有一个单独的事件队列实例。

可以使用 CS104_Slave_setServerMode 函数设置服务器模式。

CS104_Slave_setServerMode(slave, CS104_MODE_CONNECTION_IS_REDUNDANCY_GROUP);

限制客户端连接数量

可以使用 CS104_Slave_setMaxOpenConnections 函数限制客户端的数量。

CS104_Slave_setMaxOpenConnections(slave, 2);

在这种情况下，服务器将只允许两个并发的客户端连接。

设置本地端口和 IP 地址

IEC 60870-5-104 的默认 TCP 端口为 2404。可以使用 CS104_Slave_setLocalPort 函数更改端口。

CS104_Slave_setLocalPort(slave, 2405);

默认情况下，服务器侦听所有本地IP地址。使用 CS104_Slave_setLocalAddress 函数可以限制服务器监听单个本地 IP 地址。

CS104_Slave_setLocalAddress(slave, "192.168.1.50");

通过此设置，CS104 服务器将仅在指定 IP 地址为 192.168.1.50 的本地接口上侦听。

设置连接请求处理程序以限制访问并跟踪连接

CS104_ConnectionRequestHandler 可用于限制对服务器的访问。通过返回值，应用程序可以允许或拒绝客户端的连接尝试。

可以使用 CS104_Slave_setConnectionRequestHandler 函数设置 CS104_ConnectionRequestHandler。第二个参数是用户提供的任意对象，当处理程序被调用时，该对象将被传递给处理程序。如果不需要，可以将其设置为 NULL。

CS104_Slave_setConnectionRequestHandler(slave, connectionRequestHandler, NULL);

在处理程序中，您可以根据允许的客户端白名单检查客户端 IP 地址，或者实现黑名单。

示例如何实现 ConnectionRequestHandler

static bool connectionRequestHandler(void* parameter, const char* ipAddress)
{
  /* Allow only known IP addresses! */
  /* You can implement your allowed client whitelist here */
  if (strcmp(ipAddress, "127.0.0.1") == 0) {
    return true;
  else
    return false;
}

使用 TLS 创建安全连接

CS 104 标准也可以与 TLS 一起使用，以实现安全和经过验证的连接。

为了使用 TLS，必须配置相关的参数、证书和私钥。

配置存储在 TLSConfiguration 对象中。可以使用 TLSConfiguration_create 函数创建一个新的配置对象。

示例如何创建支持 TLS 的 CS 104 从机

TLSConfiguration tlsConfig = TLSConfiguration_create();

TLSConfiguration_setChainValidation(tlsConfig, false);
TLSConfiguration_setAllowOnlyKnownCertificates(tlsConfig, true);

TLSConfiguration_setOwnKeyFromFile(tlsConfig, "server-key.pem", NULL);
TLSConfiguration_setOwnCertificateFromFile(tlsConfig, "server.cer");
TLSConfiguration_addCACertificateFromFile(tlsConfig, "root.cer");

TLSConfiguration_addAllowedCertificateFromFile(tlsConfig, "client1.cer");

/* create a new slave/server instance */
CS104_Slave slave = CS104_Slave_createSecure(100, 100, tlsConfig);

lib60870-C 特定主题

调试输出

控制台的调试输出可以通过将 CONFIG_debug_output 设置为 1 来启用。默认情况下启用调试输出。可以使用函数 Lib60870_enableDebugOutput 禁用调试输出。调试输出函数的默认实现将打印到控制台（使用 printf）。如果需要重定向输出，最简单的方法是更改 lib60870_common.c 中调试输出函数 lib60870_debug_print 的实现。

大端平台

该库包含一个 C 头文件，用于在使用 GCC 编译器时确定平台字节顺序（src/inc/internal/platform_endian.h）。这取决于 C 编译器提供的定义。在一些较旧的大端平台上，如 PowerPC 或 Coldfire，对不同的编译器可能会失败。您可能需要在编译库代码时定义

PLATFORM_IS_BIGENDIAN 1

例如，当平台字节序是大端时，在 GCC 命令行中加入

-DPLATFORM_IS_BIGENDIAN=1

库编译时的配置选项

一些配置选项在库代码的编译时是固定的。这些选项可以在文件 lib60870_config.h 中找到。

编译时选项包括对特定 CS 104 冗余模式的支持、对线程和信号量的支持（当库使用线程时需要）、CS 104 从机的最大 TCP 连接数等。

参考信息

支持的消息类型

此库支持以下 ASDU (应用服务数据单元) 类型。

IEC 60870-5-101/104 消息类型

CS 104 特定参数

以下参数存储在 CS104_ConnectionParameters 对象中.

IEC 60870-5-104 参数

英文原文：https://github.com/mz-automation/lib60870
API参考：https://support.mz-automation.de/doc/lib60870/latest/index.html

最近要测一个设备，搜了搜，发现 WSL2 已经有主机串口使用方案了，社区牛人真不少。终于不用每次使用 socat 转发了。

注：以下 Windows 命令需要管理员权限

Windows 安装 USBIPD-WIN 项目

winget install --interactive --exact dorssel.usbipd-win

太慢，下载不了，还是手工下载安装吧。。下载地址

WSL2 安装 linux-tools/hwdata

sudo apt install linux-tools-virtual hwdata
sudo update-alternatives --install /usr/local/bin/usbip usbip `ls /usr/lib/linux-tools/*/usbip | tail -n1` 20

Windows 列出所有连接的 USB 设备

usbipd wsl list

BUSID  VID:PID    DEVICE                                                        STATE
1-2    2717:ff40  Redmi 9A                                                      Not attached
1-3    27c6:5125  Goodix Fingerprint USB Device                                 Not attached
1-6    13d3:5488  HD Camera, Camera DFU Device                                  Not attached
1-10   8087:0026  英特尔(R) 无线 Bluetooth(R)                                   Not attached
2-1    0bda:8152  Realtek USB FE Family Controller                              Not attached
2-2    25a4:9311  USB C Video Adaptor                                           Not attached
2-3    1ea7:0064  USB 输入设备                                                  Not attached
2-4    0403:6001  USB Serial Converter                                          Not attached

启动 WSL2

wsl -u ljd

Windows 关联 USB 串口到 WSL2

usbipd wsl attach --busid 2-4

2-4 为上面列出的 BUSID。偶尔会附加不上，反复多试试。

wsl2 中查看 usb 设备

lsusb

Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 002: ID 0403:6001 Future Technology Devices International, Ltd FT232 Serial (UART) IC
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

查找 USB 设备对应的设备文件

dmesg | grep -5 FT232

[   17.078734] usb 1-1: new full-speed USB device number 2 using vhci_hcd
[   17.168559] vhci_hcd: vhci_device speed not set
[   17.238554] usb 1-1: SetAddress Request (2) to port 0
[   17.289763] usb 1-1: New USB device found, idVendor=0403, idProduct=6001, bcdDevice= 6.00
[   17.292305] usb 1-1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[   17.292748] usb 1-1: Product: FT232R USB UART
[   17.292968] usb 1-1: Manufacturer: FTDI
[   17.293191] usb 1-1: SerialNumber: AB63OS0E
[   17.300507] ftdi_sio 1-1:1.0: FTDI USB Serial Device converter detected
[   17.301155] usb 1-1: Detected FT232RL
[   17.302566] usb 1-1: FTDI USB Serial Device converter now attached to ttyUSB0
[   49.581429] hv_balloon: Max. dynamic memory size: 8090 MB

串口设备读写权限

sudo chmod a+rw /dev/ttyUSB0

使用完成后，Windows 下分离，或直接物理断开 USB 设备

usbipd wsl detach --busid 2-4

时兼容时不兼容，不知道什么情况。

参考
微软 WSL 使用说明《连接USB设备》
isbipd wiki WSL-support

platform 总线

(1)相对于usb、pci、i2c等物理总线来说，Linux 提出了 platform 这个虚拟总线，相应的就有 platform_driver 和 platform_device。platform总线是虚拟的、抽象出来的。
(2)CPU与外部通信的2种方式：地址总线式连接和专用接口式连接。平台总线对应地址总线式连接设备，也就是SoC内部集成的各种内部外设。

Linux系统内核使用bus_type结构体表示总线，此结构体定义在文件include/linux/device.h，bus_type 结构体内容如下：

struct bus_type {
	const char		*name;
	const char		*dev_name;
	struct device		*dev_root;
	struct device_attribute	*dev_attrs;	/* use dev_groups instead */
	const struct attribute_group **bus_groups;
	const struct attribute_group **dev_groups;
	const struct attribute_group **drv_groups;

	int (*match)(struct device *dev, struct device_driver *drv);
	/* match 函数有两个参数：dev 和 drv，这两个参数分别为 device 和 device_driver 类型，也就是设备和驱动。*/
	int (*uevent)(struct device *dev, struct kobj_uevent_env *env);
	int (*probe)(struct device *dev);
	int (*remove)(struct device *dev);
	void (*shutdown)(struct device *dev);

	int (*online)(struct device *dev);
	int (*offline)(struct device *dev);

	int (*suspend)(struct device *dev, pm_message_t state);
	int (*resume)(struct device *dev);

	const struct dev_pm_ops *pm;

	const struct iommu_ops *iommu_ops;

	struct subsys_private *p;
	struct lock_class_key lock_key;
};

platform 总线是 bus_type 的一个具体实例，定义在文件drivers/base/platform.c，platform 总线定义如下：

struct bus_type platform_bus_type = {
	.name		= "platform",
	.dev_groups	= platform_dev_groups,
	.match		= platform_match,
	.uevent		= platform_uevent,
	.pm		= &platform_dev_pm_ops,
};

platform_match 函数定义在文件 drivers/base/platform.c 中，函数内容如下所示：

第一种匹配方式， OF 类型的匹配，也就是设备树采用的匹配方式,每个设备节点的 compatible 属性会和 of_match_table表中的所有成员比较，查看是否有相同的条目。
第二种匹配方式，ACPI 匹配方式。
第三种匹配方式，id_table 匹配，每个platform_driver 结构体有一个 id_table 成员变量。
第四种匹配方式，如果第三种匹配方式的 id_table不存在的话就直接比较驱动和 设备的 name 字段，看看是不是相等，如果相等的话就匹配成功。

platform 驱动

struct platform_driver {
	int (*probe)(struct platform_device *); 
	//一般驱动的提供者会编写probe 函数，当驱动与设备匹配成功以后 probe 函数就会执行，非常重要的函数！！
	int (*remove)(struct platform_device *);
	void (*shutdown)(struct platform_device *);
	int (*suspend)(struct platform_device *, pm_message_t state);
	int (*resume)(struct platform_device *);
	struct device_driver driver;
	const struct platform_device_id *id_table;
	//id_table 表，id_table 是个表(也就是数组)，每个元素的类型为 platform_device_id
	bool prevent_deferred_probe;
};

platform_driver 结构体

struct platform_device_id { 
	char name[PLATFORM_NAME_SIZE];
	kernel_ulong_t driver_data; 
};

device_driver 结构体

struct device_driver {
	const char		*name;
	struct bus_type		*bus;

	struct module		*owner;
	const char		*mod_name;	/* used for built-in modules */

	bool suppress_bind_attrs;	/* disables bind/unbind via sysfs */

	const struct of_device_id	*of_match_table;//of_match_table 就是采用设备树的时候驱动使用的匹配表
	const struct acpi_device_id	*acpi_match_table;

	int (*probe) (struct device *dev);
	int (*remove) (struct device *dev);
	void (*shutdown) (struct device *dev);
	int (*suspend) (struct device *dev, pm_message_t state);
	int (*resume) (struct device *dev);
	const struct attribute_group **groups;

	const struct dev_pm_ops *pm;

	struct driver_private *p;
};

of_device_id 结构体中的compatible 属性值和 of_match_table 中每个项目的 compatible成员变量进行比较

在编写 platform 驱动的时候，首先定义一个 platform_driver 结构体变量，然后实现结构体中的各个成员变量，重点是实现匹配方法以及 probe 函数。当驱动和设备匹配成功以后 probe函数就会执行，具体的驱动程序在 probe 函数里面编写，比如字符设备驱动等等。

初始化好 platform_driver 结构体变量以后，需要在驱动入口函数里面调用platform_driver_register 函数向 Linux 内核注册一个 platform 驱动
int platform_driver_register (struct platform_driver *driver)

函数参数和返回值含义如下：

driver：要注册的 platform 驱动。
返回值：负数，失败；0，成功。

还需要在驱动卸载函数中通过 platform_driver_unregister 函数卸载 platform 驱动，

void platform_driver_unregister(struct platform_driver *drv)

函数参数和返回值含义如下：

drv：要卸载的 platform 驱动。
返回值：无。

platform 驱动框架如下所示：

/*xxx_probe 函数，当驱动和设备匹配成功以后此函数就会执行，以前在驱动入口 init 
函数里面编写的字符设备驱动程序就全部放到此 probe 函数里面。
比如注册字符设备驱动、添加 cdev、创建类等等。*/
static int xxx_probe(struct platform_device *dev)
{
    ......
    cdev_init(&xxxdev.cdev, &xxx_fops); /* 注册字符设备驱动 */
    /* 函数具体内容 */
    return 0;
}

/*xxx_remove 函数，platform_driver 结构体中的 remove 成员变量，当关闭 plat
form设备驱动的时候此函数就会执行，以前在驱动卸载 exit 函数里面要做的事情
就放到此函数中来。比如，使用 iounmap 释放内存、删除 cdev，注销设备号等等。*/
static int xxx_remove(struct platform_device *dev)
{
    ......
    cdev_del(&xxxdev.cdev);/* 删除 cdev */
    /* 函数具体内容 */
    return 0;
}

/* xxx_of_match 匹配表，如果使用设备树的话将通过此匹配表进行驱动和设备的匹配。
设置了一个匹配项，此匹配项的 compatible 值为“xxx-gpio”，因此当设备树中
设备节点的 compatible 属性值为“xxx-gpio”的时候此设备就会与此驱动匹配。
{  Sentinel  }是一个标记，of_device_id 表最后一个匹配项必须是空的。*/
static const struct of_device_id xxx_of_match[] = {
    { .compatible = "xxx-gpio" },
    { /* Sentinel */ }
};
 
/*定义一个 platform_driver 结构体变量 xxx_driver，表示 platform 驱动，设置 paltform_driver 中的 device_driver 成员变量的 name 和 of_match_table 这两个属性。其中
name 属性用于传统的驱动与设备匹配，也就是检查驱动和设备的 name 字段是不是相同。
of_match_table 属性就是用于设备树下的驱动与设备检查。对于一个完整的驱动程序，必须提供
有设备树和无设备树两种匹配方法。一开始两行设置 probe 和 remove 这两成员变量。*/
static struct platform_driver xxx_device_driver = {
	.probe		= xxx_probe,
	.remove		= xxx_remove,
#ifdef CONFIG_PM
	.suspend	= xxx_suspend,
	.resume		= xxx_resume,
#endif
	.driver		= {
		.name	= "xxx",
		.of_match_table = xxx_of_match,
	},
};

static int __init xxx_init(void)
{
	int ret = bus_register(&xxx_bus_type);
	if (ret == 0)
		platform_driver_register(&xxx_device_driver);
	return ret;
}

static void __exit xxx_exit(void)
{
	platform_driver_unregister(&xxx_device_driver);
	bus_unregister(&xxx_bus_type);
}

platform 设备

platform_device 这个结构体表示 platform 设备，这里我们要注意，如果内核支持设备树的话就不要再使用 platform_device 来描述设备了，因为改用设备树去描述了。当然了，你如果一定要用 platform_device 来描述设备信息的话也是可以的。

struct platform_device {
	const char	*name;
	int		id;
	bool		id_auto;
	struct device	dev;
	u32		num_resources;
	struct resource	*resource;

	const struct platform_device_id	*id_entry;
	char *driver_override; /* Driver name to force a match */

	/* MFD cell pointer */
	struct mfd_cell *mfd_cell;

	/* arch specific additions */
	struct pdev_archdata	archdata;
};

name 表示设备名字，要和所使用的 platform 驱动的 name 字段相同，否则的话设备就无法匹配到对应的驱动。比如对应的 platform 驱动的 name 字段为“xxx-gpio”，那么此 name字段也要设置为“xxx-gpio”。

num_resources 表示资源数量，一般为下一行 resource 资源的大小。

resource 表示资源，也就是设备信息，比如外设寄存器等。Linux 内核使用 resource结构体表示资源

struct resource {
	resource_size_t start;
	resource_size_t end;
	const char *name;
	unsigned long flags;
	struct resource *parent, *sibling, *child;
};

start 和 end 分别表示资源的起始和终止信息，对于内存类的资源，就表示内存起始和终止地址，name 表示资源名字，flags 表示资源类型，可选的资源类型都定义在了文件include/linux/ioport.h 里面

#define IORESOURCE_BITS		0x000000ff	/* Bus-specific bits */

#define IORESOURCE_TYPE_BITS	0x00001f00	/* Resource type */
#define IORESOURCE_IO		0x00000100	/* PCI/ISA I/O ports */
#define IORESOURCE_MEM		0x00000200
#define IORESOURCE_REG		0x00000300	/* Register offsets */
#define IORESOURCE_IRQ		0x00000400
#define IORESOURCE_DMA		0x00000800
#define IORESOURCE_BUS		0x00001000

#define IORESOURCE_PREFETCH	0x00002000	/* No side effects */
#define IORESOURCE_READONLY	0x00004000
#define IORESOURCE_CACHEABLE	0x00008000
#define IORESOURCE_RANGELENGTH	0x00010000
#define IORESOURCE_SHADOWABLE	0x00020000

#define IORESOURCE_SIZEALIGN	0x00040000	/* size indicates alignment */
#define IORESOURCE_STARTALIGN	0x00080000	/* start field is alignment */

#define IORESOURCE_MEM_64	0x00100000
#define IORESOURCE_WINDOW	0x00200000	/* forwarded by bridge */
#define IORESOURCE_MUXED	0x00400000	/* Resource is software muxed */

#define IORESOURCE_EXCLUSIVE	0x08000000	/* Userland may not map this resource */
#define IORESOURCE_DISABLED	0x10000000
#define IORESOURCE_UNSET	0x20000000	/* No address assigned yet */
#define IORESOURCE_AUTO		0x40000000
#define IORESOURCE_BUSY		0x80000000	/* Driver has marked this resource busy */

/* PnP IRQ specific bits (IORESOURCE_BITS) */
#define IORESOURCE_IRQ_HIGHEDGE		(1<<0)
#define IORESOURCE_IRQ_LOWEDGE		(1<<1)
#define IORESOURCE_IRQ_HIGHLEVEL	(1<<2)
#define IORESOURCE_IRQ_LOWLEVEL		(1<<3)
#define IORESOURCE_IRQ_SHAREABLE	(1<<4)
#define IORESOURCE_IRQ_OPTIONAL 	(1<<5)

/* PnP DMA specific bits (IORESOURCE_BITS) */
#define IORESOURCE_DMA_TYPE_MASK	(3<<0)
#define IORESOURCE_DMA_8BIT		(0<<0)
#define IORESOURCE_DMA_8AND16BIT	(1<<0)
#define IORESOURCE_DMA_16BIT		(2<<0)

#define IORESOURCE_DMA_MASTER		(1<<2)
#define IORESOURCE_DMA_BYTE		(1<<3)
#define IORESOURCE_DMA_WORD		(1<<4)

#define IORESOURCE_DMA_SPEED_MASK	(3<<6)
#define IORESOURCE_DMA_COMPATIBLE	(0<<6)
#define IORESOURCE_DMA_TYPEA		(1<<6)
#define IORESOURCE_DMA_TYPEB		(2<<6)
#define IORESOURCE_DMA_TYPEF		(3<<6)

/* PnP memory I/O specific bits (IORESOURCE_BITS) */
#define IORESOURCE_MEM_WRITEABLE	(1<<0)	/* dup: IORESOURCE_READONLY */
#define IORESOURCE_MEM_CACHEABLE	(1<<1)	/* dup: IORESOURCE_CACHEABLE */
#define IORESOURCE_MEM_RANGELENGTH	(1<<2)	/* dup: IORESOURCE_RANGELENGTH */
#define IORESOURCE_MEM_TYPE_MASK	(3<<3)
#define IORESOURCE_MEM_8BIT		(0<<3)
#define IORESOURCE_MEM_16BIT		(1<<3)
#define IORESOURCE_MEM_8AND16BIT	(2<<3)
#define IORESOURCE_MEM_32BIT		(3<<3)
#define IORESOURCE_MEM_SHADOWABLE	(1<<5)	/* dup: IORESOURCE_SHADOWABLE */
#define IORESOURCE_MEM_EXPANSIONROM	(1<<6)

/* PnP I/O specific bits (IORESOURCE_BITS) */
#define IORESOURCE_IO_16BIT_ADDR	(1<<0)
#define IORESOURCE_IO_FIXED		(1<<1)

/* PCI ROM control bits (IORESOURCE_BITS) */
#define IORESOURCE_ROM_ENABLE		(1<<0)	/* ROM is enabled, same as PCI_ROM_ADDRESS_ENABLE */
#define IORESOURCE_ROM_SHADOW		(1<<1)	/* ROM is copy at C000:0 */
#define IORESOURCE_ROM_COPY		(1<<2)	/* ROM is alloc'd copy, resource field overlaid */
#define IORESOURCE_ROM_BIOS_COPY	(1<<3)	/* ROM is BIOS copy, resource field overlaid */

/* PCI control bits.  Shares IORESOURCE_BITS with above PCI ROM.  */
#define IORESOURCE_PCI_FIXED		(1<<4)	/* Do not move resource */

比如IORESOURCE_MEM表示这个资源是地址资源，IORESOURCE_IRQ表示这个资源是中断资源…。有了这几个属性，就可以完整的描述一个资源，但如果每个资源都需要单独管理而不是组成某种数据结构，显然是一种非常愚蠢的做法，所以内核的resource结构还提供了三个指针：parent,sibling,child(24)，分别用来表示资源的父资源，兄弟资源，子资源，这样内核就可以使用树结构来高效的管理大量的系统资源，linux内核有两种树结构：iomem_resource,ioport_resource，进行板级开发的时候，通常将主板上的ROM资源放入iomem_resource树的一个节点，而将系统固有的I/O资源挂到ioport_resource树上。
两种写法表示了地址资源和中断资源，强烈推荐使用DEFINE_RES_XXX的版本。

//IO地址资源，自己填充resource结构体+flags宏
struct resource res= {
	.start = 0x10000000,
	.end	 = 0x20000000-1,
	.flags = IORESOURCE_MEM
};
//IO地址资源，使用内核提供的定义宏
struct resource res = DEFINE_RES_MEM(0x20000000, 1024);
//中断资源，自己填充resource结构体+flags宏
struct resource res = {	
		.start	= 10,
		.flags	= IORESOURCE_IRQ,
};
//中断资源，使用内核提供的定义宏
struct resource res = DEFINE_RES_IRQ(11);

struct resource res[] = {
	[0] = {
		.start	= 0x10000000,
		.end	= 0x20000000-1,
		.flags	= IORESOURCE_MEM
	},
	[1] = DEFINE_RES_MEM(0x20000000, 1024),
	[2] = {
		.start	= 10,   //中断号
		.flags	= IORESOURCE_IRQ|IRQF_TRIGGER_RISING //include/linux/interrupt.h
	},
	[3] = DEFINE_RES_IRQ(11),	
};

在以前不支持设备树的Linux版本中，用户需要编写platform_device变量来描述设备信息，然后使用 platform_device_register 函数将设备信息注册到 Linux 内核中，此函数原型如下所示：

int platform_device_register(struct platform_device *pdev)

函数参数和返回值含义如下：

pdev：要注册的 platform 设备。
返回值：负数，失败；0，成功。

如果不再使用 platform 的话可以通过 platform_device_unregister 函数注销掉相应的 platform设备，platform_device_unregister 函数原型如下：

void platform_device_unregister(struct platform_device *pdev)

函数参数和返回值含义如下：

pdev：要注销的 platform 设备。
返回值：无

platform 设备信息框架如下所示：

/* 寄存器地址定义*/
#define PERIPH1_REGISTER_BASE (0X20000000) /* 外设 1 寄存器首地址 */ 
#define PERIPH2_REGISTER_BASE (0X020E0068) /* 外设 2 寄存器首地址 */
#define REGISTER_LENGTH 4 5 

/* 资源 */
static struct resource xxx_resources[] = { 
    [0] = { 
        .start = PERIPH1_REGISTER_BASE,
        .end = (PERIPH1_REGISTER_BASE + REGISTER_LENGTH - 1),
        .flags = IORESOURCE_MEM,
    }, 
    [1] = {
        .start = PERIPH2_REGISTER_BASE,
        .end = (PERIPH2_REGISTER_BASE + REGISTER_LENGTH - 1),
        .flags = IORESOURCE_MEM,
    },
};

/* platform 设备结构体 */
static struct platform_device xxxdevice = {
    .name = "xxx-gpio",
    .id = -1,
    .num_resources = ARRAY_SIZE(xxx_resources),
    .resource = xxx_resources,
};
 
/* 设备模块加载 */
static int __init xxxdevice_init(void)
{
    return platform_device_register(&xxxdevice);
}

/* 设备模块注销 */
static void __exit xxx_resourcesdevice_exit(void)
{
    platform_device_unregister(&xxxdevice);
}

module_init(xxxdevice_init);
module_exit(xxxdevice_exit);

版权声明：本文为CSDN博主「monkea123」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/monkea123/article/details/109082515

关与设备树的概念，我们在Exynos4412 内核移植（六）—— 设备树解析 里面已经学习过，下面看一下设备树在设备驱动开发中起到的作用

Device Tree是一种描述硬件的数据结构，设备树源(Device Tree Source)文件（以.dts结尾）就是用来描述目标板硬件信息的。Device Tree由一系列被命名的结点（node）和属性（property）组成，而结点本身可包含子结点。所谓属性，其实就是成对出现的name和value。在Device Tree中，可描述的信息包括（原先这些信息大多被hard code到kernel中）。

一、设备树基础概念

1、基本数据格式

device tree是一个简单的节点和属性树，属性是键值对，节点可以包含属性和子节点。下面是一个.dts格式的简单设备树。

/ {
    node1 {
        a-string-property = "A string";
        a-string-list-property = "first string", "second string";
        a-byte-data-property = [0x01 0x23 0x34 0x56];
        child-node1 {
            first-child-property;
            second-child-property = <1>;
            a-string-property = "Hello, world";
        };
        child-node2 {
        };
    };
    node2 {
        an-empty-property;
        a-cell-property = <1 2 3 4>; /* each number (cell) is a uint32 */
        child-node1 {
        };
    };
};

该树并未描述任何东西，也不具备任何实际意义，但它却揭示了节点和属性的结构。即：

a -- 一个的根节点:'/'，两个子节点：node1和node2；node1的子节点：child-node1和child-node2，一些属性分散在树之间。

b -- 属性是一些简单的键值对（key-value pairs）：value可以为空也可以包含任意的字节流。而数据类型并没有编码成数据结构，有一些基本数据表示可以在device tree源文件中表示。

c -- 文本字符串（null 终止）用双引号来表示：string-property = "a string"

d -- “Cells”是由尖括号分隔的32位无符号整数：cell-property = <0xbeef 123 0xabcd1234>

e -- 二进制数据是用方括号分隔：binary-property = [0x01 0x23 0x45 0x67];

f -- 不同格式的数据可以用逗号连接在一起：mixed-property = "a string", [0x01 0x23 0x45 0x67], <0x12345678>;

g -- 逗号也可以用来创建字符串列表：string-list = "red fish", "blue fish";

二、设备在device tree 中的描述

系统中的每个设备由device tree的一个节点来表示；

1、节点命名

花些时间谈谈命名习惯是值得的。每个节点都必须有一个[@]格式的名称。是一个简单的ascii字符串，最长为31个字符，总的来说，节点命名是根据它代表什么设备。比如说，一个代表3com以太网适配器的节点应该命名为ethernet，而不是3com509。

如果节点描述的设备有地址的话，就应该加上unit-address，unit-address通常是用来访问设备的主地址，并在节点的reg属性中被列出。后面我们将谈到reg属性。

2、设备

接下来将为设备树添加设备节点：

/ {
	compatible = "acme,coyotes-revenge";
 
	cpus {
		cpu@0 {
			compatible = "arm,cortex-a9";
		};
		cpu@1 {
            		compatible = "arm,cortex-a9";
        	};
    	};
 
	serial@101F0000 {
		compatible = "arm,pl011";
	};
 
	serial@101F2000 {
		compatible = "arm,pl011";
	};
 
	gpio@101F3000 {
		compatible = "arm,pl061";
	};
 
	interrupt-controller@10140000 {
		compatible = "arm,pl190";
	};
 
	spi@10115000 {
		compatible = "arm,pl022";
	};
	
	external-bus {
		ethernet@0,0 {
			compatible = "smc,smc91c111";
		};
	
		i2c@1,0 {
			compatible = "acme,a1234-i2c-bus";
			rtc@58 {
				compatible = "maxim,ds1338";
			};
        	};
 
		flash@2,0 {
			compatible = "samsung,k8f1315ebm", "cfi-flash";
       		 };
   	 };
};

在上面的设备树中，系统中的设备节点已经添加进来，树的层次结构反映了设备如何连到系统中。外部总线上的设备就是外部总线节点的子节点，i2c设备是i2c总线控制节点的子节点。总的来说，层次结构表现的是从CPU视角来看的系统视图。在这里这棵树是依然是无效的。它缺少关于设备之间的连接信息。稍后将添加这些数据。

设备树中应当注意：每个设备节点有一个compatible属性。flash节点的compatible属性有两个字符串。请阅读下一节以了解更多内容。 之前提到的，节点命名应当反映设备的类型，而不是特定型号。请参考ePAPR规范2.2.2节的通用节点命名，应优先使用这些命名。

3、compatible 属性

树中的每一个代表了一个设备的节点都要有一个compatible属性。compatible是OS用来决定绑定到设备的设备驱动的关键。

compatible是字符串的列表。列表中的第一个字符串指定了","格式的节点代表的确切设备，第二个字符串代表了与该设备兼容的其他设备。例如，Freescale MPC8349 SoC有一个串口设备实现了National Semiconductor ns16550寄存器接口。因此MPC8349串口设备的compatible属性为：compatible = "fsl,mpc8349-uart", "ns16550"。在这里，fsl,mpc8349-uart指定了确切的设备，ns16550表明它与National Semiconductor 16550 UART是寄存器级兼容的。

注：由于历史原因，ns16550没有制造商前缀，所有新的compatible值都应使用制造商的前缀。这种做法使得现有的设备驱动程序可以绑定到一个新设备上，同时仍能唯一准确的识别硬件。

4、编址

可编址的设备使用下列属性来将地址信息编码进设备树：

reg

#address-cells

#size-cells

每个可寻址的设备有一个reg属性，即以下面形式表示的元组列表：

      reg = <address1 length1 [address2 length2] [address3 length3] ... > 

每个元组,。每个地址值由一个或多个32位整数列表组成，被称做cells。同样地，长度值可以是cells列表，也可以为空。

既然address和length字段是大小可变的变量，父节点的#address-cells和#size-cells属性用来说明各个子节点有多少个cells。换句话说，正确解释一个子节点的reg属性需要父节点的#address-cells和#size-cells值。

5、内存映射设备

与CPU节点中的单一地址值不同，内存映射设备会被分配一个它能响应的地址范围。#size-cells用来说明每个子节点种reg元组的长度大小。
在下面的示例中，每个地址值是1 cell (32位) ，并且每个的长度值也为1 cell，这在32位系统中是非常典型的。64位计算机可以在设备树中使用2作为#address-cells和#size-cells的值来实现64位寻址。

serial@101f2000 {
	compatible = "arm,pl011";
	reg = <0x101f2000 0x1000 >;
};
 
gpio@101f3000 {
        compatible = "arm,pl061";
        reg = <0x101f3000 0x1000
               0x101f4000 0x0010>;
};
 
 
interrupt-controller@10140000 {
        compatible = "arm,pl190";
        reg = <0x10140000 0x1000 >;
};

每个设备都被分配了一个基地址及该区域大小。本例中的GPIO设备地址被分成两个地址范围:0x101f3000_{0x101f3fff和0x101f4000}0x101f400f。

三、设备树在platform设备驱动开发中的使用解析

我们仍以 Linux 设备驱动开发 —— platform设备驱动应用实例解析 文中的例子来解析设备树在platform设备驱动中如何使用；

1、设备树对platform中platform_device的替换

其实我们可以看到，Device Tree 是用来描述设备信息的，每一个设备在设备树中是以节点的形式表现出来；而在上面的 platform 设备中，我们利用platform_device 来描述一个设备，我们可以看一下二者的对比

fs4412-beep{
         compatible = "fs4412,beep";
         reg = < 0x114000a0 0x4  0x139D0000 0x14 >;
};

a -- fs4412-beep 为节点名，符合咱们前面提到的节点命名规范;
我们通过名字可以知道，该节点描述的设备是beep, 设备名是fs4412-beep；

b -- compatible = "fs4412,beep"; compatible 属性, 即一个字符串；
前面提到， 所有新的compatible值都应使用制造商的前缀，这里是
fs4412;

c -- reg = < 0x114000a0 0x4 0x139D0000 0x14 >;
reg属性来将地址信息编码进设备树，表示该设备的地址范围;这里是我们用到的寄存器及偏移量；

static struct  resource beep_resource[] =
{
    [0] = {
        .start = 0x114000a0,
        .end = 0x114000a0+0x4,
        .flags = IORESOURCE_MEM,
    },
    [1] = {
        .start = 0x139D0000,
        .end = 0x139D0000+0x14,
        .flags = IORESOURCE_MEM,
    },
};
static struct platform_device hello_device=
{
    .name = "bigbang",// 没用了
    .id = -1,
    .dev.release = hello_release,
    .num_resources = ARRAY_SIZE(beep_resource ),
    .resource = beep_resource,
};

可以看到设备树中的设备节点完全可以替代掉platform_device。

2、有了设备树，如何实现device 与 driver 的匹配？

我们在上一篇还有 platform_device 中，是利用 .name 来实现device与driver的匹配的，但现在设备树替换掉了device，那我们将如何实现二者的匹配呢？有了设备树后，platform比较的名字存在哪？

我们先看一下原来是如何匹配的 ，platform_bus_type 下有个match成员，platform_match 定义如下

static int platform_match(struct device *dev, struct device_driver *drv)
{
	struct platform_device *pdev = to_platform_device(dev);
	struct platform_driver *pdrv = to_platform_driver(drv);
 
	/* Attempt an OF style match first */
	if (of_driver_match_device(dev, drv))
		return 1;
 
	/* Then try ACPI style match */
	if (acpi_driver_match_device(dev, drv))
		return 1;
 
	/* Then try to match against the id table */
	if (pdrv->id_table)
		return platform_match_id(pdrv->id_table, pdev) != NULL;
 
	/* fall-back to driver name match */
	return (strcmp(pdev->name, drv->name) == 0);
}

其中又调用了of_driver_match_device(dev, drv) ，其定义如下：

static inline int of_driver_match_device(struct device *dev,
					 const struct device_driver *drv)
{
	return of_match_device(drv->of_match_table, dev) != NULL;
}

其调用of_match_device(drv->of_match_table, dev) ，继续追踪下去，注意这里的参数 drv->of_match_table

const struct of_device_id *of_match_device(const struct of_device_id *matches,
					   const struct device *dev)
{
	if ((!matches) || (!dev->of_node))
		return NULL;
	return of_match_node(matches, dev->of_node);
}
EXPORT_SYMBOL(of_match_device);

又调用 of_match_node(matches, dev->of_node) ，其中matches 是 struct of_device_id 类型的

/**
 * of_match_node - Tell if an device_node has a matching of_match structure
 *	@matches:	array of of device match structures to search in
 *	@node:		the of device structure to match against
 *
 *	Low level utility function used by device matching.
 */
const struct of_device_id *of_match_node(const struct of_device_id *matches,
					 const struct device_node *node)
{
	const struct of_device_id *match;
	unsigned long flags;
 
	raw_spin_lock_irqsave(&devtree_lock, flags);
	match = __of_match_node(matches, node);
	raw_spin_unlock_irqrestore(&devtree_lock, flags);
	return match;
}
EXPORT_SYMBOL(of_match_node);

找到 match = __of_match_node(matches, node); 注意着里的node是struct device_node 类型的

const struct of_device_id *__of_match_node(const struct of_device_id *matches,
					   const struct device_node *node)
{
	const struct of_device_id *best_match = NULL;
	int score, best_score = 0;
 
	if (!matches)
		return NULL;
 
	for (; matches->name[0] || matches->type[0] || matches->compatible[0]; matches++) {
		score = __of_device_is_compatible(node, matches->compatible,
						  matches->type, matches->name);
		if (score > best_score) {
			best_match = matches;
			best_score = score;
		}
	}
 
	return best_match;
}

继续追踪下去

static int __of_device_is_compatible(const struct device_node *device,
				     const char *compat, const char *type, const char *name)
{
	struct property *prop;
	const char *cp;
	int index = 0, score = 0;
 
	/* Compatible match has highest priority */
	if (compat && compat[0]) {
		prop = __of_find_property(device, "compatible", NULL);
		for (cp = of_prop_next_string(prop, NULL); cp;
		     cp = of_prop_next_string(prop, cp), index++) {
			if (of_compat_cmp(cp, compat, strlen(compat)) == 0) {
				score = INT_MAX/2 - (index << 2);
				break;
			}
		}
		if (!score)
			return 0;
	}
 
	/* Matching type is better than matching name */
	if (type && type[0]) {
		if (!device->type || of_node_cmp(type, device->type))
			return 0;
		score += 2;
	}
 
	/* Matching name is a bit better than not */
	if (name && name[0]) {
		if (!device->name || of_node_cmp(name, device->name))
			return 0;
		score++;
	}
 
	return score;
}

看这句 prop = __of_find_property(device, "compatible", NULL);
可以发先追溯到底，是利用"compatible"来匹配的，即设备树加载之后，内核会自动把设备树节点转换成 platform_device这种格式，同时把名字放到of_node这个地方。

platform_driver 部分

可以看到原来是利用platform_driver 下的 struct driver 结构体中的 name 成员来匹配的，看一下 struct driver 结构体的定义：

struct device_driver {
	const char		*name;
	struct bus_type		*bus;
 
	struct module		*owner;
	const char		*mod_name;	/* used for built-in modules */
 
	bool suppress_bind_attrs;	/* disables bind/unbind via sysfs */
 
	const struct of_device_id	*of_match_table;
	const struct acpi_device_id	*acpi_match_table;
 
	int (*probe) (struct device *dev);
	int (*remove) (struct device *dev);
	void (*shutdown) (struct device *dev);
	int (*suspend) (struct device *dev, pm_message_t state);
	int (*resume) (struct device *dev);
	const struct attribute_group **groups;
 
	const struct dev_pm_ops *pm;
 
	struct driver_private *p;
}

成员中有const struct of_device_id *of_match_table; 是struct of_device_id 类型，定义如下：

/*
 * Struct used for matching a device
 */
struct of_device_id
{
	char	name[32];
	char	type[32];
	char	compatible[128];
	const void *data;
};

可以看到其作用就是为了匹配一个设备。我们所要做的就是对 char compatible[128] 的填充；设备树加载之后，内核会自动把设备树节点转换成 platform_device这种格式，同时把名字放到of_node这个地方。

3、基于设备树的driver的结构体的填充

匹配的方式发生了改变，那我们的platform_driver 也要修改了

基于设备树的driver的结构体的填充：

static struct of_device_id beep_table[] = {
    {.compatible = "fs4412,beep"},
};
static struct platform_driver beep_driver=
{
    .probe = beep_probe,
    .remove = beep_remove,
    .driver={
        .name = "bigbang",
        .of_match_table = beep_table,
    },
};

原来的driver是这样的，可以对比一下

static struct platform_driver beep_driver=
{
    .driver.name = "bigbang",
    .probe = beep_probe,
    .remove = beep_remove,
};

4、设备树编译

我们在 arch/arm/boot/dts/exynos4412-fs4412.dts 中添加

fs4412-beep{
         compatible = "fs4412,beep";
         reg = <0x114000a0 0x4 0x139D0000 0x14>;
};

就可以编译设备树了
make dtbs 在内核根目录

vim arch/arm/boot/dts/exynos4412-fs4412.dts
sudo cp  arch/arm/boot/dts/exynos4412-fs4412.dtb /tftpboot/

然后，将设备树下载到0x42000000处，并加载驱动 insmod driver.ko, 测试下驱动。

版权声明：本文为CSDN博主「zqixiao_09」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/zqixiao_09/article/details/50889458