path: root/nsframework/framework_unified/client/include/native_service/ns_sharedmem.h

/*
 * @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_NSSharedMemory
/// \brief    This file contains implementation of class CNSSharedMem.
///           This class provides API to open, read, write and close shared memory
///
////////////////////////////////////////////////////////////////////////////////////////////////////
//@{
/**
 * @file ns_sharedmem.h
 * @brief \~english This file contains implementation of class CNSSharedMem.
 *         This class provides API to open, read, write and close shared memory
 *
 */
/** @addtogroup BaseSystem
 *  @{
 */
/** @addtogroup native_service
 *  @ingroup BaseSystem
 *  @{
 */
/** @addtogroup framework_unified
 *  @ingroup native_service
 *  @{
 */
/** @addtogroup native
 *  @ingroup framework_unified
 *  @{
 */
#ifndef __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_H__  // NOLINT  (build/header_guard)
#define __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_H__

// Used only in nstest_sharedmem.
// set environment, CNSSharedMem::Open() always fail. ===> eFrameworkunifiedStatusErrOther
#define NSTEST_FAIL_SHAREDMEM_OPEN  "NSTEST_FAIL_SHAREDMEM_OPEN"


////////////////////////////////////////////////////////////////////////////////////////////////////
// Include Files
////////////////////////////////////////////////////////////////////////////////////////////////////
#include <pthread.h>
#include <native_service/frameworkunified_types.h>
#include <string>

// Structure of the header of the shared memory buffer
typedef struct _NSSharedBuffer {
  pthread_mutex_t m_tBufMutex;    // Mutex object to mutual exclusion
  pthread_cond_t  m_tCondVar;     // Condition Variable
  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_uiShMemSize;  // Size of the shared memory buffer
} NSSharedBufferHdr;

/**
 * @class CNSSharedMem
 * \~english @brief shared memory
 * \~english @par   Brief Introduction
 *        This class is used for handle shared memory.
 *
 */
class CNSSharedMem {
 public:
  ////////////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup CNSSharedMem
  /// \~english @par Brief
  ///        Constructor for CNSSharedMem
  /// \~english @param[in] f_cSharedMemName
  ///        const std::string& - name of the shared memory
  /// \~english @param[in] f_uiSize
  ///        const UI_32 - size of shared memory
  /// \~english @retval none
  /// \~english @par Preconditons
  ///        None
  /// \~english @par Change of internal status
  ///        None
  /// \~english @par Conditions of processing failure
  ///        None
  /// \~english @par Detail
  ///        Create object of CNSSharedMem class.
  ///        This class don't used to open shared memory object or allocate memory.
  /// \~english @par Classification
  ///        Public
  /// \~english @par Type
  /// \~english @see ~CNSSharedMem
  ////////////////////////////////////////////////////////////////////////////////////////////////
  CNSSharedMem(const std::string &f_cSharedMemName, const UI_32 f_uiSize);

  ////////////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup CNSSharedMem
  /// \~english @par Brief
  ///        Destructor for CNSSharedMem.
  /// \~english @retval none
  /// \~english @par Preconditons
  ///       None
  /// \~english @par Change of internal status
  ///       - Change the state of shared memory to closed state
  /// \~english @par Conditions of processing failure
  ///       None
  /// \~english @par Detail
  ///       Closes the shared memory, if it is open.
  /// \~english @par
  ///         Please note the following points when using this API for application.
  ///         - Since the destructor does not delete the shared memory area, \n
  ///           the application must execute shm_unlink to delete the shared memory area.
  /// \~english @par Classification
  ///       Public
  /// \~english @par Type
  /// \~english @see CNSSharedMem(const std::string&, const UI_32), CNSSharedMem(), Close
  ////////////////////////////////////////////////////////////////////////////////////////////////
  ~CNSSharedMem();

  ////////////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup CNSSharedMem
  /// \~english @par Brief
  ///        This function opens and maps the shared memory object.
  /// \~english @retval eFrameworkunifiedStatusOK if shared memory opened successfully
  /// \~english @retval eFrameworkunifiedStatusFail unable to open shared memory
  /// \~english @retval eFrameworkunifiedStatusErrOther if shared memory already opened
  /// \~english @par Preconditons
  ///         None
  /// \~english @par Change of internal status
  ///         - Open shared memory object
  /// \~english @par Conditions of processing failure
  ///         - if shared memory already opened [eFrameworkunifiedStatusErrOther]
  ///         - Unable to open shared memory(shm_open) [eFrameworkunifiedStatusFail]
  ///         - Unable to create shared memory(mmap) [eFrameworkunifiedStatusFail]
  /// \~english @par Detail
  ///         It creates the shared memory if it does not exists.
  /// \~english @par Classification
  ///         Public
  /// \~english @par Type
  ///         Open Close
  /// \~english @see Close
  ////////////////////////////////////////////////////////////////////////////////////////////////
  EFrameworkunifiedStatus Open();

