2 * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
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
22 ////////////////////////////////////////////////////////////////////////////////////////////////////
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
29 /** @addtogroup BaseSystem
32 /** @addtogroup native_service
36 /** @addtogroup framework_unified
37 * @ingroup native_service
40 /** @addtogroup native
41 * @ingroup framework_unified
44 #ifndef __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_RINGBUFFER_H__ // NOLINT (build/header_guard)
45 #define __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_RINGBUFFER_H__
47 ////////////////////////////////////////////////////////////////////////////////////////////////////
49 ////////////////////////////////////////////////////////////////////////////////////////////////////
52 #include <native_service/frameworkunified_types.h>
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
65 // Structure of the mutex of the ring buffer
66 typedef struct _NSRingBufferMtx {
67 pthread_mutex_t m_tBufMutex; // Mutex object to mutual exclusion
73 * @class CNSRingBuffer
74 * \~english @brief CNSRingBuffer
75 * \~english @par Brief Introduction
76 * Class to provide class of ring buffer.
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
90 /// \~english @retval none
91 /// \~english @par Preconditons
93 /// \~english @par Change of internal status
94 /// - The internal state is not changed.
95 /// \~english @par Conditions of processing failure
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
103 /// \~english @par Type
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);
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
125 /// \~english @par Detail
126 /// Closes the ring buffer, if it is open.
128 /// Closes the ring buffer if it is open.
129 /// \~english @par Classification
131 /// \~english @par Type
133 /// \~english @see CNSRingBuffer
134 ////////////////////////////////////////////////////////////////////////////////////////////////
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
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.
162 /// Update ring buffer size for instances created with different sizes on the same path.
164 /// Execute close() to close.
165 /// \~english @par Classification
167 /// \~english @par Type
169 /// \~english @see CNSRingBuffer, Close
170 ////////////////////////////////////////////////////////////////////////////////////////////////
171 EFrameworkunifiedStatus Open();
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
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
186 /// \~english @par Detail
187 /// This function is used to check whether the ring buffer is opened or not.
188 /// \~english @par Classification
190 /// \~english @par Type
192 /// \~english @see CNSRingBuffer, Close
193 ////////////////////////////////////////////////////////////////////////////////////////////////
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.
215 /// Close processing is also performed when an instance is destructed to prevent leakage.
216 /// \~english @par Classification
218 /// \~english @par Type
220 /// \~english @see Open
221 ////////////////////////////////////////////////////////////////////////////////////////////////
222 EFrameworkunifiedStatus Close();
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
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
240 /// \~english @par Detail
241 /// - This function reads data from the ring buffer.
242 /// \~english @par Classification
244 /// \~english @par Type
246 /// \~english @see Open
247 ////////////////////////////////////////////////////////////////////////////////////////////////
248 SI_32 Read(PSTR buffer, const UI_32 f_uilength);
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
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
266 /// \~english @par Detail
267 /// - This function writes the data into the ring buffer.
268 /// \~english @par Classification
270 /// \~english @par Type
272 /// \~english @see Open
273 ////////////////////////////////////////////////////////////////////////////////////////////////
274 SI_32 Write(PCSTR buffer, const UI_32 f_uilength);
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
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.
304 /// Please note the following points when using this API for application.
305 /// - Writing to a dump file is overwritten.
307 /// This function overwrites the file if it exists.
308 /// \~english @par Classification
310 /// \~english @par Type
312 /// \~english @see Open
313 ////////////////////////////////////////////////////////////////////////////////////////////////
314 EFrameworkunifiedStatus DumpToFile(PCSTR f_pPath, PUI_32 f_uiDumpSize);
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
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
328 /// \~english @par Detail
329 /// - This function returns the number of unread bytes which can be read by Read().
330 /// \~english @par Classification
332 /// \~english @par Type
334 /// \~english @see Open
335 ////////////////////////////////////////////////////////////////////////////////////////////////
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
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.
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
358 /// \~english @par Type
360 /// \~english @see Open
361 ////////////////////////////////////////////////////////////////////////////////////////////////
362 EFrameworkunifiedStatus ClearBuf();
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
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
381 /// \~english @par Type
383 /// \~english @see Open
384 ////////////////////////////////////////////////////////////////////////////////////////////////
385 EFrameworkunifiedStatus SetReadPtrToWritePtr();
388 ////////////////////////////////////////////////////////////////////////////////////////////////
390 /// Constructor of CNSRingBuffer class
394 ////////////////////////////////////////////////////////////////////////////////////////////////
397 ////////////////////////////////////////////////////////////////////////////////////////////////
399 /// This function creates the ring buffer mutex object.
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
407 ////////////////////////////////////////////////////////////////////////////////////////////////
408 EFrameworkunifiedStatus CreateRBMutex();
410 ////////////////////////////////////////////////////////////////////////////////////////////////
412 /// This function creates the ring buffer object for header.
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
420 ////////////////////////////////////////////////////////////////////////////////////////////////
421 EFrameworkunifiedStatus CreateRBHeader();
423 ////////////////////////////////////////////////////////////////////////////////////////////////
424 /// CreateRBDataBuffer
425 /// This function creates the ring buffer object for data buffer.
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
433 ////////////////////////////////////////////////////////////////////////////////////////////////
434 EFrameworkunifiedStatus CreateRBDataBuffer();
436 ////////////////////////////////////////////////////////////////////////////////////////////////
438 /// This function open and maps the file in process space.
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
447 /// \return EFrameworkunifiedStatus
448 /// eFrameworkunifiedStatusOK if ring buffer opened successfully
449 /// eFrameworkunifiedStatusFail unable to open ring buffer
451 ////////////////////////////////////////////////////////////////////////////////////////////////
452 EFrameworkunifiedStatus Map(PVOID *f_pRbuf, const std::string &f_cMappedFile, const UI_32 f_uiRbufSize);
454 ////////////////////////////////////////////////////////////////////////////////////////////////
456 /// This function open and maps the shared memory in process space.
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
465 /// \return EFrameworkunifiedStatus
466 /// eFrameworkunifiedStatusOK if shared memory opened successfully
467 /// eFrameworkunifiedStatusFail unable to open shared memory
469 ////////////////////////////////////////////////////////////////////////////////////////////////
470 EFrameworkunifiedStatus MapSM(PVOID *f_pShMem, const std::string &f_cShmName, const UI_32 f_uiShmSize);
472 ////////////////////////////////////////////////////////////////////////////////////////////////
474 /// This function unmaps the object.
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
481 /// \return EFrameworkunifiedStatus
482 /// eFrameworkunifiedStatusOK if ring buffer closed successfully
483 /// eFrameworkunifiedStatusFail if ring buffer is not open
485 ////////////////////////////////////////////////////////////////////////////////////////////////
486 EFrameworkunifiedStatus UnMap(PVOID f_pRbuf, const UI_32 f_uiRbufSize);
488 EFrameworkunifiedStatus CheckSize(int fd, off_t size);
496 std::string m_cRbufMtxName; // name of the ring buffer mutex name
498 std::string m_cMappedFileHdrPath; // path of the ring buffer mapped file header
500 std::string m_cMappedFilePath; // path of the ring buffer mapped file
502 UI_32 m_uiRingBuffSize; // ring buffer size
504 NSRingBufferMtx *m_pRbufMtx; // The pointer to the ring buffer mutex
506 NSRingBufferHdr *m_pRbufHdr; // The pointer to the ring buffer header
508 PCHAR m_pRbuf; // The pointer to the ring buffer data buffer
510 pthread_mutex_t m_tOpenMutex; // for multithread process
512 int m_lid; // Lock ID
513 void *m_pLockAddr; // Lock Address
515 SI_32 m_siProcessLastWrtPage; // to hold page that each process wrote in last
518 #endif /* __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_RINGBUFFER_H__ */ // NOLINT (build/header_guard)