llvm/ProfileData/PGOCtxProfWriter.h

0001 //===- PGOCtxProfWriter.h - Contextual Profile Writer -----------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008 //
0009 // This file declares a utility for writing a contextual profile to bitstream.
0010 //
0011 //===----------------------------------------------------------------------===//
0012
0013 #ifndef LLVM_PROFILEDATA_PGOCTXPROFWRITER_H_
0014 #define LLVM_PROFILEDATA_PGOCTXPROFWRITER_H_
0015
0016 #include "llvm/ADT/StringExtras.h"
0017 #include "llvm/Bitstream/BitCodeEnums.h"
0018 #include "llvm/Bitstream/BitstreamWriter.h"
0019 #include "llvm/ProfileData/CtxInstrContextNode.h"
0020
0021 namespace llvm {
0022 enum PGOCtxProfileRecords { Invalid = 0, Version, Guid, CalleeIndex, Counters };
0023
0024 enum PGOCtxProfileBlockIDs {
0025   ProfileMetadataBlockID = bitc::FIRST_APPLICATION_BLOCKID,
0026   ContextNodeBlockID = ProfileMetadataBlockID + 1
0027 };
0028
0029 /// Write one or more ContextNodes to the provided raw_fd_stream.
0030 /// The caller must destroy the PGOCtxProfileWriter object before closing the
0031 /// stream.
0032 /// The design allows serializing a bunch of contexts embedded in some other
0033 /// file. The overall format is:
0034 ///
0035 ///  [... other data written to the stream...]
0036 ///  SubBlock(ProfileMetadataBlockID)
0037 ///   Version
0038 ///   SubBlock(ContextNodeBlockID)
0039 ///     [RECORDS]
0040 ///     SubBlock(ContextNodeBlockID)
0041 ///       [RECORDS]
0042 ///       [... more SubBlocks]
0043 ///     EndBlock
0044 ///   EndBlock
0045 ///
0046 /// The "RECORDS" are bitsream records. The IDs are in CtxProfileCodes (except)
0047 /// for Version, which is just for metadata). All contexts will have Guid and
0048 /// Counters, and all but the roots have CalleeIndex. The order in which the
0049 /// records appear does not matter, but they must precede any subcontexts,
0050 /// because that helps keep the reader code simpler.
0051 ///
0052 /// Subblock containment captures the context->subcontext relationship. The
0053 /// "next()" relationship in the raw profile, between call targets of indirect
0054 /// calls, are just modeled as peer subblocks where the callee index is the
0055 /// same.
0056 ///
0057 /// Versioning: the writer may produce additional records not known by the
0058 /// reader. The version number indicates a more structural change.
0059 /// The current version, in particular, is set up to expect optional extensions
0060 /// like value profiling - which would appear as additional records. For
0061 /// example, value profiling would produce a new record with a new record ID,
0062 /// containing the profiled values (much like the counters)
0063 class PGOCtxProfileWriter final {
0064   BitstreamWriter Writer;
0065
0066   void writeCounters(const ctx_profile::ContextNode &Node);
0067   void writeImpl(std::optional<uint32_t> CallerIndex,
0068                  const ctx_profile::ContextNode &Node);
0069
0070 public:
0071   PGOCtxProfileWriter(raw_ostream &Out,
0072                       std::optional<unsigned> VersionOverride = std::nullopt);
0073   ~PGOCtxProfileWriter() { Writer.ExitBlock(); }
0074
0075   void write(const ctx_profile::ContextNode &);
0076
0077   // constants used in writing which a reader may find useful.
0078   static constexpr unsigned CodeLen = 2;
0079   static constexpr uint32_t CurrentVersion = 1;
0080   static constexpr unsigned VBREncodingBits = 6;
0081   static constexpr StringRef ContainerMagic = "CTXP";
0082 };
0083
0084 Error createCtxProfFromYAML(StringRef Profile, raw_ostream &Out);
0085 } // namespace llvm
0086 #endif