xref: /aosp_15_r20/external/emboss/compiler/util/ir_data.py (revision 99e0aae7469b87d12f0ad23e61142c2d74c1ef70)

# Copyright 2019 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Intermediate representation (IR) for Emboss.

This is limited to purely data and type annotations.
"""

import dataclasses
import enum
import sys
from typing import ClassVar, Optional

from compiler.util import ir_data_fields


@dataclasses.dataclass
class Message:
  """Base class for IR data objects.

  Historically protocol buffers were used for serializing this data which has
  led to some legacy naming conventions and references. In particular this
  class is named `Message` in the sense of a protocol buffer message,
  indicating that it is intended to just be data that is used by other higher
  level services.

  There are some other legacy idioms leftover from the protocol buffer-based
  definition such as support for "oneof" and optional fields.
  """

  IR_DATACLASS: ClassVar[object] = object()
  field_specs: ClassVar[ir_data_fields.FilteredIrFieldSpecs]

  def __post_init__(self):
    """Called by dataclass subclasses after init.

    Post-processes any lists passed in to use our custom list type.
    """
    # Convert any lists passed in to CopyValuesList
    for spec in self.field_specs.sequence_field_specs:
      cur_val = getattr(self, spec.name)
      if isinstance(cur_val, ir_data_fields.TemporaryCopyValuesList):
        copy_val = cur_val.temp_list
      else:
        copy_val = ir_data_fields.CopyValuesList(spec.data_type)
        if cur_val:
          copy_val.shallow_copy(cur_val)
      setattr(self, spec.name, copy_val)

  # This hook adds a 15% overhead to end-to-end code generation in some cases
  # so we guard it in a `__debug__` block. Users can opt-out of this check by
  # running python with the `-O` flag, ie: `python3 -O ./embossc`.
  if __debug__:
    def __setattr__(self, name: str, value) -> None:
      """Debug-only hook that adds basic type checking for ir_data fields."""
      if spec := self.field_specs.all_field_specs.get(name):
        if not (
            # Check if it's the expected type
            isinstance(value, spec.data_type) or
            # Oneof fields are a special case
            spec.is_oneof or
            # Optional fields can be set to None
            (spec.container is ir_data_fields.FieldContainer.OPTIONAL and
                 value is None) or
            # Sequences can be a few variants of lists
            (spec.is_sequence and
                 isinstance(value, (
                    list, ir_data_fields.TemporaryCopyValuesList,
                    ir_data_fields.CopyValuesList))) or
            # An enum value can be an int
            (spec.is_enum and isinstance(value, int))):
          raise AttributeError(
            f"Cannot set {value} (type {value.__class__}) for type"
             "{spec.data_type}")
      object.__setattr__(self, name, value)

  # Non-PEP8 name to mimic the Google Protobuf interface.
  def HasField(self, name):  # pylint:disable=invalid-name
    """Indicates if this class has the given field defined and it is set."""
    return getattr(self, name, None) is not None

  # Non-PEP8 name to mimic the Google Protobuf interface.
  def WhichOneof(self, oneof_name):  # pylint:disable=invalid-name
    """Indicates which field has been set for the oneof value.

    Returns None if no field has been set.
    """
    for field_name, oneof in self.field_specs.oneof_mappings:
      if oneof == oneof_name and self.HasField(field_name):
        return field_name
    return None


################################################################################
# From here to the end of the file are actual structure definitions.


@dataclasses.dataclass
class Position(Message):
  """A zero-width position within a source file."""

  line: int = 0
  """Line (starts from 1)."""
  column: int = 0
  """Column (starts from 1)."""


@dataclasses.dataclass
class Location(Message):
  """A half-open start:end range within a source file."""

  start: Optional[Position] = None
  """Beginning of the range"""
  end: Optional[Position] = None
  """One column past the end of the range."""

  is_disjoint_from_parent: Optional[bool] = None
  """True if this Location is outside of the parent object's Location."""

  is_synthetic: Optional[bool] = None
  """True if this Location's parent was synthesized, and does not directly
  appear in the source file.

  The Emboss front end uses this field to cull
  irrelevant error messages.
  """


