SSBM Decomp
Loading...
Searching...
No Matches
dat_macros.h File Reference

Annotations describing how archive data is laid out, for the parts a C declaration cannot express: how many elements a pointer refers to, and which member of a union is valid. More...

Go to the source code of this file.

Macros

#define DAT_TAG(tag)
#define DAT_COUNT(count)
 The array holds, or the pointer refers to, count elements: an expression of sibling fields (or their members, x0.count) and constants, which may call the functions the tool ports, e.g.
#define DAT_TERMINATED(...)
 The pointer refers to elements up to and including a terminator: the first element whose first word is value and not a relocated pointer, e.g.
#define DAT_EXTENT   DAT_TAG("extent")
 The array holds as many elements as the data does: they continue until the next symbol, the next address a pointer refers to, or an element that no longer fits the element type.
#define DAT_IF(cond)
 The union member is valid when cond holds: a C expression over the fields of the record containing the union, and macros.
#define DAT_BIND(name, value)
 name, conventionally Type::field for a value that belongs to Type but is not stored in it, is value for everything reached through the member: its own layout and every pointer followed from within it.
#define DAT_MATCH(name, values, ...)
 Bind name to the result of matching the tuple values against the remaining arguments: (pattern, ...): value cases, ending with _: value.
#define DAT_SCRIPT(...)
 The pointer refers to a command script: commands of whole words, each with its opcode in the top 6 bits of its first byte, up to one with opcode 0.
#define DAT_BYTE_SCRIPT(length)
 A pointer to a byte command script.
#define DAT_BLOB   DAT_TAG("blob")
 On a typedef of u8: the bytes are data of one format the archive doesn't break down further, such as an animation's keyframe stream.
#define DAT_TYPE(type)
 The untyped pointer, or pointer-sized integer, refers to a type when it is relocated.
Roots

Archive symbols the game looks up by name are the roots every other part of an archive is reached from.

Loaders taking (&dst, "name") pairs wrap their calls in DAT_ROOTS, which declares one static witness per pair: its type is the type of &dst, and its dat:root annotation holds the name argument as written, a string literal or an expression.

#define DAT_ROOTS(...)

Detailed Description

Annotations describing how archive data is laid out, for the parts a C declaration cannot express: how many elements a pointer refers to, and which member of a union is valid.

They expand to nothing for every compiler except clang with DAT_ANNOTATIONS defined, where they become btf_decl_tag attributes that clang emits into DWARF as DW_TAG_LLVM_annotation. The arguments are kept as written, so constants are resolved by name through the DWARF macro table.

Union members are tested in declaration order; the first match is valid. A condition that can't be evaluated stops the search, so a last member marked DAT_IF(true) is a catch-all for the others. If every member has a condition and none holds, the union is unused.

Macro Definition Documentation

◆ DAT_TAG

#define DAT_TAG ( tag)

◆ DAT_COUNT

#define DAT_COUNT ( count)
Value:
DAT_TAG("count(" #count ")")
#define DAT_TAG(tag)
Definition dat_macros.h:23

The array holds, or the pointer refers to, count elements: an expression of sibling fields (or their members, x0.count) and constants, which may call the functions the tool ports, e.g.

GXGetTexBufferSize. On a pointer typedef, for lists of counted lists, names resolve to bindings (DAT_BIND).

◆ DAT_TERMINATED

#define DAT_TERMINATED ( ...)
Value:
DAT_TAG("terminated(" #__VA_ARGS__ ")")

The pointer refers to elements up to and including a terminator: the first element whose first word is value and not a relocated pointer, e.g.

DAT_TERMINATED(GX_VA_NULL) for a vertex descriptor list. An optional second argument, a number, is how many elements the terminator takes, for lists that end in it more than once: DAT_TERMINATED(0x83D60, 2).

◆ DAT_EXTENT

#define DAT_EXTENT   DAT_TAG("extent")

The array holds as many elements as the data does: they continue until the next symbol, the next address a pointer refers to, or an element that no longer fits the element type.

Its declared size is ignored.

Todo
This is a heuristic for arrays whose length only the code knows. Replace each use with a DAT_COUNT once counts can be read from the code's own tables (e.g. the largest anim_id in an item kind's ItemStateTable, for ItemStateArray), or from per-kind *_Count enum values where those exist.

◆ DAT_IF

#define DAT_IF ( cond)
Value:
DAT_TAG("if(" #cond ")")

The union member is valid when cond holds: a C expression over the fields of the record containing the union, and macros.

◆ DAT_BIND

#define DAT_BIND ( name,
value )
Value:
DAT_TAG("bind(" #name ", " #value ")")

name, conventionally Type::field for a value that belongs to Type but is not stored in it, is value for everything reached through the member: its own layout and every pointer followed from within it.

value is evaluated in the record containing the member; for an array or a DAT_COUNT pointer, once per element, which it can refer to as _index. Inner bindings shadow outer ones.

◆ DAT_MATCH

#define DAT_MATCH ( name,
values,
... )
Value:
DAT_TAG("bind(" #name ", (match " #values " { " #__VA_ARGS__ " }))")

Bind name to the result of matching the tuple values against the remaining arguments: (pattern, ...): value cases, ending with _: value.

Cases are comma-separated. Patterns are constants, | alternatives, or _ to ignore a tuple component. The first matching case supplies the binding, with the same scope as DAT_BIND.

◆ DAT_SCRIPT

#define DAT_SCRIPT ( ...)
Value:
DAT_TAG("script(" #__VA_ARGS__ ")")

The pointer refers to a command script: commands of whole words, each with its opcode in the top 6 bits of its first byte, up to one with opcode 0.

Relocated words within a command point to more script, such as a goto's target. Opcodes 0 to 9 are the generic commands every script shares (Command_Execute). The script's own commands, from opcode 10, are as many words long as either

  • table, an array in the code of their lengths, from opcode 10: DAT_SCRIPT(ftAction_803C0870); or
  • an expression in _command, the command's first word, such as a call to a tool-side helper: DAT_SCRIPT(itCommandLength(_command)). A length of 0 ends the script there, for scripts that stop at a command of their own (a color animation's opcode 10).

Apply to a pointer member or a pointer typedef used in an array of scripts.

◆ DAT_BYTE_SCRIPT

#define DAT_BYTE_SCRIPT ( length)
Value:
DAT_TAG("bytescript(" #length ")")

A pointer to a byte command script.

length gives the command's size in bytes, using its first byte as _command. For example: DAT_BYTE_SCRIPT(cpuCommandLength(_command)).

A length of 0 marks the terminator. The terminator byte is included in the script. Byte scripts have no generic commands or pointers. Apply to a pointer member or a pointer typedef used in an array of scripts.

◆ DAT_BLOB

typedef u8 HSD_VertexArray DAT_BLOB   DAT_TAG("blob")

On a typedef of u8: the bytes are data of one format the archive doesn't break down further, such as an animation's keyframe stream.

One attribute's vertex data, as GXSetArray takes it: elements of stride bytes, which a shape's display lists index.

Raw u8 data is unknown; the size comes from the members that point to it, e.g. DAT_COUNT(length).

◆ DAT_TYPE

#define DAT_TYPE ( type)
Value:
DAT_TAG("type(" #type ")")

The untyped pointer, or pointer-sized integer, refers to a type when it is relocated.

◆ DAT_ROOTS

#define DAT_ROOTS ( ...)