1 //===- Trace.cpp - XRay Trace Loading implementation. ---------------------===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // XRay log reader implementation.
12 //===----------------------------------------------------------------------===//
13 #include "llvm/XRay/Trace.h"
14 #include "llvm/ADT/STLExtras.h"
15 #include "llvm/Support/DataExtractor.h"
16 #include "llvm/Support/Error.h"
17 #include "llvm/Support/FileSystem.h"
18 #include "llvm/XRay/YAMLXRayRecord.h"
21 using namespace llvm::xray;
22 using llvm::yaml::Input;
24 using XRayRecordStorage =
25 std::aligned_storage<sizeof(XRayRecord), alignof(XRayRecord)>::type;
27 // Populates the FileHeader reference by reading the first 32 bytes of the file.
28 Error readBinaryFormatHeader(StringRef Data, XRayFileHeader &FileHeader) {
29 // FIXME: Maybe deduce whether the data is little or big-endian using some
30 // magic bytes in the beginning of the file?
32 // First 32 bytes of the file will always be the header. We assume a certain
35 // (2) uint16 : version
37 // (4) uint32 : bitfield
38 // (8) uint64 : cycle frequency
41 DataExtractor HeaderExtractor(Data, true, 8);
42 uint32_t OffsetPtr = 0;
43 FileHeader.Version = HeaderExtractor.getU16(&OffsetPtr);
44 FileHeader.Type = HeaderExtractor.getU16(&OffsetPtr);
45 uint32_t Bitfield = HeaderExtractor.getU32(&OffsetPtr);
46 FileHeader.ConstantTSC = Bitfield & 1uL;
47 FileHeader.NonstopTSC = Bitfield & 1uL << 1;
48 FileHeader.CycleFrequency = HeaderExtractor.getU64(&OffsetPtr);
49 std::memcpy(&FileHeader.FreeFormData, Data.bytes_begin() + OffsetPtr, 16);
50 if (FileHeader.Version != 1)
51 return make_error<StringError>(
52 Twine("Unsupported XRay file version: ") + Twine(FileHeader.Version),
53 std::make_error_code(std::errc::invalid_argument));
54 return Error::success();
57 Error loadNaiveFormatLog(StringRef Data, XRayFileHeader &FileHeader,
58 std::vector<XRayRecord> &Records) {
59 // Check that there is at least a header
61 return make_error<StringError>(
62 "Not enough bytes for an XRay log.",
63 std::make_error_code(std::errc::invalid_argument));
65 if (Data.size() - 32 == 0 || Data.size() % 32 != 0)
66 return make_error<StringError>(
67 "Invalid-sized XRay data.",
68 std::make_error_code(std::errc::invalid_argument));
70 if (auto E = readBinaryFormatHeader(Data, FileHeader))
73 // Each record after the header will be 32 bytes, in the following format:
75 // (2) uint16 : record type
78 // (4) sint32 : function id
80 // (4) uint32 : thread id
82 for (auto S = Data.drop_front(32); !S.empty(); S = S.drop_front(32)) {
83 DataExtractor RecordExtractor(S, true, 8);
84 uint32_t OffsetPtr = 0;
85 Records.emplace_back();
86 auto &Record = Records.back();
87 Record.RecordType = RecordExtractor.getU16(&OffsetPtr);
88 Record.CPU = RecordExtractor.getU8(&OffsetPtr);
89 auto Type = RecordExtractor.getU8(&OffsetPtr);
92 Record.Type = RecordTypes::ENTER;
95 Record.Type = RecordTypes::EXIT;
98 return make_error<StringError>(
99 Twine("Unknown record type '") + Twine(int{Type}) + "'",
100 std::make_error_code(std::errc::executable_format_error));
102 Record.FuncId = RecordExtractor.getSigned(&OffsetPtr, sizeof(int32_t));
103 Record.TSC = RecordExtractor.getU64(&OffsetPtr);
104 Record.TId = RecordExtractor.getU32(&OffsetPtr);
106 return Error::success();
109 /// When reading from a Flight Data Recorder mode log, metadata records are
110 /// sparse compared to packed function records, so we must maintain state as we
111 /// read through the sequence of entries. This allows the reader to denormalize
112 /// the CPUId and Thread Id onto each Function Record and transform delta
113 /// encoded TSC values into absolute encodings on each record.
119 /// Encode some of the state transitions for the FDR log reader as explicit
120 /// checks. These are expectations for the next Record in the stream.
122 NEW_BUFFER_RECORD_OR_EOF,
126 SCAN_TO_END_OF_THREAD_BUF,
131 // Each threads buffer may have trailing garbage to scan over, so we track our
133 uint64_t CurrentBufferSize;
134 uint64_t CurrentBufferConsumed;
137 Twine fdrStateToTwine(const FDRState::Token &state) {
139 case FDRState::Token::NEW_BUFFER_RECORD_OR_EOF:
140 return "NEW_BUFFER_RECORD_OR_EOF";
141 case FDRState::Token::WALLCLOCK_RECORD:
142 return "WALLCLOCK_RECORD";
143 case FDRState::Token::NEW_CPU_ID_RECORD:
144 return "NEW_CPU_ID_RECORD";
145 case FDRState::Token::FUNCTION_SEQUENCE:
146 return "FUNCTION_SEQUENCE";
147 case FDRState::Token::SCAN_TO_END_OF_THREAD_BUF:
148 return "SCAN_TO_END_OF_THREAD_BUF";
149 case FDRState::Token::CUSTOM_EVENT_DATA:
150 return "CUSTOM_EVENT_DATA";
155 /// State transition when a NewBufferRecord is encountered.
156 Error processFDRNewBufferRecord(FDRState &State, uint8_t RecordFirstByte,
157 DataExtractor &RecordExtractor) {
159 if (State.Expects != FDRState::Token::NEW_BUFFER_RECORD_OR_EOF)
160 return make_error<StringError>(
161 "Malformed log. Read New Buffer record kind out of sequence",
162 std::make_error_code(std::errc::executable_format_error));
163 uint32_t OffsetPtr = 1; // 1 byte into record.
164 State.ThreadId = RecordExtractor.getU16(&OffsetPtr);
165 State.Expects = FDRState::Token::WALLCLOCK_RECORD;
166 return Error::success();
169 /// State transition when an EndOfBufferRecord is encountered.
170 Error processFDREndOfBufferRecord(FDRState &State, uint8_t RecordFirstByte,
171 DataExtractor &RecordExtractor) {
172 if (State.Expects == FDRState::Token::NEW_BUFFER_RECORD_OR_EOF)
173 return make_error<StringError>(
174 "Malformed log. Received EOB message without current buffer.",
175 std::make_error_code(std::errc::executable_format_error));
176 State.Expects = FDRState::Token::SCAN_TO_END_OF_THREAD_BUF;
177 return Error::success();
180 /// State transition when a NewCPUIdRecord is encountered.
181 Error processFDRNewCPUIdRecord(FDRState &State, uint8_t RecordFirstByte,
182 DataExtractor &RecordExtractor) {
183 if (State.Expects != FDRState::Token::FUNCTION_SEQUENCE &&
184 State.Expects != FDRState::Token::NEW_CPU_ID_RECORD)
185 return make_error<StringError>(
186 "Malformed log. Read NewCPUId record kind out of sequence",
187 std::make_error_code(std::errc::executable_format_error));
188 uint32_t OffsetPtr = 1; // Read starting after the first byte.
189 State.CPUId = RecordExtractor.getU16(&OffsetPtr);
190 State.BaseTSC = RecordExtractor.getU64(&OffsetPtr);
191 State.Expects = FDRState::Token::FUNCTION_SEQUENCE;
192 return Error::success();
195 /// State transition when a TSCWrapRecord (overflow detection) is encountered.
196 Error processFDRTSCWrapRecord(FDRState &State, uint8_t RecordFirstByte,
197 DataExtractor &RecordExtractor) {
198 if (State.Expects != FDRState::Token::FUNCTION_SEQUENCE)
199 return make_error<StringError>(
200 "Malformed log. Read TSCWrap record kind out of sequence",
201 std::make_error_code(std::errc::executable_format_error));
202 uint32_t OffsetPtr = 1; // Read starting after the first byte.
203 State.BaseTSC = RecordExtractor.getU64(&OffsetPtr);
204 return Error::success();
207 /// State transition when a WallTimeMarkerRecord is encountered.
208 Error processFDRWallTimeRecord(FDRState &State, uint8_t RecordFirstByte,
209 DataExtractor &RecordExtractor) {
210 if (State.Expects != FDRState::Token::WALLCLOCK_RECORD)
211 return make_error<StringError>(
212 "Malformed log. Read Wallclock record kind out of sequence",
213 std::make_error_code(std::errc::executable_format_error));
214 // We don't encode the wall time into any of the records.
215 // XRayRecords are concerned with the TSC instead.
216 State.Expects = FDRState::Token::NEW_CPU_ID_RECORD;
217 return Error::success();
220 /// State transition when a CustomEventMarker is encountered.
221 Error processCustomEventMarker(FDRState &State, uint8_t RecordFirstByte,
222 DataExtractor &RecordExtractor,
223 size_t &RecordSize) {
224 // We can encounter a CustomEventMarker anywhere in the log, so we can handle
225 // it regardless of the expectation. However, we do se the expectation to read
226 // a set number of fixed bytes, as described in the metadata.
227 uint32_t OffsetPtr = 1; // Read after the first byte.
228 uint32_t DataSize = RecordExtractor.getU32(&OffsetPtr);
229 uint64_t TSC = RecordExtractor.getU64(&OffsetPtr);
231 // FIXME: Actually represent the record through the API. For now we only skip
234 RecordSize = 16 + DataSize;
235 return Error::success();
238 /// Advances the state machine for reading the FDR record type by reading one
239 /// Metadata Record and updating the State appropriately based on the kind of
240 /// record encountered. The RecordKind is encoded in the first byte of the
241 /// Record, which the caller should pass in because they have already read it
242 /// to determine that this is a metadata record as opposed to a function record.
243 Error processFDRMetadataRecord(FDRState &State, uint8_t RecordFirstByte,
244 DataExtractor &RecordExtractor,
245 size_t &RecordSize) {
246 // The remaining 7 bits are the RecordKind enum.
247 uint8_t RecordKind = RecordFirstByte >> 1;
248 switch (RecordKind) {
251 processFDRNewBufferRecord(State, RecordFirstByte, RecordExtractor))
254 case 1: // EndOfBuffer
255 if (auto E = processFDREndOfBufferRecord(State, RecordFirstByte,
261 processFDRNewCPUIdRecord(State, RecordFirstByte, RecordExtractor))
266 processFDRTSCWrapRecord(State, RecordFirstByte, RecordExtractor))
269 case 4: // WallTimeMarker
271 processFDRWallTimeRecord(State, RecordFirstByte, RecordExtractor))
274 case 5: // CustomEventMarker
275 if (auto E = processCustomEventMarker(State, RecordFirstByte,
276 RecordExtractor, RecordSize))
280 // Widen the record type to uint16_t to prevent conversion to char.
281 return make_error<StringError>(
282 Twine("Illegal metadata record type: ")
283 .concat(Twine(static_cast<unsigned>(RecordKind))),
284 std::make_error_code(std::errc::executable_format_error));
286 return Error::success();
289 /// Reads a function record from an FDR format log, appending a new XRayRecord
290 /// to the vector being populated and updating the State with a new value
291 /// reference value to interpret TSC deltas.
293 /// The XRayRecord constructed includes information from the function record
294 /// processed here as well as Thread ID and CPU ID formerly extracted into
296 Error processFDRFunctionRecord(FDRState &State, uint8_t RecordFirstByte,
297 DataExtractor &RecordExtractor,
298 std::vector<XRayRecord> &Records) {
299 switch (State.Expects) {
300 case FDRState::Token::NEW_BUFFER_RECORD_OR_EOF:
301 return make_error<StringError>(
302 "Malformed log. Received Function Record before new buffer setup.",
303 std::make_error_code(std::errc::executable_format_error));
304 case FDRState::Token::WALLCLOCK_RECORD:
305 return make_error<StringError>(
306 "Malformed log. Received Function Record when expecting wallclock.",
307 std::make_error_code(std::errc::executable_format_error));
308 case FDRState::Token::NEW_CPU_ID_RECORD:
309 return make_error<StringError>(
310 "Malformed log. Received Function Record before first CPU record.",
311 std::make_error_code(std::errc::executable_format_error));
313 Records.emplace_back();
314 auto &Record = Records.back();
315 Record.RecordType = 0; // Record is type NORMAL.
316 // Strip off record type bit and use the next three bits.
317 uint8_t RecordType = (RecordFirstByte >> 1) & 0x07;
318 switch (RecordType) {
319 case static_cast<uint8_t>(RecordTypes::ENTER):
320 Record.Type = RecordTypes::ENTER;
322 case static_cast<uint8_t>(RecordTypes::EXIT):
323 case 2: // TAIL_EXIT is not yet defined in RecordTypes.
324 Record.Type = RecordTypes::EXIT;
327 // When initializing the error, convert to uint16_t so that the record
328 // type isn't interpreted as a char.
329 return make_error<StringError>(
330 Twine("Illegal function record type: ")
331 .concat(Twine(static_cast<unsigned>(RecordType))),
332 std::make_error_code(std::errc::executable_format_error));
334 Record.CPU = State.CPUId;
335 Record.TId = State.ThreadId;
336 // Back up to read first 32 bits, including the 8 we pulled RecordType
337 // and RecordKind out of. The remaining 28 are FunctionId.
338 uint32_t OffsetPtr = 0;
339 // Despite function Id being a signed int on XRayRecord,
340 // when it is written to an FDR format, the top bits are truncated,
341 // so it is effectively an unsigned value. When we shift off the
342 // top four bits, we want the shift to be logical, so we read as
344 uint32_t FuncIdBitField = RecordExtractor.getU32(&OffsetPtr);
345 Record.FuncId = FuncIdBitField >> 4;
346 // FunctionRecords have a 32 bit delta from the previous absolute TSC
347 // or TSC delta. If this would overflow, we should read a TSCWrap record
348 // with an absolute TSC reading.
349 uint64_t new_tsc = State.BaseTSC + RecordExtractor.getU32(&OffsetPtr);
350 State.BaseTSC = new_tsc;
351 Record.TSC = new_tsc;
353 return Error::success();
356 /// Reads a log in FDR mode for version 1 of this binary format. FDR mode is
357 /// defined as part of the compiler-rt project in xray_fdr_logging.h, and such
358 /// a log consists of the familiar 32 bit XRayHeader, followed by sequences of
359 /// of interspersed 16 byte Metadata Records and 8 byte Function Records.
361 /// The following is an attempt to document the grammar of the format, which is
362 /// parsed by this function for little-endian machines. Since the format makes
363 /// use of BitFields, when we support big-Endian architectures, we will need to
364 /// adjust not only the endianness parameter to llvm's RecordExtractor, but also
365 /// the bit twiddling logic, which is consistent with the little-endian
366 /// convention that BitFields within a struct will first be packed into the
367 /// least significant bits the address they belong to.
369 /// We expect a format complying with the grammar in the following pseudo-EBNF.
371 /// FDRLog: XRayFileHeader ThreadBuffer*
372 /// XRayFileHeader: 32 bits to identify the log as FDR with machine metadata.
373 /// ThreadBuffer: BufSize NewBuffer WallClockTime NewCPUId FunctionSequence EOB
374 /// BufSize: 8 byte unsigned integer indicating how large the buffer is.
375 /// NewBuffer: 16 byte metadata record with Thread Id.
376 /// WallClockTime: 16 byte metadata record with human readable time.
377 /// NewCPUId: 16 byte metadata record with CPUId and a 64 bit TSC reading.
378 /// EOB: 16 byte record in a thread buffer plus mem garbage to fill BufSize.
379 /// FunctionSequence: NewCPUId | TSCWrap | FunctionRecord
380 /// TSCWrap: 16 byte metadata record with a full 64 bit TSC reading.
381 /// FunctionRecord: 8 byte record with FunctionId, entry/exit, and TSC delta.
382 Error loadFDRLog(StringRef Data, XRayFileHeader &FileHeader,
383 std::vector<XRayRecord> &Records) {
384 if (Data.size() < 32)
385 return make_error<StringError>(
386 "Not enough bytes for an XRay log.",
387 std::make_error_code(std::errc::invalid_argument));
389 // For an FDR log, there are records sized 16 and 8 bytes.
390 // There actually may be no records if no non-trivial functions are
392 if (Data.size() % 8 != 0)
393 return make_error<StringError>(
394 "Invalid-sized XRay data.",
395 std::make_error_code(std::errc::invalid_argument));
397 if (auto E = readBinaryFormatHeader(Data, FileHeader))
400 uint64_t BufferSize = 0;
402 StringRef ExtraDataRef(FileHeader.FreeFormData, 16);
403 DataExtractor ExtraDataExtractor(ExtraDataRef, true, 8);
404 uint32_t ExtraDataOffset = 0;
405 BufferSize = ExtraDataExtractor.getU64(&ExtraDataOffset);
407 FDRState State{0, 0, 0, FDRState::Token::NEW_BUFFER_RECORD_OR_EOF,
409 // RecordSize will tell the loop how far to seek ahead based on the record
410 // type that we have just read.
411 size_t RecordSize = 0;
412 for (auto S = Data.drop_front(32); !S.empty(); S = S.drop_front(RecordSize)) {
413 DataExtractor RecordExtractor(S, true, 8);
414 uint32_t OffsetPtr = 0;
415 if (State.Expects == FDRState::Token::SCAN_TO_END_OF_THREAD_BUF) {
416 RecordSize = State.CurrentBufferSize - State.CurrentBufferConsumed;
417 if (S.size() < State.CurrentBufferSize - State.CurrentBufferConsumed) {
418 return make_error<StringError>(
419 Twine("Incomplete thread buffer. Expected ") +
420 Twine(State.CurrentBufferSize - State.CurrentBufferConsumed) +
421 " remaining bytes but found " + Twine(S.size()),
422 make_error_code(std::errc::invalid_argument));
424 State.CurrentBufferConsumed = 0;
425 State.Expects = FDRState::Token::NEW_BUFFER_RECORD_OR_EOF;
428 uint8_t BitField = RecordExtractor.getU8(&OffsetPtr);
429 bool isMetadataRecord = BitField & 0x01uL;
430 if (isMetadataRecord) {
432 if (auto E = processFDRMetadataRecord(State, BitField, RecordExtractor,
435 State.CurrentBufferConsumed += RecordSize;
436 } else { // Process Function Record
438 if (auto E = processFDRFunctionRecord(State, BitField, RecordExtractor,
441 State.CurrentBufferConsumed += RecordSize;
444 // There are two conditions
445 if (State.Expects != FDRState::Token::NEW_BUFFER_RECORD_OR_EOF &&
446 !(State.Expects == FDRState::Token::SCAN_TO_END_OF_THREAD_BUF &&
447 State.CurrentBufferSize == State.CurrentBufferConsumed))
448 return make_error<StringError>(
449 Twine("Encountered EOF with unexpected state expectation ") +
450 fdrStateToTwine(State.Expects) +
451 ". Remaining expected bytes in thread buffer total " +
452 Twine(State.CurrentBufferSize - State.CurrentBufferConsumed),
453 std::make_error_code(std::errc::executable_format_error));
455 return Error::success();
458 Error loadYAMLLog(StringRef Data, XRayFileHeader &FileHeader,
459 std::vector<XRayRecord> &Records) {
460 // Load the documents from the MappedFile.
465 return make_error<StringError>("Failed loading YAML Data.", In.error());
467 FileHeader.Version = Trace.Header.Version;
468 FileHeader.Type = Trace.Header.Type;
469 FileHeader.ConstantTSC = Trace.Header.ConstantTSC;
470 FileHeader.NonstopTSC = Trace.Header.NonstopTSC;
471 FileHeader.CycleFrequency = Trace.Header.CycleFrequency;
473 if (FileHeader.Version != 1)
474 return make_error<StringError>(
475 Twine("Unsupported XRay file version: ") + Twine(FileHeader.Version),
476 std::make_error_code(std::errc::invalid_argument));
479 std::transform(Trace.Records.begin(), Trace.Records.end(),
480 std::back_inserter(Records), [&](const YAMLXRayRecord &R) {
481 return XRayRecord{R.RecordType, R.CPU, R.Type,
482 R.FuncId, R.TSC, R.TId};
484 return Error::success();
487 Expected<Trace> llvm::xray::loadTraceFile(StringRef Filename, bool Sort) {
489 if (auto EC = sys::fs::openFileForRead(Filename, Fd)) {
490 return make_error<StringError>(
491 Twine("Cannot read log from '") + Filename + "'", EC);
494 // Attempt to get the filesize.
496 if (auto EC = sys::fs::file_size(Filename, FileSize)) {
497 return make_error<StringError>(
498 Twine("Cannot read log from '") + Filename + "'", EC);
501 return make_error<StringError>(
502 Twine("File '") + Filename + "' too small for XRay.",
503 std::make_error_code(std::errc::executable_format_error));
506 // Attempt to mmap the file.
508 sys::fs::mapped_file_region MappedFile(
509 Fd, sys::fs::mapped_file_region::mapmode::readonly, FileSize, 0, EC);
511 return make_error<StringError>(
512 Twine("Cannot read log from '") + Filename + "'", EC);
515 // Attempt to detect the file type using file magic. We have a slight bias
516 // towards the binary format, and we do this by making sure that the first 4
517 // bytes of the binary file is some combination of the following byte
520 // 0x0001 0x0000 - version 1, "naive" format
521 // 0x0001 0x0001 - version 1, "flight data recorder" format
523 // YAML files dont' typically have those first four bytes as valid text so we
524 // try loading assuming YAML if we don't find these bytes.
526 // Only if we can't load either the binary or the YAML format will we yield an
528 StringRef Magic(MappedFile.data(), 4);
529 DataExtractor HeaderExtractor(Magic, true, 8);
530 uint32_t OffsetPtr = 0;
531 uint16_t Version = HeaderExtractor.getU16(&OffsetPtr);
532 uint16_t Type = HeaderExtractor.getU16(&OffsetPtr);
534 enum BinaryFormatType { NAIVE_FORMAT = 0, FLIGHT_DATA_RECORDER_FORMAT = 1 };
537 if (Version == 1 && Type == NAIVE_FORMAT) {
539 loadNaiveFormatLog(StringRef(MappedFile.data(), MappedFile.size()),
540 T.FileHeader, T.Records))
542 } else if (Version == 1 && Type == FLIGHT_DATA_RECORDER_FORMAT) {
543 if (auto E = loadFDRLog(StringRef(MappedFile.data(), MappedFile.size()),
544 T.FileHeader, T.Records))
547 if (auto E = loadYAMLLog(StringRef(MappedFile.data(), MappedFile.size()),
548 T.FileHeader, T.Records))
553 std::sort(T.Records.begin(), T.Records.end(),
554 [&](const XRayRecord &L, const XRayRecord &R) {
555 return L.TSC < R.TSC;