SOC间点对点通讯协议：用户应用接口层

SOC间点对点通讯协议：用户应用接口层 的协作图:

#define	XWSSC_VERSION   ("1.0.0")
#define	XWSSC_VERSION_MAJOR   1U
#define	XWSSC_VERSION_MINOR   0U
#define	XWSSC_VERSION_REVISION   0U
#define	XWSSC_PRI_NUM   (XWMDCFG_isc_xwssc_PRI_NUM)
#define	XWSSC_INVALID_PRI   (0xFFU)
#define	XWSSC_MAX_PRI   (XWSSC_PRI_NUM - 1U)
#define	XWSSC_PORT_NUM   (XWMDCFG_isc_xwssc_PORT_NUM)
#define	XWSSC_RETRY_PERIOD   (XWMDCFG_isc_xwssc_RETRY_PERIOD)
#define	XWSSC_RETRY_NUM   (XWMDCFG_isc_xwssc_RETRY_NUM)
#define	XWSSC_MEMBLK_SIZE   (XWMDCFG_isc_xwssc_MEMBLK_SIZE)
#define	XWSSC_MEMBLK_ODR   (XWMDCFG_isc_xwssc_MEMBLK_ODR)
#define	XWSSC_MEMBLK_NUM   (1U << XWSSC_MEMBLK_ODR)
#define	XWSSC_MEMPOOL_SIZE   (XWSSC_MEMBLK_SIZE * XWSSC_MEMBLK_NUM)
#define	XWSSC_DEF_MEMPOOL(name)   __xwcc_alignl1cache xwu8_t name[XWSSC_MEMPOOL_SIZE]
	定义内存池
enum	xwssc_carrier_state_em {   XWSSC_CRS_IDLE = 0U , XWSSC_CRS_READY = 1U , XWSSC_CRS_INPROGRESS = 2U , XWSSC_CRS_ABORT = 3U ,   XWSSC_CRS_FINISH = 4U }
	发送状态枚举 更多...
enum	xwssc_msg_qos_em {   XWSSC_MSG_QOS_0 = 0U , XWSSC_MSG_QOS_1 = 1U , XWSSC_MSG_QOS_2 = 2U , XWSSC_MSG_QOS_3 = 3U ,   XWSSC_MSG_QOS_NUM , XWSSC_MSG_QOS_CHKSUM_MSK = (1U) , XWSSC_MSG_QOS_RELIABLE_MSK = (2U) , XWSSC_MSG_QOS_MSK }
	服务质量枚举 更多...
typedef struct xwssc_carrier *	xwssc_txh_t
	发送句柄
typedef void(*	xwssc_ntf_f) (struct xwssc *, xwssc_txh_t, xwer_t, void *)
	通知发送结果的回调函数
xwer_t	xwssc_start (struct xwssc *xwssc, const char *name, const struct xwssc_hwifal_operation *hwifops, void *hwifcb, xwu8_t *mem, xwsz_t memsize)
	XWSSC API: 启动XWSSC
xwer_t	xwssc_stop (struct xwssc *xwssc)
	XWSSC API: 停止XWSSC
bool	xwssc_tst_connected (struct xwssc *xwssc)
	XWSSC API: 测试XWSSC是否已经连接
xwer_t	xwssc_tx (struct xwssc *xwssc, const xwu8_t data[], xwsz_t *size, xwu8_t pri, xwu8_t port, xwu8_t qos, xwtm_t to)
	XWSSC API: 将用户数据加入到XWSSC的发送队列中，并在限定的时间内等待发送结果
xwer_t	xwssc_eq (struct xwssc *xwssc, const xwu8_t data[], xwsz_t *size, xwu8_t pri, xwu8_t port, xwu8_t qos, xwssc_ntf_f ntfcb, void *cbarg, xwssc_txh_t *txhbuf)
	XWSSC API: 将一条用户数据加入到XWSSC的发送队列中
xwer_t	xwssc_abort (struct xwssc *xwssc, xwssc_txh_t txh)
	XWSSC API: 中断发送
xwsq_t	xwssc_get_txstate (xwssc_txh_t txh)
	XWSSC API: 获取发送状态
xwer_t	xwssc_rx (struct xwssc *xwssc, xwu8_t port, xwu8_t rxbuf[], xwsz_t *size, xwu8_t *qos, xwtm_t to)
	XWSSC API: 接收消息，若接收队列为空，就限时等待
