Merge branch 'linus' into irq/threaded
[linux-2.6] / drivers / staging / epl / SharedBuff.c
1 /****************************************************************************
2
3   (c) SYSTEC electronic GmbH, D-07973 Greiz, August-Bebel-Str. 29
4       www.systec-electronic.com
5
6   Project:      Project independend shared buffer (linear + circular)
7
8   Description:  Implementation of platform independend part for the
9                 shared buffer
10
11   License:
12
13     Redistribution and use in source and binary forms, with or without
14     modification, are permitted provided that the following conditions
15     are met:
16
17     1. Redistributions of source code must retain the above copyright
18        notice, this list of conditions and the following disclaimer.
19
20     2. Redistributions in binary form must reproduce the above copyright
21        notice, this list of conditions and the following disclaimer in the
22        documentation and/or other materials provided with the distribution.
23
24     3. Neither the name of SYSTEC electronic GmbH nor the names of its
25        contributors may be used to endorse or promote products derived
26        from this software without prior written permission. For written
27        permission, please contact info@systec-electronic.com.
28
29     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
30     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
31     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
32     FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
33     COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
34     INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
35     BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
36     LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
37     CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
38     LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
39     ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
40     POSSIBILITY OF SUCH DAMAGE.
41
42     Severability Clause:
43
44         If a provision of this License is or becomes illegal, invalid or
45         unenforceable in any jurisdiction, that shall not affect:
46         1. the validity or enforceability in that jurisdiction of any other
47            provision of this License; or
48         2. the validity or enforceability in other jurisdictions of that or
49            any other provision of this License.
50
51   -------------------------------------------------------------------------
52
53   2006/06/27 -rs:   V 1.00 (initial version)
54
55 ****************************************************************************/
56
57 #if defined(WIN32) || defined(_WIN32)
58
59 #ifdef UNDER_RTSS
60         // RTX header
61 #include <windows.h>
62 #include <process.h>
63 #include <rtapi.h>
64
65 #elif __BORLANDC__
66         // borland C header
67 #include <windows.h>
68 #include <process.h>
69
70 #elif WINCE
71 #include <windows.h>
72
73 #else
74         // MSVC needs to include windows.h at first
75         // the following defines ar necessary for function prototypes for waitable timers
76 #define _WIN32_WINDOWS 0x0401
77 #define _WIN32_WINNT   0x0400
78 #include <windows.h>
79 #include <process.h>
80 #endif
81
82 #endif
83
84 #include "global.h"
85 #include "SharedBuff.h"
86 #include "ShbIpc.h"
87
88 #include <linux/string.h>
89 #include <linux/kernel.h>
90
91 /***************************************************************************/
92 /*                                                                         */
93 /*                                                                         */
94 /*          G L O B A L   D E F I N I T I O N S                            */
95 /*                                                                         */
96 /*                                                                         */
97 /***************************************************************************/
98
99 //---------------------------------------------------------------------------
100 //  Configuration
101 //---------------------------------------------------------------------------
102
103 //---------------------------------------------------------------------------
104 //  Constant definitions
105 //---------------------------------------------------------------------------
106
107 #define SBC_MAGIC_ID    0x53424323      // magic ID ("SBC#")
108 #define SBL_MAGIC_ID    0x53424C23      // magic ID ("SBL#")
109
110 //---------------------------------------------------------------------------
111 //  Local types
112 //---------------------------------------------------------------------------
113
114 // structure to administrate circular shared buffer head
115 typedef struct {
116         unsigned long m_ShbCirMagicID;  // magic ID ("SBC#")
117         unsigned long m_ulBufferTotalSize;      // over-all size of complete buffer
118         unsigned long m_ulBufferDataSize;       // size of complete data area
119         unsigned long m_ulWrIndex;      // current write index (set bevore write)
120         unsigned long m_ulRdIndex;      // current read index (set after read)
121         unsigned long m_ulNumOfWriteJobs;       // number of currently (parallel running) write operations
122         unsigned long m_ulDataInUse;    // currently used buffer size (incl. uncompleted write operations)
123         unsigned long m_ulDataApended;  // buffer size of complete new written but not yet readable data (in case of m_ulNumOfWriteJobs>1)
124         unsigned long m_ulBlocksApended;        // number of complete new written but not yet readable data blocks (in case of m_ulNumOfWriteJobs>1)
125         unsigned long m_ulDataReadable; // buffer size with readable (complete written) data
126         unsigned long m_ulBlocksReadable;       // number of readable (complete written) data blocks
127         tShbCirSigHndlrNewData m_pfnSigHndlrNewData;    // application handler to signal new data
128         unsigned int m_fBufferLocked;   // TRUE if buffer is locked (because of pending reset request)
129         tShbCirSigHndlrReset m_pfnSigHndlrReset;        // application handler to signal buffer reset is done
130         unsigned char m_Data;   // start of data area (the real data size is unknown at this time)
131
132 } tShbCirBuff;
133
134 // structure to administrate linear shared buffer head
135 typedef struct {
136         unsigned int m_ShbLinMagicID;   // magic ID ("SBL#")
137         unsigned long m_ulBufferTotalSize;      // over-all size of complete buffer
138         unsigned long m_ulBufferDataSize;       // size of complete data area
139         unsigned char m_Data;   // start of data area (the real data size is unknown at this time)
140
141 } tShbLinBuff;
142
143 // type to save size of a single data block inside the circular shared buffer
144 typedef struct {
145         unsigned int m_uiFullBlockSize:28;      // a single block must not exceed a length of 256MByte :-)
146         unsigned int m_uiAlignFillBytes:4;
147
148 } tShbCirBlockSize;
149
150 #define SBC_BLOCK_ALIGNMENT                  4  // alignment must *not* be lower than sizeof(tShbCirBlockSize)!
151 #define SBC_MAX_BLOCK_SIZE         ((1<<28)-1)  // = (2^28 - 1) = (256MByte - 1) -> should be enought for real life :-)
152
153 #define SBL_BLOCK_ALIGNMENT                  4
154 #define SBL_MAX_BLOCK_SIZE         ((1<<28)-1)  // = (2^28 - 1) = (256MByte - 1) -> should be enought for real life :-)
155
156 //---------------------------------------------------------------------------
157 //  Global variables
158 //---------------------------------------------------------------------------
159
160 //---------------------------------------------------------------------------
161 //  Local variables
162 //---------------------------------------------------------------------------
163
164 //---------------------------------------------------------------------------
165 //  Prototypes of internal functions
166 //---------------------------------------------------------------------------
167
168 //---------------------------------------------------------------------------
169 //  Get pointer to Circular Shared Buffer
170 //---------------------------------------------------------------------------
171
172 tShbCirBuff *ShbCirGetBuffer(tShbInstance pShbInstance_p)
173 {
174
175         tShbCirBuff *pShbCirBuff;
176
177         pShbCirBuff = (tShbCirBuff *) ShbIpcGetShMemPtr(pShbInstance_p);
178         ASSERT(pShbCirBuff->m_ShbCirMagicID == SBC_MAGIC_ID);
179
180         return (pShbCirBuff);
181
182 }
183
184 //---------------------------------------------------------------------------
185 //  Get pointer to Linear Shared Buffer
186 //---------------------------------------------------------------------------
187
188 tShbLinBuff *ShbLinGetBuffer(tShbInstance pShbInstance_p)
189 {
190
191         tShbLinBuff *pShbLinBuff;
192
193         pShbLinBuff = (tShbLinBuff *) ShbIpcGetShMemPtr(pShbInstance_p);
194         ASSERT(pShbLinBuff->m_ShbLinMagicID == SBL_MAGIC_ID);
195
196         return (pShbLinBuff);
197
198 }
199
200 // not inlined internal functions
201 int ShbCirSignalHandlerNewData(tShbInstance pShbInstance_p);
202 void ShbCirSignalHandlerReset(tShbInstance pShbInstance_p,
203                               unsigned int fTimeOut_p);
204
205
206 //=========================================================================//
207 //                                                                         //
208 //          P U B L I C   F U N C T I O N S                                //
209 //                                                                         //
210 //=========================================================================//
211
212 // not inlined external functions
213
214 //---------------------------------------------------------------------------
215 //  Initialize Shared Buffer Module
216 //---------------------------------------------------------------------------
217
218 tShbError ShbInit(void)
219 {
220
221         tShbError ShbError;
222
223         ShbError = ShbIpcInit();
224
225         return (ShbError);
226
227 }
228
229 //---------------------------------------------------------------------------
230 //  Deinitialize Shared Buffer Module
231 //---------------------------------------------------------------------------
232
233 tShbError ShbExit(void)
234 {
235
236         tShbError ShbError;
237
238         ShbError = ShbIpcExit();
239
240         return (ShbError);
241
242 }
243
244 //-------------------------------------------------------------------------//
245 //                                                                         //
246 //          C i r c u l a r   S h a r e d   B u f f e r                    //
247 //                                                                         //
248 //-------------------------------------------------------------------------//
249
250 //---------------------------------------------------------------------------
251 //  Allocate Circular Shared Buffer
252 //---------------------------------------------------------------------------
253
254 tShbError ShbCirAllocBuffer(unsigned long ulBufferSize_p,
255                             const char *pszBufferID_p,
256                             tShbInstance * ppShbInstance_p,
257                             unsigned int *pfShbNewCreated_p)
258 {
259
260         tShbInstance pShbInstance;
261         tShbCirBuff *pShbCirBuff;
262         unsigned int fShbNewCreated;
263         unsigned long ulBufferDataSize;
264         unsigned long ulBufferTotalSize;
265         tShbError ShbError;
266
267         // check arguments
268         if ((ulBufferSize_p == 0) || (ppShbInstance_p == NULL)) {
269                 return (kShbInvalidArg);
270         }
271
272         // calculate length of memory to allocate
273         ulBufferDataSize =
274             (ulBufferSize_p +
275              (SBC_BLOCK_ALIGNMENT - 1)) & ~(SBC_BLOCK_ALIGNMENT - 1);
276         ulBufferTotalSize = ulBufferDataSize + sizeof(tShbCirBuff);
277
278         // allocate a new or open an existing shared buffer
279         ShbError = ShbIpcAllocBuffer(ulBufferTotalSize, pszBufferID_p,
280                                      &pShbInstance, &fShbNewCreated);
281         if (ShbError != kShbOk) {
282                 goto Exit;
283         }
284
285         if (pShbInstance == NULL) {
286                 ShbError = kShbOutOfMem;
287                 goto Exit;
288         }
289
290         // get pointer to shared buffer
291         pShbCirBuff = (tShbCirBuff *) ShbIpcGetShMemPtr(pShbInstance);
292
293         // if the shared buffer was new created, than this process has
294         // to initialize it, otherwise the buffer is already in use
295         // and *must not* be reseted
296         if (fShbNewCreated) {
297 #ifndef NDEBUG
298                 {
299                         memset(pShbCirBuff, 0xCC, ulBufferTotalSize);
300                 }
301 #endif
302
303                 pShbCirBuff->m_ShbCirMagicID = SBC_MAGIC_ID;
304                 pShbCirBuff->m_ulBufferTotalSize = ulBufferTotalSize;
305                 pShbCirBuff->m_ulBufferDataSize = ulBufferDataSize;
306                 pShbCirBuff->m_ulWrIndex = 0;
307                 pShbCirBuff->m_ulRdIndex = 0;
308                 pShbCirBuff->m_ulNumOfWriteJobs = 0;
309                 pShbCirBuff->m_ulDataInUse = 0;
310                 pShbCirBuff->m_ulDataApended = 0;
311                 pShbCirBuff->m_ulBlocksApended = 0;
312                 pShbCirBuff->m_ulDataReadable = 0;
313                 pShbCirBuff->m_ulBlocksReadable = 0;
314                 pShbCirBuff->m_pfnSigHndlrNewData = NULL;
315                 pShbCirBuff->m_fBufferLocked = FALSE;
316                 pShbCirBuff->m_pfnSigHndlrReset = NULL;
317         } else {
318                 if (pShbCirBuff->m_ShbCirMagicID != SBC_MAGIC_ID) {
319                         ShbError = kShbInvalidBufferType;
320                         goto Exit;
321                 }
322         }
323
324       Exit:
325
326         *ppShbInstance_p = pShbInstance;
327         *pfShbNewCreated_p = fShbNewCreated;
328
329         return (ShbError);
330
331 }
332
333 //---------------------------------------------------------------------------
334 //  Release Circular Shared Buffer
335 //---------------------------------------------------------------------------
336
337 tShbError ShbCirReleaseBuffer(tShbInstance pShbInstance_p)
338 {
339
340         tShbError ShbError;
341
342         // check arguments
343         if (pShbInstance_p == NULL) {
344                 ShbError = kShbOk;
345                 goto Exit;
346         }
347
348         ShbError = ShbIpcReleaseBuffer(pShbInstance_p);
349
350       Exit:
351
352         return (ShbError);
353
354 }
355
356 //---------------------------------------------------------------------------
357 //  Reset Circular Shared Buffer
358 //---------------------------------------------------------------------------
359
360 tShbError ShbCirResetBuffer(tShbInstance pShbInstance_p,
361                             unsigned long ulTimeOut_p,
362                             tShbCirSigHndlrReset pfnSignalHandlerReset_p)
363 {
364
365         tShbCirBuff *pShbCirBuff;
366         unsigned long ulNumOfWriteJobs = 0;     // d.k. GCC complains about uninitialized variable otherwise
367         tShbError ShbError;
368
369         // check arguments
370         if (pShbInstance_p == NULL) {
371                 ShbError = kShbInvalidArg;
372                 goto Exit;
373         }
374
375         pShbCirBuff = ShbCirGetBuffer(pShbInstance_p);
376         ShbError = kShbOk;
377
378         if (pShbCirBuff->m_ShbCirMagicID != SBC_MAGIC_ID) {
379                 ShbError = kShbInvalidBufferType;
380                 goto Exit;
381         }
382
383         // start reset job by setting request request in buffer header
384         ShbIpcEnterAtomicSection(pShbInstance_p);
385         {
386                 if (!pShbCirBuff->m_fBufferLocked) {
387                         ulNumOfWriteJobs = pShbCirBuff->m_ulNumOfWriteJobs;
388
389                         pShbCirBuff->m_fBufferLocked = TRUE;
390                         pShbCirBuff->m_pfnSigHndlrReset =
391                             pfnSignalHandlerReset_p;
392                 } else {
393                         ShbError = kShbAlreadyReseting;
394                 }
395         }
396         ShbIpcLeaveAtomicSection(pShbInstance_p);
397
398         if (ShbError != kShbOk) {
399                 goto Exit;
400         }
401
402         // if there is currently no running write operation then reset buffer
403         // immediately, otherwise wait until the last write job is ready by
404         // starting a signal process
405         if (ulNumOfWriteJobs == 0) {
406                 // there is currently no running write operation
407                 // -> reset buffer immediately
408                 ShbCirSignalHandlerReset(pShbInstance_p, FALSE);
409                 ShbError = kShbOk;
410         } else {
411                 // there is currently at least one running write operation
412                 // -> starting signal process to wait until the last write job is ready
413                 ShbError =
414                     ShbIpcStartSignalingJobReady(pShbInstance_p, ulTimeOut_p,
415                                                  ShbCirSignalHandlerReset);
416         }
417
418       Exit:
419
420         return (ShbError);
421
422 }
423
424 //---------------------------------------------------------------------------
425 //  Write data block to Circular Shared Buffer
426 //---------------------------------------------------------------------------
427
428 tShbError ShbCirWriteDataBlock(tShbInstance pShbInstance_p,
429                                const void *pSrcDataBlock_p,
430                                unsigned long ulDataBlockSize_p)
431 {
432
433         tShbCirBuff *pShbCirBuff;
434         tShbCirBlockSize ShbCirBlockSize;
435         unsigned int uiFullBlockSize;
436         unsigned int uiAlignFillBytes;
437         unsigned char *pShbCirDataPtr;
438         unsigned char *pScrDataPtr;
439         unsigned long ulDataSize;
440         unsigned long ulChunkSize;
441         unsigned long ulWrIndex = 0;    // d.k. GCC complains about uninitialized variable otherwise
442         unsigned int fSignalNewData;
443         unsigned int fSignalReset;
444         tShbError ShbError;
445         tShbError ShbError2;
446         int fRes;
447
448         // check arguments
449         if (pShbInstance_p == NULL) {
450                 ShbError = kShbInvalidArg;
451                 goto Exit;
452         }
453
454         if ((pSrcDataBlock_p == NULL) || (ulDataBlockSize_p == 0)) {
455                 // nothing to do here
456                 ShbError = kShbOk;
457                 goto Exit;
458         }
459
460         if (ulDataBlockSize_p > SBC_MAX_BLOCK_SIZE) {
461                 ShbError = kShbExceedDataSizeLimit;
462                 goto Exit;
463         }
464
465         pShbCirBuff = ShbCirGetBuffer(pShbInstance_p);
466         pScrDataPtr = (unsigned char *)pSrcDataBlock_p;
467         fSignalNewData = FALSE;
468         fSignalReset = FALSE;
469         ShbError = kShbOk;
470
471         if (pShbCirBuff->m_ShbCirMagicID != SBC_MAGIC_ID) {
472                 ShbError = kShbInvalidBufferType;
473                 goto Exit;
474         }
475
476         // calculate data block size in circular buffer
477         ulDataSize =
478             (ulDataBlockSize_p +
479              (SBC_BLOCK_ALIGNMENT - 1)) & ~(SBC_BLOCK_ALIGNMENT - 1);
480         uiFullBlockSize = ulDataSize + sizeof(tShbCirBlockSize);        // data size + header
481         uiAlignFillBytes = ulDataSize - ulDataBlockSize_p;
482
483         ShbCirBlockSize.m_uiFullBlockSize = uiFullBlockSize;
484         ShbCirBlockSize.m_uiAlignFillBytes = uiAlignFillBytes;
485
486         // reserve the needed memory for the write operation to do now
487         // and make necessary adjustments in the circular buffer header
488         ShbIpcEnterAtomicSection(pShbInstance_p);
489         {
490                 // check if there is sufficient memory available to store
491                 // the new data
492                 fRes =
493                     uiFullBlockSize <=
494                     (pShbCirBuff->m_ulBufferDataSize -
495                      pShbCirBuff->m_ulDataInUse);
496                 if (fRes) {
497                         // set write pointer for the write operation to do now
498                         // to the current write pointer of the circular buffer
499                         ulWrIndex = pShbCirBuff->m_ulWrIndex;
500
501                         // reserve the needed memory for the write operation to do now
502                         pShbCirBuff->m_ulDataInUse += uiFullBlockSize;
503
504                         // set new write pointer behind the reserved memory
505                         // for the write operation to do now
506                         pShbCirBuff->m_ulWrIndex += uiFullBlockSize;
507                         pShbCirBuff->m_ulWrIndex %=
508                             pShbCirBuff->m_ulBufferDataSize;
509
510                         // increment number of currently (parallel running)
511                         // write operations
512                         pShbCirBuff->m_ulNumOfWriteJobs++;
513                 }
514         }
515         ShbIpcLeaveAtomicSection(pShbInstance_p);
516
517         if (!fRes) {
518                 ShbError = kShbBufferFull;
519                 goto Exit;
520         }
521
522         // copy the data to the circular buffer
523         // (the copy process itself will be done outside of any
524         // critical/locked section)
525         pShbCirDataPtr = &pShbCirBuff->m_Data;  // ptr to start of data area
526
527         // write real size of current block (incl. alignment fill bytes)
528         *(tShbCirBlockSize *) (pShbCirDataPtr + ulWrIndex) = ShbCirBlockSize;
529         ulWrIndex += sizeof(tShbCirBlockSize);
530         ulWrIndex %= pShbCirBuff->m_ulBufferDataSize;
531
532         if (ulWrIndex + ulDataBlockSize_p <= pShbCirBuff->m_ulBufferDataSize) {
533                 // linear write operation
534                 memcpy(pShbCirDataPtr + ulWrIndex, pScrDataPtr,
535                        ulDataBlockSize_p);
536         } else {
537                 // wrap-around write operation
538                 ulChunkSize = pShbCirBuff->m_ulBufferDataSize - ulWrIndex;
539                 memcpy(pShbCirDataPtr + ulWrIndex, pScrDataPtr, ulChunkSize);
540                 memcpy(pShbCirDataPtr, pScrDataPtr + ulChunkSize,
541                        ulDataBlockSize_p - ulChunkSize);
542         }
543
544         // adjust header information for circular buffer with properties
545         // of the wiritten data block
546         ShbIpcEnterAtomicSection(pShbInstance_p);
547         {
548                 pShbCirBuff->m_ulDataApended += uiFullBlockSize;
549                 pShbCirBuff->m_ulBlocksApended++;
550
551                 // decrement number of currently (parallel running) write operations
552                 if (!--pShbCirBuff->m_ulNumOfWriteJobs) {
553                         // if there is no other write process running then
554                         // set new size of readable (complete written) data and
555                         // adjust number of readable blocks
556                         pShbCirBuff->m_ulDataReadable +=
557                             pShbCirBuff->m_ulDataApended;
558                         pShbCirBuff->m_ulBlocksReadable +=
559                             pShbCirBuff->m_ulBlocksApended;
560
561                         pShbCirBuff->m_ulDataApended = 0;
562                         pShbCirBuff->m_ulBlocksApended = 0;
563
564                         fSignalNewData = TRUE;
565                         fSignalReset = pShbCirBuff->m_fBufferLocked;
566                 }
567         }
568         ShbIpcLeaveAtomicSection(pShbInstance_p);
569
570         // signal new data event to a potentially reading application
571         if (fSignalNewData) {
572                 ShbError2 = ShbIpcSignalNewData(pShbInstance_p);
573                 if (ShbError == kShbOk) {
574                         ShbError = ShbError2;
575                 }
576         }
577         // signal that the last write job has been finished to allow
578         // a waiting application to reset the buffer now
579         if (fSignalReset) {
580                 ShbError2 = ShbIpcSignalJobReady(pShbInstance_p);
581                 if (ShbError == kShbOk) {
582                         ShbError = ShbError2;
583                 }
584         }
585
586       Exit:
587
588         return (ShbError);
589
590 }
591
592 //---------------------------------------------------------------------------
593 //  Allocate block within the Circular Shared Buffer for chunk writing
594 //---------------------------------------------------------------------------
595
596 tShbError ShbCirAllocDataBlock(tShbInstance pShbInstance_p,
597                                tShbCirChunk * pShbCirChunk_p,
598                                unsigned long ulDataBufferSize_p)
599 {
600
601         tShbCirBuff *pShbCirBuff;
602         tShbCirBlockSize ShbCirBlockSize;
603         unsigned int uiFullBlockSize;
604         unsigned int uiAlignFillBytes;
605         unsigned char *pShbCirDataPtr;
606         unsigned long ulDataSize;
607         unsigned long ulWrIndex = 0;    // d.k. GCC complains about uninitialized variable otherwise
608         tShbError ShbError;
609         int fRes;
610
611         // check arguments
612         if ((pShbInstance_p == NULL) || (pShbCirChunk_p == NULL)) {
613                 ShbError = kShbInvalidArg;
614                 goto Exit;
615         }
616
617         if (ulDataBufferSize_p == 0) {
618                 ShbError = kShbInvalidArg;
619                 goto Exit;
620         }
621
622         if (ulDataBufferSize_p > SBC_MAX_BLOCK_SIZE) {
623                 ShbError = kShbExceedDataSizeLimit;
624                 goto Exit;
625         }
626
627         pShbCirBuff = ShbCirGetBuffer(pShbInstance_p);
628         ShbError = kShbOk;
629
630         if (pShbCirBuff->m_ShbCirMagicID != SBC_MAGIC_ID) {
631                 ShbError = kShbInvalidBufferType;
632                 goto Exit;
633         }
634
635         // calculate data block size in circular buffer
636         ulDataSize =
637             (ulDataBufferSize_p +
638              (SBC_BLOCK_ALIGNMENT - 1)) & ~(SBC_BLOCK_ALIGNMENT - 1);
639         uiFullBlockSize = ulDataSize + sizeof(tShbCirBlockSize);        // data size + header
640         uiAlignFillBytes = ulDataSize - ulDataBufferSize_p;
641
642         ShbCirBlockSize.m_uiFullBlockSize = uiFullBlockSize;
643         ShbCirBlockSize.m_uiAlignFillBytes = uiAlignFillBytes;
644
645         // reserve the needed memory for the write operation to do now
646         // and make necessary adjustments in the circular buffer header
647         ShbIpcEnterAtomicSection(pShbInstance_p);
648         {
649                 // check if there is sufficient memory available to store
650                 // the new data
651                 fRes =
652                     (uiFullBlockSize <=
653                      (pShbCirBuff->m_ulBufferDataSize -
654                       pShbCirBuff->m_ulDataInUse));
655                 if (fRes) {
656                         // set write pointer for the write operation to do now
657                         // to the current write pointer of the circular buffer
658                         ulWrIndex = pShbCirBuff->m_ulWrIndex;
659
660                         // reserve the needed memory for the write operation to do now
661                         pShbCirBuff->m_ulDataInUse += uiFullBlockSize;
662
663                         // set new write pointer behind the reserved memory
664                         // for the write operation to do now
665                         pShbCirBuff->m_ulWrIndex += uiFullBlockSize;
666                         pShbCirBuff->m_ulWrIndex %=
667                             pShbCirBuff->m_ulBufferDataSize;
668
669                         // increment number of currently (parallel running)
670                         // write operations
671                         pShbCirBuff->m_ulNumOfWriteJobs++;
672                 }
673         }
674         ShbIpcLeaveAtomicSection(pShbInstance_p);
675
676         if (!fRes) {
677                 ShbError = kShbBufferFull;
678                 goto Exit;
679         }
680
681         // setup header information for allocated buffer
682         pShbCirDataPtr = &pShbCirBuff->m_Data;  // ptr to start of data area
683
684         // write real size of current block (incl. alignment fill bytes)
685         *(tShbCirBlockSize *) (pShbCirDataPtr + ulWrIndex) = ShbCirBlockSize;
686         ulWrIndex += sizeof(tShbCirBlockSize);
687         ulWrIndex %= pShbCirBuff->m_ulBufferDataSize;
688
689         // setup chunk descriptor
690         pShbCirChunk_p->m_uiFullBlockSize = uiFullBlockSize;
691         pShbCirChunk_p->m_ulAvailableSize = ulDataBufferSize_p;
692         pShbCirChunk_p->m_ulWrIndex = ulWrIndex;
693         pShbCirChunk_p->m_fBufferCompleted = FALSE;
694
695       Exit:
696
697         return (ShbError);
698
699 }
700
701 //---------------------------------------------------------------------------
702 //  Write data chunk into an allocated buffer of the Circular Shared Buffer
703 //---------------------------------------------------------------------------
704
705 tShbError ShbCirWriteDataChunk(tShbInstance pShbInstance_p,
706                                tShbCirChunk *pShbCirChunk_p,
707                                const void *pSrcDataChunk_p,
708                                unsigned long ulDataChunkSize_p,
709                                unsigned int *pfBufferCompleted_p)
710 {
711
712         tShbCirBuff *pShbCirBuff;
713         unsigned char *pShbCirDataPtr;
714         unsigned char *pScrDataPtr;
715         unsigned long ulSubChunkSize;
716         unsigned long ulWrIndex;
717         unsigned int fBufferCompleted;
718         unsigned int fSignalNewData;
719         unsigned int fSignalReset;
720         tShbError ShbError;
721         tShbError ShbError2;
722
723         // check arguments
724         if ((pShbInstance_p == NULL) || (pShbCirChunk_p == NULL)
725             || (pfBufferCompleted_p == NULL)) {
726                 ShbError = kShbInvalidArg;
727                 goto Exit;
728         }
729
730         if ((pSrcDataChunk_p == NULL) || (ulDataChunkSize_p == 0)) {
731                 // nothing to do here
732                 ShbError = kShbOk;
733                 goto Exit;
734         }
735
736         if (pShbCirChunk_p->m_fBufferCompleted) {
737                 ShbError = kShbBufferAlreadyCompleted;
738                 goto Exit;
739         }
740
741         if (ulDataChunkSize_p > pShbCirChunk_p->m_ulAvailableSize) {
742                 ShbError = kShbExceedDataSizeLimit;
743                 goto Exit;
744         }
745
746         pShbCirBuff = ShbCirGetBuffer(pShbInstance_p);
747         pScrDataPtr = (unsigned char *)pSrcDataChunk_p;
748         fSignalNewData = FALSE;
749         fSignalReset = FALSE;
750         ShbError = kShbOk;
751
752         if (pShbCirBuff->m_ShbCirMagicID != SBC_MAGIC_ID) {
753                 ShbError = kShbInvalidBufferType;
754                 goto Exit;
755         }
756
757         ulWrIndex = pShbCirChunk_p->m_ulWrIndex;
758
759         // copy the data to the circular buffer
760         // (the copy process itself will be done outside of any
761         // critical/locked section)
762         pShbCirDataPtr = &pShbCirBuff->m_Data;  // ptr to start of data area
763
764         if (ulWrIndex + ulDataChunkSize_p <= pShbCirBuff->m_ulBufferDataSize) {
765                 // linear write operation
766                 memcpy(pShbCirDataPtr + ulWrIndex, pScrDataPtr,
767                        ulDataChunkSize_p);
768         } else {
769                 // wrap-around write operation
770                 ulSubChunkSize = pShbCirBuff->m_ulBufferDataSize - ulWrIndex;
771                 memcpy(pShbCirDataPtr + ulWrIndex, pScrDataPtr, ulSubChunkSize);
772                 memcpy(pShbCirDataPtr, pScrDataPtr + ulSubChunkSize,
773                        ulDataChunkSize_p - ulSubChunkSize);
774         }
775
776         // adjust chunk descriptor
777         ulWrIndex += ulDataChunkSize_p;
778         ulWrIndex %= pShbCirBuff->m_ulBufferDataSize;
779
780         pShbCirChunk_p->m_ulAvailableSize -= ulDataChunkSize_p;
781         pShbCirChunk_p->m_ulWrIndex = ulWrIndex;
782
783         fBufferCompleted = (pShbCirChunk_p->m_ulAvailableSize == 0);
784         pShbCirChunk_p->m_fBufferCompleted = fBufferCompleted;
785
786         // if the complete allocated buffer is filled with data then
787         // adjust header information for circular buffer with properties
788         // of the wiritten data block
789         if (fBufferCompleted) {
790                 ShbIpcEnterAtomicSection(pShbInstance_p);
791                 {
792                         pShbCirBuff->m_ulDataApended +=
793                             pShbCirChunk_p->m_uiFullBlockSize;
794                         pShbCirBuff->m_ulBlocksApended++;
795
796                         // decrement number of currently (parallel running) write operations
797                         if (!--pShbCirBuff->m_ulNumOfWriteJobs) {
798                                 // if there is no other write process running then
799                                 // set new size of readable (complete written) data and
800                                 // adjust number of readable blocks
801                                 pShbCirBuff->m_ulDataReadable +=
802                                     pShbCirBuff->m_ulDataApended;
803                                 pShbCirBuff->m_ulBlocksReadable +=
804                                     pShbCirBuff->m_ulBlocksApended;
805
806                                 pShbCirBuff->m_ulDataApended = 0;
807                                 pShbCirBuff->m_ulBlocksApended = 0;
808
809                                 fSignalNewData = TRUE;
810                                 fSignalReset = pShbCirBuff->m_fBufferLocked;
811                         }
812                 }
813                 ShbIpcLeaveAtomicSection(pShbInstance_p);
814         }
815
816         // signal new data event to a potentially reading application
817         if (fSignalNewData) {
818                 ShbError2 = ShbIpcSignalNewData(pShbInstance_p);
819                 if (ShbError == kShbOk) {
820                         ShbError = ShbError2;
821                 }
822         }
823         // signal that the last write job has been finished to allow
824         // a waiting application to reset the buffer now
825         if (fSignalReset) {
826                 ShbError2 = ShbIpcSignalJobReady(pShbInstance_p);
827                 if (ShbError == kShbOk) {
828                         ShbError = ShbError2;
829                 }
830         }
831
832         *pfBufferCompleted_p = fBufferCompleted;
833
834       Exit:
835
836         return (ShbError);
837
838 }
839
840 //---------------------------------------------------------------------------
841 //  Read data block from Circular Shared Buffer
842 //---------------------------------------------------------------------------
843
844 tShbError ShbCirReadDataBlock(tShbInstance pShbInstance_p,
845                               void *pDstDataBlock_p,
846                               unsigned long ulRdBuffSize_p,
847                               unsigned long *pulDataBlockSize_p)
848 {
849
850         tShbCirBuff *pShbCirBuff;
851         tShbCirBlockSize ShbCirBlockSize;
852         unsigned long ulDataReadable;
853         unsigned char *pShbCirDataPtr;
854         unsigned char *pDstDataPtr;
855         unsigned long ulDataSize = 0;   // d.k. GCC complains about uninitialized variable otherwise
856         unsigned long ulChunkSize;
857         unsigned long ulRdIndex;
858         tShbError ShbError;
859
860         // check arguments
861         if ((pShbInstance_p == NULL) || (pulDataBlockSize_p == NULL)) {
862                 return (kShbInvalidArg);
863         }
864
865         if ((pDstDataBlock_p == NULL) || (ulRdBuffSize_p == 0)) {
866                 // nothing to do here
867                 ShbError = kShbOk;
868                 goto Exit;
869         }
870
871         ShbError = kShbOk;
872         pShbCirBuff = ShbCirGetBuffer(pShbInstance_p);
873         pDstDataPtr = (unsigned char *)pDstDataBlock_p;
874         ulDataSize = 0;
875
876         if (pShbCirBuff->m_ShbCirMagicID != SBC_MAGIC_ID) {
877                 ShbError = kShbInvalidBufferType;
878                 goto Exit;
879         }
880
881         // get total number of readable bytes for the whole circular buffer
882         ShbIpcEnterAtomicSection(pShbInstance_p);
883         {
884                 ulDataReadable = pShbCirBuff->m_ulDataReadable;
885         }
886         ShbIpcLeaveAtomicSection(pShbInstance_p);
887
888         // if there are readable data available, then there must be at least
889         // one complete readable data block
890         if (ulDataReadable > 0) {
891                 // get pointer to start of data area and current read index
892                 pShbCirDataPtr = &pShbCirBuff->m_Data;  // ptr to start of data area
893                 ulRdIndex = pShbCirBuff->m_ulRdIndex;
894
895                 // get real size of current block (incl. alignment fill bytes)
896                 ShbCirBlockSize =
897                     *(tShbCirBlockSize *) (pShbCirDataPtr + ulRdIndex);
898                 ulRdIndex += sizeof(tShbCirBlockSize);
899                 ulRdIndex %= pShbCirBuff->m_ulBufferDataSize;
900
901                 // get size of user data inside the current block
902                 ulDataSize =
903                     ShbCirBlockSize.m_uiFullBlockSize -
904                     ShbCirBlockSize.m_uiAlignFillBytes;
905                 ulDataSize -= sizeof(tShbCirBlockSize);
906         }
907
908         // ulDataSize = MIN(ulDataSize, ulRdBuffSize_p);
909         if (ulDataSize > ulRdBuffSize_p) {
910                 ulDataSize = ulRdBuffSize_p;
911                 ShbError = kShbDataTruncated;
912         }
913
914         if (ulDataSize == 0) {
915                 // nothing to do here
916                 ShbError = kShbNoReadableData;
917                 goto Exit;
918         }
919
920         // copy the data from the circular buffer
921         // (the copy process itself will be done outside of any
922         // critical/locked section)
923         if (ulRdIndex + ulDataSize <= pShbCirBuff->m_ulBufferDataSize) {
924                 // linear read operation
925                 memcpy(pDstDataPtr, pShbCirDataPtr + ulRdIndex, ulDataSize);
926         } else {
927                 // wrap-around read operation
928                 ulChunkSize = pShbCirBuff->m_ulBufferDataSize - ulRdIndex;
929                 memcpy(pDstDataPtr, pShbCirDataPtr + ulRdIndex, ulChunkSize);
930                 memcpy(pDstDataPtr + ulChunkSize, pShbCirDataPtr,
931                        ulDataSize - ulChunkSize);
932         }
933
934 #ifndef NDEBUG
935         {
936                 tShbCirBlockSize ClrShbCirBlockSize;
937
938                 if (ulRdIndex + ulDataSize <= pShbCirBuff->m_ulBufferDataSize) {
939                         // linear buffer
940                         memset(pShbCirDataPtr + ulRdIndex, 0xDD, ulDataSize);
941                 } else {
942                         // wrap-around read operation
943                         ulChunkSize =
944                             pShbCirBuff->m_ulBufferDataSize - ulRdIndex;
945                         memset(pShbCirDataPtr + ulRdIndex, 0xDD, ulChunkSize);
946                         memset(pShbCirDataPtr, 0xDD, ulDataSize - ulChunkSize);
947                 }
948
949                 ClrShbCirBlockSize.m_uiFullBlockSize = /*(unsigned int) */ -1;  // -1 = xFFFFFFF
950                 ClrShbCirBlockSize.m_uiAlignFillBytes = /*(unsigned int) */ -1; // -1 = Fxxxxxxx
951                 *(tShbCirBlockSize *) (pShbCirDataPtr +
952                                        pShbCirBuff->m_ulRdIndex) =
953                     ClrShbCirBlockSize;
954         }
955 #endif // #ifndef NDEBUG
956
957         // set new size of readable data, data in use, new read index
958         // and adjust number of readable blocks
959         ShbIpcEnterAtomicSection(pShbInstance_p);
960         {
961                 pShbCirBuff->m_ulDataInUse -= ShbCirBlockSize.m_uiFullBlockSize;
962                 pShbCirBuff->m_ulDataReadable -=
963                     ShbCirBlockSize.m_uiFullBlockSize;
964                 pShbCirBuff->m_ulBlocksReadable--;
965
966                 //$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
967                 if ((pShbCirBuff->m_ulDataInUse == 0)
968                     && (pShbCirBuff->m_ulDataReadable == 0)) {
969                         ASSERT(pShbCirBuff->m_ulBlocksReadable == 0);
970
971                         pShbCirBuff->m_ulWrIndex = 0;
972                         pShbCirBuff->m_ulRdIndex = 0;
973                 } else
974                         //$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
975                 {
976                         pShbCirBuff->m_ulRdIndex +=
977                             ShbCirBlockSize.m_uiFullBlockSize;
978                         pShbCirBuff->m_ulRdIndex %=
979                             pShbCirBuff->m_ulBufferDataSize;
980                 }
981         }
982         ShbIpcLeaveAtomicSection(pShbInstance_p);
983
984       Exit:
985
986         *pulDataBlockSize_p = ulDataSize;
987
988         return (ShbError);
989
990 }
991
992 //---------------------------------------------------------------------------
993 //  Get data size of next readable block from Circular Shared Buffer
994 //---------------------------------------------------------------------------
995
996 tShbError ShbCirGetReadDataSize(tShbInstance pShbInstance_p,
997                                 unsigned long *pulDataBlockSize_p)
998 {
999
1000         tShbCirBuff *pShbCirBuff;
1001         unsigned long ulDataReadable;
1002         unsigned char *pShbCirDataPtr;
1003         tShbCirBlockSize ShbCirBlockSize;
1004         unsigned long ulDataSize;
1005         tShbError ShbError;
1006
1007         // check arguments
1008         if ((pShbInstance_p == NULL) || (pulDataBlockSize_p == NULL)) {
1009                 return (kShbInvalidArg);
1010         }
1011
1012         pShbCirBuff = ShbCirGetBuffer(pShbInstance_p);
1013         ulDataSize = 0;
1014         ShbError = kShbOk;
1015
1016         if (pShbCirBuff->m_ShbCirMagicID != SBC_MAGIC_ID) {
1017                 ShbError = kShbInvalidBufferType;
1018                 goto Exit;
1019         }
1020
1021         // get total number of readable bytes for the whole circular buffer
1022         ShbIpcEnterAtomicSection(pShbInstance_p);
1023         {
1024                 ulDataReadable = pShbCirBuff->m_ulDataReadable;
1025         }
1026         ShbIpcLeaveAtomicSection(pShbInstance_p);
1027
1028         // if there are readable data available, then there must be at least
1029         // one complete readable data block
1030         if (ulDataReadable > 0) {
1031                 pShbCirDataPtr =
1032                     &pShbCirBuff->m_Data + pShbCirBuff->m_ulRdIndex;
1033
1034                 // get real size of current block (incl. alignment fill bytes)
1035                 ShbCirBlockSize = *(tShbCirBlockSize *) pShbCirDataPtr;
1036
1037                 // get size of user data inside the current block
1038                 ulDataSize =
1039                     ShbCirBlockSize.m_uiFullBlockSize -
1040                     ShbCirBlockSize.m_uiAlignFillBytes;
1041                 ulDataSize -= sizeof(tShbCirBlockSize);
1042         }
1043
1044       Exit:
1045
1046         *pulDataBlockSize_p = ulDataSize;
1047
1048         return (ShbError);
1049
1050 }
1051
1052 //---------------------------------------------------------------------------
1053 //  Get number of readable blocks from Circular Shared Buffer
1054 //---------------------------------------------------------------------------
1055
1056 tShbError ShbCirGetReadBlockCount(tShbInstance pShbInstance_p,
1057                                   unsigned long *pulDataBlockCount_p)
1058 {
1059
1060         tShbCirBuff *pShbCirBuff;
1061         unsigned long ulBlockCount;
1062         tShbError ShbError;
1063
1064         // check arguments
1065         if ((pShbInstance_p == NULL) || (pulDataBlockCount_p == NULL)) {
1066                 ShbError = kShbInvalidArg;
1067                 goto Exit;
1068         }
1069
1070         pShbCirBuff = ShbCirGetBuffer(pShbInstance_p);
1071         ulBlockCount = 0;
1072         ShbError = kShbOk;
1073
1074         if (pShbCirBuff->m_ShbCirMagicID != SBC_MAGIC_ID) {
1075                 ShbError = kShbInvalidBufferType;
1076                 goto Exit;
1077         }
1078
1079         ShbIpcEnterAtomicSection(pShbInstance_p);
1080         {
1081                 ulBlockCount = pShbCirBuff->m_ulBlocksReadable;
1082         }
1083         ShbIpcLeaveAtomicSection(pShbInstance_p);
1084
1085         *pulDataBlockCount_p = ulBlockCount;
1086
1087       Exit:
1088
1089         return (ShbError);
1090
1091 }
1092
1093 //---------------------------------------------------------------------------
1094 //  Set application handler to signal new data for Circular Shared Buffer
1095 //  d.k.: new parameter priority as enum
1096 //---------------------------------------------------------------------------
1097
1098 tShbError ShbCirSetSignalHandlerNewData(tShbInstance pShbInstance_p,
1099                                         tShbCirSigHndlrNewData pfnSignalHandlerNewData_p,
1100                                         tShbPriority ShbPriority_p)
1101 {
1102
1103         tShbCirBuff *pShbCirBuff;
1104         tShbError ShbError;
1105
1106         // check arguments
1107         if (pShbInstance_p == NULL) {
1108                 ShbError = kShbInvalidArg;
1109                 goto Exit;
1110         }
1111
1112         pShbCirBuff = ShbCirGetBuffer(pShbInstance_p);
1113         ShbError = kShbOk;
1114
1115         if (pShbCirBuff->m_ShbCirMagicID != SBC_MAGIC_ID) {
1116                 ShbError = kShbInvalidBufferType;
1117                 goto Exit;
1118         }
1119
1120         if (pfnSignalHandlerNewData_p != NULL) {
1121                 // set a new signal handler
1122                 if (pShbCirBuff->m_pfnSigHndlrNewData != NULL) {
1123                         ShbError = kShbAlreadySignaling;
1124                         goto Exit;
1125                 }
1126
1127                 pShbCirBuff->m_pfnSigHndlrNewData = pfnSignalHandlerNewData_p;
1128                 ShbError =
1129                     ShbIpcStartSignalingNewData(pShbInstance_p,
1130                                                 ShbCirSignalHandlerNewData,
1131                                                 ShbPriority_p);
1132         } else {
1133                 // remove existing signal handler
1134                 ShbError = ShbIpcStopSignalingNewData(pShbInstance_p);
1135                 if (pShbCirBuff->m_pfnSigHndlrNewData != NULL) {
1136                         pShbCirBuff->m_pfnSigHndlrNewData(pShbInstance_p, 0);
1137                 }
1138                 pShbCirBuff->m_pfnSigHndlrNewData = NULL;
1139         }
1140
1141       Exit:
1142
1143         return (ShbError);
1144
1145 }
1146
1147 //---------------------------------------------------------------------------
1148 //  DEBUG: Trace Circular Shared Buffer
1149 //---------------------------------------------------------------------------
1150
1151 #ifndef NDEBUG
1152 tShbError ShbCirTraceBuffer(tShbInstance pShbInstance_p)
1153 {
1154
1155         tShbCirBuff *pShbCirBuff;
1156         char szMagigID[sizeof(SBC_MAGIC_ID) + 1];
1157         tShbCirBlockSize ShbCirBlockSize;
1158         unsigned long ulDataReadable;
1159         unsigned char *pShbCirDataPtr;
1160         unsigned long ulBlockIndex;
1161         unsigned int nBlockCount;
1162         unsigned long ulDataSize;
1163         unsigned long ulChunkSize;
1164         unsigned long ulRdIndex;
1165         tShbError ShbError;
1166
1167         TRACE0("\n\n##### Circular Shared Buffer #####\n");
1168
1169         // check arguments
1170         if (pShbInstance_p == NULL) {
1171                 TRACE1("\nERROR: invalid buffer address (0x%08lX)\n",
1172                        (unsigned long)pShbInstance_p);
1173                 ShbError = kShbInvalidArg;
1174                 goto Exit;
1175         }
1176
1177         pShbCirBuff = ShbCirGetBuffer(pShbInstance_p);
1178         ShbError = kShbOk;
1179
1180         if (pShbCirBuff->m_ShbCirMagicID != SBC_MAGIC_ID) {
1181                 ShbError = kShbInvalidBufferType;
1182                 goto Exit;
1183         }
1184
1185         *(unsigned long *)&szMagigID[0] = pShbCirBuff->m_ShbCirMagicID;
1186         szMagigID[sizeof(SBC_MAGIC_ID)] = '\0';
1187
1188         ShbIpcEnterAtomicSection(pShbInstance_p);
1189         {
1190                 TRACE1("\nBuffer Address:   0x%08lX\n",
1191                        (unsigned long)pShbCirBuff);
1192
1193                 TRACE0("\nHeader Info:");
1194                 TRACE2("\nMagigID:          '%s' (%08lX)", szMagigID,
1195                        pShbCirBuff->m_ShbCirMagicID);
1196                 TRACE1("\nBufferTotalSize:  %4lu [Bytes]",
1197                        pShbCirBuff->m_ulBufferTotalSize);
1198                 TRACE1("\nBufferDataSize:   %4lu [Bytes]",
1199                        pShbCirBuff->m_ulBufferDataSize);
1200                 TRACE1("\nWrIndex:          %4lu", pShbCirBuff->m_ulWrIndex);
1201                 TRACE1("\nRdIndex:          %4lu", pShbCirBuff->m_ulRdIndex);
1202                 TRACE1("\nNumOfWriteJobs:   %4lu",
1203                        pShbCirBuff->m_ulNumOfWriteJobs);
1204                 TRACE1("\nDataInUse:        %4lu [Bytes]",
1205                        pShbCirBuff->m_ulDataInUse);
1206                 TRACE1("\nDataApended:      %4lu [Bytes]",
1207                        pShbCirBuff->m_ulDataApended);
1208                 TRACE1("\nBlocksApended:    %4lu",
1209                        pShbCirBuff->m_ulBlocksApended);
1210                 TRACE1("\nDataReadable:     %4lu [Bytes]",
1211                        pShbCirBuff->m_ulDataReadable);
1212                 TRACE1("\nBlocksReadable:   %4lu",
1213                        pShbCirBuff->m_ulBlocksReadable);
1214                 TRACE1("\nSigHndlrNewData:  %08lX",
1215                        (unsigned long)pShbCirBuff->m_pfnSigHndlrNewData);
1216                 TRACE1("\nBufferLocked:     %d", pShbCirBuff->m_fBufferLocked);
1217                 TRACE1("\nSigHndlrReset:    %08lX",
1218                        (unsigned long)pShbCirBuff->m_pfnSigHndlrReset);
1219
1220                 ShbTraceDump(&pShbCirBuff->m_Data,
1221                              pShbCirBuff->m_ulBufferDataSize, 0x00000000L,
1222                              "\nData Area:");
1223
1224                 ulDataReadable = pShbCirBuff->m_ulDataReadable;
1225                 nBlockCount = 1;
1226                 ulBlockIndex = pShbCirBuff->m_ulRdIndex;
1227
1228                 while (ulDataReadable > 0) {
1229                         TRACE1("\n\n--- Block #%u ---", nBlockCount);
1230
1231                         // get pointer to start of data area and current read index
1232                         pShbCirDataPtr = &pShbCirBuff->m_Data;  // ptr to start of data area
1233                         ulRdIndex = ulBlockIndex;
1234
1235                         // get real size of current block (incl. alignment fill bytes)
1236                         ShbCirBlockSize =
1237                             *(tShbCirBlockSize *) (pShbCirDataPtr + ulRdIndex);
1238                         ulRdIndex += sizeof(tShbCirBlockSize);
1239                         ulRdIndex %= pShbCirBuff->m_ulBufferDataSize;
1240
1241                         // get size of user data inside the current block
1242                         ulDataSize =
1243                             ShbCirBlockSize.m_uiFullBlockSize -
1244                             ShbCirBlockSize.m_uiAlignFillBytes;
1245                         ulDataSize -= sizeof(tShbCirBlockSize);
1246
1247                         TRACE1
1248                             ("\nFull Data Size:       %4u [Bytes] (incl. header and alignment fill bytes)",
1249                              ShbCirBlockSize.m_uiFullBlockSize);
1250                         TRACE1("\nUser Data Size:       %4lu [Bytes]",
1251                                ulDataSize);
1252                         TRACE1("\nAlignment Fill Bytes: %4u [Bytes]",
1253                                ShbCirBlockSize.m_uiAlignFillBytes);
1254
1255                         if (ulRdIndex + ulDataSize <=
1256                             pShbCirBuff->m_ulBufferDataSize) {
1257                                 // linear data buffer
1258                                 ShbTraceDump(pShbCirDataPtr + ulRdIndex,
1259                                              ulDataSize, 0x00000000L, NULL);
1260                         } else {
1261                                 // wrap-around data buffer
1262                                 ulChunkSize =
1263                                     pShbCirBuff->m_ulBufferDataSize - ulRdIndex;
1264                                 ShbTraceDump(pShbCirDataPtr + ulRdIndex,
1265                                              ulChunkSize, 0x00000000L, NULL);
1266                                 ShbTraceDump(pShbCirDataPtr,
1267                                              ulDataSize - ulChunkSize,
1268                                              ulChunkSize, NULL);
1269                         }
1270
1271                         nBlockCount++;
1272
1273                         ulBlockIndex += ShbCirBlockSize.m_uiFullBlockSize;
1274                         ulBlockIndex %= pShbCirBuff->m_ulBufferDataSize;
1275
1276                         ulDataReadable -= ShbCirBlockSize.m_uiFullBlockSize;
1277                 }
1278
1279                 ASSERT(pShbCirBuff->m_ulBlocksReadable == nBlockCount - 1);
1280         }
1281         ShbIpcLeaveAtomicSection(pShbInstance_p);
1282
1283       Exit:
1284
1285         return (ShbError);
1286
1287 }
1288 #endif
1289
1290 //-------------------------------------------------------------------------//
1291 //                                                                         //
1292 //          L i n e a r   S h a r e d   B u f f e r                        //
1293 //                                                                         //
1294 //-------------------------------------------------------------------------//
1295
1296 //---------------------------------------------------------------------------
1297 //  Allocate Linear Shared Buffer
1298 //---------------------------------------------------------------------------
1299
1300 tShbError ShbLinAllocBuffer(unsigned long ulBufferSize_p,
1301                             const char *pszBufferID_p,
1302                             tShbInstance * ppShbInstance_p,
1303                             unsigned int *pfShbNewCreated_p)
1304 {
1305
1306         tShbInstance pShbInstance;
1307         tShbLinBuff *pShbLinBuff;
1308         unsigned int fShbNewCreated;
1309         unsigned long ulBufferDataSize;
1310         unsigned long ulBufferTotalSize;
1311         tShbError ShbError;
1312
1313         // check arguments
1314         if ((ulBufferSize_p == 0) || (ppShbInstance_p == NULL)) {
1315                 return (kShbInvalidArg);
1316         }
1317
1318         // calculate length of memory to allocate
1319         ulBufferDataSize =
1320             (ulBufferSize_p +
1321              (SBL_BLOCK_ALIGNMENT - 1)) & ~(SBL_BLOCK_ALIGNMENT - 1);
1322         ulBufferTotalSize = ulBufferDataSize + sizeof(tShbLinBuff);
1323
1324         // allocate a new or open an existing shared buffer
1325         ShbError = ShbIpcAllocBuffer(ulBufferTotalSize, pszBufferID_p,
1326                                      &pShbInstance, &fShbNewCreated);
1327         if (ShbError != kShbOk) {
1328                 goto Exit;
1329         }
1330
1331         if (pShbInstance == NULL) {
1332                 ShbError = kShbOutOfMem;
1333                 goto Exit;
1334         }
1335
1336         // get pointer to shared buffer
1337         pShbLinBuff = (tShbLinBuff *) ShbIpcGetShMemPtr(pShbInstance);
1338
1339         // if the shared buffer was new created, than this process has
1340         // to initialize it, otherwise the buffer is already in use
1341         // and *must not* be reseted
1342         if (fShbNewCreated) {
1343 #ifndef NDEBUG
1344                 {
1345                         memset(pShbLinBuff, 0xCC, ulBufferTotalSize);
1346                 }
1347 #endif
1348
1349                 pShbLinBuff->m_ShbLinMagicID = SBL_MAGIC_ID;
1350                 pShbLinBuff->m_ulBufferTotalSize = ulBufferTotalSize;
1351                 pShbLinBuff->m_ulBufferDataSize = ulBufferDataSize;
1352         } else {
1353                 if (pShbLinBuff->m_ShbLinMagicID != SBL_MAGIC_ID) {
1354                         ShbError = kShbInvalidBufferType;
1355                         goto Exit;
1356                 }
1357         }
1358
1359       Exit:
1360
1361         *ppShbInstance_p = pShbInstance;
1362         *pfShbNewCreated_p = fShbNewCreated;
1363
1364         return (ShbError);
1365
1366 }
1367
1368 //---------------------------------------------------------------------------
1369 //  Release Linear Shared Buffer
1370 //---------------------------------------------------------------------------
1371
1372 tShbError ShbLinReleaseBuffer(tShbInstance pShbInstance_p)
1373 {
1374
1375         tShbError ShbError;
1376
1377         // check arguments
1378         if (pShbInstance_p == NULL) {
1379                 ShbError = kShbOk;
1380                 goto Exit;
1381         }
1382
1383         ShbError = ShbIpcReleaseBuffer(pShbInstance_p);
1384
1385       Exit:
1386
1387         return (ShbError);
1388
1389 }
1390
1391 //---------------------------------------------------------------------------
1392 //  Write data block to Linear Shared Buffer
1393 //---------------------------------------------------------------------------
1394 tShbError ShbLinWriteDataBlock(tShbInstance pShbInstance_p,
1395                                unsigned long ulDstBufferOffs_p,
1396                                const void *pSrcDataBlock_p,
1397                                unsigned long ulDataBlockSize_p)
1398 {
1399
1400         tShbLinBuff *pShbLinBuff;
1401         unsigned char *pShbLinDataPtr;
1402         unsigned char *pScrDataPtr;
1403         unsigned long ulBufferDataSize;
1404         tShbError ShbError;
1405
1406         // check arguments
1407         if (pShbInstance_p == NULL) {
1408                 ShbError = kShbInvalidArg;
1409                 goto Exit;
1410         }
1411
1412         if ((pSrcDataBlock_p == NULL) || (ulDataBlockSize_p == 0)) {
1413                 // nothing to do here
1414                 ShbError = kShbOk;
1415                 goto Exit;
1416         }
1417
1418         if (ulDataBlockSize_p > SBL_MAX_BLOCK_SIZE) {
1419                 ShbError = kShbExceedDataSizeLimit;
1420                 goto Exit;
1421         }
1422
1423         pShbLinBuff = ShbLinGetBuffer(pShbInstance_p);
1424         pScrDataPtr = (unsigned char *)pSrcDataBlock_p;
1425         ShbError = kShbOk;
1426
1427         if (pShbLinBuff->m_ShbLinMagicID != SBL_MAGIC_ID) {
1428                 ShbError = kShbInvalidBufferType;
1429                 goto Exit;
1430         }
1431
1432         // check if offeset and size for the write operation matches with
1433         // the size of the shared buffer
1434         ulBufferDataSize = pShbLinBuff->m_ulBufferDataSize;
1435         if ((ulDstBufferOffs_p > ulBufferDataSize) ||
1436             (ulDataBlockSize_p > ulBufferDataSize) ||
1437             ((ulDstBufferOffs_p + ulDataBlockSize_p) > ulBufferDataSize)) {
1438                 ShbError = kShbDataOutsideBufferArea;
1439                 goto Exit;
1440         }
1441
1442         // copy the data to the linear buffer
1443         // (the copy process will be done inside of any critical/locked section)
1444         pShbLinDataPtr = &pShbLinBuff->m_Data;  // ptr to start of data area
1445         pShbLinDataPtr += ulDstBufferOffs_p;
1446
1447         ShbIpcEnterAtomicSection(pShbInstance_p);
1448         {
1449                 memcpy(pShbLinDataPtr, pScrDataPtr, ulDataBlockSize_p);
1450         }
1451         ShbIpcLeaveAtomicSection(pShbInstance_p);
1452
1453       Exit:
1454
1455         return (ShbError);
1456
1457 }
1458
1459 //---------------------------------------------------------------------------
1460 //  Read data block from Linear Shared Buffer
1461 //---------------------------------------------------------------------------
1462 tShbError ShbLinReadDataBlock(tShbInstance pShbInstance_p,
1463                               void *pDstDataBlock_p,
1464                               unsigned long ulSrcBufferOffs_p,
1465                               unsigned long ulDataBlockSize_p)
1466 {
1467
1468         tShbLinBuff *pShbLinBuff;
1469         unsigned char *pShbLinDataPtr;
1470         unsigned char *pDstDataPtr;
1471         unsigned long ulBufferDataSize;
1472         tShbError ShbError;
1473
1474         // check arguments
1475         if (pShbInstance_p == NULL) {
1476                 ShbError = kShbInvalidArg;
1477                 goto Exit;
1478         }
1479
1480         if ((pDstDataBlock_p == NULL) || (ulDataBlockSize_p == 0)) {
1481                 // nothing to do here
1482                 ShbError = kShbOk;
1483                 goto Exit;
1484         }
1485
1486         if (ulDataBlockSize_p > SBL_MAX_BLOCK_SIZE) {
1487                 ShbError = kShbExceedDataSizeLimit;
1488                 goto Exit;
1489         }
1490
1491         pShbLinBuff = ShbLinGetBuffer(pShbInstance_p);
1492         pDstDataPtr = (unsigned char *)pDstDataBlock_p;
1493         ShbError = kShbOk;
1494
1495         if (pShbLinBuff->m_ShbLinMagicID != SBL_MAGIC_ID) {
1496                 ShbError = kShbInvalidBufferType;
1497                 goto Exit;
1498         }
1499
1500         // check if offeset and size for the read operation matches with
1501         // the size of the shared buffer
1502         ulBufferDataSize = pShbLinBuff->m_ulBufferDataSize;
1503         if ((ulSrcBufferOffs_p > ulBufferDataSize) ||
1504             (ulDataBlockSize_p > ulBufferDataSize) ||
1505             ((ulSrcBufferOffs_p + ulDataBlockSize_p) > ulBufferDataSize)) {
1506                 ShbError = kShbDataOutsideBufferArea;
1507                 goto Exit;
1508         }
1509
1510         // copy the data to the linear buffer
1511         // (the copy process will be done inside of any critical/locked section)
1512         pShbLinDataPtr = &pShbLinBuff->m_Data;  // ptr to start of data area
1513         pShbLinDataPtr += ulSrcBufferOffs_p;
1514
1515         ShbIpcEnterAtomicSection(pShbInstance_p);
1516         {
1517                 memcpy(pDstDataPtr, pShbLinDataPtr, ulDataBlockSize_p);
1518         }
1519         ShbIpcLeaveAtomicSection(pShbInstance_p);
1520
1521       Exit:
1522
1523         return (ShbError);
1524
1525 }
1526
1527 //---------------------------------------------------------------------------
1528 //  DEBUG: Trace Linear Shared Buffer
1529 //---------------------------------------------------------------------------
1530
1531 #ifndef NDEBUG
1532 tShbError ShbLinTraceBuffer(tShbInstance pShbInstance_p)
1533 {
1534
1535         tShbLinBuff *pShbLinBuff;
1536         char szMagigID[sizeof(SBL_MAGIC_ID) + 1];
1537         tShbError ShbError;
1538
1539         TRACE0("\n\n##### Linear Shared Buffer #####\n");
1540
1541         // check arguments
1542         if (pShbInstance_p == NULL) {
1543                 TRACE1("\nERROR: invalid buffer address (0x%08lX)\n",
1544                        (unsigned long)pShbInstance_p);
1545                 ShbError = kShbInvalidArg;
1546                 goto Exit;
1547         }
1548
1549         pShbLinBuff = ShbLinGetBuffer(pShbInstance_p);
1550         ShbError = kShbOk;
1551
1552         if (pShbLinBuff->m_ShbLinMagicID != SBL_MAGIC_ID) {
1553                 ShbError = kShbInvalidBufferType;
1554                 goto Exit;
1555         }
1556
1557         *(unsigned int *)&szMagigID[0] = pShbLinBuff->m_ShbLinMagicID;
1558         szMagigID[sizeof(SBL_MAGIC_ID)] = '\0';
1559
1560         ShbIpcEnterAtomicSection(pShbInstance_p);
1561         {
1562                 TRACE1("\nBuffer Address:   0x%08lX\n",
1563                        (unsigned long)pShbLinBuff);
1564
1565                 TRACE0("\nHeader Info:");
1566                 TRACE2("\nMagigID:          '%s' (%08X)", szMagigID,
1567                        pShbLinBuff->m_ShbLinMagicID);
1568                 TRACE1("\nBufferTotalSize:  %4lu [Bytes]",
1569                        pShbLinBuff->m_ulBufferTotalSize);
1570                 TRACE1("\nBufferDataSize:   %4lu [Bytes]",
1571                        pShbLinBuff->m_ulBufferDataSize);
1572
1573                 ShbTraceDump(&pShbLinBuff->m_Data,
1574                              pShbLinBuff->m_ulBufferDataSize, 0x00000000L,
1575                              "\nData Area:");
1576         }
1577         ShbIpcLeaveAtomicSection(pShbInstance_p);
1578
1579       Exit:
1580
1581         return (ShbError);
1582
1583 }
1584 #endif
1585
1586 //---------------------------------------------------------------------------
1587 //  Dump buffer contents
1588 //---------------------------------------------------------------------------
1589
1590 #ifndef NDEBUG
1591 tShbError ShbTraceDump(const unsigned char *pabStartAddr_p,
1592                        unsigned long ulDataSize_p,
1593                        unsigned long ulAddrOffset_p, const char *pszInfoText_p)
1594 {
1595
1596         const unsigned char *pabBuffData;
1597         unsigned long ulBuffSize;
1598         unsigned char bData;
1599         int nRow;
1600         int nCol;
1601
1602         // get pointer to buffer and length of buffer
1603         pabBuffData = pabStartAddr_p;
1604         ulBuffSize = ulDataSize_p;
1605
1606         if (pszInfoText_p != NULL) {
1607                 TRACE1("%s", pszInfoText_p);
1608         }
1609         // dump buffer contents
1610         for (nRow = 0;; nRow++) {
1611                 TRACE1("\n%08lX:   ",
1612                        (unsigned long)(nRow * 0x10) + ulAddrOffset_p);
1613
1614                 for (nCol = 0; nCol < 16; nCol++) {
1615                         if ((unsigned long)nCol < ulBuffSize) {
1616                                 TRACE1("%02X ",
1617                                        (unsigned int)*(pabBuffData + nCol));
1618                         } else {
1619                                 TRACE0("   ");
1620                         }
1621                 }
1622
1623                 TRACE0(" ");
1624
1625                 for (nCol = 0; nCol < 16; nCol++) {
1626                         bData = *pabBuffData++;
1627                         if ((unsigned long)nCol < ulBuffSize) {
1628                                 if ((bData >= 0x20) && (bData < 0x7F)) {
1629                                         TRACE1("%c", bData);
1630                                 } else {
1631                                         TRACE0(".");
1632                                 }
1633                         } else {
1634                                 TRACE0(" ");
1635                         }
1636                 }
1637
1638                 if (ulBuffSize > 16) {
1639                         ulBuffSize -= 16;
1640                 } else {
1641                         break;
1642                 }
1643         }
1644
1645         return (kShbOk);
1646
1647 }
1648 #endif // #ifndef NDEBUG
1649
1650 //=========================================================================//
1651 //                                                                         //
1652 //          P R I V A T E   F U N C T I O N S                              //
1653 //                                                                         //
1654 //=========================================================================//
1655
1656 //---------------------------------------------------------------------------
1657 //  Handler to signal new data event for Circular Shared Buffer
1658 //---------------------------------------------------------------------------
1659
1660 int ShbCirSignalHandlerNewData(tShbInstance pShbInstance_p)
1661 {
1662
1663         tShbCirBuff *pShbCirBuff;
1664         unsigned long ulDataSize;
1665         unsigned long ulBlockCount;
1666         tShbError ShbError;
1667
1668         // check arguments
1669         if (pShbInstance_p == NULL) {
1670                 return FALSE;
1671         }
1672
1673         pShbCirBuff = ShbCirGetBuffer(pShbInstance_p);
1674         ShbError = kShbOk;
1675
1676         if (pShbCirBuff->m_ShbCirMagicID != SBC_MAGIC_ID) {
1677                 return FALSE;
1678         }
1679
1680         // call application handler
1681         if (pShbCirBuff->m_pfnSigHndlrNewData != NULL) {
1682 /*        do
1683         {*/
1684                 ShbError = ShbCirGetReadDataSize(pShbInstance_p, &ulDataSize);
1685                 if ((ulDataSize > 0) && (ShbError == kShbOk)) {
1686                         pShbCirBuff->m_pfnSigHndlrNewData(pShbInstance_p,
1687                                                           ulDataSize);
1688                 }
1689
1690                 ShbError =
1691                     ShbCirGetReadBlockCount(pShbInstance_p, &ulBlockCount);
1692 /*        }
1693         while ((ulBlockCount > 0) && (ShbError == kShbOk));*/
1694         }
1695         // Return TRUE if there are pending blocks.
1696         // In that case ShbIpc tries to call this function again immediately if there
1697         // is no other filled shared buffer with higher priority.
1698         return ((ulBlockCount > 0) && (ShbError == kShbOk));
1699
1700 }
1701
1702 //---------------------------------------------------------------------------
1703 //  Handler to reset Circular Shared Buffer
1704 //---------------------------------------------------------------------------
1705
1706 void ShbCirSignalHandlerReset(tShbInstance pShbInstance_p,
1707                               unsigned int fTimeOut_p)
1708 {
1709
1710         tShbCirBuff *pShbCirBuff;
1711
1712         // check arguments
1713         if (pShbInstance_p == NULL) {
1714                 return;
1715         }
1716
1717         pShbCirBuff = ShbCirGetBuffer(pShbInstance_p);
1718         if (pShbCirBuff->m_ShbCirMagicID != SBC_MAGIC_ID) {
1719                 return;
1720         }
1721
1722         // reset buffer header
1723         if (!fTimeOut_p) {
1724                 ShbIpcEnterAtomicSection(pShbInstance_p);
1725                 {
1726                         pShbCirBuff->m_ulWrIndex = 0;
1727                         pShbCirBuff->m_ulRdIndex = 0;
1728                         pShbCirBuff->m_ulNumOfWriteJobs = 0;
1729                         pShbCirBuff->m_ulDataInUse = 0;
1730                         pShbCirBuff->m_ulDataApended = 0;
1731                         pShbCirBuff->m_ulBlocksApended = 0;
1732                         pShbCirBuff->m_ulDataReadable = 0;
1733                         pShbCirBuff->m_ulBlocksReadable = 0;
1734                 }
1735                 ShbIpcLeaveAtomicSection(pShbInstance_p);
1736
1737 #ifndef NDEBUG
1738                 {
1739                         memset(&pShbCirBuff->m_Data, 0xCC,
1740                                pShbCirBuff->m_ulBufferDataSize);
1741                 }
1742 #endif
1743         }
1744
1745         // call application handler
1746         if (pShbCirBuff->m_pfnSigHndlrReset != NULL) {
1747                 pShbCirBuff->m_pfnSigHndlrReset(pShbInstance_p, fTimeOut_p);
1748         }
1749
1750         // unlock buffer
1751         ShbIpcEnterAtomicSection(pShbInstance_p);
1752         {
1753                 pShbCirBuff->m_fBufferLocked = FALSE;
1754                 pShbCirBuff->m_pfnSigHndlrReset = NULL;
1755         }
1756         ShbIpcLeaveAtomicSection(pShbInstance_p);
1757
1758         return;
1759
1760 }
1761
1762 // EOF