home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 5 / ctrom5b.zip / ctrom5b / PROGRAM / ASM / AS65_107 / AS65.MAN < prev    next >
Text File  |  1994-11-22  |  23KB  |  638 lines

  1. Kingswood Software Development Tools                                 AS65
  2. -------------------------------------------------------------------------
  3.  
  4. NAME
  5.    as65 - assembler for 6502 and 65SC02 microprocessors.
  6.  
  7.  
  8. SYNOPSIS
  9.    as65 [-cghlnopqstvwxz] file
  10.  
  11.  
  12. DESCRIPTION
  13.    This documentation is for as65 [1.07].
  14.    Copyright 1990-1994, Frank A. Vorstenbosch, Kingswood Software.
  15.  
  16.    AS65 is an assembler for the 6502 and 65SC02 microprocessors. It reads
  17.    input from an ASCII text file, assembles this into memory, and then 
  18.    writes a listing and a binary or hex file.
  19.  
  20.    AS65 is case sensitive, not only does it differentiate between the
  21.    labels XYZ and xyz, but it also requires all (pseudo) instruction and
  22.    register names to be lower case.  This way, the listing is the most
  23.    readable.  Option -i can be used to make the assembler case insensitive.
  24.    Alternatively, the included TOLOWER program can be used to convert
  25.    sources to lower case.
  26.  
  27. OPTIONS
  28.    As65 recognizes the following options:
  29.  
  30.       -c   Show number of cycles per instruction in listing.  This
  31.            decreases the number of columns available for listing by 5.
  32.            The number of cycles is printed between brackets [ and ].
  33.  
  34.       -g   Generate source-level debug information file.  This file
  35.            can then be used in in-system debugging or a software
  36.            simulator.
  37.  
  38.       -h<lines>
  39.            Specify height of page for listing.  This option determines
  40.            the number of lines per printed page.  Each page has a header
  41.            and is terminated by a form-feed character.  The special
  42.            case -h0 indicates an infinite page length.  In this case,
  43.            page breaks are only inserted between the two passes and
  44.            the symbol table (if present).
  45.  
  46.       -i   Ignore case in opcodes.  In this way, the assembler does not
  47.            differentiate between 'adc' and 'ADC', for example.  Labels
  48.            are still case sensitive.
  49.  
  50.       -l   Generate pass 2 listing.
  51.  
  52.       -l<filename>
  53.             Listing file name.  The listing file is used for pass 1 and
  54.             pass 2 listing, for the symbol table (printed between the
  55.             two passes), and some statistics.  When neither -p nor -t
  56.             is specified, and -l<filename> is given, then the assembler
  57.             automatically generates a pass 2 listing.  When -p or -t is
  58.             specified, an additional -l should be given is a pass 2
  59.             listing is required.  The filename - can be used to direct
  60.             the listing to standard output.
  61.  
  62.       -l   Generate pass 2 listing.
  63.  
  64.       -n   Disable optimizations.  When this option is specified no
  65.            optimizations will be done, even when the _opt_ pseudo-
  66.            instruction is used in the source code.
  67.  
  68.       -o<filename>
  69.            Specify binary or s-records output file name.  The assembler
  70.            automatically adds ".bin" for binary output or ".s19" for
  71.            s-records output when no extension is given.
  72.  
  73.       -p   Generate pass 1 listing.  This may be used to examine any
  74.            optimizations/bugs generated in pass 2.
  75.  
  76.       -q   Quiet mode.  No running line counter is displayed on standard
  77.            error output.
  78.  
  79.       -s   Write s-records instead of binary file.  The s-records file
  80.            contains data for (only) the used memory; the binary file
  81.            begins at the lowest used address, and continues up to the
  82.            highest used address; filling unused memory between these
  83.            two addresses with either $ff or $00.
  84.  
  85.       -s2  Write intel-hex file instead of binary file.  The intel-hex
  86.            file contains data for (only) the used memory.
  87.  
  88.       -t   Generate symbol table.  The symbol table is listed between
  89.            passes one and two, displaying the name, hexadecimal and
  90.            decimal value of each label, using 4-digit hexadecimal
  91.            numbers where possible, otherwise 8-digit numbers.  The
  92.            decimal value is followed by an asterisk if the label is
  93.            redefinable (defined using _set_ instead of _equ_).
  94.  
  95.       -v   Verbose mode.  More information is displayed on standard
  96.            output.
  97.  
  98.       -w<width>
  99.            Specify column width.  Normally, the listing is printed using
  100.            79 columns for output to a 80-column screen or printer.  If
  101.            the -w option is given without a number following it, then
  102.            the listing will be 131 columns wide, otherwise it will be
  103.            the number of colulmns specified (between 60 and 200).
  104.  
  105.       -x   Use 65SC02 extensions.  This CPU has several additional 
  106.            instructions. When this option is not specified the assembler 
  107.            rejects the 65SC02 extensions.
  108.  
  109.       -z   Fill unused memory with zeros.  Normally when a binary file
  110.            is generated, unused bytes between the lowest and highest
  111.            used addresses are filled with $ff, the unprogrammed state
  112.            of EPROMs.  If this is not wanted, the -z option can be used
  113.            to initialize this memory to $00.  With s-records, unused
  114.            memory is not output to the file, and this option forces the
  115.            creation of an S9 (start address) record instead, even if no 
  116.            start address is specified in the file with the _end_ pseudo-
  117.            instruction.
  118.  
  119.    Commandline options can be catenated, but no other option can follow
  120.    one that may have a parameter.  Thus:
  121.       -tlfile
  122.    is correct (specifying symbol table and pass 2 listing), but
  123.       -h5t
  124.    is not.
  125.  
  126.    It is possible to discard any of the the output files by specifying
  127.    the name 'nul'.
  128.  
  129.  
  130. EXPRESSIONS
  131.  
  132.    The assembler recognizes most C-language expressions.  The operators
  133.    are listed here in order of precedence, highest first:
  134.  
  135.        ()            braces to group subexpressions
  136.        * $           current location counter
  137.        unary + - ! ~ unary + (no-operation), negation, logical NOT,
  138.                      binary NOT
  139.        * / %         multiplication, division, modulo
  140.        + -           addition, subtraction
  141.        << >>         shift left, shift right
  142.        < > <= >=     comparison for greater/less than
  143.        = !=          comparison for equality (== can be used for =)
  144.        &             binary AND
  145.        ^             binary XOR
  146.        |             binary OR
  147.  
  148.    The logical NOT (!) evaluates to zero if the parameter is nonzero,
  149.    and vice versa.  The binary NOT (~) complements all the bits in its
  150.    parameter.
  151.  
  152.    Note: the asterisk is both used as the multiplication operator, and
  153.    as symbol for the current location.  The assembler determines from
  154.    the context which is which. Thus:
  155.  
  156.        5**
  157.  
  158.    is a valid expression, evaluating to five times the current location
  159.    counter, and:
  160.  
  161.        2+*/2
  162.  
  163.    is too, evaluating to the current location counter divided by two, to
  164.    which two is added.  In the same way, the % sign is both used as the
  165.    modulo operator and the prefix for binary numbers.
  166.  
  167.    Numbers can be specified in any number base between 2 and 36.
  168.    Decimal numbers can be used without a prefix, hexadecimal numbers
  169.    can be prefixed by $, octal numbers by @, and binary numbers by %.
  170.    Other number bases can be used by using the following format:  
  171.       <base>#<number>, 
  172.    where the base is the number base to use (must be specified in 
  173.    decimal), and number is the value.  Thus:
  174.       1000    - decimal number, value 10*10*10=1000
  175.       %1000   - binary number, value 2*2*2=8
  176.       @1000   - octal number, value 8*8*8=512
  177.       $1000   - hexadecimal number, value 16*16*16=4096
  178.       2#1000  - binary number, value 2*2*2=8
  179.       4#1000  - base-4 number, value 4*4*4=64
  180.       7#1000  - base-7 number, value 7*7*7=343
  181.       36#1000 - base-36 number, value 36*36*36=444528
  182.    For number bases greater than 10, additional digits are represented
  183.    by letters, starting from A.  Both lower and upper case letters can
  184.    be used.
  185.       11#aa = 120
  186.       16#ff = 255
  187.       25#oo = 624
  188.       36#zz = 1295
  189.  
  190.  
  191. PSEUDO-INSTRUCTIONS
  192.  
  193.    align <expression>
  194.  
  195.       Align fills zero or more bytes with zeros until the new address
  196.       modulo <expression> equals zero.  If the expression is not present,
  197.       align fills zero or one bytes with zeros until the new address
  198.       is even.
  199.  
  200.       Example 1:
  201.                       align  256             ; continue assembly on the
  202.                                              ; next 256-byte page
  203.  
  204.       Example 2:
  205.                       align                  ; make sure table begins
  206.       Table           dw     1,2,3           ; on an even address
  207.  
  208.  
  209.  
  210.    bss
  211.  
  212.       Put all following data in the bss segment.  Only data pseudo-instructions 
  213.       can be used in the bss segment, and these only increment the location 
  214.       counter.  It is up to the programmer to initialize the bss segment.  The 
  215.       bss segment is especially meaningful in a ROM based system where
  216.       variables must be placed in RAM, and RAM is not automatically initialized.
  217.  
  218.       The assembler internally maintains three separate location counters,
  219.       one for the code segment, one for the data segment and one for the
  220.       uninitialized data segment.  The user is responsible for not overlapping
  221.       the segments by setting appropriate origins.  The code, data and bss
  222.       pseudo-instructions can be used to interleave code and data in the source
  223.       listing, while separating the three in the generated program.  The
  224.       assembler starts with the code segment if none is specified.
  225.  
  226.       Example:
  227.                      code
  228.                      org    $f000           ; Assuming 4 kbyte code ROM
  229.                      data                   ; with 2 kbyte program and
  230.                      org    $f800           ; 2 kbyte initialized data
  231.                      bss
  232.                      org    0               ; bss segment is in RAM
  233.  
  234.       Buffer         ds     100
  235.  
  236.                      code
  237.       Begin          lda    Table,x
  238.                      jsr    MyFunc
  239.                      .
  240.                      .
  241.  
  242.                      data
  243.       Table          db     1,2,3
  244.  
  245.                      code
  246.       MyFunc         .
  247.                      .
  248.  
  249.    code
  250.  
  251.       Put all assembled instructions and data in the code segment.
  252.       See _bss_
  253.  
  254.  
  255.    data
  256.  
  257.       Put all assembled instructions and data in the data segment.
  258.       See _bss_
  259.  
  260.  
  261.    db <bytelist>
  262.  
  263.       Define bytes.  The bytes may be specified as expressions or strings,
  264.       and are placed in the current (code or data) segment.  This pseudo
  265.       instruction is similar to the fcb and fcc pseudo-instructions.
  266.  
  267.       Example:
  268.       Message         db     7,"Error",13,10,0
  269.  
  270.  
  271.    ds <expression>
  272.  
  273.       Define zero or more bytes empty space.  The specified number of
  274.       bytes are filled with zeros.  This pseudo-instruction is identical
  275.       to the pseudo-instruction rmb.
  276.  
  277.       Example:
  278.                      ds     100             ; reserve 100 bytes here
  279.  
  280.  
  281.    dw <wordlist>
  282.  
  283.       Define words.  The words are placed in the current (code or data)
  284.       segment.  This pseudo-instruction is identical to the fcw and fdb 
  285.       pseudo-instructions.
  286.  
  287.       Example:
  288.                      lda    Function        ; number of function
  289.                      asl    a
  290.                      tax
  291.                      lda    JumpTable+1,x
  292.                      pha
  293.                      lda    JumpTable,x
  294.                      pha
  295.                      rts
  296.  
  297.       JumpTable      dw     Function0
  298.                      dw     Function1
  299.                      dw     Function2
  300.  
  301.  
  302.    else
  303.  
  304.       The else pseudo-instruction can be used for if-then-else
  305.       constructions. It must be placed between an if and an endif
  306.       instruction.  For an example, see the if pseudo-instruction.
  307.  
  308.  
  309.    end <expression>
  310.  
  311.       The end pseudo-instruction is optional, and need not be used.  If
  312.       it is used, its optional operand specifies the staring address of
  313.       the program.  This address is displayed when the program is
  314.       assembled, and is also placed in the s-record output file.
  315.  
  316.       Example:
  317.                      end    Start
  318.  
  319.    endif
  320.  
  321.       The endif pseudo-instruction must be used to close an if-endif
  322.       or if-else-endif construction.  For an example, see the if
  323.       pseudo-instruction.
  324.  
  325.  
  326.    <label> equ <expression>
  327.  
  328.       The equ (equate) pseudo-instruction sets the specified label to
  329.       the value of the expression.  The label may not already exist.
  330.       Some programmers choose to use only upper-case identifiers for
  331.       labels defined in this way to differentiate them from addresses.
  332.  
  333.       Example:
  334.       ESCAPE          equ    27
  335.  
  336.  
  337.    fcb <bytelist>
  338.  
  339.       Define bytes (form constant byte).  The bytes may be specified
  340.       only as expressions, and are placed in the current (code or data)
  341.       segment.  This pseudo-instruction is similar to the db 
  342.       pseudo-instruction.
  343.  
  344.       Example:
  345.       Message        fcb    7
  346.                      fcc    "Error"
  347.                      fcb    13,10,0
  348.  
  349.  
  350.    fcc <string>
  351.  
  352.       Define bytes (form constant character).  The bytes may be
  353.       specified only as a string, and are placed in the current (code or
  354.       data) segment.  This pseudo-instruction is similar to the db 
  355.       pseudo-instruction.
  356.  
  357.  
  358.    fcw <wordlist>
  359.  
  360.       Define words (form constant word).  The words are placed in the
  361.       current (code or data) segment.  This pseudo-instruction is similar
  362.       to the fdb and dw pseudo-instructions.
  363.  
  364.  
  365.    fdb <wordlist>
  366.  
  367.       Define words (form double byte).  The words are placed in the
  368.       current (code or data) segment.  This pseudo instruction is
  369.       identical to the fcw and dw pseudo-instructions.
  370.  
  371.  
  372.    if <expression>
  373.  
  374.       The if pseudo-instruction can be used in conjunction with the
  375.       endif and possibly the else pseudo-instructions to selectively
  376.       enable and disable pieces of code in the source.  If the expression
  377.       given evaluates to zero, then the following code up to the matching
  378.       else or endif is not included in the assembly.  If the expression
  379.       is nonzero, then the following code is included, but any code
  380.       between the matching else and endif is not.
  381.  
  382.       Example:
  383.                      if COUNT=2 | COUNT=4
  384.                      asl     a              ; shift left for counts
  385.                      if COUNT=4             ; of 2 and 4
  386.                      asl     a
  387.                      endif
  388.                      else
  389.                      ldx     #COUNT         ; otherwise use slow
  390.                      jsr     Multiply       ; multiply subroutine
  391.                      endif
  392.  
  393.  
  394.    include <string>
  395.  
  396.       The named file is included in the assembly at this point.  After
  397.       it has been read, assembly continues with the next line of the
  398.       current file. Include files may be nested.
  399.  
  400.       Example:
  401.                      include "defines.i"
  402.  
  403.  
  404.    list
  405.  
  406.       Enable generation of the listing in the list-file.  If the listing
  407.       has been disabled twice, it must be enabled twice before it is
  408.       generated.  When no -p or -l option has been specified on the
  409.       command line, this pseudo-instruction has no effect.
  410.  
  411.  
  412.    nolist
  413.  
  414.       Disable generation of the listing in the list-file.
  415.  
  416.  
  417.    noopt
  418.  
  419.       Disable optimizations.  If the -n option has been specified on the
  420.       command line, this pseudo-instruction has no effect.
  421.  
  422.  
  423.    nop <expression>
  424.  
  425.       No operation.  When the optional expression is not present, this
  426.       is simply the nop instruction of the processor.  When the
  427.       expression is present, the specified number of nop instructions
  428.       are inserted.
  429.  
  430.       Example:
  431.                      nop    10
  432.  
  433.  
  434.    opt
  435.  
  436.       Enable optimizations.  If the -n option has been specified on the
  437.       command line, this pseudo-instruction has no effect.
  438.       When optimization is enabled, the assembler tries to use the
  439.       shortest and fastest instructions possible which have the effect
  440.       the user wants.  It may replace any extended-address instruction
  441.       by zero-page instructions.  It replaces jumps with branches (65SC02
  442.       only) and absolute address instructions by zero page instructions.
  443.       The effects of optimizations is clearly visible if both a pass
  444.       one and a pass two listing is generated.
  445.  
  446.  
  447.    org <expression>
  448.  
  449.       The org (origin) pseudo-instruction specifies the next address to
  450.       be used for assembly.  When no origin has been specified, the
  451.       assembler uses the value 0.  The assembler maintains three separate
  452.       location counters: one for the code segment, one for the data
  453.       segment, and one for the bss segment.  See the code and pseudo-
  454.       instruction for more information.
  455.  
  456.  
  457.    page <expression>
  458.  
  459.       When the optional expression is not present, the assembly listing
  460.       is continued on the next page.  When the expression is present,
  461.       the listing is continued on the next page only if the specified
  462.       number of lines do not fit on the current page.
  463.  
  464.  
  465.    rmb <expression>
  466.  
  467.       Define zero or more bytes empty space.  The specified number of
  468.       bytes are filled with zeros.  This pseudo-instruction is identical
  469.       to the pseudo-instruction ds.
  470.  
  471.  
  472.    <label> set <expression>
  473.    <label> = <expression>
  474.  
  475.       The set pseudo-instruction sets the specified label to the value
  476.       of the expression.  The label may or may not already exist.
  477.       Some programmers choose to use only upper-case identifiers for
  478.       labels defined in this way to differentiate them from addresses.
  479.  
  480.       Example:
  481.       CURRENT         set    0
  482.  
  483.                       .
  484.                       .
  485.                       .
  486.  
  487.       CURRENT         set    CURRENT+1
  488.  
  489.  
  490.    struct <name>
  491.    struct <name>,<expression>
  492.  
  493.       The struct (structure) pseudo-instruction can be used to define
  494.       data structures in memory more easily.
  495.  
  496.       The name of the structure is set to the total size of the structure;
  497.       if the expression is present, the starting offset is the value of
  498.       the expression in stead of zero.
  499.  
  500.       Between the struct and end struct pseudo-instructions the following
  501.       pseudo-instructions can be used: db, dw, ds, label, align.
  502.       Within structures these pseudo-instructions take a slightly different
  503.       format than normally:
  504.  
  505.          db <name>                element is one byte
  506.  
  507.          dw <name>                element is two bytes
  508.  
  509.          ds <name>,<expression>   element is the specified number of bytes
  510.  
  511.          ds <expression>          skip the specified number of bytes
  512.  
  513.          label <name>             element is zero bytes, i.e. set the name
  514.                                   to the current structure offset
  515.  
  516.          align <expression>       skip until (offset%expression)=0
  517.  
  518.          align                    skip until offset is even
  519.  
  520.  
  521.       Example:
  522.                      struct ListNode,4
  523.                      dw     LN_Next
  524.                      dw     LN_Previous
  525.                      db     LN_Type
  526.                      align
  527.                      label  LN_Simple       ; size of structure so far
  528.                      align  8
  529.                      ds     LN_Data,10
  530.                      end struct
  531.  
  532.       This is identical to:
  533.  
  534.       LN_Next        equ     4       ;\
  535.       LN_Previous    equ     6       ; offset of structure elements
  536.       LN_Type        equ     8       ;/
  537.       LN_Simple      equ     10      ; size of structure so far
  538.       LN_Data        equ     16      ; offset of structure element
  539.       ListNode       equ     26      ; size of structure
  540.  
  541.  
  542.    title <string>
  543.  
  544.       The title pseudo-instruction sets the title to be used in the
  545.       header of each listing page.  The string should be no longer than
  546.       80 characters.
  547.  
  548.       Example:
  549.                    title  "DIS65 : A disassembler for a 6502 CPU"
  550.  
  551.  
  552. ADDRESSING MODES
  553.    The assembler allows all 6502 and 65SC02 addressing modes.
  554.  
  555.    List of available modes:
  556.       a
  557.       #Expression
  558.       Expression
  559.       Expression,x
  560.       Expression,y
  561.       (Expression)
  562.       (Expression,x)
  563.       (Expression),y
  564.  
  565. LIST OF ACCEPTED INSTRUCTIONS
  566.    adc align and asl bcc bcs beq bit bmi bne bpl bra brk bvc bvs clc cld
  567.    cli clr clv cmp code cpx cpy data db dd dec dex dey disable ds dw else
  568.    enable end endif eor equ fcb fcc fcw fdb if inc include inx iny jmp jsr
  569.    lda ldx ldy list lsr nolist noopt nop opt ora org page pha php phx phy
  570.    pla plp plx ply rmb rol ror rti rts sbc sec sed sei set sta stc std sti
  571.    struct stx sty stz tax tay title trb tsb tsx txa txs tya
  572.  
  573.    Of these instructions, the following are (more or less) synonymous,
  574.    and can be used interchangably.
  575.    YOU CAN USE     WHERE YOU WOULD PREVIOUSLY USE
  576.       disable   -  sei
  577.       enable    -  cli
  578.       nop 6     -  nop nop nop ....
  579.       stc       -  sec
  580.       sti       -  sei
  581.       stv       -  sev
  582.       clr       -  stz
  583.  
  584.    And pseudo-instructions:
  585.       db        -  fcb, fcc
  586.       dw        -  fcw, fdb
  587.       ds        -  rmb
  588.       =         -  set
  589.       struct    -  lots of EQUs
  590.  
  591.  
  592. LIST OF OTHER KEYWORDS
  593.    !  !=  #  %  &  (  )  *  +  ++  ,  -  --  /  <
  594.    <<  <=  =  >  >=  >>  [  ]  ^  | ~  a x y
  595.  
  596.  
  597. FILES
  598.    <file>.a65 - source file.
  599.    <file>.asm - source file -- alternative.
  600.    <file>.lst - List file.
  601.    <file>.s19 - Motorola S-records output file.
  602.    <file>.hex - Intel hex output file.
  603.    <file>.bin - Binary output file.
  604.  
  605.  
  606. BUGS
  607.    No provision for linking other pre-assembled modules is made.
  608.  
  609.  
  610. RETURNS
  611.    As65 returns one of the following values:
  612.  
  613.       0 - Source file assembled without errors.
  614.       1 - Incorrect parameter specified on the commandline.
  615.       2 - Unable to open input or output file.
  616.       3 - Assembly gave errors.
  617.       4 - No memory could be allocated.
  618.  
  619.  
  620. DIAGNOSTICS
  621.    Help message if only parameter is a question mark, or if an
  622.    illegal option has been specified.
  623.  
  624.  
  625. AUTHOR
  626.    This is copyrighted software, but may be distributed freely as long
  627.    as this document accompanies the assembler, and no copyright messages
  628.    are removed.  You are explicitly _not_ allowed to sell this software
  629.    for anything more than a reasonable copying fee, say US$5.
  630.    To contact the author:
  631.       Frank A. Vorstenbosch
  632.       Kingswood Software
  633.       P.O. Box 85800              Phone: +31-(70)-355 5241
  634.       2508CM  The Hague           BBS:   +31-(70)-355 8674
  635.       Netherlands                 Email: prompt@xs4all.nl
  636.  
  637. -------------------------------------------------------------------------
  638.