CeLog Buffering Scheme (Windows CE 5.0)
The CeLog RAM buffer forms the interface between the event tracking library, which places data into the buffer, and the flushing application, which removes it. To communicate properly, both the library and the flushing application must interpret the data in the same way and follow certain rules about adding and removing data from the buffer. Only one event tracking library and one flush application may access the CeLog buffer at a time.
CeLog.dll is the default event tracking library, but any event tracking library that must work with the existing flushing applications must be able to place the data in the CeLog buffer the same way the default library CeLog.dll does.
Windows CE 5.0 includes several flushing applications, such as CeLogFlush.exe, OSCapture.exe, and the Remote Kernel Tracker data transport layer. In addition, OEMs and application developers can create their own flushing applications. Any flushing applications must be able to work with the data in the CeLog buffer.
CeLog buffers its data in a named, memory-mapped file. The buffer name is SYSTEM/CeLog Data. The CELOG_DATAMAP_NAME macro is provided for referring to this name.
An event tracking library creates this buffer by calling the pCreateFileMappingW and pMapViewOfFile functions from CeLogImportTable. A flushing application can open a view of this buffer by calling CreateFileForMapping and MapViewOfFile.
The buffer data structure is a MAPHEADER structure followed by a ring buffer, where data can wrap around from the end of the ring buffer to the beginning.
One other object is used to communicate between event tracking libraries and flushing applications: a named event that the event tracking library signals when the buffer is nearly full. An event-tracking library creates and signals this event by calling the pCreateEventW and pEventModify functions from CeLogImportTable. A flushing application can open and wait for this event by calling OpenEvent and WaitForSingleObject. The event name is SYSTEM/CeLog Fill. The CELOG_FILLEVENT_NAME macro is provided for referring to this event.
The following table describes how event tracking libraries and flushing applications use the members of the MAPHEADER structure.
| Member | Description of use |
|---|---|
| dwBufSize | This member is initialized by the event tracking library that creates the buffer, and can be used by the flush application to determine where the end of the ring buffer wraps to the beginning.
dwBufSize does not include the size of the MAPHEADER structure at the beginning of the map. The ring buffer starts at address (map_addr + sizeof(MAPHEADER)) and ends at (map_addr + sizeof(MAPHEADER) + dwBufSize). |
| pWrite | This member represents the end of the buffered data. This pointer is maintained by the event-tracking library and should not be modified by the flush application.
The event-tracking library should never allow pWrite to wrap past pRead. If pWrite reaches pRead, the buffer is full, and the event-tracking library must discard data until the flush application moves pRead to make room for more data. |
| pRead | This member points to the oldest data in the buffer, the next location for the flush application to read from the ring buffer. This pointer is maintained by the flush application and should not be modified by the event-tracking library.
The flush application should never allow pRead to wrap past pWrite. If pRead reaches pWrite, the buffer is empty, and the flush application must wait until the event-tracking library moves pWrite when it writes new data into the buffer. |
| fSetEvent | This member indicates whether the event-tracking library should signal the fill event to indicate that the buffer is approaching full. fSetEvent is used to keep the event tracking library from setting the event multiple times in a row.
The flush application sets this value to TRUE when it is done flushing, and the event tracking library sets it to FALSE after it signals the fill event. |
| dwLostBytes |
The remainder of the buffer contains data.
The following list further explains the rules that govern the interaction of the event tracking library and flush application with the data buffer.
Read and write range
The flush application is free to read between pRead and pWrite, but not past pWrite. Addresses must be managed modulo the buffer size.
The event-tracking library writes data starting at pWrite and stops at pRead. If the space between pWrite and pRead is insufficient to contain new event data, the event-tracking library must discard the new data without writing into the buffer. The event-tracking library should update the dwLostBytes counter with the amount of discarded data.
Data loss events
The event-tracking library does not generate CELID_DATA_LOSS data loss events. The flush application is responsible for creating the data loss event and adding it to the event stream. This allows the flush application to ensure that the data loss events are not lost. For more information, see Writing your own CeLog Flush Application.
Fill events
The event-tracking library signals this event when the amount of empty space in the buffer passes below a minimum mark. The flush application can wait until this event is signaled and then reads the data. This eliminates the need for polling.
The fill event is used in coordination with the fSetEvent flag.
The event-tracking library sets this flag to FALSE when it signals the fill event, and does not signal the event again as long as the flag is FALSE. This prevents the event-tracking library from signaling the event many times in a row while the flush application is busy flushing.
The flush application should reset the flag to TRUE when it is ready to wait for the fill event again. If the flag is not reset, the event-tracking library no longer signals the fill event.
See Also
Implementing an Event Tracking Library | Writing Your Own CeLog Flush Application
Send Feedback on this topic to the authors