  ////////////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup CNSSharedMem
  /// \~english @par Brief
  ///        This function is used to check whether the shared memory buffer is opened or not.
  /// \~english @retval TRUE - Open
  /// \~english @retval FALSE - Not open
  /// \~english @par Preconditons
  ///         - None
  /// \~english @par Change of internal status
  ///         - None
  /// \~english @par Conditions of processing failure
  ///         - None
  /// \~english @par Detail
  ///         - Check whether the shared memory buffer is opened or not, and return the result.
  /// \~english @par Classification
  ///         public
  /// \~english @par Type
  ///         Open Close
  /// \~english @see none
  ////////////////////////////////////////////////////////////////////////////////////////////////
  BOOL IsOpen();

  ////////////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup CNSSharedMem
  /// \~english @par Brief
  ///        This function unmaps the shared memory object.
  /// \~english @retval eFrameworkunifiedStatusOK if shared memory closed successfully
  /// \~english @retval eFrameworkunifiedStatusFail if shared memory is not opened
  /// \~english @par Preconditons
  ///         - Open the shared memory object
  /// \~english @par Change of internal status
  ///         - Close the shared memory object
  /// \~english @par Conditions of processing failure
  ///         - The shared memory object is not opened. [eFrameworkunifiedStatusFail]
  ///         - Unable to unmap(munmap) the shared memory object [eFrameworkunifiedStatusFail]
  /// \~english @par Detail
  ///         - This function unmaps the shared memory object from memory space.
  /// \~english @par
  ///         Please note the following points when using this API for application.
  ///         - Since the destructor does not delete the shared memory area, \n
  ///           the application must execute shm_unlink to delete the shared memory area.
  /// \~english @par Classification
  ///         public
  /// \~english @par Type
  ///         Open Close
  /// \~english @see Open
  ////////////////////////////////////////////////////////////////////////////////////////////////
  EFrameworkunifiedStatus Close();

  ////////////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup CNSSharedMem
  /// \~english @par Brief
  //          Read data from shared memory.
  /// \~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 @param [in] f_bBlock
  ///         BOOL - TRUE -  blocking call
  ///                FALSE - non blocking call
  /// \~english @retval SI_32 Returns The number of bytes actually read, or NS_SHM_ERROR if an error occurred
  /// \~english @retval NS_SHM_ERROR
  /// \~english @par Preconditons
  ///         - Open the shared memory object
  /// \~english @par Change of internal status
  ///         - None
  /// \~english @par Conditions of processing failure
  ///         - The shared memory object is not opened. [NS_SHM_ERROR]
  ///         - Pointor to buffer(buffer) is NULL. [NS_SHM_ERROR]
  ///         - Byte of data(f_uilength)is 0. [NS_SHM_ERROR]
  /// \~english @par Detail
  ///         This function reads data from the shared memory.
  ///         If this function is used as blocking call, then the calling thread will get blocked
  ///         until data is available for read. By default it is a blocking call.
  /// \~english @par Classification
  ///         public
  /// \~english @par Type
  ///         Open Close
  /// \~english @see Write
  ////////////////////////////////////////////////////////////////////////////////////////////////
  SI_32 Read(PSTR buffer, const UI_32 f_uilength, const BOOL f_bBlock = TRUE);

  ////////////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup CNSSharedMem
  /// \~english @par Brief
  ///        This function writes the data into the shared memory.
  /// \~english @param[in] buffer
  ///        PCSTR - pointer to the buffer containing the data to be written
  /// \~english @param[in] f_uilength
  ///        const UI_32 - length of the data buffer to be written
  /// \~english @retval SI_32 Returns The number of bytes written, or NS_SHM_ERROR if an error occurred
  /// \~english @par Preconditons
  ///         - Open the shared memory object
  /// \~english @par Change of internal status
  ///         - None
  /// \~english @par Conditions of processing failure
  ///         - The shared memory object is not opened. [NS_SHM_ERROR]
  ///         - Pointor to buffer(buffer) is NULL. [NS_SHM_ERROR]
  ///         - Size of buffer(f_uilength) is larger than the size designated by constructor. [NS_SHM_ERROR]
  /// \~english @par Detail
  ///         - This function writes the data into the shared memory.
  /// \~english @par Classification
  ///         public
  /// \~english @par Type
  ///         Open Close
  /// \~english @see Read
  ////////////////////////////////////////////////////////////////////////////////////////////////
  SI_32 Write(PCSTR buffer, const UI_32 f_uilength);