xwer_t	xwssc_try_rx (struct xwssc *xwssc, xwu8_t port, xwu8_t rxbuf[], xwsz_t *size, xwu8_t *qos)
	XWSSC API: 尝试接收消息，若接收队列为空，立即返回错误码

详细描述

宏定义说明

XWSSC_DEF_MEMPOOL

#define XWSSC_DEF_MEMPOOL

(

name

)

__xwcc_alignl1cache xwu8_t name[XWSSC_MEMPOOL_SIZE]

定义内存池

参数

[in]

name

数值名

在文件 mif.h 第 58 行定义.

XWSSC_INVALID_PRI

#define XWSSC_INVALID_PRI   (0xFFU)

无效优先级

在文件 mif.h 第 42 行定义.

XWSSC_MAX_PRI

#define XWSSC_MAX_PRI   (XWSSC_PRI_NUM - 1U)

XWSSC的大版本号

在文件 mif.h 第 43 行定义.

XWSSC_MEMBLK_NUM

#define XWSSC_MEMBLK_NUM   (1U << XWSSC_MEMBLK_ODR)

内存块的数量

在文件 mif.h 第 50 行定义.

XWSSC_MEMBLK_ODR

#define XWSSC_MEMBLK_ODR   (XWMDCFG_isc_xwssc_MEMBLK_ODR)

内存块数量的阶， 阶是指2的n次方中的n

在文件 mif.h 第 49 行定义.

XWSSC_MEMBLK_SIZE

#define XWSSC_MEMBLK_SIZE   (XWMDCFG_isc_xwssc_MEMBLK_SIZE)

单位内存块的大小

在文件 mif.h 第 47 行定义.

XWSSC_MEMPOOL_SIZE

#define XWSSC_MEMPOOL_SIZE   (XWSSC_MEMBLK_SIZE * XWSSC_MEMBLK_NUM)

内存池的总大小

在文件 mif.h 第 51 行定义.

XWSSC_PORT_NUM

#define XWSSC_PORT_NUM   (XWMDCFG_isc_xwssc_PORT_NUM)

端口号

在文件 mif.h 第 44 行定义.

XWSSC_PRI_NUM

#define XWSSC_PRI_NUM   (XWMDCFG_isc_xwssc_PRI_NUM)

优先级数量

在文件 mif.h 第 41 行定义.

XWSSC_RETRY_NUM

#define XWSSC_RETRY_NUM   (XWMDCFG_isc_xwssc_RETRY_NUM)

重试发送的次数

在文件 mif.h 第 46 行定义.

XWSSC_RETRY_PERIOD

#define XWSSC_RETRY_PERIOD   (XWMDCFG_isc_xwssc_RETRY_PERIOD)

重试发送的周期

在文件 mif.h 第 45 行定义.

XWSSC_VERSION

#define XWSSC_VERSION   ("1.0.0")

XWSSC的版本号字符串

在文件 mif.h 第 36 行定义.

XWSSC_VERSION_MAJOR

#define XWSSC_VERSION_MAJOR   1U

XWSSC的大版本号

在文件 mif.h 第 37 行定义.

XWSSC_VERSION_MINOR

#define XWSSC_VERSION_MINOR   0U

XWSSC的小版本号

在文件 mif.h 第 38 行定义.

XWSSC_VERSION_REVISION

#define XWSSC_VERSION_REVISION   0U

XWSSC的修订版本号

在文件 mif.h 第 39 行定义.

类型定义说明

xwssc_ntf_f

typedef void(* xwssc_ntf_f) (struct xwssc *, xwssc_txh_t, xwer_t, void *)

通知发送结果的回调函数

在文件 mif.h 第 99 行定义.

xwssc_txh_t

typedef struct xwssc_carrier* xwssc_txh_t

发送句柄

在文件 mif.h 第 67 行定义.

枚举类型说明

xwssc_carrier_state_em

enum xwssc_carrier_state_em

发送状态枚举

枚举值
XWSSC_CRS_IDLE
XWSSC_CRS_READY
XWSSC_CRS_INPROGRESS
XWSSC_CRS_ABORT
XWSSC_CRS_FINISH

在文件 mif.h 第 72 行定义.

                            {
        XWSSC_CRS_IDLE = 0U,
        XWSSC_CRS_READY = 1U,
        XWSSC_CRS_INPROGRESS = 2U,
        XWSSC_CRS_ABORT = 3U,
        XWSSC_CRS_FINISH = 4U,
};

xwssc_msg_qos_em

enum xwssc_msg_qos_em

服务质量枚举

