From e16803ad757617a20b3ae05f567ed8175017c4af Mon Sep 17 00:00:00 2001 From: ShermanShao Date: Tue, 18 May 2021 16:26:59 +0800 Subject: [PATCH] =?UTF-8?q?!1=20[=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3]=20?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=20rt-link=20=E7=BB=84=E4=BB=B6=E6=96=87?= =?UTF-8?q?=E6=A1=A3=20*=20[=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3]=20?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=20rt-link=20=E7=BB=84=E4=BB=B6=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../programming-manual/rtlink/rtlink.md | 61 ++++++++++++------- 1 file changed, 40 insertions(+), 21 deletions(-) diff --git a/rt-thread-version/rt-thread-standard/programming-manual/rtlink/rtlink.md b/rt-thread-version/rt-thread-standard/programming-manual/rtlink/rtlink.md index 02223f0..77dd553 100644 --- a/rt-thread-version/rt-thread-standard/programming-manual/rtlink/rtlink.md +++ b/rt-thread-version/rt-thread-standard/programming-manual/rtlink/rtlink.md @@ -1,21 +1,22 @@ # RT-Link 介绍 -## 简介 - RT-Link 是一套开放的链路层传输协议，设计的初衷是为了稳定、安全、高效率的完成设备间 点对点 的数据传输，并且接口简单、使用便捷。 -## 目录结构 +**目录结构:** ```shell -linklayer -├───hw_port // 对接硬件端口 -├───inc // 头文件 -├───src // rtlink源码文件 -├───Kconfig -└───SConscript +rtthread +└───components + └───utilities + └───rt-link + ├───hw_port // 对接硬件端口 + ├───inc // 头文件 + ├───src // rtlink源码文件 + ├───Kconfig + └───SConscript ``` -## 功能特点 +**功能特点:** - **稳定**：RT-Link 具有 数据重传、帧序号检查、状态同步等一系列能力，保证传输的稳定； - **安全**：支持 CRC 校验，采用以太网检验协议； @@ -25,20 +26,21 @@ linklayer # 工作原理 -## 整体框架 -![rtlink整体框架](./figures/rtlink应用框架.jpg) +**整体框架:** -最上层为 APP 应用服务层，提供发送和注册接收回调两个操作接口，使用非常便捷； -第二层为 RT-Link 传输层，是 RT-Link 核心功能的实现，用来保证数据传输功能的可靠稳定。 -第三层为 hardware 链路层，是用来对接具体的硬件端口，例如 UART、SPI、USB 等； -最下层为设备的 BSP 驱动层。 +![rtlink整体框架](./figures/rtlink应用框架.jpg) +- 最上层为 APP 应用服务层，提供发送和注册接收回调两个操作接口，使用非常便捷； +- 第二层为 RT-Link 传输层，是 RT-Link 核心功能的实现，用来保证数据传输功能的可靠稳定。 +- 第三层为 hardware 链路层，是用来对接具体的硬件端口，例如 UART、SPI、USB 等； +- 最下层为设备的 BSP 驱动层。 # 使用指南 -## 如何添加、使用 RT-Link +## 如何添加、使用 RT-Link： 这里以 studio 为例，在配置页找到 组件-->工具-->RT-Link，选择开启并进行配置。如下图所示。 + ![rtlink整体框架](./figures/settings.jpg) - 配置 CRC 计算方式，软件 CRC 功能已包含在 RT-Link 中，硬件 CRC 需要根据不同平台自行对接相关接口； @@ -46,11 +48,12 @@ linklayer - 保存设置就可以将 RT-Link 添加到现在的工程中了，DEBUG 选项可根据调试需求选择开启，默认关闭。 - 还有一件事，别忘了打开要使用的硬件接口 + ![rtlink整体框架](./figures/uart.jpg) - 这里选择了两块潘多拉开发板来测试运行效果，[示例代码](#示例代码) 在文档尾部↓↓↓。运行效果如下： -![rtlink整体框架](./figures/收发测试.jpg) +![rtlink整体框架](./figures/收发测试.jpg) ## 上层应用接口介绍 @@ -66,10 +69,12 @@ rt_err_t rt_link_service_detach(rt_link_service_t service); ``` ### 初始化 + ```c int rt_link_init(void); ``` 默认为自动初始化，可根据具体应用决定是否开启自动初始化，如需关闭自动初始化可在 `rtlink.h` 中注释掉宏定义 `RT_LINK_AUTO_INIT` + | 返回值 | 描述 | | ------ | ---------- | | RT_EOK | 初始化成功 | @@ -77,18 +82,22 @@ int rt_link_init(void); | -RT_ERROR | 初始化失败 | ### 去初始化 + ```c rt_err_t rt_link_deinit(void); ``` 当不需要使用 RT-Link 时，可执行 deinit 删除处理线程，释放系统资源。 + | 返回值 | 描述 | | ------ | ---------- | | RT_EOK | 去初始化成功 | ### 注册服务接收回调 + ```c rt_err_t rt_link_service_attach(rt_link_service_t service, rt_err_t (*function)(void *data, rt_size_t size)); ``` + ```c typedef enum { @@ -104,7 +113,7 @@ typedef enum | 参数 | 描述 | | ------ | ---------- | | service | 要注册的服务通道,可在`rt_link_service_t`中选择，或添加自定义服务类型 | -| function | 服务对应的接收回调函数，接收回调的参数为 `void *data, rt_size_t size`，返回值为 `rt_err_t` 类型，需要注意的是 **data 指向的空间由 RT-link 动态申请，应用层使用完毕后自行释放** | +| function | 服务对应的接收回调函数，接收回调的参数为 `void *data, rt_size_t size`，返回值为 `rt_err_t` 类型，
需要注意的是 **data 指向的空间由 RT-link 动态申请，应用层使用完毕后自行释放** | | 返回值 | 描述 | | ------ | ---------- | @@ -112,9 +121,11 @@ typedef enum ### 解除服务接收通道 + ```c rt_err_t rt_link_service_detach(rt_link_service_t service); ``` + | 参数 | 描述 | | ------ | ---------- | | service | 要解除的服务通道 | @@ -125,9 +136,11 @@ rt_err_t rt_link_service_detach(rt_link_service_t service); ### 发送数据 + ```c rt_size_t rt_link_send(rt_link_service_t service, void *data, rt_size_t size); ``` + | 参数 | 描述 | | ------ | ---------- | | service | 数据所属的服务通道 | @@ -141,7 +154,9 @@ rt_size_t rt_link_send(rt_link_service_t service, void *data, rt_size_t size); ## 底层链路对接接口介绍 + 底层链路对接接口定义在 `rtlink_port.h` 中，需要在对接移植是实现。 + ```c /* Functions that need to be implemented at the hardware */ int rt_link_port_init(void); @@ -153,16 +168,20 @@ rt_size_t rt_link_hw_write_cb(void *data, rt_size_t length); ``` ### 初始化与去初始化 + ```c int rt_link_port_init(void); int rt_link_port_deinit(void); ``` + 主要用于初始化底层端口的资源，在 RT-Link 初始化和去初始化时会调用，这部分是需要在移植对接时自行实现。对于 UART、SPI 等在 RT-Thread 中则可使用 device 框架提供的相关接口。 ### 数据发送 + ```c rt_size_t rt_link_port_send(void *data, rt_size_t length); ``` + 此函数将会由 RT-Link 的核心逻辑调用，用于通过实际的端口发送数据。对于 UART 这类比较 **简单的** 接口，可以直接发送，不会影响系统的运行。对于比较 **复杂的** 通信接口，例如 **SPI, USB** 等可以通过事件、邮箱等机制来实现发送逻辑。 | 参数 | 描述 | @@ -177,9 +196,11 @@ rt_size_t rt_link_port_send(void *data, rt_size_t length); ### 数据写入 + ```c rt_size_t rt_link_hw_write_cb(void *data, rt_size_t length); ``` + 在底层接口接收到数据时，可以直接调用该函数来向 RT-Link 发送数据，向上层服务提供接收的数据。 **该函数可在中断内直接调用。** | 参数 | 描述 | @@ -192,8 +213,6 @@ rt_size_t rt_link_hw_write_cb(void *data, rt_size_t length); | 0 | 写入失败 | | > 0 | 实际写入的数据长度 | - - # 示例代码 ```c -- Gitee