1/**
2* @file hi_sem.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.
16*
17* Description: Semaphore APIs.CNcomment:接口。CNend
18*
19* @li Wait semaphore. In the interrupt function, disable interrupt context, and lock task context, this API must not be
20*     called. Otherwise, uncontrollable exception scheduling may result.CNcomment:等待信号量:在中断、关中断、
21锁任务上下文禁止调用等待信号量接口，进而产生不可控的异常调度。CNend
22* @li Release semaphore.In the disable interrupt context, this API must not be called. Otherwise, uncontrollable
23*     exception scheduling may result.CNcomment:释放信号量:在关中断上下文禁止调用释放信号量接口，
24进而产生不可控的异常调度。CNend   \n
25* Create: 2019-05-29
26*/
27
28/**
29 * @defgroup iot_sem Semaphore
30 * @ingroup osa
31 */
32#ifndef __HI_SEM_H__
33#define __HI_SEM_H__
34#include <hi_types_base.h>
35
36#define HI_SEM_ONE  ((hi_u8)1) /**< ucInit Obtained value of the input: Critical resource protection.
37                                 CNcomment:输入的取值: 临界资源保护 CNend */
38#define HI_SEM_ZERO ((hi_u8)0) /**< ucInit Obtained value of the input: Synchronization
39                                 CNcomment:输入的取值: 同步 CNend */
40
41/**
42* @ingroup  iot_sem
43* @brief  Creates a semaphore.CNcomment:创建信号量。CNend
44*
45* @par 描述:
46*           Creates a semaphore.CNcomment:创建信号量。CNend
47*
48* @attention The blocking mode (permanent blocking or timing blocking) of the semaphore application operation cannot
49*            be used in the interrupt, and the interrupt cannot be blocked.CNcomment:信号量申请操作的阻塞模式
50（永久阻塞和定时阻塞）不能在中断中使用，中断不能被阻塞。CNend
51*
52* @param  sem_id          [OUT] type #hi_u32*，semaphore ID.CNcomment:信号量ID号。CNend
53* @param  init_value      [IN]  type #hi_u16，Number of initialized valid signals. The value range is [0, 0xFFFF].
54CNcomment:有效信号的初始化个数，范围为:[0, 0xFFFF]CNend
55*
56* @retval #0      Success.
57* @retval #Other  Failure, for details, see hi_errno.h
58* @par 依赖:
59*            @li hi_sem.h：Describes the semaphore APIs.CNcomment:文件用于描述信号量相关接口。CNend
60* @see  hi_sem_delete。
61*/
62hi_u32 hi_sem_create(hi_u32 *sem_id, hi_u16 init_value);
63
64
65/**
66* @ingroup  iot_sem
67* @brief  Creates a two-value semaphore(0/1).CNcomment:创建二值信号量（0/1）。CNend
68*
69* @par 描述:
70*           Creates a two-value semaphore(0/1).CNcomment:创建二值信号量（0/1）。CNend
71*
72* @attention The blocking mode (permanent blocking or timing blocking) of the semaphore application operation cannot
73*            be used in the interrupt, and the interrupt cannot be blocked.CNcomment:信号量申请操作的阻塞模式
74（永久阻塞和定时阻塞）不能在中断中使用，中断不能被阻塞。CNend
75*
76* @param  sem_id      [OUT] type #hi_u32*，semaphore ID.CNcomment:信号量ID号。CNend
77* @param  init_value  [IN]  type #hi_u8，initial value. Generally, when the value is HI_SEM_ONE, the API is used for
78*                     critical resource protection. When the value is HI_SEM_ZERO, the API is used for synchronization.
79CNcomment:初始值。一般情况下，当值为HI_SEM_ONE时，用作临界资源保护；当值为HI_SEM_ZERO时，用作同步。CNend
80*
81* @retval #0      Success.
82* @retval #Other  Failure, for details, see hi_errno.h
83* @par 依赖:
84*            @li hi_sem.h：Describes the semaphore APIs.CNcomment:文件用于描述信号量相关接口。CNend
85* @see  hi_sem_delete。
86*/
87hi_u32 hi_sem_bcreate(hi_u32 *sem_id, hi_u8 init_value);
88
89/**
90* @ingroup  iot_sem
91* @brief  Deletes the semaphore.CNcomment:删除信号量。CNend
92*
93* @par 描述:
94*           Deletes the semaphore.CNcomment:删除信号量。CNend
95*
96* @attention The blocking mode (permanent blocking or timing blocking) of the semaphore application operation cannot
97*            be used in the interrupt, and the interrupt cannot be blocked.CNcomment:信号量申请操作的阻塞模式
98（永久阻塞和定时阻塞）不能在中断中使用，中断不能被阻塞。CNend
99*
100* @param  sem_id    [IN] type #hi_u32，semaphore ID.CNcomment:信号量ID号。CNend
101*
102* @retval #0      Success.
103* @retval #Other  Failure, for details, see hi_errno.h
104* @par 依赖:
105*            @li hi_sem.h：Describes the semaphore APIs.CNcomment:文件用于描述信号量相关接口。CNend
106* @see  hi_sem_bcreate。
107*/
108hi_u32 hi_sem_delete(hi_u32 sem_id);
109
110/**
111* @ingroup  iot_sem
112* @brief  Obtains the semaphore.CNcomment:获取信号量。CNend
113*
114* @par 描述:
115*           Obtains the semaphore.CNcomment:获取信号量。CNend
116*
117*
118* @attention The blocking mode (permanent blocking or timing blocking) of the semaphore application operation cannot
119*            be used in the interrupt, and the interrupt cannot be blocked.CNcomment:信号量申请操作的阻塞模式
120（永久阻塞和定时阻塞）不能在中断中使用，中断不能被阻塞。CNend
121*
122* @param  sem_id     [IN] type #hi_u32，semaphore ID.CNcomment:信号量ID号。CNend
123* @param  timeout_ms [IN] type #hi_u32，timeout period (unit: ms). HI_SYS_WAIT_FOREVER indicates permanent wait.
124CNcomment:超时时间（单位：ms），HI_SYS_WAIT_FOREVER为永久等待。CNend
125*
126* @retval #0      Success.
127* @retval #Other  Failure, for details, see hi_errno.h
128* @par 依赖:
129*            @li hi_sem.h：Describes the semaphore APIs.CNcomment:文件用于描述信号量相关接口。CNend
130* @see  hi_sem_signal。
131*/
132hi_u32 hi_sem_wait(hi_u32 sem_id, hi_u32 timeout_ms);
133
134/**
135* @ingroup  iot_sem
136* @brief  Releases the semaphore.CNcomment:释放信号量。CNend
137*
138* @par 描述:
139*           Releases the semaphore.CNcomment:释放信号量。CNend
140*
141* @attention The blocking mode (permanent blocking or timing blocking) of the semaphore application operation cannot
142*            be used in the interrupt, and the interrupt cannot be blocked.CNcomment:信号量申请操作的阻塞模式
143（永久阻塞和定时阻塞）不能在中断中使用，中断不能被阻塞。CNend
144*
145* @param  sem_id    [IN] type #hi_u32，semaphore ID.CNcomment:信号量ID号。CNend
146*
147* @retval #0      Success.
148* @retval #Other  Failure, for details, see hi_errno.h
149* @par 依赖:
150*            @li hi_sem.h：Describes the semaphore APIs.CNcomment:文件用于描述信号量相关接口。CNend
151* @see  hi_sem_wait。
152*/
153hi_u32 hi_sem_signal(hi_u32 sem_id);
154
155#endif
156
157