枚举值
XWSSC_MSG_QOS_0	不可靠消息，无CRC校验码
XWSSC_MSG_QOS_1	不可靠消息，有CRC校验码
XWSSC_MSG_QOS_2	可靠消息，无CRC校验码
XWSSC_MSG_QOS_3	可靠消息，有CRC校验码
XWSSC_MSG_QOS_NUM	QOS数量
XWSSC_MSG_QOS_CHKSUM_MSK	CHKSUM标志的掩码，BIT(0)
XWSSC_MSG_QOS_RELIABLE_MSK	RELIABLE标志的掩码，BIT(1)
XWSSC_MSG_QOS_MSK	掩码，BIT(0) | BIT(1)

在文件 mif.h 第 83 行定义.

                      {
        XWSSC_MSG_QOS_0 = 0U, 
        XWSSC_MSG_QOS_1 = 1U, 
        XWSSC_MSG_QOS_2 = 2U, 
        XWSSC_MSG_QOS_3 = 3U, 
        XWSSC_MSG_QOS_NUM, 
        XWSSC_MSG_QOS_CHKSUM_MSK = (1U), 
        XWSSC_MSG_QOS_RELIABLE_MSK = (2U), 
        XWSSC_MSG_QOS_MSK = (XWSSC_MSG_QOS_CHKSUM_MSK |
                             XWSSC_MSG_QOS_RELIABLE_MSK), 
};

函数说明

xwssc_abort()

xwer_t xwssc_abort	(	struct xwssc *	xwssc,
		xwssc_txh_t	txh
	)

XWSSC API: 中断发送

参数

[in]	xwssc	XWSSC对象的指针
[in]	txh	发送句柄

返回

错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-EACCES	消息帧已经正在发送

注解

• 上下文：中断、中断底半部、线程
• 异步函数

如果消息已经被 XWSSC TX 线程选中，发送不可被中断； 仅当消息还在就绪队列中，未被选中发送时才可中断。

这是这个函数的调用关系图:

xwssc_eq()

xwer_t xwssc_eq	(	struct xwssc *	xwssc,
		const xwu8_t	data[],
		xwsz_t *	size,
		xwu8_t	pri,
		xwu8_t	port,
		xwu8_t	qos,
		xwssc_ntf_f	ntfcb,
		void *	cbarg,
		xwssc_txh_t *	txhbuf
	)

XWSSC API: 将一条用户数据加入到XWSSC的发送队列中

参数

[in]	xwssc	XWSSC对象的指针
[in]	data	数据缓冲区的指针
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示数据长度 (O) 作为输出时，返回实际入队的数据长度
[in]	pri	优先级
[in]	port	端口
[in]	qos	服务质量
[in]	ntfcb	通知发送结果的回调函数
[in]	cbarg	调用回调函数时的用户数据
[out]	txhbuf	指向缓冲区的指针，通过此缓冲区返回发送句柄

返回

错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-E2BIG	数据太长
-ENODEV	端口号超出范围
-EINVAL	qos错误
-ENOBUFS	帧槽被使用完
-EPERM	XWSSC未启动

注解

• 上下文：中断、中断底半部、线程
• 异步函数

• 此函数将用户数据放如发送队列就返回。当用户数据被XWSSC的发送线程成功发送 （接收到远程端应答），注册的回调函数会被调用；
• 回调函数在XWSSC的发送线程的线程上下文中执行，如果在此函数中使用了会 长时间阻塞线程的函数，会导致XWSSC停止发送。
• to 表示等待超时的时间点：
  • to 通常是未来的时间，即 当前系统时间 + delta ， 可以使用 xwtm_ft(delta) 表示；
  • 如果 to 是过去的时间点，将直接返回 -ETIMEDOUT 。

这是这个函数的调用关系图:

xwssc_get_txstate()

xwsq_t xwssc_get_txstate

(

xwssc_txh_t

txh

)

XWSSC API: 获取发送状态

参数

[in]

txh

发送句柄

返回

发送状态，取值： xwssc_carrier_state_em

注解

• 上下文：中断、中断底半部、线程

这是这个函数的调用关系图:

xwssc_rx()

xwer_t xwssc_rx	(	struct xwssc *	xwssc,
		xwu8_t	port,
		xwu8_t	rxbuf[],
		xwsz_t *	size,
		xwu8_t *	qos,
		xwtm_t	to
	)

XWSSC API: 接收消息，若接收队列为空，就限时等待

参数

