CeLog Buffering Scheme (Windows Embedded CE 6.0)

  • Article

1/5/2010

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.

Remarks

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 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 name of the memory mapped file is SYSTEM/CeLog Data. The CELOG_DATAMAP_NAME macro is provided for referring to this name. The files contain both headers and buffers.

An event tracking library creates this memory-mapped file by calling the pCreateFileMappingW and pMapViewOfFile functions from CeLogImportTable. A flushing application can open a view of this buffer by calling CreateFileMapping and MapViewOfFile.

The memory-mapped file contains a MAPHEADER structure followed by a buffer of CeLog event data. The event data buffer is a "ring" buffer, meaning that data can wrap around from the end of the 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 ring 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.

CELOG_DATAMAP_NAME and CELOG_FILLEVENT_NAME are defined in celog.h.

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 memory-mapped file, 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 event 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 ring 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 ring 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 ring buffer is empty, and the flush application must wait until the event-tracking library moves pWrite when it writes new data into the ring buffer.

fSetEvent

This member indicates whether the event-tracking library should signal the fill event to indicate that the ring 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

Last count of lost bytes.

The remainder of the memory-mapped file after the MAPHEADER structure contains the ring buffer of event data.

The following list further explains the rules that govern the interaction of the event tracking library and flush application with the ring buffer of event data.

  • 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 ring buffer size dwBufSize.
    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 ring 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 ring 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

Concepts

Logging Event Data
Implementing an Event Tracking Library
Writing Your Own CeLog Flush Application