Re: [LuxAsm] Where's C's macro documentation?

From: C (blackmarlin_at_asean-mail.com)
Date: 06/28/04 

Date: 28 Jun 2004 06:45:15 -0700

"Beth" <BethStone21@hotmail.NOSPICEDHAM.com> wrote in message news:<TfLDc.497$WZ4.336@newsfe3-gui>...
> Hi,
>
> Subject line says it all, I suppose; Frank said that C has
> provided documentation for the macros but I just can't find
> it...is it a separate file or did C add comments to the source
> code or what?

It was in the post "Update 2004-06-22" to the Luxasm users
group -- you can see it on the mail archive. (As an admin
you should be keeping up with the progress reports, Beth.)

I should really document them in the source to the macro
library -- but that can wait until Luxasm is complete and we
write the Luxasm version of this library. (A wish list for the
library would be a good idea at this point.)

Here is a copy of the relevant portions of that mail anyway...

[======

Brief notes on macros (luxasm/_nasm/macros):
(macro syntax is loosly based on Ada language)
[limited overview of code generated]

module / end_module
  group procedures into a module (for name
  mangling)
  [no code generated]

interface / end_interface
  specify interface for another module, define
  external labels (with name mangling)
  [generate _start code if 'start' procedure
  found, else no code generated]

procedure / end_procedure
  define the call frame and setup data for access
  (via esp) for parameters & local variables
  [no code generated, end_procedure calls 'return']

locals
  define local variables (assumes size is 4bytes,
  unless number is specified following label)
  [ generates sub esp, <n> ]

return
  cleanup stack frame & return from procedure
  (return is auto called from end_procedure)
  [ generates add esp, <n> \\ ret <n> ]

if / end_if / do / loop / ...
  standard condition constructs -- you should be
  able to guess the meaning from the name
  stack _must_ be balanced else error
  [ generates cmp <p>, <p> \\ jcc <l> ]

goto
  conditional goto (issue cmp / jcc)
  [ generates cmp <p>, <p> \\ jcc <l> or jmp <l> ]

select
  generate a jump table & jump (similar to the
  C-language 'switch'), parameters are register
  for index, default option, <value / jump to
  label><pairs> -- takes ages for nasm to
  process this macro, but generates really
  fast code :-)
  [ generates cmp lt <low> \\ jcc <default>
              cmp gt <high> \\ jcc <default>
              jmp dword [ table + <reg>*4 ]
              <jump table> ]

call
  mangle name & push params depending on call mode
  note: _will_ leave junk on stack when 'ret'
  does not cleanup stack -- ie. using the C call
  convention, stack is cleaned up on end of
  block grouping (so as to clean up multiple
  calls with a single 'add esp,<n>') -- user can
  force cleanup of junk with 'drop junk', though
  as I am using the Pascal calling convention this
  is not really an issue.)
  [ generates push \\ ... \\ push \\ call <l> ]

push / pop / pushad / ...
  modify internal varaibles so 'local' access
  points to correct place on stack (via esp).
  else same as normal push/pop
  [ generates push / pop / ... ]

drop
  remove junk / data from stack (pseudo op)
  [ generates add esp, <n>*4 ]

clr
  set register to zero (pseudo op)
  [ generates xor <reg>, <reg> ]

enumerate / end_enumerate
  define group, start & stepping for enumerations
  defined with 'enum'
  [ generates nothing ]

type / end_type
  define a struct / union -- can specify alignment
  of data types
  [ generates nothing ]

variable
  define data in the ".data" or ".bss" section
  [ generates data specified, or moves bss ptr ]

constant
  define data in the ".rodata" section
  [ generates data specified ]

assert
  check a condition is true (code only generated
  when DEBUG flag is defined, else generates
  nothing) -- if condition is false 'assertion
  failed' message is printed (used a a debugging
  aid because gdb is rubbish :-) ).
  [ generates assert call, if DEBUG flag]

review
  print a review message (contents of g/p regs)
  if REVIEW flag is set
  [ generates review call, if REVIEW flag]

That should provide a good look at what is
happening, of course this is just an overview
and several features have not been covered
(including the infamous 'stack imbalance' error,
and several bugs which the library can produce
if you are not aware of them -- primarily due
to implicit stack management) but most of the
common macros are sketched here.

======]

Oh, by the way the 'code review' I am conducting is
going well, but is taking a little longer than expected.
I found and removed (or documented) a few subtle
bugs and I am changing some the the interfaces
between the modules to allow the most of the modules
to be fully stateless. (I will update when Luxasm is
compiling correctly again, though we are past 10,000
lines of code (at near 300Kb), so that may be a few
days hence...)

Having stateless modules now should help work out
the interface for the plugable architecture -- again am I
the only one throwing about ideas for this? This is the
time to get your veiws heard, or at least comment on my
ideas -- otherwise I will just consider what ever I am
doing to be perfect, which may result in problems arrising
when you try something not originally though of initially.
Some ideas for the interface sepecifcation would be
nice -- text / UML diagrams ideal, or am I the only one
who likes the top-down design approach :-).

C
2004