1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
|
/*
* @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef _cl_lock_h_ // NOLINT(build/header_guard)
#define _cl_lock_h_ // NOLINT(build/header_guard)
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @file cl_lock.h
* @brief \~english This file contains the base api of cl_clock.
*/
/** @addtogroup BaseSystem
* @{
*/
/** @addtogroup native_service
* @ingroup BaseSystem
* @{
*/
/** @addtogroup common_library
* @ingroup native_service
* @{
*/
////////////////////////////////////////////////////////////////////////////////////
/// \ingroup CL_LockSystemInit
/// \~english @par Brief
/// Initialize the system lock.
/// \~english @retval 0 Success
/// \~english @retval -1 Error
/// \~english @par Prerequisite
/// - Prerequisites are nothing.
/// \~english @par Change of internal state
/// - Change of internal state according to the API does not occur.
/// \~english @par Conditions of processing failure
/// - On system call shm_open error, -1 is returned.
/// - On system call ftrancate error, -1 is returned.
/// - On system call mmap error, -1 is returned.
/// - On system call pthread_mutexattr_setpshared error, -1 is returned.
/// \~english @par Detail
/// This function will generate the Lock file, and initialize all the pthread_mutex_t slots.\n
/// This function must to be called in the system once, which is recommended on the SystemManager start.\n
/// \~english @par
/// Lock file is formed with lots of slots. Every slot occupies 4KB.
/// The slot layout is:
/// 0 ~ 4Byte : field of PID
/// 4Byte ~ 28Byte : field of pthread_mutex_t
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Sync only
/// \~english @see
/// none
////////////////////////////////////////////////////////////////////////////////////
int32_t CL_LockSystemInit(void); // NOLINT(readability/nolint)
////////////////////////////////////////////////////////////////////////////////////
/// \ingroup CL_LockProcessInit
/// \~english @par Brief
/// Initialize the process Lock file.
/// \~english @retval 0 Success
/// \~english @retval -1 Error
/// \~english @par Prerequisite
/// Should call CL_LockSystemInit() to generate Lock file.
/// \~english @par Change of internal state
/// - Change of internal state according to the API does not occur.
/// \~english @par Conditions of processing failure
/// - On system call shm_open error, -1 is returned.
/// \~english @par Detail
/// Open the Lock file.\n
/// If process want to use the Lock, this function should be called.\n
/// It is recommended that this function should be called since start main function.
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Sync only
/// \~english @see
/// none
////////////////////////////////////////////////////////////////////////////////////
int32_t CL_LockProcessInit(void); // NOLINT(readability/nolint)
////////////////////////////////////////////////////////////////////////////////////
/// \ingroup CL_LockMap
/// \~english @par Brief
/// Mapping the Lock information address.
/// \~english @param [in] lid
/// int32_t - LockID of the Lock used.(0~LID_NUM) \n
/// \~english @retval addr Lock address
/// \~english @retval MAP_FAILED Error (errno)
/// \~english @par Prerequisite
/// Should call CL_LockSystemInit(), CL_LockProcessInit() to open the Lock file.
/// \~english @par Change of internal state
/// - Change of internal state according to the API does not occur.
/// \~english @par Conditions of processing failure
/// - If LockID(lid) < 0, errno is set as EINVAL, and MAP_FAILED is returned
/// - If LockID(lid) > LID_NUM, errno is set as EINVAL, and MAP_FAILED is returned
/// - If systemcall mmap is failure, errno is set euqal with the errno of mmap, and MAP_FAILED is returned
/// \~english @par Detail
/// Mapping the Lock information to the memory.\n
/// The related LockID should be assigned, when apply the share memory.\n
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Sync only
/// \~english @see
/// CL_LockUnmap
////////////////////////////////////////////////////////////////////////////////////
void *CL_LockMap(int32_t lid); // NOLINT(readability/nolint)
////////////////////////////////////////////////////////////////////////////////////
/// \ingroup CL_LockUnmap
/// \~english @par Brief
/// Unmapping the Lock information.
/// \~english @param [in] addr
/// void* - Lock information address.
/// \~english @retval 0 Success
/// \~english @retval -1 Error
/// \~english @par Prerequisite
/// Should call CL_LockSystemInit(), CL_LockProcessInit() before this function is called
/// \~english @par Change of internal state
/// - Change of internal state according to the API does not occur.
/// \~english @par Conditions of processing failure
/// - If systemcall munmap is failure, errno is set euqal with the errno of munmap, -1 is returned
/// \~english @par Detail
/// 0 would be returned, even if not get the Lock.
/// The addr is the Lock information address that acquired from CL_LockMap.
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Sync only
/// \~english @see
/// CL_LockMap
////////////////////////////////////////////////////////////////////////////////////
int32_t CL_LockUnmap(void *addr); // NOLINT(readability/nolint)
////////////////////////////////////////////////////////////////////////////////////
/// \ingroup CL_LockGet
/// \~english @par Brief
/// Get the Lock. Block until get the Lock.
/// \~english @param [in] addr
/// void* - Lock information address.
/// \~english @retval 0 Success
/// \~english @retval EINVAL Invalid parameter
/// \~english @retval EDEADLK Mutex already locked
/// \~english @par Prerequisite
/// Should call CL_LockMap to get the Lock information address.
/// \~english @par Change of internal state
/// - Change of internal state according to the API does not occur.
/// \~english @par Conditions of processing failure
/// - EINVAL as the parameter of Lock information address is NULL
/// - EINVAL as the parameter of Lock information address is MAP_FAILED
/// - EINVAL as the mutex does not be initialized in the systemcall pthread_mutex_lock failure.
/// - EDEADLK as the current thread already owns the mutex in the systemcall pthread_mutex_lock failure.
/// \~english @par Detail
/// Get the Lock until other threads release it.
/// It will be deadlock if the current thread already owns the mutex.
/// The addr is the Lock information address that should be acquired from CL_LockMap.
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Sync only
/// \~english @see
/// CL_LockRelease
////////////////////////////////////////////////////////////////////////////////////
int32_t CL_LockGet(void *addr); // NOLINT(readability/nolint)
////////////////////////////////////////////////////////////////////////////////////
/// \ingroup CL_LockNowait
/// \~english @par Brief
/// Try to get Lock, shall immediately return.
/// \~english @param [in] addr
/// void* - Lock information address.
/// \~english @retval 0 Success
/// \~english @retval EINVAL Invalid parameter
/// \~english @retval EBUSY Busy
/// \~english @par Prerequisite
/// Should call CL_LockMap to get the Lock information address.
/// \~english @par Change of internal state
/// - Change of internal state according to the API does not occur.
/// \~english @par Conditions of processing failure
/// - EINVAL as input parameter addr, the Lock information address is NULL
/// - EINVAL as input parameter addr, the Lock information address if MAP_FAILED
/// - EINVAL as the mutex does not be initialized in the systemcall pthread_mutex_trylock failure.
/// - EBUSY as the mutex could not be acquired as it was already locked in the
/// systemcall pthread_mutex_trylock failure.
/// \~english @par Detail
/// The addr is the Lock information address that should be acquired from CL_LockMap.
/// Get the Lock information from the pointed share memory.
/// Shall immediately return while not acquire the Lock.
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Sync only
/// \~english @see
/// CL_LockRelease
////////////////////////////////////////////////////////////////////////////////////
int32_t CL_LockNowait(void *addr); // NOLINT(readability/nolint)
////////////////////////////////////////////////////////////////////////////////////
/// \ingroup CL_LockRelease
/// \~english @par Brief
/// Release the Lock.
/// \~english @param [in] addr
/// addr - Lock information address.
/// \~english @retval 0 Success
/// \~english @retval EINVAL Invalid parameter
/// \~english @retval EPERM The current thread does not own the mutex
/// \~english @par Prerequisite
/// - Should call CL_LockMap to get the Lock information address.
/// \~english @par Change of internal state
/// - Change of internal state according to the API does not occur.
/// \~english @par Conditions of processing failure
/// - EINVAL as input parameter addr, the Lock information address is NULL
/// - EINVAL as input parameter addr, the Lock information address if MAP_FAILED
/// - EINVAL as the mutex does not be initialized in the systemcall pthread_mutex_unlock failure.
/// - EPERM as the current thread does not own the mutex in the systemcall pthread_mutex_unlock failure.
/// \~english @par Detail
/// 0 would be returned, even if not get the Lock.
/// The addr is the Lock information address that should be acquired from CL_LockMap.
/// Release the Lock related with the share memory.
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Sync only
/// \~english @see
/// CL_LockGet, CL_LockNowait
////////////////////////////////////////////////////////////////////////////////////
int CL_LockRelease(void *addr); // NOLINT(readability/nolint)
#ifdef __cplusplus
}
#endif
/** @}*/ // end of common_library
/** @}*/ // end of NativeService
/** @}*/ // end of BaseSystem
#define LOCK_POS_MTX_RSV 40
#define LOCK_HRDS_RSV 15
#define LOCK_NSLOG_ACCES_IF_RSV 50
#define LID_NUM 140
#endif // #ifndef _cl_lock_h_ // NOLINT(build/header_guard)
|