@dataclasses.dataclass
class Word(Message):
  """IR for a bare word in the source file.

  This is used in NameDefinitions and References.
  """

  text: Optional[str] = None
  source_location: Optional[Location] = None


@dataclasses.dataclass
class String(Message):
  """IR for a string in the source file."""

  text: Optional[str] = None
  source_location: Optional[Location] = None


@dataclasses.dataclass
class Documentation(Message):
  text: Optional[str] = None
  source_location: Optional[Location] = None


@dataclasses.dataclass
class BooleanConstant(Message):
  """IR for a boolean constant."""

  value: Optional[bool] = None
  source_location: Optional[Location] = None


@dataclasses.dataclass
class Empty(Message):
  """Placeholder message for automatic element counts for arrays."""

  source_location: Optional[Location] = None


@dataclasses.dataclass
class NumericConstant(Message):
  """IR for any numeric constant."""

  # Numeric constants are stored as decimal strings; this is the simplest way
  # to store the full -2**63..+2**64 range.
  #
  # TODO(bolms): switch back to int, and just use strings during
  # serialization, now that we're free of proto.
  value: Optional[str] = None
  source_location: Optional[Location] = None


class FunctionMapping(int, enum.Enum):
  """Enum of supported function types"""

  UNKNOWN = 0
  ADDITION = 1
  """`+`"""
  SUBTRACTION = 2
  """`-`"""
  MULTIPLICATION = 3
  """`*`"""
  EQUALITY = 4
  """`==`"""
  INEQUALITY = 5
  """`!=`"""
  AND = 6
  """`&&`"""
  OR = 7
  """`||`"""
  LESS = 8
  """`<`"""
  LESS_OR_EQUAL = 9
  """`<=`"""
  GREATER = 10
  """`>`"""
  GREATER_OR_EQUAL = 11
  """`>=`"""
  CHOICE = 12
  """`?:`"""
  MAXIMUM = 13
  """`$max()`"""
  PRESENCE = 14
  """`$present()`"""
  UPPER_BOUND = 15
  """`$upper_bound()`"""
  LOWER_BOUND = 16
  """`$lower_bound()`"""


@dataclasses.dataclass
class Function(Message):
  """IR for a single function (+, -, *, ==, $max, etc.) in an expression."""

  function: Optional[FunctionMapping] = None
  args: list["Expression"] = ir_data_fields.list_field(lambda: Expression)
  function_name: Optional[Word] = None
  source_location: Optional[Location] = None


@dataclasses.dataclass
class CanonicalName(Message):
  """CanonicalName is the unique, absolute name for some object.

  A CanonicalName is the unique, absolute name for some object (Type, field,
  etc.) in the IR.  It is used both in the definitions of objects ("struct
  Foo"), and in references to objects (a field of type "Foo").
  """

  module_file: str = ir_data_fields.str_field()
  """The module_file is the Module.source_file_name of the Module in which this
  object's definition appears.

  Note that the Prelude always has a Module.source_file_name of "", and thus
  references to Prelude names will have module_file == "".
  """

  object_path: list[str] = ir_data_fields.list_field(str)
  """The object_path is the canonical path to the object definition within its
  module file.

  For example, the field "bar" would have an object path of
  ["Foo", "bar"]:

  struct Foo:
    0:3  UInt  bar


  The enumerated name "BOB" would have an object path of ["Baz", "Qux",
  "BOB"]:

  struct Baz:
    0:3  Qux   qux

    enum Qux:
      BOB = 0
  """