[in]	xwssc	XWSSC对象的指针
[in]	port	接收消息的端口
[out]	rxbuf	指向缓冲区的指针，此缓冲区用于接收消息
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的消息大小
[out]	qos	指向缓冲区的指针，此缓冲区用于返回消息的QoS，可为NULL表示不关心QoS
[in]	to	期望唤醒的时间点

返回

错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENODEV	端口号超出范围
-EPERM	XWSSC未启动
-ETIMEDOUT	超时

注解

• 上下文：线程

to 表示等待超时的时间点：

• to 通常是未来的时间，即 当前系统时间 + delta ， 可以使用 xwtm_ft(delta) 表示；
• 如果 to 是过去的时间点，将直接返回 -ETIMEDOUT 。

这是这个函数的调用关系图:

xwssc_start()

xwer_t xwssc_start	(	struct xwssc *	xwssc,
		const char *	name,
		const struct xwssc_hwifal_operation *	hwifops,
		void *	hwifcb,
		xwu8_t *	mem,
		xwsz_t	memsize
	)

XWSSC API: 启动XWSSC

参数

[in]	xwssc	XWSSC对象的指针
[in]	name	XWSSC实例的名字
[in]	hwifops	硬件接口抽象层操作函数集合
[in]	hwifcb	硬件接口控制块指针
[in]	mem	连续的内存块
[in]	memsize	连续的内存块大小，值必须为 XWSSC_MEMPOOL_SIZE

返回

错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENOMEM	内存池太小
-EPERM	XWSSC未初始化

注解

• 参数 mem 作为xwssc发送和接收缓冲区，用户可以使用 XWSSC_DEF_MEMPOOL 定义， XWSSC_DEF_MEMPOOL 增加修饰符 __xwcc_alignl1cache ，可提高内存的访问的效率。
• 参数 memsize 作用是提醒用户 mem 的大小必须为 XWSSC_MEMPOOL_SIZE ， API内部也会做检查。

• 上下文：线程
• 重入性：不可重入

xwssc_stop()

xwer_t xwssc_stop

(

struct xwssc *

xwssc

)

XWSSC API: 停止XWSSC

参数

[in]

xwssc

XWSSC对象的指针

返回

错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

• 上下文：中断、中断底半部、线程
• 重入性：不可重入

xwssc_try_rx()

xwer_t xwssc_try_rx	(	struct xwssc *	xwssc,
		xwu8_t	port,
		xwu8_t	rxbuf[],
		xwsz_t *	size,
		xwu8_t *	qos
	)

XWSSC API: 尝试接收消息，若接收队列为空，立即返回错误码

参数

[in]	xwssc	XWSSC对象的指针
[in]	port	接收消息的端口
[out]	rxbuf	指向缓冲区的指针，此缓冲区用于接收消息
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的消息大小
[out]	qos	返回消息的QoS的缓冲区，可为 NULL 表示不关心QoS

返回

错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENODEV	端口号超出范围
-ENODATA	接收队列为空
-EPERM	XWSSC未启动

注解

• 上下文：中断、中断底半部、线程

这是这个函数的调用关系图:

xwssc_tst_connected()

bool xwssc_tst_connected

(

struct xwssc *

xwssc

)

XWSSC API: 测试XWSSC是否已经连接

参数

[in]

xwssc

XWSSC对象的指针

返回

布尔值

返回值

true	已链接
false	未链接

注解

• 上下文：中断、中断底半部、线程

xwssc_tx()

xwer_t xwssc_tx	(	struct xwssc *	xwssc,
		const xwu8_t	data[],
		xwsz_t *	size,
		xwu8_t	pri,
		xwu8_t	port,
		xwu8_t	qos,
		xwtm_t	to
	)

XWSSC API: 将用户数据加入到XWSSC的发送队列中，并在限定的时间内等待发送结果

参数

[in]	xwssc	XWSSC对象的指针
[in]	data	数据缓冲区的指针
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示数据长度 (O) 作为输出时，返回实际发送的数据长度
[in]	pri	用户数据的优先级
[in]	port	端口
[in]	qos	服务质量，取值范围： xwssc_msg_qos_em
[in]	to	期望唤醒的时间点

返回

错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-E2BIG	数据太长
-ENODEV	端口号超出范围
-EINVAL	qos错误
-ENOBUFS	帧槽被使用完
-EPERM	XWSSC未启动

注解

• 上下文：线程

to 表示等待超时的时间点：

• to 通常是未来的时间，即 当前系统时间 + delta ， 可以使用 xwtm_ft(delta) 表示；
• 如果 to 是过去的时间点，将直接返回 -ETIMEDOUT 。

这是这个函数的调用关系图: