1 /** 2 * @file hi_msg.h 3 * 4 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. \n 16 * 17 * Description: message APIs.CNcomment:消息接口。CNend 18 * @li Wait message: the wait message API cannot be called, to avoid uncontrollable exception scheduling. 19 CNcomment:等待消息:在中断、关中断、锁任务上下文禁止调用等待消息接口，进而产生不可控的异常调度。CNend 20 * @li TX message: In the interrupt off context, the message TX API cannot be called, to avoid uncontrollable exception 21 * scheduling.CNcomment:发送消息:在关中断上下文禁止调用发送消息接口，进而产生不可控的异常调度。CNend 22 * @li TX message (the timeout period is not 0): In the interrupt and task locked context, the message TX API cannot be 23 * called, to avoid uncontrollable exception scheduling.CNcomment:发送消息(超时时间非0):在中断、锁任务上下文禁止调用 24 超时时间非0发送消息接口，进而产生不可控的异常调度。CNend \n 25 */ 26 27 /** 28 * @defgroup iot_msgqueue Message Queue 29 * @ingroup osa 30 */ 31 #ifndef __HI_MSG_H__ 32 #define __HI_MSG_H__ 33 #include <hi_types_base.h> 34 35 /** 36 * @ingroup iot_msgqueue 37 * 38 * Failed to read the message queue.CNcomment:读取消息队列出错。CNend 39 */ 40 #define HI_MSG_INVALID_MSG_NUM 0xFFFFFFFF 41 #define HI_SYS_MSG_PARAM_NUM_MAX 4 42 43 typedef struct { 44 hi_u32 msg_id; /* < Message ID.CNcomment:消息ID CNend */ 45 uintptr_t param[HI_SYS_MSG_PARAM_NUM_MAX]; /* < Message parameter.CNcomment:消息参数 CNend */ 46 } hi_sys_queue_msg; 47 48 /** 49 * @ingroup iot_msgqueue 50 * @brief Creates a message queue.CNcomment:创建消息队列。CNend 51 * 52 * @par 描述: 53 * Creates a message queue.CNcomment:创建消息队列。CNend 54 * 55 * @attention The number of message queues supported by the system needs to be set during initialization. 56 CNcomment:系统支持的总消息队列个数，需要在初始化阶段设置。CNend 57 * 58 * @param id [OUT] type #hi_u32*，Handle of the created message queue. 59 CNcomment:所创建的消息队列句柄。CNend 60 * @param queue_len [IN] type #hi_u16，Message queue length, that is, the number of messages that can be stored 61 * in the message queue.CNcomment:消息队列长度，即该消息队列支持存储多少条消息。CNend 62 * @param msg_size [IN] type #hi_u32，Size of each message in the message queue (unit: byte) 63 CNcomment:消息队列中一条消息大小（单位：byte）。CNend 64 * 65 * @retval #HI_ERR_SUCCESS Success 66 * @retval #HI_ERR_MSG_INVALID_PARAM An input argument is incorrect, the handle pointer is null, the name address is 67 * null, or the message queue length is 0.CNcomment:入参错误、句柄指针为空、名字地址为空、消息队列长度为0。CNend 68 * @retval #HI_ERR_MSG_CREATE_Q_FAIL An error occurred when creating the message queue, for example, insufficient 69 * memory or insufficient message queue resources. 70 CNcomment:创建消息队列错误，比如：内存不足、消息队列资源不足。CNend 71 * @par 依赖: 72 * @li hi_msg.h：Describes message queue APIs.CNcomment:文件用于描述消息队列相关接口。CNend 73 * @li hi_config.h：Describes the message queue configuration.CNcomment:文件用于消息队列配置。CNend 74 * @li hi_errno.h：Describes file configuration error codes.CNcomment:文件配置错误码。CNend 75 * @see hi_msg_queue_delete。 76 */ 77 hi_u32 hi_msg_queue_create(HI_OUT hi_u32 *id, hi_u16 queue_len, hi_u32 msg_size); 78 79 /** 80 * @ingroup iot_msgqueue 81 * @brief Deletes a message queue.CNcomment:删除消息队列。CNend 82 * 83 * @par 描述: 84 * Deletes a message queue.CNcomment:删除消息队列。CNend 85 * 86 * @attention None 87 * @param id [IN] type #hi_u32，Handle of the created message queue.CNcomment:消息队列句柄。CNend 88 * 89 * @retval #HI_ERR_SUCCESS Success 90 * @retval #HI_ERR_MSG_Q_DELETE_FAIL An error occurred with the message queue, for example, the ID is out of 91 * range, the message queue is not created, or the message queue is in use.CNcomment:删除消息队列错误， 92 比如：ID越界、消息队列未创建、消息队列正在使用中无法删除等。CNend 93 * @par 依赖: 94 * @li hi_msg.h：Describes message queue APIs.CNcomment:文件用于描述消息队列相关接口。CNend 95 * @li hi_config.h：Describes the message queue configuration.CNcomment:文件用于消息队列配置。CNend 96 * @li hi_errno.h：Describes file configuration error codes.CNcomment:文件配置错误码。CNend 97 @see hi_msg_queue_create。 98 */ 99 hi_u32 hi_msg_queue_delete(hi_u32 id); 100 101 /** 102 * @ingroup iot_msgqueue 103 * @brief Sends a message.CNcomment:发送消息。CNend 104 * 105 * @par 描述: 106 * Sends a message.发送消息。CNend 107 * 108 * @attention None 109 * @param id [IN] type #hi_u32，Message queue handle.CNcomment:消息队列句柄。CNend 110 * @param msg [IN] type #hi_pvoid，Message content pointer.CNcomment:消息内容指针。CNend 111 * @param timeout_ms [IN] type #hi_u32，Timeout period for sending a message. The value 0 indicates 112 * that the message is sent immediately.CNcomment:消息发送的最大超时时间(单位：ms)， 113 立即发送时写0。CNend 114 * @param msg_size [IN] type #hi_u32，Size of the sent message (unit: byte). 115 CNcomment:发送消息大小（单位：byte）。CNend 116 * 117 * @retval #HI_ERR_SUCCESS Success. 118 * @retval #HI_ERR_MSG_SEND_FAIL An error occurs with the message queue, for example, an input argument is 119 * incorrect, the message queue is not created, the size of the sent data is 120 * greater than the configured size when the queue is created, or the API is 121 * used in an interrupt but the timeout period is not 0. 122 CNcomment:发送消息队列错误，包括：入参错误、消息队列未创建、发送数据大于队列创建时设置大小、 123 中断中使用但超时时间不为0。CNend 124 * 125 * @retval #HI_ERR_MSG_INVALID_PARAM An input argument is incorrect or the message queue pointer is null. 126 CNcomment:入参错误、消息队列指针为空。CNend 127 * 128 * @par 依赖: 129 * @li hi_msg.h：Describes message queue APIs.CNcomment:文件用于描述消息队列相关接口。CNend 130 * @li hi_config.h：Describes the message queue configuration.CNcomment:文件用于消息队列配置。CNend 131 * @li hi_errno.h：Describes file configuration error codes.CNcomment:文件配置错误码。CNend 132 * @see hi_msg_queue_wait。 133 */ 134 hi_u32 hi_msg_queue_send(hi_u32 id, hi_pvoid msg, hi_u32 timeout_ms, hi_u32 msg_size); 135 136 /** 137 * @ingroup iot_msgqueue 138 * @brief Receives a message.CNcomment:接收消息。CNend 139 * 140 * @par 描述: 141 * Receives a message.CNcomment:接收消息。CNend 142 * 143 * @attention None 144 * @param id [IN] type #hi_u32，Message queue handle.CNcomment:消息队列句柄。CNend 145 * @param msg [OUT] type #hi_pvoid，Message content pointer.CNcomment:消息内容指针。CNend 146 * @param timeout_ms [IN] type #hi_u32，Timeout period for receiving a message. The value #HI_SYS_WAIT_FOREVER 147 * indicates permanent wait.CNcomment:消息接收超时时间(单位：ms)， 148 如果表示永久等待使用#HI_SYS_WAIT_FOREVER。CNend 149 * @param msg_size [IN] type #hi_u32*，Expected message length (unit: byte),if wait msg success, this val will fill 150 with actually size of msg. 151 CNcomment:输入期望的消息长度（单位：byte），如果等待消息成功，该值将被赋值为实际接收到的消息长度。CNend 152 * 153 * @retval #HI_ERR_SUCCESS Success.CNcomment:消息接收成功。CNend 154 * @retval #HI_ERR_MSG_WAIT_FAIL An error occurs with the message queue, for example, an input argument is incorrect, 155 * the message queue is not created, the size of the waiting message is smaller than 156 * the size set when the queue is created, or the API is used in an interrupt but the 157 * timeout period is not 0.CNcomment:等待消息队列错误，比如：入参不正确、消息队列未 158 创建、等待消息大小小于队列创建时设置大小、中断中等待超时非零的消息队列。CNend 159 * @retval #HI_ERR_MSG_INVALID_PARAM An input argument is incorrect or the message queue pointer is null. 160 CNcomment:入参错误、消息队列指针为空。CNend 161 * @retval #HI_ERR_MSG_WAIT_TIME_OUT No message is received when the waiting times out. 162 CNcomment:等待超时未收到消息。CNend 163 * @par 依赖: 164 * @li hi_msg.h：Describes message queue APIs.CNcomment:文件用于描述消息队列相关接口。CNend 165 * @li hi_config.h：Describes the message queue configuration.CNcomment:文件用于消息队列配置。CNend 166 * @li hi_errno.h：Describes file configuration error codes.CNcomment:文件配置错误码。CNend 167 * @see hi_msg_queue_send。 168 */ 169 hi_u32 hi_msg_queue_wait(hi_u32 id, HI_OUT hi_pvoid msg, hi_u32 timeout_ms, hi_u32* msg_size); 170 171 /** 172 * @ingroup iot_msgqueue 173 * @brief Checks whether the message queue is full.CNcomment:检查消息队列是否已满。CNend 174 * 175 * @par 描述: 176 * Checks whether the message queue is full.CNcomment:检查消息队列是否已满。CNend 177 * 178 * @attention None 179 * @param id [IN] type #hi_u32，Message queue handle.CNcomment:消息队列句柄。CNend 180 * 181 * @retval #HI_TRUE The message queue is full or the message queue information fails to be obtained. 182 CNcomment:消息队列已满或获取消息队列信息失败。CNend 183 * @retval #HI_FALSE The message queue is not full.CNcomment:消息队列未满。CNend 184 * @par 依赖: 185 * @li hi_msg.h：Describes message queue APIs.CNcomment:文件用于描述消息队列相关接口。CNend 186 * @see None 187 */ 188 hi_bool hi_msg_queue_is_full(hi_u32 id); 189 190 /** 191 * @ingroup iot_msgqueue 192 * @brief Obtains the number of used message queues.CNcomment:获取当前已经使用的消息队列个数。CNend 193 * 194 * @par 描述: 195 * Obtains the number of used message queues.CNcomment:获取当前已经使用的消息队列个数。CNend 196 * 197 * @attention None 198 * @param id [IN] #hi_u32，Handle of the created message queue.CNcomment:消息队列句柄。CNend 199 * 200 * @retval #HI_ERR_MSG_INVALID_MSG_NUM Failed to read the message queue.CNcomment:读取消息队列出错。CNend 201 * @retval value Number of used message queues.CNcomment:消息队列使用个数。CNend 202 * @par 依赖: 203 * @li hi_msg.h：Describes message queue APIs.CNcomment:文件用于描述消息队列相关接口。CNend 204 * @see None 205 */ 206 hi_u32 hi_msg_queue_get_msg_num(hi_u32 id); 207 208 /** 209 * @ingroup iot_msgqueue 210 * @brief Obtains the number of message queues.CNcomment:获取消息队列总个数。CNend 211 * 212 * @par 描述: 213 * Obtains the number of message queues.CNcomment:获取消息队列总个数。CNend 214 * 215 * @attention None 216 * @param id [IN] #hi_u32，Handle of the created message queue.CNcomment:消息队列句柄。CNend 217 * 218 * @retval #HI_ERR_MSG_INVALID_MSG_NUM An error occurs with the message queue. For example: An input argument is 219 * incorrect, or the message queue is not created. 220 CNcomment:读取消息队列出错、入参错误、消息队列未创建。CNend 221 * @retval value Number of message queues.CNcomment:消息队列总个数。CNend 222 * @par 依赖: 223 * @li hi_msg.h：Describes message queue APIs.CNcomment:文件用于描述消息队列相关接口。CNend 224 * @see None 225 */ 226 hi_u32 hi_msg_queue_get_msg_total(hi_u32 id); 227 228 229 /** 230 * @ingroup iot_msgqueue 231 * @brief Send a message to the head of the queue.发送消息到队列头。Nend 232 * 233 * @par 描述: 234 * Send a message to the head of the queue.发送消息到队列头。CNend 235 * 236 * @attention None 237 * @param id [IN] type #hi_u32，Message queue handle.CNcomment:消息队列句柄。CNend 238 * @param msg [IN] type #hi_pvoid，Message content pointer.CNcomment:消息内容指针。CNend 239 * @param timeout_ms [IN] type #hi_u32，Timeout period for sending a message. The value 0 indicates 240 * that the message is sent immediately.CNcomment:消息发送的最大超时时间(单位：ms)， 241 立即发送时写0。CNend 242 * @param msg_size [IN] type #hi_u32，Size of the sent message (unit: byte). 243 CNcomment:发送消息大小（单位：byte）。CNend 244 * 245 * @retval #HI_ERR_SUCCESS Success. 246 * @retval #HI_ERR_MSG_SEND_FAIL An error occurs with the message queue, for example, an input argument is 247 * incorrect, the message queue is not created, the size of the sent data is 248 * greater than the configured size when the queue is created, or the API is 249 * used in an interrupt but the timeout period is not 0. 250 CNcomment:发送消息队列错误，包括：入参错误、消息队列未创建、发送数据大于队列创建时设置大小、 251 中断中使用但超时时间不为0。CNend 252 * 253 * @retval #HI_ERR_MSG_INVALID_PARAM An input argument is incorrect or the message queue pointer is null. 254 CNcomment:入参错误、消息队列指针为空。CNend 255 * 256 * @par 依赖: 257 * @li hi_msg.h：Describes message queue APIs.CNcomment:文件用于描述消息队列相关接口。CNend 258 * @li hi_config.h：Describes the message queue configuration.CNcomment:文件用于消息队列配置。CNend 259 * @li hi_errno.h：Describes file configuration error codes.CNcomment:文件配置错误码。CNend 260 * @see hi_msg_queue_wait。 261 */ 262 hi_u32 hi_msg_queue_send_msg_to_front(hi_u32 id, hi_pvoid msg, hi_u32 msg_size, hi_u32 timeout_ms); 263 264 265 #endif 266 267