@dataclasses.dataclass
class NameDefinition(Message):
  """NameDefinition is IR for the name of an object, within the object.

  That is, a TypeDefinition or Field will hold a NameDefinition as its
  name.
  """

  name: Optional[Word] = None
  """The name, as directly generated from the source text.

  name.text will match the last element of canonical_name.object_path. Note
  that in some cases, the exact string in name.text may not appear in the
  source text.
  """

  canonical_name: Optional[CanonicalName] = None
  """The CanonicalName that will appear in References.
  This field is technically redundant: canonical_name.module_file should always
  match the source_file_name of the enclosing Module, and
  canonical_name.object_path should always match the names of parent nodes.
  """

  is_anonymous: Optional[bool] = None
  """If true, indicates that this is an automatically-generated name, which
  should not be visible outside of its immediate namespace.
  """

  source_location: Optional[Location] = None
  """The location of this NameDefinition in source code."""


@dataclasses.dataclass
class Reference(Message):
  """A Reference holds the canonical name of something defined elsewhere.

  For example, take this fragment:

   struct Foo:
    0:3  UInt    size (s)
    4:s  Int:8[] payload

  "Foo", "size", and "payload" will become NameDefinitions in their
  corresponding Field and Message IR objects, while "UInt", the second "s",
  and "Int" are References.  Note that the second "s" will have a
  canonical_name.object_path of ["Foo", "size"], not ["Foo", "s"]: the
  Reference always holds the single "true" name of the object, regardless of
  what appears in the .emb.
  """

  canonical_name: Optional[CanonicalName] = None
  """The canonical name of the object being referred to.

  This name should be used to find the object in the IR.
  """

  source_name: list[Word] = ir_data_fields.list_field(Word)
  """The source_name is the name the user entered in the source file.

  The source_name could be either relative or absolute, and may be an alias
  (and thus not match any part of the canonical_name).  Back ends should use
  canonical_name for name lookup, and reserve source_name for error messages.
  """

  is_local_name: Optional[bool] = None
  """If true, then symbol resolution should only look at local names when
  resolving source_name.

  This is used so that the names of inline types aren't "ambiguous" if there
  happens to be another type with the same name at a parent scope.
  """

  # TODO(bolms): Allow absolute paths starting with ".".

  source_location: Optional[Location] = None
  """Note that this is the source_location of the *Reference*, not of the
  object to which it refers.
  """


@dataclasses.dataclass
class FieldReference(Message):
  """IR for a "field" or "field.sub.subsub" reference in an expression.

  The first element of "path" is the "base" field, which should be directly
  readable in the (runtime) context of the expression.  For example:

    struct Foo:
     0:1  UInt      header_size (h)
     0:h  UInt:8[]  header_bytes

  The "h" will translate to ["Foo", "header_size"], which will be the first
  (and in this case only) element of "path".

  Subsequent path elements should be treated as subfields.  For example, in:

    struct Foo:
     struct Sizes:
      0:1  UInt  header_size
      1:2  UInt  body_size
     0                 [+2]                  Sizes     sizes
     0                 [+sizes.header_size]  UInt:8[]  header
     sizes.header_size [+sizes.body_size]    UInt:8[]  body

  The references to "sizes.header_size" will have a path of [["Foo",
  "sizes"], ["Foo", "Sizes", "header_size"]].  Note that each path element is
  a fully-qualified reference; some back ends (C++, Python) may only use the
  last element, while others (C) may use the complete path.

  This representation is a bit awkward, and is fundamentally limited to a
  dotted list of static field names.  It does not allow an expression like
  `array[n]` on the left side of a `.`.  At this point, it is an artifact of
  the era during which I (bolms@) thought I could get away with skipping
  compiler-y things.
  """

  # TODO(bolms): Add composite types to the expression type system, and
  # replace FieldReference with a "member access" Expression kind.  Further,
  # move the symbol resolution for FieldReferences that is currently in
  # symbol_resolver.py into type_check.py.

  # TODO(bolms): Make the above change before declaring the IR to be "stable".

  path: list[Reference] = ir_data_fields.list_field(Reference)
  source_location: Optional[Location] = None


