video_in_hal/nsframework/framework_unified/client/include/native_service/ns_sharedmem.h

   1 /*
   2  * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 ////////////////////////////////////////////////////////////////////////////////////////////////////
  18 /// \ingroup  tag_NSSharedMemory
  19 /// \brief    This file contains implementation of class CNSSharedMem.
  20 ///           This class provides API to open, read, write and close shared memory
  21 ///
  22 ////////////////////////////////////////////////////////////////////////////////////////////////////
  23 //@{
  24 /**
  25  * @file ns_sharedmem.h
  26  * @brief \~english This file contains implementation of class CNSSharedMem.
  27  *         This class provides API to open, read, write and close shared memory
  28  *
  29  */
  30 /** @addtogroup BaseSystem
  31  *  @{
  32  */
  33 /** @addtogroup native_service
  34  *  @ingroup BaseSystem
  35  *  @{
  36  */
  37 /** @addtogroup framework_unified
  38  *  @ingroup native_service
  39  *  @{
  40  */
  41 /** @addtogroup native
  42  *  @ingroup framework_unified
  43  *  @{
  44  */
  45 #ifndef __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_H__  // NOLINT  (build/header_guard)
  46 #define __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_H__
  47
  48 // Used only in nstest_sharedmem.
  49 // set environment, CNSSharedMem::Open() always fail. ===> eFrameworkunifiedStatusErrOther
  50 #define NSTEST_FAIL_SHAREDMEM_OPEN  "NSTEST_FAIL_SHAREDMEM_OPEN"
  51
  52
  53 ////////////////////////////////////////////////////////////////////////////////////////////////////
  54 // Include Files
  55 ////////////////////////////////////////////////////////////////////////////////////////////////////
  56 #include <pthread.h>
  57 #include <native_service/frameworkunified_types.h>
  58 #include <string>
  59
  60 // Structure of the header of the shared memory buffer
  61 typedef struct _NSSharedBuffer {
  62   pthread_mutex_t m_tBufMutex;    // Mutex object to mutual exclusion
  63   pthread_cond_t  m_tCondVar;     // Condition Variable
  64   UI_32           m_uiReadPtr;    // Read pointer
  65   UI_32           m_uiWritePtr;   // Write pointer
  66   UI_32           m_uiUnReadSize;  // Data size not read yet
  67   BOOL            m_bIsFull;      // Flag indicating if the buffer has full of data
  68   UI_32           m_uiShMemSize;  // Size of the shared memory buffer
  69 } NSSharedBufferHdr;
  70
  71 /**
  72  * @class CNSSharedMem
  73  * \~english @brief shared memory
  74  * \~english @par   Brief Introduction
  75  *        This class is used for handle shared memory.
  76  *
  77  */
  78 class CNSSharedMem {
  79  public:
  80   ////////////////////////////////////////////////////////////////////////////////////////////////
  81   /// \ingroup CNSSharedMem
  82   /// \~english @par Brief
  83   ///        Constructor for CNSSharedMem
  84   /// \~english @param[in] f_cSharedMemName
  85   ///        const std::string& - name of the shared memory
  86   /// \~english @param[in] f_uiSize
  87   ///        const UI_32 - size of shared memory
  88   /// \~english @retval none
  89   /// \~english @par Preconditons
  90   ///        None
  91   /// \~english @par Change of internal status
  92   ///        None
  93   /// \~english @par Conditions of processing failure
  94   ///        None
  95   /// \~english @par Detail
  96   ///        Create object of CNSSharedMem class.
  97   ///        This class don't used to open shared memory object or allocate memory.
  98   /// \~english @par Classification
  99   ///        Public
 100   /// \~english @par Type
 101   /// \~english @see ~CNSSharedMem
 102   ////////////////////////////////////////////////////////////////////////////////////////////////
 103   CNSSharedMem(const std::string &f_cSharedMemName, const UI_32 f_uiSize);
 104
 105   ////////////////////////////////////////////////////////////////////////////////////////////////
 106   /// \ingroup CNSSharedMem
 107   /// \~english @par Brief
 108   ///        Destructor for CNSSharedMem.
 109   /// \~english @retval none
 110   /// \~english @par Preconditons
 111   ///       None
 112   /// \~english @par Change of internal status
 113   ///       - Change the state of shared memory to closed state
 114   /// \~english @par Conditions of processing failure
 115   ///       None
 116   /// \~english @par Detail
 117   ///       Closes the shared memory, if it is open.
 118   /// \~english @par
 119   ///         Please note the following points when using this API for application.
 120   ///         - Since the destructor does not delete the shared memory area, \n
 121   ///           the application must execute shm_unlink to delete the shared memory area.
 122   /// \~english @par Classification
 123   ///       Public
 124   /// \~english @par Type
 125   /// \~english @see CNSSharedMem(const std::string&, const UI_32), CNSSharedMem(), Close
 126   ////////////////////////////////////////////////////////////////////////////////////////////////
 127   ~CNSSharedMem();
 128
 129   ////////////////////////////////////////////////////////////////////////////////////////////////
 130   /// \ingroup CNSSharedMem
 131   /// \~english @par Brief
 132   ///        This function opens and maps the shared memory object.
 133   /// \~english @retval eFrameworkunifiedStatusOK if shared memory opened successfully
 134   /// \~english @retval eFrameworkunifiedStatusFail unable to open shared memory
 135   /// \~english @retval eFrameworkunifiedStatusErrOther if shared memory already opened
 136   /// \~english @par Preconditons
 137   ///         None
 138   /// \~english @par Change of internal status
 139   ///         - Open shared memory object
 140   /// \~english @par Conditions of processing failure
 141   ///         - if shared memory already opened [eFrameworkunifiedStatusErrOther]
 142   ///         - Unable to open shared memory(shm_open) [eFrameworkunifiedStatusFail]
 143   ///         - Unable to create shared memory(mmap) [eFrameworkunifiedStatusFail]
 144   /// \~english @par Detail
 145   ///         It creates the shared memory if it does not exists.
 146   /// \~english @par Classification
 147   ///         Public
 148   /// \~english @par Type
 149   ///         Open Close
 150   /// \~english @see Close
 151   ////////////////////////////////////////////////////////////////////////////////////////////////
 152   EFrameworkunifiedStatus Open();
 153
 154   ////////////////////////////////////////////////////////////////////////////////////////////////
 155   /// \ingroup CNSSharedMem
 156   /// \~english @par Brief
 157   ///        This function is used to check whether the shared memory buffer is opened or not.
 158   /// \~english @retval TRUE - Open
 159   /// \~english @retval FALSE - Not open
 160   /// \~english @par Preconditons
 161   ///         - None
 162   /// \~english @par Change of internal status
 163   ///         - None
 164   /// \~english @par Conditions of processing failure
 165   ///         - None
 166   /// \~english @par Detail
 167   ///         - Check whether the shared memory buffer is opened or not, and return the result.
 168   /// \~english @par Classification
 169   ///         public
 170   /// \~english @par Type
 171   ///         Open Close
 172   /// \~english @see none
 173   ////////////////////////////////////////////////////////////////////////////////////////////////
 174   BOOL IsOpen();
 175
 176   ////////////////////////////////////////////////////////////////////////////////////////////////
 177   /// \ingroup CNSSharedMem
 178   /// \~english @par Brief
 179   ///        This function unmaps the shared memory object.
 180   /// \~english @retval eFrameworkunifiedStatusOK if shared memory closed successfully
 181   /// \~english @retval eFrameworkunifiedStatusFail if shared memory is not opened
 182   /// \~english @par Preconditons
 183   ///         - Open the shared memory object
 184   /// \~english @par Change of internal status
 185   ///         - Close the shared memory object
 186   /// \~english @par Conditions of processing failure
 187   ///         - The shared memory object is not opened. [eFrameworkunifiedStatusFail]
 188   ///         - Unable to unmap(munmap) the shared memory object [eFrameworkunifiedStatusFail]
 189   /// \~english @par Detail
 190   ///         - This function unmaps the shared memory object from memory space.
 191   /// \~english @par
 192   ///         Please note the following points when using this API for application.
 193   ///         - Since the destructor does not delete the shared memory area, \n
 194   ///           the application must execute shm_unlink to delete the shared memory area.
 195   /// \~english @par Classification
 196   ///         public
 197   /// \~english @par Type
 198   ///         Open Close
 199   /// \~english @see Open
 200   ////////////////////////////////////////////////////////////////////////////////////////////////
 201   EFrameworkunifiedStatus Close();
 202
 203   ////////////////////////////////////////////////////////////////////////////////////////////////
 204   /// \ingroup CNSSharedMem
 205   /// \~english @par Brief
 206   //          Read data from shared memory.
 207   /// \~english @param [out] buffer
 208   ///         PSTR - pointer to the buffer in which the read data is stored
 209   /// \~english @param [in] f_uilength
 210   ///         UI_32 - length of the data buffer provided
 211   /// \~english @param [in] f_bBlock
 212   ///         BOOL - TRUE -  blocking call
 213   ///                FALSE - non blocking call
 214   /// \~english @retval SI_32 Returns The number of bytes actually read, or NS_SHM_ERROR if an error occurred
 215   /// \~english @retval NS_SHM_ERROR
 216   /// \~english @par Preconditons
 217   ///         - Open the shared memory object
 218   /// \~english @par Change of internal status
 219   ///         - None
 220   /// \~english @par Conditions of processing failure
 221   ///         - The shared memory object is not opened. [NS_SHM_ERROR]
 222   ///         - Pointor to buffer(buffer) is NULL. [NS_SHM_ERROR]
 223   ///         - Byte of data(f_uilength)is 0. [NS_SHM_ERROR]
 224   /// \~english @par Detail
 225   ///         This function reads data from the shared memory.
 226   ///         If this function is used as blocking call, then the calling thread will get blocked
 227   ///         until data is available for read. By default it is a blocking call.
 228   /// \~english @par Classification
 229   ///         public
 230   /// \~english @par Type
 231   ///         Open Close
 232   /// \~english @see Write
 233   ////////////////////////////////////////////////////////////////////////////////////////////////
 234   SI_32 Read(PSTR buffer, const UI_32 f_uilength, const BOOL f_bBlock = TRUE);
 235
 236   ////////////////////////////////////////////////////////////////////////////////////////////////
 237   /// \ingroup CNSSharedMem
 238   /// \~english @par Brief
 239   ///        This function writes the data into the shared memory.
 240   /// \~english @param[in] buffer
 241   ///        PCSTR - pointer to the buffer containing the data to be written
 242   /// \~english @param[in] f_uilength
 243   ///        const UI_32 - length of the data buffer to be written
 244   /// \~english @retval SI_32 Returns The number of bytes written, or NS_SHM_ERROR if an error occurred
 245   /// \~english @par Preconditons
 246   ///         - Open the shared memory object
 247   /// \~english @par Change of internal status
 248   ///         - None
 249   /// \~english @par Conditions of processing failure
 250   ///         - The shared memory object is not opened. [NS_SHM_ERROR]
 251   ///         - Pointor to buffer(buffer) is NULL. [NS_SHM_ERROR]
 252   ///         - Size of buffer(f_uilength) is larger than the size designated by constructor. [NS_SHM_ERROR]
 253   /// \~english @par Detail
 254   ///         - This function writes the data into the shared memory.
 255   /// \~english @par Classification
 256   ///         public
 257   /// \~english @par Type
 258   ///         Open Close
 259   /// \~english @see Read
 260   ////////////////////////////////////////////////////////////////////////////////////////////////
 261   SI_32 Write(PCSTR buffer, const UI_32 f_uilength);
 262
 263   ////////////////////////////////////////////////////////////////////////////////////////////////
 264   /// \ingroup CNSSharedMem
 265   /// \~english @par Brief
 266   ///           Dump data to file.
 267   /// \~english @param [in] f_pPath
 268   ///            PCSTR - file path.
 269   /// \~english @param[in] [in] f_uiDumpSize
 270   ///            PUI_32 - Returns The number of bytes written into file
 271   /// \~english @retval EFrameworkunifiedStatus
 272   ///             eFrameworkunifiedStatusOK on success,
 273   ///             eFrameworkunifiedStatusFileLoadError - file path is incorrect
 274   ///             eFrameworkunifiedStatusSemLockFail/
 275   ///             eFrameworkunifiedStatusSemLockFail - mutex locking/unlocking error
 276   ///             eFrameworkunifiedStatusFail - shared memory is not opened
 277   ///             eFrameworkunifiedStatusInvldParam - invalid param
 278   /// \~english @par Preconditons
 279   ///           -
 280   /// \~english @par Change of internal status
 281   ///           -None
 282   /// \~english @par Conditions of processing failure
 283   ///           - file path is incorrect.[eFrameworkunifiedStatusFileLoadError]
 284   ///           - mutex locking/unlocking error.[eFrameworkunifiedStatusSemLockFail/eFrameworkunifiedStatusSemLockFail]
 285   ///           - shared memory is not opened.[eFrameworkunifiedStatusFail]
 286   ///           - invalid param.[eFrameworkunifiedStatusInvldParam]
 287   /// \~english @par Detail
 288   ///           - This function writes all the data in the buffer into provided file f_pPath.
 289   ///           - This function does not changes the unread buffer.
 290   ///           - This function overwrites the file if it exists.
 291   /// \~english @par Classification
 292   ///           public
 293   /// \~english @par Type
 294   ///           sync only
 295   /// \~english @par
 296   ///           - eFrameworkunifiedStatus:Result
 297   ///               - eFrameworkunifiedStatusOK:Success
 298   ///               - Except eFrameworkunifiedStatusOK:Failure
 299   /// \~english @see None
 300   ////////////////////////////////////////////////////////////////////////////////////////////////
 301   EFrameworkunifiedStatus DumpToFile(PCSTR f_pPath, PUI_32 f_uiDumpSize);
 302
 303   ////////////////////////////////////////////////////////////////////////////////////////////////
 304   /// \ingroup CNSSharedMem
 305   /// \~english @par Brief
 306   ///        This function gets size of unread bytes.
 307   /// \~english @param None
 308   /// \~english @retval Except NS_SHM_ERROR - Returns The number of unread bytes
 309   /// \~english @retval NS_SHM_ERROR  -if an error occurred
 310   /// \~english @par Preconditons
 311   ///           -
 312   /// \~english @par Change of internal status
 313   ///           None
 314   /// \~english @par Conditions of processing failure
 315   ///           if m_pShmHdr is null.[NS_SHM_ERROR]
 316   /// \~english @par Detail
 317   ///           This function returns the number of unread bytes which can be read by Read().
 318   /// \~english @par Classification
 319   ///           Public
 320   /// \~english @par Type
 321   ///           sync only
 322   /// \~english @par
 323   ///           - l_uiReadSize:Result
 324   ///               - NS_SHM_ERROR:Failure
 325   ///               - Except NS_SHM_ERROR:Success
 326   /// \~english @see None
 327   ////////////////////////////////////////////////////////////////////////////////////////////////
 328   SI_32 GetSize();
 329
 330   ////////////////////////////////////////////////////////////////////////////////////////////////
 331   /// \ingroup CNSSharedMem
 332   /// \~english @par Brief
 333   ///           Clear buffer.
 334   /// \~english @param None
 335   /// \~english @retval EFrameworkunifiedStatus
 336   ///             eFrameworkunifiedStatusOK on success,
 337   ///             eFrameworkunifiedStatusSemLockFail/
 338   ///             eFrameworkunifiedStatusSemLockFail - mutex locking/unlocking error
 339   ///             eFrameworkunifiedStatusFail - shared memory is not opened
 340   /// \~english @par Preconditons
 341   ///           -
 342   /// \~english @par Change of internal status
 343   ///           - set m_pShmHdr->m_uiReadPtr with 0;
 344   ///           - set m_pShmHdr->m_uiWritePtr with 0;
 345   ///           - set m_pShmHdr->m_uiUnReadSize with 0;
 346   ///           - set m_pShmHdr->m_bIsFull with FALSE;
 347   /// \~english @par Conditions of processing failure
 348   ///           - mutex locking/unlocking error.[eFrameworkunifiedStatusSemLockFail/eFrameworkunifiedStatusSemLockFail]
 349   ///           - shared memory is not opened.[eFrameworkunifiedStatusFail]
 350   /// \~english @par Detail
 351   ///           - This function clears the shared memory buffer.if m_pShmHdr is null,return failure.
 352   /// \~english @par Classification
 353   ///           public
 354   /// \~english @par Type
 355   ///           sync only
 356   /// \~english @par
 357   ///           - eFrameworkunifiedStatus:Result
 358   ///               - eFrameworkunifiedStatusOK:Success
 359   ///               - Except eFrameworkunifiedStatusOK:Failure
 360   /// \~english @see None
 361   ////////////////////////////////////////////////////////////////////////////////////////////////
 362   EFrameworkunifiedStatus ClearBuf();
 363
 364   ////////////////////////////////////////////////////////////////////////////////////////////////
 365   /// \ingroup CNSSharedMem
 366   /// \~english @par Brief
 367   ///           This function sets the position of read ptr to write ptr in buffer.
 368   /// \~english @param None
 369   /// \~english @retval EFrameworkunifiedStatus
 370   ///             eFrameworkunifiedStatusOK on success,
 371   ///             eFrameworkunifiedStatusSemLockFail/
 372   ///             eFrameworkunifiedStatusSemLockFail - mutex locking/unlocking error
 373   ///             eFrameworkunifiedStatusFail - shared memory is not opened
 374   /// \~english @par Preconditons
 375   ///           -
 376   /// \~english @par Change of internal status
 377   ///           - set m_pShmHdr->m_uiReadPtr with m_pShmHdr->m_uiWritePtr;
 378   ///           - set m_pShmHdr->m_uiUnReadSize with 0;
 379   /// \~english @par Conditions of processing failure
 380   ///           - mutex locking/unlocking error.[eFrameworkunifiedStatusSemLockFail/eFrameworkunifiedStatusSemLockFail]
 381   ///           - shared memory is not opened.[eFrameworkunifiedStatusFail]
 382   /// \~english @par Detail
 383   ///           - This function sets the position of read ptr to write ptr in buffer.\n
 384   ///             If m_pShmHdr of lock failure or unlock failure,result is error.
 385   /// \~english @par Classification
 386   ///           public
 387   /// \~english @par Type
 388   ///           sync only
 389   /// \~english @par
 390   ///           - eFrameworkunifiedStatus:Result
 391   ///               - eFrameworkunifiedStatusOK:Success
 392   ///               - Except eFrameworkunifiedStatusOK:Failure
 393   /// \~english @see None
 394   ////////////////////////////////////////////////////////////////////////////////////////////////
 395   EFrameworkunifiedStatus SetReadPtrToWritePtr();
 396
 397  protected:
 398   // no members in protected
 399
 400  private:
 401   ////////////////////////////////////////////////////////////////////////////////////////////////
 402   /// CNSSharedMem
 403   /// Constructor of CNSSharedMem class
 404   ///
 405   /// \return     None
 406   ///
 407   ////////////////////////////////////////////////////////////////////////////////////////////////
 408   CNSSharedMem();
 409
 410   ////////////////////////////////////////////////////////////////////////////////////////////////
 411   /// CreateSMHeader
 412   /// This function creates the shared memory object for header.
 413   ///
 414   /// \return EFrameworkunifiedStatus
 415   ///             eFrameworkunifiedStatusOK            shared memory created successfully
 416   ///             eFrameworkunifiedStatusDuplicate     shared memory already exists
 417   ///             eFrameworkunifiedStatusInvldParam    invalid shared memory name
 418   ///             eFrameworkunifiedStatusFail          on error
 419   ///
 420   ////////////////////////////////////////////////////////////////////////////////////////////////
 421   EFrameworkunifiedStatus CreateSMHeader();
 422
 423   ////////////////////////////////////////////////////////////////////////////////////////////////
 424   /// CreateSMDataBuffer
 425   /// This function creates the shared memory object for data buffer.
 426   ///
 427   /// \return EFrameworkunifiedStatus
 428   ///             eFrameworkunifiedStatusOK            shared memory created successfully
 429   ///             eFrameworkunifiedStatusDuplicate     shared memory already exists
 430   ///             eFrameworkunifiedStatusInvldParam    invalid shared memory name
 431   ///             eFrameworkunifiedStatusFail          on error
 432   ///
 433   ////////////////////////////////////////////////////////////////////////////////////////////////
 434   EFrameworkunifiedStatus CreateSMDataBuffer();
 435
 436   ////////////////////////////////////////////////////////////////////////////////////////////////
 437   /// MapSMHeader
 438   /// This function open and maps the shared memory in process space.
 439   ///
 440   /// \param  [out] f_pShMem
 441   ///         PVOID* - address of the mapped memory
 442   /// \param  [in] f_cShmName
 443   ///         std::string - Name of the shared memory
 444   /// \param  [in] f_uiShmSize
 445   ///         UI_32 - Size of the shared memory
 446   ///
 447   /// \return EFrameworkunifiedStatus
 448   ///             eFrameworkunifiedStatusOK if shared memory opened successfully
 449   ///             eFrameworkunifiedStatusFail unable to open shared memory
 450   ///
 451   ////////////////////////////////////////////////////////////////////////////////////////////////
 452   EFrameworkunifiedStatus MapSM(PVOID *f_pShMem, const std::string &f_cShmName, const UI_32 f_uiShmSize);
 453
 454   ////////////////////////////////////////////////////////////////////////////////////////////////
 455   /// UnMapSM
 456   /// This function unmaps the shared memory object.
 457   ///
 458   /// \param  [in] f_pShMem
 459   ///         PCSTR - address of the memory to unmap
 460   /// \param  [in] f_uiShmSize
 461   ///         UI_32 - Size of the memory to be unmapped
 462   ///
 463   /// \return EFrameworkunifiedStatus
 464   ///             eFrameworkunifiedStatusOK if shared memory closed successfully
 465   ///             eFrameworkunifiedStatusFail if shared memory is not opened
 466   ///
 467   ////////////////////////////////////////////////////////////////////////////////////////////////
 468   EFrameworkunifiedStatus UnMapSM(PVOID f_pShMem, const UI_32 f_uiShmSize);
 469
 470   std::string m_cShmHdrName;      // name of the shared memory header
 471
 472   std::string m_cShmName;         // name of the shared memory data
 473
 474   UI_32 m_uiShmBuffSize;          // shared memory size
 475
 476   NSSharedBufferHdr *m_pShmHdr;   // The pointer to the shared memory header
 477
 478   PCHAR m_pShmBuff;               // The pointer to the shared memory data buffer
 479 };
 480
 481 #endif /* __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_H__ */  // NOLINT  (build/header_guard)
 482 /** @}*/
 483 /** @}*/
 484 /** @}*/
 485 /** @}*/
 486 //@}