diff options
Diffstat (limited to 'nsframework/common_library/client/include/native_service/cl_lock.h')
| -rw-r--r-- | nsframework/common_library/client/include/native_service/cl_lock.h | 259 |
1 files changed, 259 insertions, 0 deletions
diff --git a/nsframework/common_library/client/include/native_service/cl_lock.h b/nsframework/common_library/client/include/native_service/cl_lock.h new file mode 100644 index 00000000..d9745405 --- /dev/null +++ b/nsframework/common_library/client/include/native_service/cl_lock.h @@ -0,0 +1,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) |