f-cpu/ygasm/ygasm.txt
created dim mar 17 10:19:58 GMT 2002 by whygee@f-cpu.org

"ygasm" is whygee's assembler for the F-CPU project.

It is designed for easy manual programming in F-CPU assembly langage.
The syntax borrows from NASM (the coolest x86 asm SW) and a bit from C.
The goal is to have a very handy, monolithic tool that can be later
statically cross-compiled and running in a F-CPU system with reduced
ressources. It is not compatible with GCC's output format (which is
ugly and useless for manual development) and not designed for blazing
speed or minimal footprint, but entirely for the programmer's comfort.

Although manual development is the target (and not much code can
be written this way, theoretically), the system should later be able
to handle very large and scattered data sets.


The basics :

* keywords are not case sensitive (that's handy) but symbols/labels are.

* comments are like in C : either /* - */ or //
  /* - */ comments can be nested up to a user definable level (0 by default)

* all instructions and pseudo-instructions (like ORG and ALIGN) are always
 finished by a ';', so it can span several lines (but error messages might
 get confused about the exact line where the error appeared).

* Available preprocessing commands are :
  #INCLUDE "file" (no <file> yet)
  #DEFINE  a b
  #IFDEF  a
  #IFNDEF a
  #ELSE
  #ENDIF
(all these behave more or less like in CPP, beware of side effects
 however and don't rely on CPP-specific stuff)
  #NESTED_COMMENTS  (set max comment nesting depth to 1000)
  #NO_NESTED_COMMENTS  (max nesting depth is set to 0)
  #EOF   (simulate an end of file)

Not yet available :
  macro expansion
  #ENDIAN
  #UNDEF
  #INCBIN
  #IF

* Pseudo-instructions :
  ORG
  ALIGN
  DB, DW, DD, DQ

* Label/symbol computations :
  - a symbol and a label are the same thing : a 64-bit value
    but it is distinct from a #DEFINE'ed symbol
  - symbols/labels are defined by :
      unknown_string:
    or
      unknown_string = defined value
    or by an explicit use in an instruction or pseudo-instruction
  - @ is the "virtual PC" that is incremented after each instruction is decoded
  - symbols can be computed with the following operators,
    in decreasing precedence :

    parenthesis : ( x )
    unary minus : - x
    minus       : x - y
    plus        : x + y
    multiply    : x * y
    divide      : x / y
    remainder   : x % y
    logical AND : x & y
    logical OR  : x | y
    logical XOR : x ^ y
    shift left  : x << y
    shift right : x >> y (logical)
    bool. neg.  : ~ x

Do not hesitate to use parenthesis to keep the code clean
and free from interpretation errors.

- command line parameters :
  ygasm [options] [[in files ...] out file]

When no input source is given, it is read on stdin.
If no parameter is given, the output is also sent to stdout.
messages are sent to stderr.

additional parameters (not yet implemented) :
 -v X
   where X a positive integer number
   indicated the verbosity level.
   default is 1 : no informative message,
   but important warnings are displayed anyway
   (this is a way to get some statistics
   or idea of what is going on in the program.)
   level 0 disables warnings on stderr.

 -h
   prints a little summary and exits
/*
 -i xxxx
   in put file is xxxx (may be used several times)

 -o xxxx
   output file is named xxxx (may be used only once)
*/
 -l xxxx
   listing output is written to a file named xxxx
   (no listing by default)

 -s xxxx
  writes the symbol table to a file named xxxx.
  