  ////////////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup CNSSharedMem
  /// \~english @par Brief
  ///           Dump data to file.
  /// \~english @param [in] f_pPath
  ///            PCSTR - file path.
  /// \~english @param[in] [in] f_uiDumpSize
  ///            PUI_32 - Returns The number of bytes written into file
  /// \~english @retval EFrameworkunifiedStatus
  ///             eFrameworkunifiedStatusOK on success,
  ///             eFrameworkunifiedStatusFileLoadError - file path is incorrect
  ///             eFrameworkunifiedStatusSemLockFail/
  ///             eFrameworkunifiedStatusSemLockFail - mutex locking/unlocking error
  ///             eFrameworkunifiedStatusFail - shared memory is not opened
  ///             eFrameworkunifiedStatusInvldParam - invalid param
  /// \~english @par Preconditons
  ///           -
  /// \~english @par Change of internal status
  ///           -None
  /// \~english @par Conditions of processing failure
  ///           - file path is incorrect.[eFrameworkunifiedStatusFileLoadError]
  ///           - mutex locking/unlocking error.[eFrameworkunifiedStatusSemLockFail/eFrameworkunifiedStatusSemLockFail]
  ///           - shared memory is not opened.[eFrameworkunifiedStatusFail]
  ///           - invalid param.[eFrameworkunifiedStatusInvldParam]
  /// \~english @par Detail
  ///           - This function writes all the data in the buffer into provided file f_pPath.
  ///           - This function does not changes the unread buffer.
  ///           - This function overwrites the file if it exists.
  /// \~english @par Classification
  ///           public
  /// \~english @par Type
  ///           sync only
  /// \~english @par
  ///           - eFrameworkunifiedStatus:Result
  ///               - eFrameworkunifiedStatusOK:Success
  ///               - Except eFrameworkunifiedStatusOK:Failure
  /// \~english @see None
  ////////////////////////////////////////////////////////////////////////////////////////////////
  EFrameworkunifiedStatus DumpToFile(PCSTR f_pPath, PUI_32 f_uiDumpSize);

  ////////////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup CNSSharedMem
  /// \~english @par Brief
  ///        This function gets size of unread bytes.
  /// \~english @param None
  /// \~english @retval Except NS_SHM_ERROR - Returns The number of unread bytes
  /// \~english @retval NS_SHM_ERROR  -if an error occurred
  /// \~english @par Preconditons
  ///           -
  /// \~english @par Change of internal status
  ///           None
  /// \~english @par Conditions of processing failure
  ///           if m_pShmHdr is null.[NS_SHM_ERROR]
  /// \~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 @par
  ///           - l_uiReadSize:Result
  ///               - NS_SHM_ERROR:Failure
  ///               - Except NS_SHM_ERROR:Success
  /// \~english @see None
  ////////////////////////////////////////////////////////////////////////////////////////////////
  SI_32 GetSize();

  ////////////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup CNSSharedMem
  /// \~english @par Brief
  ///           Clear buffer.
  /// \~english @param None
  /// \~english @retval EFrameworkunifiedStatus
  ///             eFrameworkunifiedStatusOK on success,
  ///             eFrameworkunifiedStatusSemLockFail/
  ///             eFrameworkunifiedStatusSemLockFail - mutex locking/unlocking error
  ///             eFrameworkunifiedStatusFail - shared memory is not opened
  /// \~english @par Preconditons
  ///           -
  /// \~english @par Change of internal status
  ///           - set m_pShmHdr->m_uiReadPtr with 0;
  ///           - set m_pShmHdr->m_uiWritePtr with 0;
  ///           - set m_pShmHdr->m_uiUnReadSize with 0;
  ///           - set m_pShmHdr->m_bIsFull with FALSE;
  /// \~english @par Conditions of processing failure
  ///           - mutex locking/unlocking error.[eFrameworkunifiedStatusSemLockFail/eFrameworkunifiedStatusSemLockFail]
  ///           - shared memory is not opened.[eFrameworkunifiedStatusFail]
  /// \~english @par Detail
  ///           - This function clears the shared memory buffer.if m_pShmHdr is null,return failure.
  /// \~english @par Classification
  ///           public
  /// \~english @par Type
  ///           sync only
  /// \~english @par
  ///           - eFrameworkunifiedStatus:Result
  ///               - eFrameworkunifiedStatusOK:Success
  ///               - Except eFrameworkunifiedStatusOK:Failure
  /// \~english @see None
  ////////////////////////////////////////////////////////////////////////////////////////////////
  EFrameworkunifiedStatus ClearBuf();

