Module access_trace

Expand description

Record types of the access trace (--record-access-trace-to).

The access trace is a sidecar of a run that records its schedule. It says what each guest operation touched, keyed by the operation’s position in that schedule (the run’s own .events file), so a reader can line two runs up and name the conflicting operations whose order differs between them.

The file is JSON Lines: one TraceRecord per line, tagged by "kind". The first line is a TraceHeader. A run that finishes cleanly ends with a TraceEnd; a trace without one was cut short. A record is written when its last schedule event is recorded, so syscall records follow post; a call that never returned is written when its thread enters its next call, or at the end of the run. Readers sort by the index they need.

Every event index here is a position in the recorded schedule: the index the scheduler gave the event when it recorded it. Syscall records carry the thread’s own syscall count as nth, the unit of crate::happens_before::Position::SyscallCount, so (tid, nth) names the same operation in two runs of one program while its control flow agrees.

The trace observes; it never feeds back into the run. Nothing in these types is read by the scheduler.

Not recorded: some operations touch more than their records say.

splice and copy_file_range with a NULL offset move the file cursor, but record no cursor access;
poll, select, ppoll and the epoll waits record no access to the descriptors or channels they check;
path operations (unlink, rename, stat by path, the dirfd of the *at calls) record nothing;
FUTEX_WAIT_REQUEUE_PI records no access to its second futex word;
kill(-1) records nothing.

Structs§

AccessTrace: A whole trace, as read_access_trace returns it.
ByteRange: A half-open byte range [start, end).
EdgeRecord: One happens-before edge between two events of two threads. from precedes to in the recorded schedule.
EventRef: A thread at one schedule event: one end of an EdgeRecord.
ReturnedBytes: The bytes a syscall returned through guest buffers, summarized.
SignalRecord: One signal event and the disposition observed before submitting it.
SignalSender: The sender of a user-generated signal, from its siginfo.
StackFrame: One frame of a watchpoint hit’s stack.
SyscallRecord: One syscall, from its prehook event to its posthook event.
TraceEnd: Closes a complete trace.
TraceHeader: Identifies the file and the slice of the schedule it covers.
WatchHitRecord: A hardware watchpoint hit (reserved for --watch; no writer emits it yet).

Enums§

Access: One resource access of a syscall. Section 4 of the M5 design names the identities; Access::conflicts_with states which pairs conflict.
AccessTraceError: Why a trace could not be read.
ChannelId: The identity both ends of one channel share.
ChannelKind: Kinds of channel.
ChannelOp: What a syscall did to a channel end.
CursorOp: How a syscall used an open file’s cursor.
DataOp: Read or write of data.
EdgeKind: Kinds of synchronization edge (design section 7). Data edges through pipes and sockets are derived by the reader from syscall results; they are not recorded.
FdOp: What a syscall did to a descriptor slot.
FutexOp: A futex operation on one word.
LifetimeOp: What a syscall did to a thread or process.
MemoryOp: What a syscall did to a range of memory.
ObservedSignalDisposition: The installed signal disposition observed before submitting its schedule event.
SyncObject: The object an edge synchronizes through.
Task: A thread, a process, or a process group.
TimerId: Identity of a timer.
TimerOp: What a syscall did to a timer.
TraceRecord: One line of an access trace.

Constants§

ACCESS_TRACE_DEFAULT_MAX_BYTES: The bytes of header and records a trace holds at most when --access-trace-max-bytes is not given: 1 GiB. A record takes about 350 bytes, so this is some three million records; a run with more stops its trace there, without the end line, rather than fill the disk.
ACCESS_TRACE_FORMAT: The format string every access trace header carries.
ACCESS_TRACE_VERSION: The record format version this crate writes and reads.
OUT_BYTES_CAP: At most this many leading bytes of a write to fd 1 or 2 are kept in SyscallRecord::out_bytes.
RETURNED_DIGEST_CAP: At most this many returned bytes enter ReturnedBytes::digest.
RETURNED_DIGEST_SEED: The FNV-1a offset basis, the starting value of returned_digest.

Functions§

read_access_trace: Read and validate a whole access trace.
returned_digest: The 64-bit FNV-1a hash ReturnedBytes::digest uses: fold each buffer’s bytes in order into the running value, starting from RETURNED_DIGEST_SEED.

Type Aliases§

EventIndex: A position in the run’s recorded schedule (its .events file).