Xiaojie雷达之路---Mailbox Driver External Functions详解

本文链接：https://blog.csdn.net/Xiao_Jie123/article/details/110562923

文章目录

init
Config_init
open
write
read
readFlush

本文主要讲解为了使用驱动程序Mailbox而需要调用的所有导出的API

init

函数原型：

int32_t Mailbox_init(	
	Mailbox_Type localEndpoint	
)

函数功能：
该函数用于初始化邮箱模块。对于本地的端点只能调用一次。这个函数一定要其他任何邮箱API之前进行调用。

函数参数：
localEndpoint为输入参数，为本地的端点的类型，Mailbox_Type是一个枚举类型，它的值有以下四种

MAILBOX_TYPE_BSS
MAILBOX_TYPE_MSS
MAILBOX_TYPE_DSS
MAILBOX_TYPE_LAST

函数返回值：
失败的时候返回错误代码

Config_init

函数原型：

int32_t Mailbox_Config_init(	
	Mailbox_Config * 	cfg
)

函数功能：
函数将Mailbox_Config结构体初始化为默认值

函数参数：
cfg为输入参数，指向用于初始化Mailbox_Config结构体的指针，结构体的默认值如下：

readMode         = Mailbox_MODE_BLOCKING
writeMode        = Mailbox_MODE_BLOCKING
readTimeout      = MAILBOX_WAIT_FOREVER     
writeTimeout     = MAILBOX_WAIT_FOREVER    
readCallback     = NULL
opMode           = MAILBOX_OPERATION_MODE_PARTIAL_READ_ALLOWED
dataTransferMode = MAILBOX_DATA_TRANSFER_MEMCPY
chType           = MAILBOX_CHTYPE_SINGLE
chId             = MAILBOX_CH_ID_0

下面对每个结构体的变量进行说明：

readMode：这个变量指的是邮箱的读模式设置，并不是所有的模式都支持read/write API，下面是枚举类型的值：
1. MAILBOX_MODE_BLOCKING：Blocking mode，在发送或接收数据时，驱动要使用信号量来阻塞，调用的上下文必须时任务。更多参考Mailbox_write()和Mailbox_read()。
2. MAILBOX_MODE_POLLING：Polling mode，更多参考Mailbox_write()和Mailbox_read()。
3. MAILBOX_MODE_CALLBACK：Call back mode，这个模式仅对Mailbox_read API有效，当接收到要读取的新消息的中断或从先前发送的消息的应答接收到中断时，调用应用回调函数。应用程序仍然需要调用Mailbox_read() API来处理接收消息
writeMode：和readMode取值一样
readTimeout：读信号量的超时
writeTimeout：写信号量的超时
readCallback：指向读取的回调函数的指针，MAILBOX驱动程序在MAILBOX_MODE_CALLBACK模式下使用时回调函数被定义。回调可以发生在task和HWI上下文中。强烈要求在其自己的回调例程中进行Mailbox_read()调用，因为这会影响任务和系统栈的大小要求。
opMode：驱动的操作模式，是一个枚举型的变量，取值为：MAILBOX_OPERATION_MODE_PARTIAL_READ_ALLOWED，只有一种可用的操作模式，在这个模式下，驱动程序允许部分读取接收到的消息。应用程序读取完邮件后，Mailbox_readFlush()被调用。
dataTransferMode：数据的传输模式，这个配置定义了如何在Mailbox_write()和Mailbox_read() API中将数据从应用程序缓冲区传输到外围设备，以及如何从邮箱外围设备传输到应用程序缓冲区。这种配置用于两个方向。它是一个枚举型的变量，一个是MAILBOX_DATA_TRANSFER_MEMCPY ，这种方式是通过函数memcpy()在mailbox内存和application内存中进行数据的传输。另一个是MAILBOX_DATA_TRANSFER_DMA，这种方式是通过DMA在mailbox内存和application内存中进行数据的传输，但是当前不支持这种模式。
chType：邮箱的通道类型。仅当远程结点为MSS或DSS时使用。这个枚举定义一个了邮箱通道的类型，仅仅适用于MSS和DSS之间。这个字段允许MSS和DSS使用多个(虚拟)邮箱通道进行通信。由于只有一个邮箱物理通道，即使多个通道打开，应用程序一次只能使用一个通道。当使用多个通道时，每个通道由一个邮箱标识，MSS和DSS之间的最大通道数(或邮箱实例)由MAILBOX_CH_ID_MAX给出。通过MSS和DSS之间使用不同的Mailbox_ChID打开邮箱驱动程序的新实例来创建每个通道。如果一个通道被按MAILBOX_CHTYPE_SINGLE打开时，则只允许一个MSS和DSS通过，并且不用指定Mailbox_ChID。注意不能混合通道的类型，也就是说，MSS(或DSS)中的MAILBOX_CHTYPE_SINGLE不能与DSS(或MSS)上的MAILBOX_CHTYPE_MULTI类型的的通道通信。另外，如果打开的通道类型为MAILBOX_CHTYPE_MULTI ，则所有的频道都必须为MAILBOX_CHTYPE_MULTI 。在XWR14xx上，不使此字段。应用程序不需要在XWR14xx中设置此字段。在XWR16xx/XWR18xx/XWR68xx上，此字段仅仅用于MSS和DSS之间通信，当打开MSS和DSS之间的信道时，应用程序需要相应地设置此字段。在XWR16xx/XWR18xx/XWR68xx，此字段不能用于MSS和BSS之间或者DSS和BSS之间地通信。因此，当MSS或DSS打开带有BSS的信道时，应用程序不需要设置此字段。枚举类型的值为：MAILBOX_CHTYPE_SINGLE，DSS和MSS之间只允许一个邮箱通道(每个方向)，在这种情况下，不需要指定字段Mailbox_ChID。MAILBOX_CHTYPE_MULTI ，DSS和MSS之间允许多个邮箱通道(每个方向)。在这种情况下，需要指定Mailbox_ChID字段