  ////////////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup CNSSharedMem
  /// \~english @par Brief
  ///           This function sets the position of read ptr to write ptr in buffer.
  /// \~english @param None
  /// \~english @retval EFrameworkunifiedStatus
  ///             eFrameworkunifiedStatusOK on success,
  ///             eFrameworkunifiedStatusSemLockFail/
  ///             eFrameworkunifiedStatusSemLockFail - mutex locking/unlocking error
  ///             eFrameworkunifiedStatusFail - shared memory is not opened
  /// \~english @par Preconditons
  ///           -
  /// \~english @par Change of internal status
  ///           - set m_pShmHdr->m_uiReadPtr with m_pShmHdr->m_uiWritePtr;
  ///           - set m_pShmHdr->m_uiUnReadSize with 0;
  /// \~english @par Conditions of processing failure
  ///           - mutex locking/unlocking error.[eFrameworkunifiedStatusSemLockFail/eFrameworkunifiedStatusSemLockFail]
  ///           - shared memory is not opened.[eFrameworkunifiedStatusFail]
  /// \~english @par Detail
  ///           - This function sets the position of read ptr to write ptr in buffer.\n
  ///             If m_pShmHdr of lock failure or unlock failure,result is error.
  /// \~english @par Classification
  ///           public
  /// \~english @par Type
  ///           sync only
  /// \~english @par
  ///           - eFrameworkunifiedStatus:Result
  ///               - eFrameworkunifiedStatusOK:Success
  ///               - Except eFrameworkunifiedStatusOK:Failure
  /// \~english @see None
  ////////////////////////////////////////////////////////////////////////////////////////////////
  EFrameworkunifiedStatus SetReadPtrToWritePtr();

 protected:
  // no members in protected

 private:
  ////////////////////////////////////////////////////////////////////////////////////////////////
  /// CNSSharedMem
  /// Constructor of CNSSharedMem class
  ///
  /// \return     None
  ///
  ////////////////////////////////////////////////////////////////////////////////////////////////
  CNSSharedMem();

  ////////////////////////////////////////////////////////////////////////////////////////////////
  /// CreateSMHeader
  /// This function creates the shared memory object for header.
  ///
  /// \return EFrameworkunifiedStatus
  ///             eFrameworkunifiedStatusOK            shared memory created successfully
  ///             eFrameworkunifiedStatusDuplicate     shared memory already exists
  ///             eFrameworkunifiedStatusInvldParam    invalid shared memory name
  ///             eFrameworkunifiedStatusFail          on error
  ///
  ////////////////////////////////////////////////////////////////////////////////////////////////
  EFrameworkunifiedStatus CreateSMHeader();

  ////////////////////////////////////////////////////////////////////////////////////////////////
  /// CreateSMDataBuffer
  /// This function creates the shared memory object for data buffer.
  ///
  /// \return EFrameworkunifiedStatus
  ///             eFrameworkunifiedStatusOK            shared memory created successfully
  ///             eFrameworkunifiedStatusDuplicate     shared memory already exists
  ///             eFrameworkunifiedStatusInvldParam    invalid shared memory name
  ///             eFrameworkunifiedStatusFail          on error
  ///
  ////////////////////////////////////////////////////////////////////////////////////////////////
  EFrameworkunifiedStatus CreateSMDataBuffer();

  ////////////////////////////////////////////////////////////////////////////////////////////////
  /// MapSMHeader
  /// 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);

  ////////////////////////////////////////////////////////////////////////////////////////////////
  /// UnMapSM
  /// This function unmaps the shared memory object.
  ///
  /// \param  [in] f_pShMem
  ///         PCSTR - address of the memory to unmap
  /// \param  [in] f_uiShmSize
  ///         UI_32 - Size of the memory to be unmapped
  ///
  /// \return EFrameworkunifiedStatus
  ///             eFrameworkunifiedStatusOK if shared memory closed successfully
  ///             eFrameworkunifiedStatusFail if shared memory is not opened
  ///
  ////////////////////////////////////////////////////////////////////////////////////////////////
  EFrameworkunifiedStatus UnMapSM(PVOID f_pShMem, const UI_32 f_uiShmSize);

  std::string m_cShmHdrName;      // name of the shared memory header

  std::string m_cShmName;         // name of the shared memory data

  UI_32 m_uiShmBuffSize;          // shared memory size

  NSSharedBufferHdr *m_pShmHdr;   // The pointer to the shared memory header

  PCHAR m_pShmBuff;               // The pointer to the shared memory data buffer
};

#endif /* __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_H__ */  // NOLINT  (build/header_guard)
/** @}*/
/** @}*/
/** @}*/
/** @}*/
//@}