@dataclasses.dataclass
class OpaqueType(Message):
  pass


@dataclasses.dataclass
class IntegerType(Message):
  """Type of an integer expression."""

  # For optimization, the modular congruence of an integer expression is
  # tracked.  This consists of a modulus and a modular_value, such that for
  # all possible values of expression, expression MOD modulus ==
  # modular_value.
  #
  # The modulus may be the special value "infinity" to indicate that the
  # expression's value is exactly modular_value; otherwise, it should be a
  # positive integer.
  #
  # A modulus of 1 places no constraints on the value.
  #
  # The modular_value should always be a nonnegative integer that is smaller
  # than the modulus.
  #
  # Note that this is specifically the *modulus*, which is not equivalent to
  # the value from C's '%' operator when the dividend is negative: in C, -7 %
  # 4 == -3, but the modular_value here would be 1.  Python uses modulus: in
  # Python, -7 % 4 == 1.
  modulus: Optional[str] = None
  """The modulus portion of the modular congruence of an integer expression.

  The modulus may be the special value "infinity" to indicate that the
  expression's value is exactly modular_value; otherwise, it should be a
  positive integer.

  A modulus of 1 places no constraints on the value.
  """
  modular_value: Optional[str] = None
  """ The modular_value portion of the modular congruence of an integer expression.

  The modular_value should always be a nonnegative integer that is smaller
  than the modulus.
  """

  # The minimum and maximum values of an integer are tracked and checked so
  # that Emboss can implement reliable arithmetic with no operations
  # overflowing either 64-bit unsigned or 64-bit signed 2's-complement
  # integers.
  #
  # Note that constant subexpressions are allowed to overflow, as long as the
  # final, computed constant value of the subexpression fits in a 64-bit
  # value.
  #
  # The minimum_value may take the value "-infinity", and the maximum_value
  # may take the value "infinity".  These sentinel values indicate that
  # Emboss has no bound information for the Expression, and therefore the
  # Expression may only be evaluated during compilation; the back end should
  # never need to compile such an expression into the target language (e.g.,
  # C++).
  minimum_value: Optional[str] = None
  maximum_value: Optional[str] = None


@dataclasses.dataclass
class BooleanType(Message):
  value: Optional[bool] = None


@dataclasses.dataclass
class EnumType(Message):
  name: Optional[Reference] = None
  value: Optional[str] = None


@dataclasses.dataclass
class ExpressionType(Message):
  opaque: Optional[OpaqueType] = ir_data_fields.oneof_field("type")
  integer: Optional[IntegerType] = ir_data_fields.oneof_field("type")
  boolean: Optional[BooleanType] = ir_data_fields.oneof_field("type")
  enumeration: Optional[EnumType] = ir_data_fields.oneof_field("type")


@dataclasses.dataclass
class Expression(Message):
  """IR for an expression.

  An Expression is a potentially-recursive data structure.  It can either
  represent a leaf node (constant or reference) or an operation combining
  other Expressions (function).
  """

  constant: Optional[NumericConstant] = ir_data_fields.oneof_field("expression")
  constant_reference: Optional[Reference] = ir_data_fields.oneof_field(
      "expression"
  )
  function: Optional[Function] = ir_data_fields.oneof_field("expression")
  field_reference: Optional[FieldReference] = ir_data_fields.oneof_field(
      "expression"
  )
  boolean_constant: Optional[BooleanConstant] = ir_data_fields.oneof_field(
      "expression"
  )
  builtin_reference: Optional[Reference] = ir_data_fields.oneof_field(
      "expression"
  )

  type: Optional[ExpressionType] = None
  source_location: Optional[Location] = None


@dataclasses.dataclass
class ArrayType(Message):
  """IR for an array type ("Int:8[12]" or "Message[2]" or "UInt[3][2]")."""

  base_type: Optional["Type"] = None

  element_count: Optional[Expression] = ir_data_fields.oneof_field("size")
  automatic: Optional[Empty] = ir_data_fields.oneof_field("size")

  source_location: Optional[Location] = None


