EQU badly documented?

[EPAstor]

New member here, starting work on a maybe-crazy project (described after my question).

I've been trying to make out how the EQU directive (and =, and TEXTEQU) actually work. When I read Microsoft's documentation, it seems to specify only two forms:
macro-id EQU numeric-expression
and
macro-id EQU < text >
where the angle brackets appear to be literal, and actually supposed to appear in the MASM code.

But... I see plenty of cases like
SYMBOL_NAME EQU ?XYZ_2
in the wild, which doesn't seem to fit either of these. Even looking closer at what I've summarized as numeric-expression, it can take an identifier... but identifiers can't start with a ?.

Can anyone help me figure out what EQU actually does and doesn't do in ml.exe and ml64.exe? Ideally, by helping me understand where I should find reliable documentation on 32- and 64-bit MASM syntax... or just how I'm reading the Microsoft documentation wrong!



Maybe-crazy project: I'm trying to build a MASM assembler as a part of the LLVM project.

LLVM's solved a lot of this already to deal with implementing MSVC-style inline assembly, and most directives have parallels in styles LLVM already supports. The points I see so far that may be tricky: EQU, PROC, INVOKE, STRUCT, ASSUME, and field access (the . operator). There are probably more I don't realize are hard yet.

[jj2007]

Welcome to the Forum 

Some older threads treat this:
http://masm32.com/board/index.php?topic=3974.msg41915#msg41915
http://masm32.com/board/index.php?topic=641.msg5243#msg5243

Symbols can indeed start with ?, also with _ btw.

[EPAstor]

Thanks! I think my confusion comes from the syntax documentation I found in an old MASM reference manual... which now that I look at it might be 16-bit. It gave a BNF grammar for MASM... and after tracing everything from the right-hand side of an EQU, the only possible resolution for a symbol was the id non-terminal... and that's specified to be alphanumeric, with the first character being a letter.

I'll look a bit harder at the older threads you linked... but I'm still not sure what the full set of possibilities for the right-hand side of an EQU are. Based on Microsoft documentation [1], I'd've expected to see
SYMBOL_NAME EQU <?XYZ_2>
instead, so I don't quite get why it's legal to leave off the angle-brackets in this case?

    [1]: https://docs.microsoft.com/en-us/cpp/assembler/masm/equ?view=vs-2019

[FORTRANS]

Hi,

   You should note that various names, labels, and symbols
are human recognizable representations that MASM translates
to a numeric value for its use to generate executable code.
EQUates assign such numbers to another named symbol
to aid the programmer.  Generate a program listing, cross
reference, and map to get a better feel for this.

   The text versions can also be looked at in a similar manner
to see how they work.

Regards,

Steve N.

[EPAstor]

... oh, of course! Thank you, I should have realized that an earlier pass must be translating the symbol name into a numeric expression.

Which explains perfectly why going back and forth to disassembly output was just confusing me... the disassembler is helpfully resolving the numeric value back into a symbol name. Which means that (as you say) I need to use the /S options to generate a listing, rather than using an intermediary disassembler.

Thanks again!

[jj2007]

I don't quite get why it's legal to leave off the angle-brackets in this case?

You are right that the documentation is messy. So is the implementation. Most of the time you can omit them. I just checked one of my sources, 800 equates of which only 100 use the brackets. Occasionally it makes a difference if you use MASM or UAsm.