home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / BEEHIVE / OS / SUPER8.ARC / XS8.DOC < prev   
Text File  |  1990-09-21  |  22KB  |  575 lines
  1.                  Super8  Cross Assembler,  v1.01
  2.                  -------------------------------
  3.  
  4.  
  5. Overview
  6. --------
  7.   The  Super8 Cross assembler is the first of the META family  of
  8. assemblers.  These are very fast, fairly simple & reliable  soft-
  9. ware  tools based on a tested common core.  META  assemblers  are
  10. absolute,  therefore  they  will not  produce  relocatable  code.
  11. Given  that assemblies run at 6,000 to 10,000 lines/minute,  this
  12. is not much of a penalty, as it is faster than many linkers.
  13.  
  14. Invocation:
  15. -----------
  16.   The  source  file name and all options are extracted  from  the
  17. command line when the cross assembler is invoked.  The  extension
  18. on the source file must be <.S8>.  The command line format is  as
  19. follows:
  20.  
  21.           A>xs8 <filename> [/options]
  22.  
  23.   The options, as one might expect, are optional.  If no  options
  24. are specified, the file  <filename>.S8 is assembled, but produces
  25. no output other than to list errors on the console  (this is  the
  26. fastest way to check for assembly errors).  The options are  each
  27. a single letter, and they may be used in any combination:
  28.  
  29.      L    Generate listing
  30.      F    Direct listing to <filename>.prn
  31.      P    Direct listing to printer
  32.      S    Generate a symbol table
  33.      H    Generate Intel hex record file to <filename>.hex
  34.      T    Generate TEK HEX file to <filename>.tek
  35.  
  36.  
  37.   For  example,  the line "xs8 mon/LSPH"  would take  the  source
  38. file "mon.s8",  produce a listing and a symbol table to the  CP/M
  39. LST: device, and generate an output file of "mon.hex".  Note that
  40. whenever  a listing is generated (via L), it is sent to the  con-
  41. sole as well as any other specified devices.  F and P are  useful
  42. without  the L option to list just assembly errors.  Note that  T
  43. and H are mutually exclusive options.  In the case where both are
  44. specified, the right-most determines the type of output file.
  45.  
  46.  
  47. Symbols:
  48. -------
  49.   Symbols  (labels and equates) always start in column  one,  may
  50. optionally  be followed by a colon,  and may be up to 32  charac-
  51. ters  in  length (all characters are  significant,  although  the
  52. symbol  table will only print the first ten characters).   Inter-
  53. nally,  everything  is upcased when defining or  referring  to  a
  54. symbol, therefore case has no significance other than aesthetics.
  55.  
  56.   Symbols may not start with a digit (0-9) address mode specifier
  57. (@ or #). or a base specifier (% or $), but it is permissible  to
  58. embed  these characters.  Symbols should not  contain  characters
  59. which would cause them to be evaluated as expressions, such as +,
  60. -,  * or / (i.e. lbl*2 is a bad name) Sticking with  letters  and
  61. numbers is generally safest.
  62.  
  63.   Note that internally, the symbol table requires three plus  the
  64. length of the symbol bytes for each entry.  A typical CP/M system
  65. will have 50-54k of memory available for the symbol table.   This
  66. means  the  longer the symbols, the fewer can be  stored.   Prac-
  67. tically speaking, though, the difference between 5000 seven char-
  68. acter  symbols  vs 2500 17 character symbols is  academic,  as  a
  69. program that size would be a little too big for a Super8.
  70.  
  71.   All internal register names on the Super8 are pre-defined  sym-
  72. bols.   These  symbols are reserved, and attempting to  create  a
  73. symbol  with the same name will result in a  'Previously  defined
  74. Symbol' error.
  75.  
  76.  
  77. Numbers
  78. -------
  79.   Numeric values always start with a digit (0-9) or a base speci-
  80. fier ($ for hex, % for binary).  This first digit is used to help
  81. the  assembler differentiate numbers and symbols.  The pseudo  op
  82. ".RADIX" may be used to change the default number base, which de-
  83. faults  to  decimal.  Unless preceded by a  base  specifier,  hex
  84. numbers (or any base > 10) starting with A-F must be preceded  by
  85. a  0.  A trailing base specifier ('h' or 'H') may be used to  in-
  86. dicate hexadecimal (e.g. 80h).
  87.  
  88.  
  89. Strings
  90. -------
  91.   Strings are used to embed text using one of the four pseudo ops
  92. db, .ascii, .ascil or .ascic.  Either single or double quotes may
  93. be  used as delimiters, however the lead and trailing  delimiters
  94. must match.  The other delimiter character may be used inside the
  95. string (eg. "jeff's code").
  96.  
  97.   C-style  escape sequences are allowed inside strings  to  embed
  98. special characters.  The following are supported:
  99.  
  100.      \q        The string delimiter (' or ")
  101.      \n        Carriage return/line feed
  102.      \r        Carriage return
  103.      \f        Form feed
  104.      \t        Tab
  105.      \b        Backspace
  106.      \z        Clear screen (control Z)
  107.      \'        The single quote character (')
  108.      \"        The double quote character (")
  109.  
  110. Expressions,  (Demo Version)
  111. ---------------------------
  112.   Expressions work on values (symbols or numbers) and  operators.
  113. All  math is with 16b binary.  In the demo  version,  expressions
  114. may be in only two forms:
  115.  
  116.      1) <unary op> <value>         [eg: -label]
  117.      2) <value><binary op><value>  [eg: label+4]
  118.  
  119. Unary operators are:
  120.  
  121.       +        unary plus     (eg. +value)
  122.       -        unary minus    (eg. -value)
  123.      ^HB       high byte      (eg.  ^HB value)
  124.      ^LB       low byte       (eg.  ^LB value)
  125.      ^C        complement     (eg.  ^C value)
  126.  
  127. Binary operators are:
  128.  
  129.       +        add            (eg. value+23)
  130.       -        subtract       (eg. $-value)
  131.  
  132.  
  133.   A  special  symbol is '$', which is used to reference the  cur-
  134. rent value of the location counter (thus 'jr $' would be an  end-
  135. less loop).
  136.  
  137.  
  138.  
  139. Expressions,  (Commercial Version)
  140. ----------------------------------
  141.   A  major  subset of the asmS8 operators are  included  in  XS8.
  142. Arithmetic expressions can be as long as 16 bits, and are  parsed
  143. left  to  right.   Unary operators must  be  followed  by  either
  144. another  unary operator, a number or symbol, or by an  expression
  145. in parentheses.
  146.  
  147.      Operator   Precedence    Function
  148.      -------    ----------    --------
  149.  
  150.         ^HB         2         ; high byte
  151.         ^LB         2         ; low byte
  152.         ^C          2         ; 1's complement
  153.         ^REV        2         ; byte reverse
  154.         *           4         ; Multiply
  155.         /           4         ; Divide (unsigned)
  156.         MOD         4         ; Modulo
  157.         SHL         4         ; Shift left
  158.         SHR         4         ; Shift right
  159.         +           5         ; Addition
  160.         -           5         ; Subtraction
  161.         AND         6         ; bitwise and
  162.         &           6         ; bitwise and
  163.         OR          7         ; bitwise or
  164.         |           7         ; bitwise or
  165.         XOR         7         ; bitwise exclusive or
  166.         =           8         ; Equal
  167.         >           8         ; Greater than
  168.         <           8         ; Less
  169.         >=          8         ; Greater than or equal
  170.         <=          8         ; Less than or equal
  171.         <>          8         ; Not equal
  172.  
  173.  
  174.   Parentheses may be used to alter precedence of evaluation.  the
  175. forms   [expression] and {expression} are also valid.  Note  that
  176. with  some   instructions, (ld, lde, ldc) the presence of  a  '('
  177. indicates  base index addressing.  In such cases, use one of  the
  178. other forms.  Parentheses may be nested without limit.
  179.  
  180.    One  character operators  and all relational operators  do not
  181. require  surrounding white  space (e.g. gork+3 is  equivalent  to
  182. gork + 3).  Operators  starting  with ^ require no  leading space.
  183. All  relational operators output 0 for false, -1 for true.
  184.  
  185.   For more details on usage, see the example source file MATH.S8.
  186.  
  187.  
  188.                          **************
  189.                          * Pseudo ops *
  190.                          **************
  191.  
  192.   Note that pseudo ops can not start in column one, or they  will
  193. be considered labels.
  194.  
  195.  
  196.  .ASCIC <string>
  197.  ---------------
  198.   Similar in function to .ASCII, but sets bit 7 in the last char-
  199. acter  in the string expression.  If the statement has more  than
  200. one string, the last character in each will have bit 7 set.
  201.  
  202.  .ASCII <string>
  203.  ---------------
  204.   Define  ascii string.  .ASCII allows one or more ascii  strings
  205. to  be defined in memory.  See the section on strings for  infor-
  206. mation  about escape sequences and delimiters.  More  often  than
  207. not, it is easier to use the DB statement.
  208.  
  209.  
  210.  .ASCIL <string>
  211.  ---------------
  212.   Yet  another  variation of .ASCII, .ASCIL precedes  the  string
  213. with a length byte equal to the number of characters in the  fol-
  214. lowing  string.  As with .ASCIC, multiple strings in  one  .ASCIL
  215. statement  will  act  as if they were each in  their  own  .ASCIL
  216. statement (e.i. each will be preceded with a length byte)
  217.  
  218.  
  219.  .LIST
  220.  -----
  221.   See .XLIST.
  222.  
  223.  
  224.  .RADIX <value>
  225.  -------------
  226.   Sets the default number base.  If <value> is a number, it  will
  227. be treated as decimal regardless of current system number base.
  228.  
  229.  
  230.  .XLIST
  231.  -----
  232.   If a listing is being generated, .XLIST will suspend the  list
  233. ing until a .LIST is encountered.
  234.  
  235.  
  236. DB <string or expressions>
  237. --------------------------
  238.   Define Byte.  Used to define data areas in memory.  One or more
  239. numeric  expressions (separated by commas) may be defined.   Exp-
  240. ressions > 255 are truncated to eight bits.  Strings may also  be
  241. used, in which case each character of the string defines a  byte.
  242. Note  that  DB  can do what .ascii can do,  but  not  vice  versa
  243. (.ascii handles only strings)
  244.  
  245.  
  246. DS  <value>
  247. -----------
  248.   Define storage.  This statement is used to reserve some  number
  249. of bytes by advancing the location counter by <value>.  DS state-
  250. ments  produce  no code, therefore no .HEX or .TEK  output.   The
  251. statement  ORG $+<value> has the same effect.
  252.  
  253.   If  should be noted that in order to use base index  addressing
  254. with the LDC and LDE instructions, the offset must be defined  in
  255. pass  one before encountering the instruction (otherwise the  as-
  256. sembler would not know weather to use the short or long forms  of
  257. these  instructions).  For this reason, it is not a bad  idea  to
  258. define  storage at the beginning of a program rather than at  the
  259. end.
  260.  
  261.  
  262. DW <value>
  263. ----------
  264.   Define word.  Used to define data areas in memory.  One or more
  265. numeric  expressions (separated by commas) may be  defined.   The
  266. byte order used is high byte at the lower address, thus the  line
  267. "ADR:   DW   $AA55" would place $AA at ADR and $55 at ADR+1.
  268.  
  269.  
  270. EQU <value>
  271. -----------
  272.   Sets  the most recently defined symbol to  <value>.   Normally,
  273. this symbol is declared in the same line as the equ statement.
  274.  
  275. END
  276. ---
  277.   Used  to mark the end of the source code, END also keeps  track
  278. of  pass 1 and pass 2 end addresses, and generates an error  mes-
  279. sage  if they change.  This error should only be caused  by  some
  280. other error.  If a program assembles with only this error,  it is
  281. due  to a bug in the assembler and I would appreciate getting  my
  282. hands on any source files that cause such errors.
  283.  
  284.  
  285. INCLUDE <filename> (commercial version only)
  286. --------------------------------------------
  287.   The include pseudo op allows some other file to be included  in
  288. the  file being assembled.  The effect is the same as pulling  in
  289. <filename> at the location of the include.  If <filename> is  not
  290. in upper case, it will be upcased internally prior to opening the
  291. file.   No  default  extension  is  provided  by  the  assembler,
  292. <filename> may be any legal CP/M file.  If <filename> can not  be
  293. opened, the assembler will abort.
  294.  
  295.   In  the  current implementation, include files  may  be  nested
  296. without limit as long as there is stack space.  Future  implemen-
  297. tations will support at least four levels of nesting.
  298.  
  299.  
  300.  
  301. ORG  <value>
  302. ------------
  303.   Sets  the  location counter to <value>.  The  default  location
  304. counter value is zero.
  305.  
  306.                       *         *         *
  307.  
  308. asmS8 compatibility
  309. -------------------
  310.   The  Zilog Super8 cross assembler 'asmS8' (which is not  avail-
  311. able for CP/M) differs from XS8 in several areas.  Porting source
  312. between  the two is not difficult given a good wordprocessor,  as
  313. long as you are aware of the following:
  314.  
  315.   1)  Zilog uses a different scheme for representing  number
  316.   bases. A lead '%' means hexadecimal, and '%(n)' means base
  317.   N.   XS8  uses  a lead % in the more conventional  way  to
  318.   indicate  binary,  and a lead '$' or trailing 'h' to indi-
  319.   cate hex.
  320.  
  321.   2) Modules are not supported under XS8. To convert to XS8,
  322.   comment out all .BEGIN and .END statements.   This prohib-
  323.   its  local  symbols,  and  if there are  duplicate  symbol
  324.   names, the assembler will issue error messages.  By taking
  325.   a  listing of the errors,  and referring to the  commented
  326.   out  .BEGIN and .END statements,  it is not  difficult  to
  327.   change what needs changing.
  328.  
  329.   3) XS8 is not a relocating assembler.  This means programs
  330.   written  as  several source files and linked must be  con-
  331.   catenated  to  be assembled,  as well as all  .GLOBAL  and
  332.   .EXTERN  statements removed.   If the concatenated file is
  333.   too  big to handle easily,  one solution if you  have  the
  334.   commercial  version  is to use INCLUDE statements  in  the
  335.   first file to perform the concatination.
  336.  
  337.   4)  The  expression handler under the demo version XS8  is
  338.   not very sophisticated.   Some of this can be resolved  by
  339.   using  a few more EQU's to do the math.  For any work  in-
  340.   volving  more advance expression,  purchase of the commer-
  341.   cial version is strongly recommended.
  342.  
  343.   5)  XS8  is not a macro assembler.   Any  macros  must  be
  344.   manually expanded.
  345.  
  346.   6) According to the test listing on page E-11 of the users
  347.   guide,  it  appears that asmS8 will not correctly assemble
  348.   LDC  or LDE instructions when using the direct  addressing
  349.   mode.   Given that I am rather fond of using memory  vari-
  350.   ables  as well as register variables,  XS8 will  correctly
  351.   assemble  these instructions.   Be aware of this error  if
  352.   you  are trying to get the output of XS8 to match that  of
  353.   asmS8.   If  you are curious,  the monitor in  the  Super8
  354.   contest  board does not use this instruction in this form,
  355.   which  may  explain why an unnecessarily large  number  of
  356.   registers are tied up by the monitor.
  357.  
  358.   7)  In  the monitor source there is a string at the  label
  359.   BRK_MSG which is delimited by a ` (grave).   This seems to
  360.   add $60 $0A to the end of the string, which is useless, as
  361.   the  string is delimited by the \r.   Use of the grave  in
  362.   this fashion is not documented in the asmS8  manual.   The
  363.   grave is not a valid string delimiter under XS8.
  364.  
  365.  
  366.   8)  Many (if not all) of the zilog pseudo ops begin with a
  367.   period.  Most under XS8 (such as EQU, DB, DW, ORG, etc) do
  368.   not.
  369.  
  370.                       *         *         *
  371.  
  372. Sample code
  373. -----------
  374.   Two  source files are provided as examples for using XS8.   The
  375. first,  T.S8  contains all instructions in all forms and  may  be
  376. used  to  validate this assembler (note LDC error on  asmS8  men-
  377. tioned  earlier).  The second program (MON.S8) is  a  replacement
  378. monitor  for  the super8 demo board, basically the  same  as  the
  379. monitor that came with, with following modifications:
  380.  
  381.  
  382.   1) It doesn't clobber the user program's working registers
  383.   2) The user's stack pointer is maintained
  384.   3) A single step function (T) has been added
  385.   4) The routine HOST_DELAY has been disabled
  386.   5) Breakpoint  set  routine  has been debugged
  387.   6) W command also shows user stack
  388.   7) Monitor uses external stack, preserving registers
  389.   8) EMT is set up for a 250 ns rom.
  390.   9) Various routines have been cleaned up.
  391.  10) Baud rate is set at 19,200
  392.  
  393.   The  HOST_DELAY routine is called in many places to  allow  the
  394. IBM-PC to catch up with the monitor.  As CP/M computers as a rule
  395. are  not  as grossly inefficient as IBM-PC's in  performing  i/o,
  396. this  annoying  and unnecessary delay was disabled.  If  you  are
  397. using  a CP/M emulator on a PC, and intend to use  HOST.EXE,  you
  398. will  have to re-enable HOST-DELAY.  See the source for  details.
  399. If  you have need of a new monitor prom and can not  program  one
  400. yourself, contact me for details in obtaining one.
  401.  
  402.   Another  thing that should be mentioned is that  HOST.EXE  off-
  403. loaded the in line assembler to the host computer.  This function
  404. has not yet been incorporated into the monitor rom.
  405.  
  406.  
  407. Performance
  408. -----------
  409.   The  two  programs just mentioned provide good bench  marks  of
  410. this  assembler.  On a 4mhz Z-80 system running CP/M 3.0  off  an
  411. ST-225 hard disk, the following results were obtained:
  412.  
  413.                          T.S8           MON.S8
  414.  
  415.      Assembly time:      3.0 seconds    86 seconds
  416.      Lines assembled:    500            7744
  417.      Lines/minute        10,000         6,114
  418.  
  419.  
  420.   MON.S8 assembles at a slower rate for two reasons:  1) It  con-
  421. tains a large number of comments, thus increasing disk i/o  time.
  422. 2)  It contains a large number of symbols.  The time required  to
  423. search  the  symbol table is a linear function of the  number  of
  424. elements in the table.
  425.  
  426.   In  any  case, assembly time is a good order  of  magnitude  or
  427. better than asmS8 under MS-DOS, due in part to the fact the  8088
  428. processor is not a very good machine to run 'C' on.  To  assemble
  429. and link the four monitor files into a hex file takes 12:02 on  a
  430. Leading Edge Model D w/st-225 hard disk (one of the faster  PC-XT
  431. clones).  3:08 of this is just for linking (twice as long as  the
  432. entire assembly on the CP/M machine).  It would appear from these
  433. numbers that a low-end floppy-based CP/M system running XS8 would
  434. be  roughly comparable in performance to a 80286 machine  running
  435. asmS8.
  436.  
  437.   In  case you think I must be some sort of super hack, I  should
  438. point out that assemblers from other companies that are available
  439. for  both  CP/M and ms-dos (eg. Avocet's  XASM05  for  the  6805)
  440. perform  in very similar ratios.  XS8 is actually  optimized  for
  441. compactness and simplicity of code rather than for speed.
  442.  
  443.  
  444.  
  445.                        ******************
  446.                        * Error Messages *
  447.                        ******************
  448.  
  449. Can't Open File
  450. ---------------
  451.   More  often  than not, this is caused by the  source  file  not
  452. being  present  (remember, it must have a .S8  extension).   This
  453. error  can also be caused by being unable to open an output  file
  454. (.hex, .prn or .tek) due to the directory being full, or the disk
  455. being  in  r/o mode.  This error is fatal, and  will  immediately
  456. abort the program.
  457.  
  458.  
  459. Disk Full
  460. ---------
  461.   Self explanatory.
  462.  
  463.  
  464. Previously defined symbol
  465. -------------------------
  466.   Rather self explanatory.  Be aware that at the start, there are
  467. 50 some odd register names in the symbol table (they do not  show
  468. in  the table listing, however).  When a duplicate symbol is  en-
  469. countered, it is ignored, and the first symbol remains valid.
  470.  
  471. Unrecognized op code
  472. --------------------
  473.   Having  something  in the op code field that is neither  an  op
  474. code nor a pseudo op will cause this error.
  475.  
  476.  
  477. Bad number encountered
  478. ----------------------
  479.   Self  explanatory.   Something like  add r14,47xyz  will  cause
  480. this error.
  481.  
  482.  
  483. Value expected
  484. --------------
  485.   Self explanatory
  486.  
  487.  
  488. Operand syntax error
  489. --------------------
  490.   If  an error is encountered in parsing the arguments to an  op-
  491. code, this error is generated.
  492.  
  493. Symbol too long
  494. ---------------
  495.   If a symbol if more than 16 characters in length, this error is
  496. generated.
  497.  
  498.  
  499. Missing END statement
  500. ---------------------
  501.   An END statement is required at the end of a source file.
  502.  
  503.  
  504. Offset not defined on pass1
  505. ---------------------------
  506.   As  mentioned earlier,  the offset used with LDC & LDE  in  the
  507. base  index addressing mode must be evaluable in pass 1  for  the
  508. assembler to know if the short or long form of the instruction is
  509. to be used.
  510.  
  511.  
  512. Relative jump out of range
  513. -------------------------
  514.   A  relative jump can only range -128 to +127 from  the  address
  515. following the instruction.  Trying to go further results in  this
  516. error.
  517.  
  518.  
  519. Symbol not found
  520. ----------------
  521.   Self explanatory.  Certain ops like EQU, ORG, and LDC/LDE  must
  522. be able to evaluate symbols on pass 1 as well as pass two.
  523.  
  524.  
  525. Too many Symbols!  Out of memory!
  526. --------------------------------
  527.   It  takes one hell of a lot of symbols to do this, but  if  you
  528. do, this is the error message you get.
  529.  
  530.  
  531. Missing "
  532. ---------
  533.   If an expression contains an improperly terminated string, this
  534. is the error you will get.
  535.  
  536.  
  537. End address changed on pass 2
  538. -----------------------------
  539.   Pass 1 figures out how much memory each line of code will take,
  540. and defines all the symbols.  Pass 2 actually generates the code.
  541. If the location counter at the end changes from pass one to  pass
  542. two, something went wrong.
  543.  
  544.  
  545.                       *         *         *
  546.  
  547. Royalties, etc.
  548. ---------------
  549.   If  you are reading this, you no doubt obtained it directly  or
  550. indirectly  through a BBS system.  The topic of 'share  ware'  is
  551. very  controversial  these days, and I do not wish to  muddy  the
  552. waters further by asking you to send me money, especially if your
  553. intention is just for hobbyist use.
  554.  
  555.   On  the other hand, if you would like to be kept posted on  im-
  556. provements,  updates, and bug fixes on this product, if you  need
  557. some  support, or if you are a commercial user,  it  is  strongly
  558. advised that you purchase the commercial version.
  559.  
  560.   The  commercial version of this assembler has a few more  bells
  561. and whistles, most noticeably  1) a full blown expression evalua-
  562. tor,   2) support for nested INCLUDE files  3) support  for  con-
  563. ditional  assembly and 4) Support for threaded  language  genera-
  564. tion.  The current price for this product is $150.00.  Also under
  565. development  is a multi-tasking ultra high speed FORTH  tool  kit
  566. for the Super8.  For more information, please contact:
  567.  
  568.  
  569.                               Jeffrey D. Wilson
  570.                               96 E. Broad Street
  571.                               Bergenfield, NJ 07621
  572.                               (201) 384-1596
  573.  
  574. this assembler has a few more  bells
  575. and whistles, most noticeably  1) a full blown