@dataclasses.dataclass
class AtomicType(Message):
  """IR for a non-array type ("UInt" or "Foo(Version.SIX)")."""

  reference: Optional[Reference] = None
  runtime_parameter: list[Expression] = ir_data_fields.list_field(Expression)
  source_location: Optional[Location] = None


@dataclasses.dataclass
class Type(Message):
  """IR for a type reference ("UInt", "Int:8[12]", etc.)."""

  atomic_type: Optional[AtomicType] = ir_data_fields.oneof_field("type")
  array_type: Optional[ArrayType] = ir_data_fields.oneof_field("type")

  size_in_bits: Optional[Expression] = None
  source_location: Optional[Location] = None


@dataclasses.dataclass
class AttributeValue(Message):
  """IR for a attribute value."""

  # TODO(bolms): Make String a type of Expression, and replace
  # AttributeValue with Expression.
  expression: Optional[Expression] = ir_data_fields.oneof_field("value")
  string_constant: Optional[String] = ir_data_fields.oneof_field("value")

  source_location: Optional[Location] = None


@dataclasses.dataclass
class Attribute(Message):
  """IR for a [name = value] attribute."""

  name: Optional[Word] = None
  value: Optional[AttributeValue] = None
  back_end: Optional[Word] = None
  is_default: Optional[bool] = None
  source_location: Optional[Location] = None


@dataclasses.dataclass
class WriteTransform(Message):
  """IR which defines an expression-based virtual field write scheme.

  E.g., for a virtual field like `x_plus_one`:

    struct Foo:
     0 [+1]  UInt  x
     let x_plus_one = x + 1

  ... the `WriteMethod` would be `transform`, with `$logical_value - 1` for
  `function_body` and `x` for `destination`.
  """

  function_body: Optional[Expression] = None
  destination: Optional[FieldReference] = None


@dataclasses.dataclass
class WriteMethod(Message):
  """IR which defines the method used for writing to a virtual field."""

  physical: Optional[bool] = ir_data_fields.oneof_field("method")
  """A physical Field can be written directly."""

  read_only: Optional[bool] = ir_data_fields.oneof_field("method")
  """A read_only Field cannot be written."""

  alias: Optional[FieldReference] = ir_data_fields.oneof_field("method")
  """An alias is a direct, untransformed forward of another field; it can be
  implemented by directly returning a reference to the aliased field.

  Aliases are the only kind of virtual field that may have an opaque type.
  """

  transform: Optional[WriteTransform] = ir_data_fields.oneof_field("method")
  """A transform is a way of turning a logical value into a value which should
  be written to another field.

  A virtual field like `let y = x + 1` would
  have a transform WriteMethod to subtract 1 from the new `y` value, and
  write that to `x`.
  """


@dataclasses.dataclass
class FieldLocation(Message):
  """IR for a field location."""

  start: Optional[Expression] = None
  size: Optional[Expression] = None
  source_location: Optional[Location] = None


