#
# This file is distributed under the MIT License. See LICENSE.md for details.
#

version: 1
definitions:
  - name: Function
    type: struct
    fields:
      - name: Entry
        type: MetaAddress

      - name: Blocks
        sequence:
          type: SortedVector
          elementType: BasicBlock

    key:
      - Entry

  - name: BasicBlock
    type: struct
    fields:
      - name: ID
        type: BasicBlockID

      - name: End
        doc: |
          End address of the basic block, i.e., the address where the last
          instruction ends
        type: MetaAddress

      - name: InlinedFrom
        type: MetaAddress
        optional: true
        doc: Address of the function this basic block has been inlined from

      - name: Label
        type: TaggedString

      - name: Successors
        doc: List of successor edges
        sequence:
          type: SortedVector
          upcastable: true
          elementType: FunctionEdgeBase

      - name: Instructions
        sequence:
          type: SortedVector
          elementType: Instruction

      - name: IsLabelAlwaysRequired
        doc: |
          This flag is set to `false` for basic blocks that are never directly
          pointed to, i.e. blocks that are only ever entered from the previous
          instructions and such.
          This lets us dynamically decide whether we want to show labels like this
          or not.
        type: bool

      - name: HasDelaySlot
        doc: >
          This flag is set if the last instruction of the block is in a delay slot
          and is executed at the same time as the instruction preceding it.
          \note: This is always equal to `false` on architectures that do not
          support delay slots.
        type: bool
        optional: true

    key:
      - ID
  - name: FunctionEdgeBase
    doc: An edge on the CFG
    type: struct
    fields:
      - name: Destination
        optional: true
        doc: |
          Target of the CFG edge

          If invalid, it's an indirect edge such as a return instruction or an
          indirect function call.
          If valid, it's either the address of the basic block in case of a direct
          branch, or, in case of a function call, the address of the callee.
          TODO: switch to TupleTreeReference
        type: BasicBlockID
      - name: Kind
        type: FunctionEdgeBaseKind
      - name: Type
        doc: Type of the CFG edge
        type: FunctionEdgeType
    key:
      - Destination
      - Kind
    abstract: true
  - name: FunctionEdge
    doc: An edge on the CFG
    type: struct
    inherits: FunctionEdgeBase
    fields: []
  - name: CallEdge
    doc: A CFG edge to represent function calls (direct, indirect and tail calls)
    type: struct
    inherits: FunctionEdgeBase
    fields:
      - name: DynamicFunction
        doc: |
          Name of the dynamic function being called, or empty if not a dynamic call
        type: string
        optional: true
      - name: IsTailCall
        doc: Is this a tail call?
        type: bool
        optional: true
      - name: Attributes
        doc: |
          Attributes for this function

          Note: To have the effective list of attributes for this call site, you
          have to add attributes on the called function.
          TODO: switch to std::set
        sequence:
          type: MutableSet
          elementType: model::FunctionAttribute::Values
        optional: true
  - name: FunctionEdgeType
    doc: Type of edge on the CFG
    type: enum
    members:
      - name: DirectBranch
        doc: Branch due to function-local CFG (a regular branch)
      - name: FunctionCall
        doc: A function call for which the cache was able to produce a summary
      - name: Return
        doc: A proper function return
      - name: BrokenReturn
        doc: |
          A branch returning to the return address, but leaving the stack in an
          unexpected situation
      - name: LongJmp
        doc: A branch representing a longjmp or similar constructs
      - name: Killer
        doc: A killer basic block (killer syscall or endless loop)
      - name: Unreachable
        doc: The basic block ends with an unreachable instruction
  - name: Instruction
    type: struct
    fields:
      - name: Address
        doc: >
          Indicates the address of the first byte of the instruction.
        type: MetaAddress

      - name: RawBytes
        type: yield::ByteContainer

      - name: Disassembled
        sequence:
          type: SortedVector
          elementType: TaggedString

      - name: PrecedingDirectives
        sequence:
          type: SortedVector
          elementType: TaggedLine

      - name: FollowingDirectives
        sequence:
          type: SortedVector
          elementType: TaggedLine

      - name: OpcodeIdentifier
        type: string
        optional: true

      - name: Comment
        doc: >
          Contains any extra information deduced based on the disassembly of this
          instruction that could be relevant for the user.
        type: string
        optional: true

      - name: Error
        doc: >
          Contains any extra extra warning/error style information deduced based on
          the disassembly of this instruction that could be relevant for the user.
        type: string
        optional: true

    key:
      - Address

  - name: TaggedLine
    type: struct
    fields:
      - name: Index
        type: uint64_t

      - name: Tags
        sequence:
          type: SortedVector
          elementType: TaggedString

    key:
      - Index

  - name: TaggedString
    type: struct
    fields:
      - name: Index
        type: uint64_t

      - name: Type
        type: TagType

      - name: Content
        type: string

      - name: Attributes
        sequence:
          type: SortedVector
          elementType: TagAttribute
        optional: true
    key:
      - Index

  - name: TagAttribute
    type: struct
    fields:
      - name: Name
        type: string

      - name: Value
        type: string

    key:
      - Name

  - name: TagType
    doc: Enum for identifying different instruction markup tag types
    type: enum
    members:
      - name: Untagged
      - name: Helper
      - name: Memory
      - name: Register
      - name: Immediate
      - name: Address
      - name: AbsoluteAddress
      - name: PCRelativeAddress
      - name: Mnemonic
      - name: MnemonicPrefix
      - name: MnemonicSuffix
      - name: Directive
      - name: Whitespace
      - name: Label