Author Topic: EQU badly documented?  (Read 470 times)

EPAstor

  • Regular Member
  • *
  • Posts: 3
EQU badly documented?
« on: November 26, 2019, 12:16:16 AM »
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

  • Member
  • *****
  • Posts: 10446
  • Assembler is fun ;-)
    • MasmBasic
Re: EQU badly documented?
« Reply #1 on: November 26, 2019, 12:29:35 AM »
Welcome to the Forum  :thup:

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

  • Regular Member
  • *
  • Posts: 3
Re: EQU badly documented?
« Reply #2 on: November 26, 2019, 12:42:31 AM »
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

  • Member
  • *****
  • Posts: 1076
Re: EQU badly documented?
« Reply #3 on: November 26, 2019, 12:50:30 AM »
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

  • Regular Member
  • *
  • Posts: 3
Re: EQU badly documented?
« Reply #4 on: November 26, 2019, 12:55:31 AM »
... 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

  • Member
  • *****
  • Posts: 10446
  • Assembler is fun ;-)
    • MasmBasic
Re: EQU badly documented?
« Reply #5 on: November 26, 2019, 01:12:55 AM »
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.