@dataclasses.dataclass
class Field(Message):  # pylint:disable=too-many-instance-attributes
  """IR for a field in a struct definition.

  There are two kinds of Field: physical fields have location and (physical)
  type; virtual fields have read_transform.  Although there are differences,
  in many situations physical and virtual fields are treated the same way,
  and they can be freely intermingled in the source file.
  """

  location: Optional[FieldLocation] = None
  """The physical location of the field."""
  type: Optional[Type] = None
  """The physical type of the field."""

  read_transform: Optional[Expression] = None
  """The value of a virtual field."""

  write_method: Optional[WriteMethod] = None
  """How this virtual field should be written."""

  name: Optional[NameDefinition] = None
  """The name of the field."""
  abbreviation: Optional[Word] = None
  """An optional short name for the field, only visible inside the enclosing bits/struct."""
  attribute: list[Attribute] = ir_data_fields.list_field(Attribute)
  """Field-specific attributes."""
  documentation: list[Documentation] = ir_data_fields.list_field(Documentation)
  """Field-specific documentation."""

  # TODO(bolms): Document conditional fields better, and replace some of this
  # explanation with a reference to the documentation.
  existence_condition: Optional[Expression] = None
  """The field only exists when existence_condition evaluates to true.

  For example:
  ```
  struct Message:
    0 [+4]  UInt         length
    4 [+8]  MessageType  message_type
    if message_type == MessageType.FOO:
      8 [+length]  Foo   foo
    if message_type == MessageType.BAR:
      8 [+length]  Bar   bar
    8+length [+4]  UInt  crc
  ```
  For `length`, `message_type`, and `crc`, existence_condition will be
  `boolean_constant { value: true }`

  For `foo`, existence_condition will be:
  ```
      function { function: EQUALITY
                 args: [reference to message_type]
                 args: { [reference to MessageType.FOO] } }
  ```

  The `bar` field will have a similar existence_condition to `foo`:
  ```
      function { function: EQUALITY
                 args: [reference to message_type]
                 args: { [reference to MessageType.BAR] } }
  ```

  When `message_type` is `MessageType.BAR`, the `Message` struct does not contain
  field `foo`, and vice versa for `message_type == MessageType.FOO` and field
  `bar`: those fields only conditionally exist in the structure.
  """

  source_location: Optional[Location] = None


@dataclasses.dataclass
class Structure(Message):
  """IR for a bits or struct definition."""

  field: list[Field] = ir_data_fields.list_field(Field)

  fields_in_dependency_order: list[int] = ir_data_fields.list_field(int)
  """The fields in `field` are listed in the order they appear in the original
  .emb.

  For text format output, this can lead to poor results.  Take the following
  struct:
  ```
      struct Foo:
        b [+4]  UInt  a
        0 [+4]  UInt  b
  ```
  Here, the location of `a` depends on the current value of `b`.  Because of
  this, if someone calls
  ```
      emboss::UpdateFromText(foo_view, "{ a: 10, b: 4 }");
  ```
  then foo_view will not be updated the way one would expect: if `b`'s value
  was something other than 4 to start with, then `UpdateFromText` will write
  the 10 to some other location, then update `b` to 4.

  To avoid surprises, `emboss::DumpAsText` should return `"{ b: 4, a: 10
  }"`.

  The `fields_in_dependency_order` field provides a permutation of `field`
  such that each field appears after all of its dependencies.  For example,
  `struct Foo`, above, would have `{ 1, 0 }` in
  `fields_in_dependency_order`.

  The exact ordering of `fields_in_dependency_order` is not guaranteed, but
  some effort is made to keep the order close to the order fields are listed
  in the original `.emb` file.  In particular, if the ordering 0, 1, 2, 3,
  ... satisfies dependency ordering, then `fields_in_dependency_order` will
  be `{ 0, 1, 2, 3, ... }`.
  """

  source_location: Optional[Location] = None


@dataclasses.dataclass
class External(Message):
  """IR for an external type declaration."""

  # Externals have no values other than name and attribute list, which are
  # common to all type definitions.

  source_location: Optional[Location] = None


@dataclasses.dataclass
class EnumValue(Message):
  """IR for a single value within an enumerated type."""

  name: Optional[NameDefinition] = None
  """The name of the enum value."""
  value: Optional[Expression] = None
  """The value of the enum value."""
  documentation: list[Documentation] = ir_data_fields.list_field(Documentation)
  """Value-specific documentation."""
  attribute: list[Attribute] = ir_data_fields.list_field(Attribute)
  """Value-specific attributes."""

  source_location: Optional[Location] = None