chId：通道ID是驱动程序的实例，当远端的端点是MSS或者DSS的时候并且chType被设置为MAILBOX_CHTYPE_MULTI的时候才被使用。他是一个枚举型的变量，取值可以为以下值：

 MAILBOX_CH_ID_0	ID=0
 MAILBOX_CH_ID_1	ID=1
 MAILBOX_CH_ID_2	ID=2
 MAILBOX_CH_ID_3	ID=3
 MAILBOX_CH_ID_4	ID=4
 MAILBOX_CH_ID_5	ID=5
 MAILBOX_CH_ID_6	ID=6
 MAILBOX_CH_ID_7	ID=7
 MAILBOX_CH_ID_MAX	Maximum ID value，which is 	MAILBOX_CH_ID_7

函数返回值：
失败的时候返回错误代码

open

函数原型：

Mbox_Handle Mailbox_open(	
	Mailbox_Type 	remoteEndpoint,
	const Mailbox_Config * 	cfg,
	int32_t * 	errCode 
)

函数功能：
这个函数的功能是初始化邮箱驱动程序的实例，对于在XWR14xx中，在MSS和BSS之间只能打开一个驱动实例，对于在XWR16xx/XWR18xx/XWR68xx，在MSS和BSS之间只能打开一个驱动实例，在DSS和BSS之间只能打开一个驱动实例，在MSS和DSS之间多个驱动的实例可以被打开，每一个实例控制一个虚拟邮箱通道

函数参数：
remoteEndpoint是一个输入参数，是本地的邮箱实例将要与之通信的远端节点，Mailbox_Type是一个枚举类型，它的值有以下四种

MAILBOX_TYPE_BSS
MAILBOX_TYPE_MSS
MAILBOX_TYPE_DSS
MAILBOX_TYPE_LAST

cfg是一个输入参数，是指向Mailbox_Config的一个指针，关于Mailbox_Config的介绍，见Config_init中的参数介绍。
errCode是一个输出参数，指向了函数返回的错误代码值/状态的指针。

函数返回值：
执行成功返回一个Mbox_Handle，执行错误返回NULL值。

write

函数原型：

int32_t Mailbox_write(	
	Mbox_Handle handle,
	const uint8_t * buffer,
	uint32_t size 
)

函数功能：
这个函数的功能是写一个数据到邮箱，邮箱只能向远程结点一次只能发送一封邮件，将数据复制到邮箱缓冲区后，驱动程序将触发对远程端点的中断。这意味着对Mailbox_write()的调用始终是一个完整的邮箱事物。只有在远程端点确认前一条消息后，才能发送新消息。确认过程由驱动程序内部处理。所有写操作相关的中断都由驱动程序管理，不会暴露给应用程序。如果调用的数据超过邮箱缓冲区的大小，则写入操作将失败并返回错误代码，并且不会向邮箱缓冲区中写入任何内容。返回写入的字节数或错误。

