1 /*
2  * Copyright (c) 2020-2021 Huawei Device Co., Ltd.
3  *
4  * HDF is dual licensed: you can use it either under the terms of
5  * the GPL, or the BSD license, at your option.
6  * See the LICENSE file in the root of this repository for complete details.
7  */
8 
9 /**
10  * @addtogroup OSAL
11  * @{
12  *
13  * @brief Defines the structures and interfaces for the Operating System Abstraction Layer (OSAL) module.
14  *
15  * The OSAL module OpenHarmony OS interface differences and provides unified OS interfaces externally,
16  * including the memory management, thread, mutex, spinlock, semaphore, timer, file, interrupt, time,
17  * atomic, firmware, and I/O operation modules.
18  *
19  * @since 1.0
20  * @version 1.0
21  */
22 
23 /**
24  * @file osal_sem.h
25  *
26  * @brief Declares semaphore structures and interfaces.
27  *
28  * @since 1.0
29  * @version 1.0
30  */
31 #ifndef OSAL_SEM_H
32 #define OSAL_SEM_H
33 
34 #include "hdf_base.h"
35 
36 #ifdef __cplusplus
37 extern "C" {
38 #endif /* __cplusplus */
39 
40 #define OSAL_WAIT_FOREVER 0xFFFFFFFF
41 
42 /**
43  * @brief Describes a semaphore.
44  */
45 struct OsalSem {
46     void *realSemaphore; /**< Pointer to a semaphore to operate */
47 };
48 
49 /**
50  * @brief Defines a semaphore.
51  */
52 #define OSAL_DECLARE_SEMAPHORE(sem) struct OsalSem sem
53 
54 /**
55  * @brief Initializes a semaphore.
56  *
57  * @param sem Indicates the pointer to the semaphore {@link OsalSem}.
58  * @param value Indicates the initial value of the semaphore.
59  *
60  * @return Returns a value listed below: \n
61  * HDF_STATUS | Description
62  * ----------------------| -----------------------
63  * HDF_SUCCESS | The operation is successful.
64  * HDF_FAILURE | Failed to invoke the system function to initialize the semaphore.
65  * HDF_ERR_INVALID_PARAM | Invalid parameter.
66  *
67  * @since 1.0
68  * @version 1.0
69  */
70 int32_t OsalSemInit(struct OsalSem *sem, uint32_t value);
71 
72 /**
73  * @brief Waits for a semaphore.
74  *
75  * @param sem Indicates the pointer to the semaphore {@link OsalSem}.
76  * @param ms Indicates the timeout interval.
77  *
78  * @return Returns a value listed below: \n
79  * HDF_STATUS | Description
80  * ----------------------| -----------------------
81  * HDF_SUCCESS | The operation is successful.
82  * HDF_FAILURE | Failed to invoke the system function to wait for the semaphore.
83  * HDF_ERR_INVALID_PARAM | Invalid parameter.
84  * HDF_ERR_TIMEOUT | Timeout occurs.
85  *
86  * @since 1.0
87  * @version 1.0
88  */
89 int32_t OsalSemWait(struct OsalSem *sem, uint32_t ms);
90 
91 /**
92  * @brief Releases a semaphore.
93  *
94  * @param sem Indicates the pointer to the semaphore {@link OsalSem}.
95  *
96  * @return Returns a value listed below: \n
97  * HDF_STATUS | Description
98  * ----------------------| -----------------------
99  * HDF_SUCCESS | The operation is successful.
100  * HDF_FAILURE | Failed to invoke the system function to release the semaphore.
101  * HDF_ERR_INVALID_PARAM | Invalid parameter.
102  *
103  * @since 1.0
104  * @version 1.0
105  */
106 int32_t OsalSemPost(struct OsalSem *sem);
107 
108 /**
109  * @brief Destroys a semaphore.
110  *
111  * @param sem Indicates the pointer to the semaphore {@link OsalSem}.
112  *
113  * @return Returns a value listed below: \n
114  * HDF_STATUS | Description
115  * ----------------------| -----------------------
116  * HDF_SUCCESS | The operation is successful.
117  * HDF_FAILURE | Failed to invoke the system function to destroy the semaphore.
118  * HDF_ERR_INVALID_PARAM | Invalid parameter.
119  *
120  * @since 1.0
121  * @version 1.0
122  */
123 int32_t OsalSemDestroy(struct OsalSem *sem);
124 
125 #ifdef __cplusplus
126 }
127 #endif /* __cplusplus */
128 
129 #endif /* OSAL_SEM_H */
130 /** @} */
131