diff options
Diffstat (limited to 'nsframework/framework_unified/client/include/native_service/ns_ringbuffer.h')
| -rw-r--r-- | nsframework/framework_unified/client/include/native_service/ns_ringbuffer.h | 523 |
1 files changed, 523 insertions, 0 deletions
diff --git a/nsframework/framework_unified/client/include/native_service/ns_ringbuffer.h b/nsframework/framework_unified/client/include/native_service/ns_ringbuffer.h new file mode 100644 index 00000000..b67cd17e --- /dev/null +++ b/nsframework/framework_unified/client/include/native_service/ns_ringbuffer.h @@ -0,0 +1,523 @@ +/* + * @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. + */ + +//////////////////////////////////////////////////////////////////////////////////////////////////// +/// \ingroup tag_NSRingBuffer +/// \brief This file contains implementation of class CNSRingBuffer. +/// This class provides API to open, read, write and close ring buffer +/// +//////////////////////////////////////////////////////////////////////////////////////////////////// +//@{ +/** + * @file ns_ringbuffer.h + * @brief \~english This file contains implementation of class CNSRingBuffer. + * This class provides API to open, read, write and close ring buffer + */ +/** @addtogroup BaseSystem + * @{ + */ +/** @addtogroup native_service + * @ingroup BaseSystem + * @{ + */ +/** @addtogroup framework_unified + * @ingroup native_service + * @{ + */ +/** @addtogroup native + * @ingroup framework_unified + * @{ + */ +#ifndef __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_RINGBUFFER_H__ // NOLINT (build/header_guard) +#define __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_RINGBUFFER_H__ + +//////////////////////////////////////////////////////////////////////////////////////////////////// +// Include Files +//////////////////////////////////////////////////////////////////////////////////////////////////// +#include <pthread.h> + +#include <native_service/frameworkunified_types.h> + +#include <string> + +// Structure of the header of the ring buffer +typedef struct _NSRingBufferHdr { + UI_32 m_uiReadPtr; // Read pointer + UI_32 m_uiWritePtr; // Write pointer + UI_32 m_uiUnReadSize; // Data size not read yet + BOOL m_bIsFull; // Flag indicating if the buffer has full of data + UI_32 m_uiRingBufferSize; // Size of the ring buffer +} NSRingBufferHdr; + +// Structure of the mutex of the ring buffer +typedef struct _NSRingBufferMtx { + pthread_mutex_t m_tBufMutex; // Mutex object to mutual exclusion + int m_lid; +} NSRingBufferMtx; + + +/** + * @class CNSRingBuffer + * \~english @brief CNSRingBuffer + * \~english @par Brief Introduction + * Class to provide class of ring buffer. + */ +class CNSRingBuffer { + public: + //////////////////////////////////////////////////////////////////////////////////////////////// + /// \ingroup CNSRingBuffer + /// \~english @par Brief + /// Constructor for CNSRingBuffer + /// \~english @param[in] f_cMappedFilePath + /// const std::string& - path of the ring buffer mapped file + /// \~english @param[in] f_uiSize + /// const UI_32 - size of ring buffer + /// \~english @param[in] f_lid + /// int - Lock ID + /// \~english @retval none + /// \~english @par Preconditons + /// none + /// \~english @par Change of internal status + /// - The internal state is not changed. + /// \~english @par Conditions of processing failure + /// none + /// \~english @par Detail + /// Create an instance of CNSRingBuffer class.\n + /// Initializes cass member (m_cMappedFilePath, m_uiRingBuffSize, m_pRbufMtx, m_pRbufHdr, + /// m_pRbuf, m_lid, m_pLockAddr, m_siProcessLastWrtPage, m_cRbufMtxName).\n + /// \~english @par Classification + /// Public + /// \~english @par Type + /// sync only + /// \~english @par Detail + /// Constructor of CNSRingBuffer class. + /// variables (m_cMappedFilePath, m_uiRingBuffSize, m_pRbufMtx, m_pRbufHdr, + /// m_pRbuf, m_lid, m_pLockAddr, m_siProcessLastWrtPage, m_cRbufMtxName) to be initialization. + /// \~english @see ~CNSRingBuffer + //////////////////////////////////////////////////////////////////////////////////////////////// + CNSRingBuffer(const std::string &f_cMappedFilePath, const UI_32 f_uiSize, int f_lid = -1); + + //////////////////////////////////////////////////////////////////////////////////////////////// + /// \ingroup CNSRingBuffer + /// \~english @par Brief + /// Destructor for CNSRingBuffer. + /// \~english @param none + /// \~english @retval none + /// \~english @par Preconditons + /// - The constructor creates an instance of the CNSRingBuffer class. + /// \~english @par Change of internal status + /// - The internal state is not changed. + /// \~english @par Conditions of processing failure + /// none + /// \~english @par Detail + /// Closes the ring buffer, if it is open. + /// \~english @par + /// Closes the ring buffer if it is open. + /// \~english @par Classification + /// Public + /// \~english @par Type + /// sync only + /// \~english @see CNSRingBuffer + //////////////////////////////////////////////////////////////////////////////////////////////// + ~CNSRingBuffer(); + + //////////////////////////////////////////////////////////////////////////////////////////////// + /// \ingroup CNSRingBuffer + /// \~english @par Brief + /// This function opens and maps the ring buffer object. + /// \~english @param none + /// \~english @retval eFrameworkunifiedStatusOK + /// \~english @retval eFrameworkunifiedStatusInvldParam + /// \~english @retval eFrameworkunifiedStatusFail + /// \~english @retval eFrameworkunifiedStatusErrOther + /// \~english @par Preconditons + /// none + /// \~english @par Change of internal status + /// - The internal state is not changed. + /// \~english @par Conditions of processing failure + /// - Different Lock ID in constructor parameter and mutex object [eFrameworkunifiedStatusInvldParam] + /// - If the path at the time of CNSRingBuffer class instantiation is empty [eFrameworkunifiedStatusFail] + /// - When the CNSRingBuffer class is instantiated with a path longer than 255 characters... [eFrameworkunifiedStatusFail] + /// - If accessing the information header file (shm_open/ mmap) fails [eFrameworkunifiedStatusFail] + /// - When accessing the ring buffer file (shm_open/ mmap) fails [eFrameworkunifiedStatusFail] + /// - Accessing a mutex file (shm_open/ mmap) fails [eFrameworkunifiedStatusFail] + /// - Alreadey opened [eFrameworkunifiedStatusErrOther] + /// \~english @par Detail + /// It creates the ring buffer if it does not exists. + /// Opens the path information header, ring buffer, and mutex set at instance creation. + /// \~english @par + /// Update ring buffer size for instances created with different sizes on the same path. + /// \~english @par + /// Execute close() to close. + /// \~english @par Classification + /// Public + /// \~english @par Type + /// sync only + /// \~english @see CNSRingBuffer, Close + //////////////////////////////////////////////////////////////////////////////////////////////// + EFrameworkunifiedStatus Open(); + + //////////////////////////////////////////////////////////////////////////////////////////////// + /// \ingroup CNSRingBuffer + /// \~english @par Brief + /// This function is used to check whether the ring buffer is opened or not.. + /// \~english @param none + /// \~english @retval TRUE - Open + /// \~english @retval FALSE - Not open + /// \~english @par Preconditions + /// - None. + /// \~english @par Change of the internal state + /// - Change of internal state according to the API does not occur. + /// \~english @par Conditions of processing failure + /// none + /// \~english @par Detail + /// This function is used to check whether the ring buffer is opened or not. + /// \~english @par Classification + /// Public + /// \~english @par Type + /// sync only + /// \~english @see CNSRingBuffer, Close + //////////////////////////////////////////////////////////////////////////////////////////////// + BOOL IsOpen(); + + //////////////////////////////////////////////////////////////////////////////////////////////// + /// \ingroup CNSRingBuffer + /// \~english @par Brief + /// This function unmaps the ring buffer object. + /// \~english @param none + /// \~english @retval eFrameworkunifiedStatusOK + /// \~english @retval eFrameworkunifiedStatusFail + /// \~english @par Preconditons + /// - Open has been performed. + /// \~english @par Change of internal status + /// - The internal state is not changed. + /// \~english @par Conditions of processing failure + /// - not open [eFrameworkunifiedStatusFail] + /// - information header file munmap fail [eFrameworkunifiedStatusFail] + /// - ring buffer file munmap fail [eFrameworkunifiedStatusFail] + /// - minidesk file munmap fail [eFrameworkunifiedStatusFail] + /// \~english @par Detail + /// - This function unmaps the ring buffer object. + /// \~english @par + /// Close processing is also performed when an instance is destructed to prevent leakage. + /// \~english @par Classification + /// Public + /// \~english @par Type + /// sync only + /// \~english @see Open + //////////////////////////////////////////////////////////////////////////////////////////////// + EFrameworkunifiedStatus Close(); + + //////////////////////////////////////////////////////////////////////////////////////////////// + /// \ingroup CNSRingBuffer + /// \~english @par Brief + /// This function reads data from the ring buffer. + /// \~english @param [OUT] buffer + /// PSTR - pointer to the buffer in which the read data is stored + /// \~english @param [IN] f_uilength + /// UI_32 - length of the data buffer provided + /// \~english @retval SI_32 Returns The number of bytes actually read + /// \~english @retval -1 error occurred + /// \~english @par Preconditions + /// - Open(). + /// \~english @par Change of the internal state + /// - Change of internal state according to the API does not occur. + /// \~english @par Conditions of processing failure + /// - not open [-1] + /// \~english @par Detail + /// - This function reads data from the ring buffer. + /// \~english @par Classification + /// Public + /// \~english @par Type + /// sync only + /// \~english @see Open + //////////////////////////////////////////////////////////////////////////////////////////////// + SI_32 Read(PSTR buffer, const UI_32 f_uilength); + + //////////////////////////////////////////////////////////////////////////////////////////////// + /// \ingroup CNSRingBuffer + /// \~english @par Brief + /// This function writes the data into the ring buffer. + /// \~english @param [OUT] buffer + /// PSTR - pointer to the buffer containing the data to be written + /// \~english @param [IN] f_uilength + /// UI_32 - length of the data buffer to be written + /// \~english @retval SI_32 Returns The number of bytes written + /// \~english @retval -1 error occurred + /// \~english @par Preconditions + /// - Open(). + /// \~english @par Change of the internal state + /// - Change of internal state according to the API does not occur. + /// \~english @par Conditions of processing failure + /// - not open [-1] + /// \~english @par Detail + /// - This function writes the data into the ring buffer. + /// \~english @par Classification + /// Public + /// \~english @par Type + /// sync only + /// \~english @see Open + //////////////////////////////////////////////////////////////////////////////////////////////// + SI_32 Write(PCSTR buffer, const UI_32 f_uilength); + + //////////////////////////////////////////////////////////////////////////////////////////////// + /// \ingroup CNSRingBuffer + /// \~english @par Brief + /// This function writes all the data in the buffer into provided file f_pPath. + /// \~english @param[in] f_pPath + /// PCSTR - file path. + /// \~english @param[in] f_uiDumpSize + /// PUI_32 - Returns The number of bytes written into file + /// \~english @retval eFrameworkunifiedStatusOK + /// \~english @retval eFrameworkunifiedStatusNullPointer + /// \~english @retval eFrameworkunifiedStatusInvldParam + /// \~english @retval eFrameworkunifiedStatusFail + /// \~english @retval eFrameworkunifiedStatusFileLoadError + /// \~english @retval eFrameworkunifiedStatusErrOther + /// \~english @par Preconditions + /// - Open(). + /// \~english @par Change of the internal state + /// - Change of internal state according to the API does not occur. + /// \~english @par Conditions of processing failure + /// - f_uiDumpSize is NULL [eFrameworkunifiedStatusNullPointer] + /// - dump file path is NULL [eFrameworkunifiedStatusInvldParam] + /// - not open [eFrameworkunifiedStatusFail] + /// - dump file open fail [eFrameworkunifiedStatusFileLoadError] + /// - ring buffer access fail [eFrameworkunifiedStatusFail] + /// - dump file write fail [eFrameworkunifiedStatusErrOther] + /// \~english @par Detail + /// This function does not changes the unread buffer. + /// \~english @par + /// Please note the following points when using this API for application. + /// - Writing to a dump file is overwritten. + /// \~english @par + /// This function overwrites the file if it exists. + /// \~english @par Classification + /// Public + /// \~english @par Type + /// sync only + /// \~english @see Open + //////////////////////////////////////////////////////////////////////////////////////////////// + EFrameworkunifiedStatus DumpToFile(PCSTR f_pPath, PUI_32 f_uiDumpSize); + + //////////////////////////////////////////////////////////////////////////////////////////////// + /// \ingroup CNSRingBuffer + /// \~english @par Brief + /// This function returns the number of unread bytes which can be read by Read(). + /// \~english @retval SI_32 Returns The number of bytes which can be read by Read() + /// \~english @retval -1 error occurred + /// \~english @par Preconditions + /// - Open(). + /// \~english @par Change of the internal state + /// - Change of internal state according to the API does not occur. + /// \~english @par Conditions of processing failure + /// - not open [-1] + /// \~english @par Detail + /// - This function returns the number of unread bytes which can be read by Read(). + /// \~english @par Classification + /// Public + /// \~english @par Type + /// sync only + /// \~english @see Open + //////////////////////////////////////////////////////////////////////////////////////////////// + SI_32 GetSize(); + + //////////////////////////////////////////////////////////////////////////////////////////////// + /// \ingroup CNSRingBuffer + /// \~english @par Brief + /// This function clears the ring buffer. + /// \~english @param none + /// \~english @retval eFrameworkunifiedStatusOK + /// \~english @retval eFrameworkunifiedStatusFail + /// \~english @par Preconditions + /// - Open(). + /// \~english @par Change of the internal state + /// - Change of internal state according to the API does not occur. + /// \~english @par Conditions of processing failure + /// - not open [eFrameworkunifiedStatusFail] + /// \~english @par Detail + /// This function clears the ring buffer. + /// \~english @par + /// Please note the following points when using this API for application. + /// - Only read/write information cleared, and the size of the ring buffer itself is not changed. + /// \~english @par Classification + /// Public + /// \~english @par Type + /// sync only + /// \~english @see Open + //////////////////////////////////////////////////////////////////////////////////////////////// + EFrameworkunifiedStatus ClearBuf(); + + //////////////////////////////////////////////////////////////////////////////////////////////// + /// \ingroup CNSRingBuffer + /// \~english @par Brief + /// This function sets the position of read ptr to write ptr in buffer. + /// \~english @param none + /// \~english @retval eFrameworkunifiedStatusOK success + /// \~english @retval eFrameworkunifiedStatusFail ring buffer is not open + /// \~english @par Preconditions + /// - Open(). + /// \~english @par Change of the internal state + /// - Change of internal state according to the API does not occur. + /// \~english @par Conditions of processing failure + /// - not open [eFrameworkunifiedStatusFail] + /// \~english @par Detail + /// This function sets the position of read ptr to write ptr in buffer. + /// \~english @par Classification + /// Public + /// \~english @par Type + /// sync only + /// \~english @see Open + //////////////////////////////////////////////////////////////////////////////////////////////// + EFrameworkunifiedStatus SetReadPtrToWritePtr(); + + private: + //////////////////////////////////////////////////////////////////////////////////////////////// + /// CNSRingBuffer + /// Constructor of CNSRingBuffer class + /// + /// \return None + /// + //////////////////////////////////////////////////////////////////////////////////////////////// + CNSRingBuffer(); + + //////////////////////////////////////////////////////////////////////////////////////////////// + /// CreateRBMutex + /// This function creates the ring buffer mutex object. + /// + /// \return EFrameworkunifiedStatus + /// eFrameworkunifiedStatusOK ring buffer created successfully + /// eFrameworkunifiedStatusDuplicate ring buffer already exists + /// eFrameworkunifiedStatusInvldParam invalid ring buffer name + /// eFrameworkunifiedStatusFail on error + /// + //////////////////////////////////////////////////////////////////////////////////////////////// + EFrameworkunifiedStatus CreateRBMutex(); + + //////////////////////////////////////////////////////////////////////////////////////////////// + /// CreateRBHeader + /// This function creates the ring buffer object for header. + /// + /// \return EFrameworkunifiedStatus + /// eFrameworkunifiedStatusOK ring buffer created successfully + /// eFrameworkunifiedStatusDuplicate ring buffer already exists + /// eFrameworkunifiedStatusInvldParam invalid ring buffer name + /// eFrameworkunifiedStatusFail on error + /// + //////////////////////////////////////////////////////////////////////////////////////////////// + EFrameworkunifiedStatus CreateRBHeader(); + + //////////////////////////////////////////////////////////////////////////////////////////////// + /// CreateRBDataBuffer + /// This function creates the ring buffer object for data buffer. + /// + /// \return EFrameworkunifiedStatus + /// eFrameworkunifiedStatusOK ring buffer created successfully + /// eFrameworkunifiedStatusDuplicate ring buffer already exists + /// eFrameworkunifiedStatusInvldParam invalid ring buffer name + /// eFrameworkunifiedStatusFail on error + /// + //////////////////////////////////////////////////////////////////////////////////////////////// + EFrameworkunifiedStatus CreateRBDataBuffer(); + + //////////////////////////////////////////////////////////////////////////////////////////////// + /// MapRBHeader + /// This function open and maps the file in process space. + /// + /// \param [out] f_pRbuf + /// PVOID* - address of the mapped memory + /// \param [in] f_cMappedFile + /// std::string - Path of the ring buffer mapped file + /// \param [in] f_uiRbufSize + /// UI_32 - Size of the ring buffer + /// + /// \return EFrameworkunifiedStatus + /// eFrameworkunifiedStatusOK if ring buffer opened successfully + /// eFrameworkunifiedStatusFail unable to open ring buffer + /// + //////////////////////////////////////////////////////////////////////////////////////////////// + EFrameworkunifiedStatus Map(PVOID *f_pRbuf, const std::string &f_cMappedFile, const UI_32 f_uiRbufSize); + + //////////////////////////////////////////////////////////////////////////////////////////////// + /// MapRBHeader + /// This function open and maps the shared memory in process space. + /// + /// \param [out] f_pShMem + /// PVOID* - address of the mapped memory + /// \param [in] f_cShmName + /// std::string - Name of the shared memory + /// \param [in] f_uiShmSize + /// UI_32 - Size of the shared memory + /// + /// \return EFrameworkunifiedStatus + /// eFrameworkunifiedStatusOK if shared memory opened successfully + /// eFrameworkunifiedStatusFail unable to open shared memory + /// + //////////////////////////////////////////////////////////////////////////////////////////////// + EFrameworkunifiedStatus MapSM(PVOID *f_pShMem, const std::string &f_cShmName, const UI_32 f_uiShmSize); + + //////////////////////////////////////////////////////////////////////////////////////////////// + /// UnMapRB + /// This function unmaps the object. + /// + /// \param [in] f_pRbuf + /// PCSTR - address of the memory to unmap + /// \param [in] f_uiRbufSize + /// UI_32 - Size of the memory to be unmapped + /// + /// \return EFrameworkunifiedStatus + /// eFrameworkunifiedStatusOK if ring buffer closed successfully + /// eFrameworkunifiedStatusFail if ring buffer is not open + /// + //////////////////////////////////////////////////////////////////////////////////////////////// + EFrameworkunifiedStatus UnMap(PVOID f_pRbuf, const UI_32 f_uiRbufSize); + + EFrameworkunifiedStatus CheckSize(int fd, off_t size); + + +// void LockMtx(); + int LockMtx(); + + void UnlockMtx(); + + std::string m_cRbufMtxName; // name of the ring buffer mutex name + + std::string m_cMappedFileHdrPath; // path of the ring buffer mapped file header + + std::string m_cMappedFilePath; // path of the ring buffer mapped file + + UI_32 m_uiRingBuffSize; // ring buffer size + + NSRingBufferMtx *m_pRbufMtx; // The pointer to the ring buffer mutex + + NSRingBufferHdr *m_pRbufHdr; // The pointer to the ring buffer header + + PCHAR m_pRbuf; // The pointer to the ring buffer data buffer + + pthread_mutex_t m_tOpenMutex; // for multithread process + + int m_lid; // Lock ID + void *m_pLockAddr; // Lock Address + + SI_32 m_siProcessLastWrtPage; // to hold page that each process wrote in last +}; + +#endif /* __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_RINGBUFFER_H__ */ // NOLINT (build/header_guard) +/** @}*/ +/** @}*/ +/** @}*/ +/** @}*/ +//@} |