@dataclasses.dataclass
class Enum(Message):
  """IR for an enumerated type definition."""

  value: list[EnumValue] = ir_data_fields.list_field(EnumValue)
  source_location: Optional[Location] = None


@dataclasses.dataclass
class Import(Message):
  """IR for an import statement in a module."""

  file_name: Optional[String] = None
  """The file to import."""
  local_name: Optional[Word] = None
  """The name to use within this module."""
  source_location: Optional[Location] = None


@dataclasses.dataclass
class RuntimeParameter(Message):
  """IR for a runtime parameter definition."""

  name: Optional[NameDefinition] = None
  """The name of the parameter."""
  type: Optional[ExpressionType] = None
  """The type of the parameter."""

  # TODO(bolms): Actually implement the set builder type notation.
  physical_type_alias: Optional[Type] = None
  """For convenience and readability, physical types may be used in the .emb
  source instead of a full expression type.

  That way, users can write
  something like:
  ```
      struct Foo(version :: UInt:8):
  ```
  instead of:
  ```
      struct Foo(version :: {$int x |: 0 <= x <= 255}):
  ```
  In these cases, physical_type_alias holds the user-supplied type, and type
  is filled in after initial parsing is finished.
  """

  source_location: Optional[Location] = None


class AddressableUnit(int, enum.Enum):
  """The "addressable unit" is the size of the smallest unit that can be read

  from the backing store that this type expects.  For `struct`s, this is
  BYTE; for `enum`s and `bits`, this is BIT, and for `external`s it depends
  on the specific type
  """

  NONE = 0
  BIT = 1
  BYTE = 8


@dataclasses.dataclass
class TypeDefinition(Message):
  """Container IR for a type definition (struct, union, etc.)"""

  external: Optional[External] = ir_data_fields.oneof_field("type")
  enumeration: Optional[Enum] = ir_data_fields.oneof_field("type")
  structure: Optional[Structure] = ir_data_fields.oneof_field("type")

  name: Optional[NameDefinition] = None
  """The name of the type."""
  attribute: list[Attribute] = ir_data_fields.list_field(Attribute)
  """All attributes attached to the type."""
  documentation: list[Documentation] = ir_data_fields.list_field(Documentation)
  """Docs for the type."""
  # pylint:disable=undefined-variable
  subtype: list["TypeDefinition"] = ir_data_fields.list_field(
      lambda: TypeDefinition
  )
  """Subtypes of this type."""
  addressable_unit: Optional[AddressableUnit] = None

  runtime_parameter: list[RuntimeParameter] = ir_data_fields.list_field(
      RuntimeParameter
  )
  """If the type requires parameters at runtime, these are its parameters.

  These are currently only allowed on structures, but in the future they
  should be allowed on externals.
  """
  source_location: Optional[Location] = None


@dataclasses.dataclass
class Module(Message):
  """The IR for an individual Emboss module (file)."""

  attribute: list[Attribute] = ir_data_fields.list_field(Attribute)
  """Module-level attributes."""
  type: list[TypeDefinition] = ir_data_fields.list_field(TypeDefinition)
  """Module-level type definitions."""
  documentation: list[Documentation] = ir_data_fields.list_field(Documentation)
  """Module-level docs."""
  foreign_import: list[Import] = ir_data_fields.list_field(Import)
  """Other modules imported."""
  source_text: Optional[str] = None
  """The original source code."""
  source_location: Optional[Location] = None
  """Source code covered by this IR."""
  source_file_name: Optional[str] = None
  """Name of the source file."""


@dataclasses.dataclass
class EmbossIr(Message):
  """The top-level IR for an Emboss module and all of its dependencies."""

  module: list[Module] = ir_data_fields.list_field(Module)
  """All modules.

  The first entry will be the main module; back ends should
  generate code corresponding to that module.  The second entry will be the
  prelude module.
  """


# Post-process the dataclasses to add cached fields.
ir_data_fields.cache_message_specs(sys.modules[Message.__module__], Message)