nsframework/framework_unified/client/include/native_service/ns_ringbuffer.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_NSRingBuffer
  19 /// \brief    This file contains implementation of class CNSRingBuffer.
  20 ///           This class provides API to open, read, write and close ring buffer
  21 ///
  22 ////////////////////////////////////////////////////////////////////////////////////////////////////
  23 //@{
  24 /**
  25  * @file ns_ringbuffer.h
  26  * @brief \~english This file contains implementation of class CNSRingBuffer.
  27  *        This class provides API to open, read, write and close ring buffer
  28  */
  29 /** @addtogroup BaseSystem
  30  *  @{
  31  */
  32 /** @addtogroup native_service
  33  *  @ingroup BaseSystem
  34  *  @{
  35  */
  36 /** @addtogroup framework_unified
  37  *  @ingroup native_service
  38  *  @{
  39  */
  40 /** @addtogroup native
  41  *  @ingroup framework_unified
  42  *  @{
  43  */
  44 #ifndef __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_RINGBUFFER_H__  // NOLINT  (build/header_guard)
  45 #define __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_RINGBUFFER_H__
  46
  47 ////////////////////////////////////////////////////////////////////////////////////////////////////
  48 // Include Files
  49 ////////////////////////////////////////////////////////////////////////////////////////////////////
  50 #include <pthread.h>
  51
  52 #include <native_service/frameworkunified_types.h>
  53
  54 #include <string>
  55
  56 // Structure of the header of the ring buffer
  57 typedef struct _NSRingBufferHdr {
  58   UI_32           m_uiReadPtr;        // Read pointer
  59   UI_32           m_uiWritePtr;       // Write pointer
  60   UI_32           m_uiUnReadSize;     // Data size not read yet
  61   BOOL            m_bIsFull;          // Flag indicating if the buffer has full of data
  62   UI_32           m_uiRingBufferSize;  // Size of the ring buffer
  63 } NSRingBufferHdr;
  64
  65 // Structure of the mutex of the ring buffer
  66 typedef struct _NSRingBufferMtx {
  67   pthread_mutex_t m_tBufMutex;        // Mutex object to mutual exclusion
  68   int m_lid;
  69 } NSRingBufferMtx;
  70
  71
  72 /**
  73  * @class CNSRingBuffer
  74  * \~english @brief CNSRingBuffer
  75  * \~english @par   Brief Introduction
  76  *        Class to provide class of ring buffer.
  77  */
  78 class CNSRingBuffer {
  79  public:
  80   ////////////////////////////////////////////////////////////////////////////////////////////////
  81   /// \ingroup CNSRingBuffer
  82   /// \~english @par Brief
  83   ///        Constructor for CNSRingBuffer
  84   /// \~english @param[in] f_cMappedFilePath
  85   ///        const std::string& - path of the ring buffer mapped file
  86   /// \~english @param[in] f_uiSize
  87   ///        const UI_32 - size of ring buffer
  88   /// \~english @param[in] f_lid
  89   ///        int - Lock ID
  90   /// \~english @retval none
  91   /// \~english @par Preconditons
  92   ///         none
  93   /// \~english @par Change of internal status
  94   ///       - The internal state is not changed.
  95   /// \~english @par Conditions of processing failure
  96   ///         none
  97   /// \~english @par Detail
  98   ///       Create an instance of CNSRingBuffer class.\n
  99   ///       Initializes cass member (m_cMappedFilePath, m_uiRingBuffSize, m_pRbufMtx, m_pRbufHdr,
 100   ///       m_pRbuf, m_lid, m_pLockAddr, m_siProcessLastWrtPage, m_cRbufMtxName).\n
 101   /// \~english @par Classification
 102   ///       Public
 103   /// \~english @par Type
 104   ///          sync only
 105   /// \~english @par Detail
 106   ///       Constructor of CNSRingBuffer class.
 107   ///       variables (m_cMappedFilePath, m_uiRingBuffSize, m_pRbufMtx, m_pRbufHdr,
 108   ///       m_pRbuf, m_lid, m_pLockAddr, m_siProcessLastWrtPage, m_cRbufMtxName) to be initialization.
 109   /// \~english @see  ~CNSRingBuffer
 110   ////////////////////////////////////////////////////////////////////////////////////////////////
 111   CNSRingBuffer(const std::string &f_cMappedFilePath, const UI_32 f_uiSize, int f_lid = -1);
 112
 113   ////////////////////////////////////////////////////////////////////////////////////////////////
 114   /// \ingroup CNSRingBuffer
 115   /// \~english @par Brief
 116   ///        Destructor for CNSRingBuffer.
 117   /// \~english @param none
 118   /// \~english @retval none
 119   /// \~english @par Preconditons
 120   ///       - The constructor creates an instance of the CNSRingBuffer class.
 121   /// \~english @par Change of internal status
 122   ///       - The internal state is not changed.
 123   /// \~english @par Conditions of processing failure
 124   ///         none
 125   /// \~english @par Detail
 126   ///       Closes the ring buffer, if it is open.
 127   /// \~english @par
 128   ///       Closes the ring buffer if it is open.
 129   /// \~english @par Classification
 130   ///       Public
 131   /// \~english @par Type
 132   ///          sync only
 133   /// \~english @see CNSRingBuffer
 134   ////////////////////////////////////////////////////////////////////////////////////////////////
 135   ~CNSRingBuffer();
 136
 137   ////////////////////////////////////////////////////////////////////////////////////////////////
 138   /// \ingroup CNSRingBuffer
 139   /// \~english @par Brief
 140   ///        This function opens and maps the ring buffer object.
 141   /// \~english @param none
 142   /// \~english @retval eFrameworkunifiedStatusOK
 143   /// \~english @retval eFrameworkunifiedStatusInvldParam
 144   /// \~english @retval eFrameworkunifiedStatusFail
 145   /// \~english @retval eFrameworkunifiedStatusErrOther
 146   /// \~english @par Preconditons
 147   ///         none
 148   /// \~english @par Change of internal status
 149   ///       - The internal state is not changed.
 150   /// \~english @par Conditions of processing failure
 151   ///       - Different Lock ID in constructor parameter and mutex object  [eFrameworkunifiedStatusInvldParam]
 152   ///       - If the path at the time of CNSRingBuffer class instantiation is empty [eFrameworkunifiedStatusFail]
 153   ///       - When the CNSRingBuffer class is instantiated with a path longer than 255 characters... [eFrameworkunifiedStatusFail]
 154   ///       - If accessing the information header file (shm_open/ mmap) fails [eFrameworkunifiedStatusFail]
 155   ///       - When accessing the ring buffer file (shm_open/ mmap) fails [eFrameworkunifiedStatusFail]
 156   ///       - Accessing a mutex file (shm_open/ mmap) fails [eFrameworkunifiedStatusFail]
 157   ///       - Alreadey opened [eFrameworkunifiedStatusErrOther]
 158   /// \~english @par Detail
 159   ///       It creates the ring buffer if it does not exists.
 160   ///       Opens the path information header, ring buffer, and mutex set at instance creation.
 161   /// \~english @par
 162   ///       Update ring buffer size for instances created with different sizes on the same path.
 163   /// \~english @par
 164   ///       Execute close() to close.
 165   /// \~english @par Classification
 166   ///       Public
 167   /// \~english @par Type
 168   ///          sync only
 169   /// \~english @see CNSRingBuffer, Close
 170   ////////////////////////////////////////////////////////////////////////////////////////////////
 171   EFrameworkunifiedStatus Open();
 172
 173   ////////////////////////////////////////////////////////////////////////////////////////////////
 174   /// \ingroup CNSRingBuffer
 175   /// \~english @par Brief
 176   ///        This function is used to check whether the ring buffer is opened or not..
 177   /// \~english @param none
 178   /// \~english @retval TRUE - Open
 179   /// \~english @retval FALSE - Not open
 180   /// \~english @par Preconditions
 181   ///       - None.
 182   /// \~english @par Change of the internal state
 183   ///       - Change of internal state according to the API does not occur.
 184   /// \~english @par Conditions of processing failure
 185   ///         none
 186   /// \~english @par Detail
 187   ///       This function is used to check whether the ring buffer is opened or not.
 188   /// \~english @par Classification
 189   ///       Public
 190   /// \~english @par Type
 191   ///          sync only
 192   /// \~english @see CNSRingBuffer, Close
 193   ////////////////////////////////////////////////////////////////////////////////////////////////
 194   BOOL IsOpen();
 195
 196   ////////////////////////////////////////////////////////////////////////////////////////////////
 197   /// \ingroup CNSRingBuffer
 198   /// \~english @par Brief
 199   ///        This function unmaps the ring buffer object.
 200   /// \~english @param none
 201   /// \~english @retval eFrameworkunifiedStatusOK
 202   /// \~english @retval eFrameworkunifiedStatusFail
 203   /// \~english @par Preconditons
 204   ///       - Open has been performed.
 205   /// \~english @par Change of internal status
 206   ///       - The internal state is not changed.
 207   /// \~english @par Conditions of processing failure
 208   ///       - not open [eFrameworkunifiedStatusFail]
 209   ///       - information header file munmap fail [eFrameworkunifiedStatusFail]
 210   ///       - ring buffer file munmap fail [eFrameworkunifiedStatusFail]
 211   ///       - minidesk file munmap fail [eFrameworkunifiedStatusFail]
 212   /// \~english @par Detail
 213   ///       - This function unmaps the ring buffer object.
 214   /// \~english @par
 215   ///       Close processing is also performed when an instance is destructed to prevent leakage.
 216   /// \~english @par Classification
 217   ///       Public
 218   /// \~english @par Type
 219   ///          sync only
 220   /// \~english @see Open
 221   ////////////////////////////////////////////////////////////////////////////////////////////////
 222   EFrameworkunifiedStatus Close();
 223
 224   ////////////////////////////////////////////////////////////////////////////////////////////////
 225   /// \ingroup CNSRingBuffer
 226   /// \~english @par Brief
 227   ///        This function reads data from the ring buffer.
 228   /// \~english @param [OUT] buffer
 229   ///         PSTR - pointer to the buffer in which the read data is stored
 230   /// \~english @param [IN] f_uilength
 231   ///         UI_32 - length of the data buffer provided
 232   /// \~english @retval SI_32 Returns The number of bytes actually read
 233   /// \~english @retval -1 error occurred
 234   /// \~english @par Preconditions
 235   ///       - Open().
 236   /// \~english @par Change of the internal state
 237   ///       - Change of internal state according to the API does not occur.
 238   /// \~english @par Conditions of processing failure
 239   ///       - not open [-1]
 240   /// \~english @par Detail
 241   ///       - This function reads data from the ring buffer.
 242   /// \~english @par Classification
 243   ///       Public
 244   /// \~english @par Type
 245   ///          sync only
 246   /// \~english @see Open
 247   ////////////////////////////////////////////////////////////////////////////////////////////////
 248   SI_32 Read(PSTR buffer, const UI_32 f_uilength);
 249
 250   ////////////////////////////////////////////////////////////////////////////////////////////////
 251   /// \ingroup CNSRingBuffer
 252   /// \~english @par Brief
 253   ///        This function writes the data into the ring buffer.
 254   /// \~english @param [OUT] buffer
 255   ///         PSTR - pointer to the buffer containing the data to be written
 256   /// \~english @param [IN] f_uilength
 257   ///         UI_32 - length of the data buffer to be written
 258   /// \~english @retval SI_32 Returns The number of bytes written
 259   /// \~english @retval -1 error occurred
 260   /// \~english @par Preconditions
 261   ///       - Open().
 262   /// \~english @par Change of the internal state
 263   ///       - Change of internal state according to the API does not occur.
 264   /// \~english @par Conditions of processing failure
 265   ///       - not open [-1]
 266   /// \~english @par Detail
 267   ///       - This function writes the data into the ring buffer.
 268   /// \~english @par Classification
 269   ///       Public
 270   /// \~english @par Type
 271   ///          sync only
 272   /// \~english @see Open
 273   ////////////////////////////////////////////////////////////////////////////////////////////////
 274   SI_32 Write(PCSTR buffer, const UI_32 f_uilength);
 275
 276   ////////////////////////////////////////////////////////////////////////////////////////////////
 277   /// \ingroup CNSRingBuffer
 278   /// \~english @par Brief
 279   ///        This function writes all the data in the buffer into provided file f_pPath.
 280   /// \~english @param[in] f_pPath
 281   ///        PCSTR - file path.
 282   /// \~english @param[in] f_uiDumpSize
 283   ///        PUI_32 - Returns The number of bytes written into file
 284   /// \~english @retval eFrameworkunifiedStatusOK
 285   /// \~english @retval eFrameworkunifiedStatusNullPointer
 286   /// \~english @retval eFrameworkunifiedStatusInvldParam
 287   /// \~english @retval eFrameworkunifiedStatusFail
 288   /// \~english @retval eFrameworkunifiedStatusFileLoadError
 289   /// \~english @retval eFrameworkunifiedStatusErrOther
 290   /// \~english @par Preconditions
 291   ///       - Open().
 292   /// \~english @par Change of the internal state
 293   ///       - Change of internal state according to the API does not occur.
 294   /// \~english @par Conditions of processing failure
 295   ///       - f_uiDumpSize is NULL [eFrameworkunifiedStatusNullPointer]
 296   ///       - dump file path is NULL [eFrameworkunifiedStatusInvldParam]
 297   ///       - not open  [eFrameworkunifiedStatusFail]
 298   ///       - dump file open fail [eFrameworkunifiedStatusFileLoadError]
 299   ///       - ring buffer access fail [eFrameworkunifiedStatusFail]
 300   ///       - dump file write fail [eFrameworkunifiedStatusErrOther]
 301   /// \~english @par Detail
 302   ///       This function does not changes the unread buffer.
 303   /// \~english @par
 304   ///       Please note the following points when using this API for application.
 305   ///       - Writing to a dump file is overwritten.
 306   /// \~english @par
 307   ///       This function overwrites the file if it exists.
 308   /// \~english @par Classification
 309   ///       Public
 310   /// \~english @par Type
 311   ///          sync only
 312   /// \~english @see Open
 313   ////////////////////////////////////////////////////////////////////////////////////////////////
 314   EFrameworkunifiedStatus DumpToFile(PCSTR f_pPath, PUI_32 f_uiDumpSize);
 315
 316   ////////////////////////////////////////////////////////////////////////////////////////////////
 317   /// \ingroup CNSRingBuffer
 318   /// \~english @par Brief
 319   ///        This function returns the number of unread bytes which can be read by Read().
 320   /// \~english @retval SI_32 Returns The number of bytes which can be read by Read()
 321   /// \~english @retval -1 error occurred
 322   /// \~english @par Preconditions
 323   ///       - Open().
 324   /// \~english @par Change of the internal state
 325   ///       - Change of internal state according to the API does not occur.
 326   /// \~english @par Conditions of processing failure
 327   ///       - not open [-1]
 328   /// \~english @par Detail
 329   ///       - This function returns the number of unread bytes which can be read by Read().
 330   /// \~english @par Classification
 331   ///       Public
 332   /// \~english @par Type
 333   ///          sync only
 334   /// \~english @see Open
 335   ////////////////////////////////////////////////////////////////////////////////////////////////
 336   SI_32 GetSize();
 337
 338   ////////////////////////////////////////////////////////////////////////////////////////////////
 339   /// \ingroup CNSRingBuffer
 340   /// \~english @par Brief
 341   ///        This function clears the ring buffer.
 342   /// \~english @param none
 343   /// \~english @retval eFrameworkunifiedStatusOK
 344   /// \~english @retval eFrameworkunifiedStatusFail
 345   /// \~english @par Preconditions
 346   ///       - Open().
 347   /// \~english @par Change of the internal state
 348   ///       - Change of internal state according to the API does not occur.
 349   /// \~english @par Conditions of processing failure
 350   ///       - not open [eFrameworkunifiedStatusFail]
 351   /// \~english @par Detail
 352   ///        This function clears the ring buffer.
 353   /// \~english @par
 354   ///        Please note the following points when using this API for application.
 355   ///        - Only read/write information cleared, and the size of the ring buffer itself is not changed.
 356   /// \~english @par Classification
 357   ///       Public
 358   /// \~english @par Type
 359   ///          sync only
 360   /// \~english @see Open
 361   ////////////////////////////////////////////////////////////////////////////////////////////////
 362   EFrameworkunifiedStatus ClearBuf();
 363
 364   ////////////////////////////////////////////////////////////////////////////////////////////////
 365   /// \ingroup CNSRingBuffer
 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 eFrameworkunifiedStatusOK success
 370   /// \~english @retval eFrameworkunifiedStatusFail ring buffer is not open
 371   /// \~english @par Preconditions
 372   ///       - Open().
 373   /// \~english @par Change of the internal state
 374   ///       - Change of internal state according to the API does not occur.
 375   /// \~english @par Conditions of processing failure
 376   ///       - not open [eFrameworkunifiedStatusFail]
 377   /// \~english @par Detail
 378   ///        This function sets the position of read ptr to write ptr in buffer.
 379   /// \~english @par Classification
 380   ///       Public
 381   /// \~english @par Type
 382   ///          sync only
 383   /// \~english @see Open
 384   ////////////////////////////////////////////////////////////////////////////////////////////////
 385   EFrameworkunifiedStatus SetReadPtrToWritePtr();
 386
 387  private:
 388   ////////////////////////////////////////////////////////////////////////////////////////////////
 389   /// CNSRingBuffer
 390   /// Constructor of CNSRingBuffer class
 391   ///
 392   /// \return     None
 393   ///
 394   ////////////////////////////////////////////////////////////////////////////////////////////////
 395   CNSRingBuffer();
 396
 397   ////////////////////////////////////////////////////////////////////////////////////////////////
 398   /// CreateRBMutex
 399   /// This function creates the ring buffer mutex object.
 400   ///
 401   /// \return EFrameworkunifiedStatus
 402   ///             eFrameworkunifiedStatusOK            ring buffer created successfully
 403   ///             eFrameworkunifiedStatusDuplicate     ring buffer already exists
 404   ///             eFrameworkunifiedStatusInvldParam    invalid ring buffer name
 405   ///             eFrameworkunifiedStatusFail          on error
 406   ///
 407   ////////////////////////////////////////////////////////////////////////////////////////////////
 408   EFrameworkunifiedStatus CreateRBMutex();
 409
 410   ////////////////////////////////////////////////////////////////////////////////////////////////
 411   /// CreateRBHeader
 412   /// This function creates the ring buffer object for header.
 413   ///
 414   /// \return EFrameworkunifiedStatus
 415   ///             eFrameworkunifiedStatusOK            ring buffer created successfully
 416   ///             eFrameworkunifiedStatusDuplicate     ring buffer already exists
 417   ///             eFrameworkunifiedStatusInvldParam    invalid ring buffer name
 418   ///             eFrameworkunifiedStatusFail          on error
 419   ///
 420   ////////////////////////////////////////////////////////////////////////////////////////////////
 421   EFrameworkunifiedStatus CreateRBHeader();
 422
 423   ////////////////////////////////////////////////////////////////////////////////////////////////
 424   /// CreateRBDataBuffer
 425   /// This function creates the ring buffer object for data buffer.
 426   ///
 427   /// \return EFrameworkunifiedStatus
 428   ///             eFrameworkunifiedStatusOK            ring buffer created successfully
 429   ///             eFrameworkunifiedStatusDuplicate     ring buffer already exists
 430   ///             eFrameworkunifiedStatusInvldParam    invalid ring buffer name
 431   ///             eFrameworkunifiedStatusFail          on error
 432   ///
 433   ////////////////////////////////////////////////////////////////////////////////////////////////
 434   EFrameworkunifiedStatus CreateRBDataBuffer();
 435
 436   ////////////////////////////////////////////////////////////////////////////////////////////////
 437   /// MapRBHeader
 438   /// This function open and maps the file in process space.
 439   ///
 440   /// \param  [out] f_pRbuf
 441   ///         PVOID* - address of the mapped memory
 442   /// \param  [in] f_cMappedFile
 443   ///         std::string - Path of the ring buffer mapped file
 444   /// \param  [in] f_uiRbufSize
 445   ///         UI_32 - Size of the ring buffer
 446   ///
 447   /// \return EFrameworkunifiedStatus
 448   ///             eFrameworkunifiedStatusOK if ring buffer opened successfully
 449   ///             eFrameworkunifiedStatusFail unable to open ring buffer
 450   ///
 451   ////////////////////////////////////////////////////////////////////////////////////////////////
 452   EFrameworkunifiedStatus Map(PVOID *f_pRbuf, const std::string &f_cMappedFile, const UI_32 f_uiRbufSize);
 453
 454   ////////////////////////////////////////////////////////////////////////////////////////////////
 455   /// MapRBHeader
 456   /// This function open and maps the shared memory in process space.
 457   ///
 458   /// \param  [out] f_pShMem
 459   ///         PVOID* - address of the mapped memory
 460   /// \param  [in] f_cShmName
 461   ///         std::string - Name of the shared memory
 462   /// \param  [in] f_uiShmSize
 463   ///         UI_32 - Size of the shared memory
 464   ///
 465   /// \return EFrameworkunifiedStatus
 466   ///             eFrameworkunifiedStatusOK if shared memory opened successfully
 467   ///             eFrameworkunifiedStatusFail unable to open shared memory
 468   ///
 469   ////////////////////////////////////////////////////////////////////////////////////////////////
 470   EFrameworkunifiedStatus MapSM(PVOID *f_pShMem, const std::string &f_cShmName, const UI_32 f_uiShmSize);
 471
 472   ////////////////////////////////////////////////////////////////////////////////////////////////
 473   /// UnMapRB
 474   /// This function unmaps the object.
 475   ///
 476   /// \param  [in] f_pRbuf
 477   ///         PCSTR - address of the memory to unmap
 478   /// \param  [in] f_uiRbufSize
 479   ///         UI_32 - Size of the memory to be unmapped
 480   ///
 481   /// \return EFrameworkunifiedStatus
 482   ///             eFrameworkunifiedStatusOK if ring buffer closed successfully
 483   ///             eFrameworkunifiedStatusFail if ring buffer is not open
 484   ///
 485   ////////////////////////////////////////////////////////////////////////////////////////////////
 486   EFrameworkunifiedStatus UnMap(PVOID f_pRbuf, const UI_32 f_uiRbufSize);
 487
 488   EFrameworkunifiedStatus CheckSize(int fd, off_t size);
 489
 490
 491 //  void LockMtx();
 492   int LockMtx();
 493
 494   void UnlockMtx();
 495
 496   std::string m_cRbufMtxName;       // name of the ring buffer mutex name
 497
 498   std::string m_cMappedFileHdrPath;  // path of the ring buffer mapped file header
 499
 500   std::string m_cMappedFilePath;    // path of the ring buffer mapped file
 501
 502   UI_32 m_uiRingBuffSize;           // ring buffer size
 503
 504   NSRingBufferMtx *m_pRbufMtx;      // The pointer to the ring buffer mutex
 505
 506   NSRingBufferHdr *m_pRbufHdr;      // The pointer to the ring buffer header
 507
 508   PCHAR m_pRbuf;                    // The pointer to the ring buffer data buffer
 509
 510   pthread_mutex_t m_tOpenMutex;     // for multithread process
 511
 512   int m_lid;                        // Lock ID
 513   void *m_pLockAddr;                // Lock Address
 514
 515   SI_32 m_siProcessLastWrtPage;     // to hold page that each process wrote in last
 516 };
 517
 518 #endif /* __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_RINGBUFFER_H__ */  // NOLINT  (build/header_guard)
 519 /** @}*/
 520 /** @}*/
 521 /** @}*/
 522 /** @}*/
 523 //@}