Add some documentation on the CAS Schema in MCCASObjectV1.h

llvm/include/llvm/MC/CAS/MCCASObjectV1.h

@@ -6,6 +6,104 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// \verbatim
+/// CAS Schema:
+///
+/// Debug Line Section
+/// The .debug_line section is stored as one CAS object per line table program.
+/// All relocations in the line table programs are zeroed out to maximize
+/// deduplication.
+///
+/// DebugLineSectionRef: The DebugLineSectionRef represents the .debug_line
+/// section, it contains the relocations for that section as well as any addends
+/// and their offsets and sizes, that were zero-ed out for deduplication
+/// purposes. A DebugLineSectionRef has edges to one or more DebugLine Ref.
+///
+/// DebugLineRef: The DebugLineRef represents one function's contribution to the
+/// debug_line section, or one line table. Each function has its own line
+/// table entry in the debug_line section when compiled with
+/// -fcas-friendly-debug-info.
+///
+/// ┌─────────────────┐
+/// │  DebugLineRef   │
+/// │  [Line Table 1] │
+/// │                 │         ┌──────────────────────┐
+/// └──────────▲──────┘         │  DebugLineSectionRef │
+///       .    ├────────────────┤                      │
+///       .    │                │     [Relocations]    │
+///       .    │                │     [Addends]        │
+/// ┌──────────▼──────┐         └──────────────────────┘
+/// │  DebugLineRef   │
+/// │  [Line Table N] │
+/// │                 │
+/// └─────────────────┘
+///
+/// Debug String Section
+///
+/// DebugStringSectionRef: The DebugStringSectionRef represents the debug_str
+/// section. This object is empty and has one edge per string. The order of the
+/// strings is implicitly encoded as the order of edges.
+///
+/// DebugStrRef: A DebugStrRef represents one string in the debug_str section,
+/// each string gets its own cas object.
+///                         ┌────────────────┐
+///            ┌────────────┤  DebugString   ├───────────┐
+///            │            │  SectionRef    │           │
+///            │            └────────────────┘           │
+///     ┌──────▼───────┐                         ┌───────▼──────┐
+///     | DebugStrRef  │                         │ DebugStrRef  |
+///     │ [String 1]   │          ...            │ [String N]   │
+///     └──────────────┘                         └──────────────┘
+///
+///
+/// Debug Info Section
+///
+/// DebugInfoSectionRef: The DebugInfoSectionRef represents the .debug_info
+/// section, it contains the relocations for that section as well as any addends
+/// and their offsets and sizes, that were zero-ed out for deduplication
+/// purposes.
+///
+/// DistinctDataRef: The DistinctDataRef is one CAS block per translation unit
+/// (object file) that contains all the information from all compile units that
+/// is not expected to deduplicate.
+///
+/// AbbrevOffsetRef: The AbbrevOffsetRef is one CAS block per translation unit
+/// that contains all the abbreviation offsets of every compile unit in that
+/// translation unit.
+///
+/// DebugInfoCURef: A DebugInfoCURef represents one function's contribution to
+/// the debug_info section, i.e. one compile unit. When compiling with
+/// -fcas-friendly each function is stored in its own compile unit instead of
+/// the whole translation unit being in one compile unit. The DebugInfoCURef
+/// contains only the data in the compile unit that is expected to deduplicate.
+///
+///                                         ┌───────────────────────┐
+///    ┌────────────────────────────┐       │  DebugInfoSectionRef  │
+///    │ DistinctDataRef            |◄──┬───┤                       │
+///    │ [Data that doesn't dedupe] │   │   │                       │
+///    │ [FormsToPartition]         │   │   │     [Relocations]     │
+///    └────────────────────────────┘   │   │     [Addends]         │
+///                                     │   └────┬─────┬────────────┘
+///    ┌────────────────────────┐       │        │     │
+///    │ AbbrevOffsetRef        |◄──────┘        │     │
+///    │ [Abbrev Offset per CU] │                │     │
+///    └────────────────────────┘                │     │
+///                                              │     │
+///    ┌───────────────────────────┐             │     │
+///    |  DebugInfoCURef 1         │             │     │
+///    │ [CU data that does dedupe]|◄────────────┘     │
+///    │                           │                   │
+///    └───────────────────────────┘                   │
+///                  .                                 |
+///                  .                                 │
+///                  .                                 │
+///    ┌───────────────────────────┐                   │
+///    │  DebugInfoCURef N         │                   │
+///    │ [CU data that does dedupe]|◄──────────────────┘
+///    │                           │
+///    └───────────────────────────┘
+/// \endverbatim
+
 #ifndef LLVM_MC_CAS_MCCASOBJECTV1_H
 #define LLVM_MC_CAS_MCCASOBJECTV1_H