邮箱缓冲区的大小由MAILBOX_DATA_BUFFER_SIZE给定，如果邮件大小大于邮箱缓冲区，则应用程序代码将负责邮件的碎片化。

写模式：

Mailbox_MODE_BLOCKING：
Mailbox_write()将阻塞任务执行，直到将消息从应用程序复制到邮箱缓冲区，并从远程终点收到确认。如果在收到确认之前产生了新的Mail_write()，则写入操作将失败，并向应用程序返回错误代码。

Mailbox_MODE_POLLING：
Mailbox_write()将阻塞任务的执行，直到消息从应用程序复制到邮箱缓冲区，但它不等待来自远程终点的确认。如果在收到确认之前发出了新的Mailbox_write()，则写入操作将失败并向应用程序返回错误代码。在这种模式下，应用程序不知道何时收到确认，它可能会尝试多次写入下一条消息，直到成功为止，就像它在轮询确认的状态一样。

函数参数：
handle是一个输入参数，指的是邮箱的句柄
buffer是一个输入参数，指向包含要写入邮箱的数据的缓冲区的指针
size是一个输入参数，缓冲区应该要写入邮箱的字节数

函数返回值：
返回已写入邮箱的字节数，如果发生错误，将返回一个邮箱错误代码

read

函数原型：

int32_t Mailbox_read(
	Mbox_Handle 	handle,
	uint8_t * 	buffer,
	uint32_t 	size 
)

函数功能：
这个函数的功能是从邮箱读取数据。邮箱一次只能从远程节点读取一封邮件，可以对邮箱的同一邮件执行多个Mailbox_read()调用。邮箱驱动程序在内部跟踪邮件读取的字节数。对于一条消息来说第一次Mailbox_read()总是从0开始。如果对同一个消息由多个Mailbox_read()调用，则后续读取将从上次读取停止的下一个字节开始。一旦应用程序读取完消息，它必须调用Mailbox_readFlush()以释放邮箱缓冲区并通知远程节点。邮箱缓冲区的最大大小由MAILBOX_DATA_BUFFER_SIZE给定，如果邮箱大小大于邮箱缓冲区，则应用程序代码负责邮件的碎片化。所有与读取操作相关的中断都由驱动程序管理，不会暴露给应用程序。返回读取的字节数或错误。

读模式：

Mailbox_MODE_BLOCKING：
如果这是对新消息的第一次读取，则Mailbox_read()将阻止任务执行，直到新邮件到达本地邮箱缓冲区并将其复制到应用程序缓冲区。如果这不是新的消息，则Mailbox_read()将阻止任务执行，直到"size"字节复制到应用程序缓冲区。

Mailbox_MODE_POLLING：
如果这是对新消息的第一次读取，但是新消息尚未到达，则Mailbox_read()将返回大小为0的值，表示没有读取到任何字节。如果新消息已到达，或者这不是新消息，则Mailbox_read()会将数据拷贝到应用程序缓冲区。“size”大小的字节被拷贝到应用缓冲区后，Mailbox_read()将被返回。

Mailbox_MODE_CALLBACK：
一旦邮箱中接受到新消息后，驱动程序将调用应用程序回调函数。应用程序负责调用Mail_read()来读取新邮件。Mailbox_read()将数据复制到应用程序缓冲区，然后退出。

在上述任何以一种模式下，在应用程序完全读取邮件后Mailbox_readFlush()将被引用

函数参数：
hangle是一个输入参数，指向邮箱的句柄
buffer是一个输入参数，指向一个空缓冲区的指针，接收到的数据应写入其中
size是一个输入参数，要写入缓冲区的字节数
函数返回值：
返回已从邮箱读取的字节数，如果发生错误，将返回一个邮箱错误代码

readFlush

函数原型：

int32_t Mailbox_readFlush(	
	Mbox_Handle 	handle
)

函数功能：
在应用程序读取消息后会调用这个函数，通知远程结点本地邮箱已准备好在读取前一个消息后接收新的消息。在本地结点调用Mailbox_readFlush()之前，远程结点无法向本地结点发送新的消息。一旦Mailbox_readFlush()被发出，本地结点必须假定以前的接收消息不再位于邮箱缓冲区中，并且后续的Mailbox_read()在在新消息到达邮箱之前不会返回任何数据

函数参数：
handle是一个输入参数，指的是邮箱的句柄
函数返回值：
失败的时候返回错误代码

参考文献：