User/Kernel Interface and Synchronization

The MAGNeT additions to the kernel export the circular buffer to user-space applications via Linux kernel/user shared memory. That is, a device file⁴ serves as an user-level handle to the kernel's shared-memory region. Opening this file causes Linux to create a mapping between the kernel-memory region and the user-address space. With this mapping in place, no additional kernel code is executed; the application program simply reads the shared memory and writes it to disk.

Because the kernel and user processes share the same area of physical memory, they must have a means of synchronization. This is accomplished by using the timestamp field of the instrumentation record as a synchronization flag between the MAGNeT user and kernel processes, as shown in Figures 4 and 5.

Figure 4: MAGNeT Kernel Operation

Figure 5: MAGNeT User Operation

Before writing to a slot in the circular buffer, the MAGNeT kernel code checks the value of the timestamp field for that slot. A non-zero value indicates that the slot has not yet been copied to user space and that the kernel buffer is full. In this case, the kernel code increments a count of the number of instrumentation records that could not be saved due to the buffer being full. Otherwise, the kernel code writes a new instrumentation record and advances its pointer to the next slot in the circular buffer.

The user application accesses the same circular buffer via kernel/user shared memory and maintains a pointer to its current slot in the buffer. When the timestamp field at this slot becomes non-zero, the application reads the entire record, saves it to disk, and sets the timestamp field back to zero to signal the kernel that the slot is once again available. It then advances its pointer to the next slot in the circular buffer.

If the kernel has a non-zero count of unsaved events and buffer space becomes available (i.e., the timestamp field of the kernel's currently active slot is set to zero by the user application), the kernel writes a special instrumentation record with an event type of MAGNET_LOST and with the size field set to the number of instrumentation records that were not recorded. Thus, during post-processing of the data, the fact that events were lost is detected at the appropriate chronological place in the data stream and in time.