Subversion Repositories pentevo

Rev

Blame | Last modification | View Log | Download | RSS feed | ?url?

  1. %% Hi Folks,
  2. %%
  3. %% this is a release of the English AS manual.  I haven't
  4. %% done the entire translation myself, large parts of it are the work of some
  5. %% other people around the net who deserve my deep appreciation for this job.
  6. %% My parts of the translation are the results of a brute-force attempt,
  7. %% so there are surely tons of spelling errors and passages that will
  8. %% make people with English as their mother tongue either laugh or cry...
  9.  
  10. %% Alfred Arnold
  11.  
  12. %%         translation by: Oliver Sellke (OSIP, D-65199 Wiesbaden)
  13. %%                           (proof-read in parts by Stefan Hilse, Wiesbaden)
  14. %%                         Alfred Arnold
  15. %%                         Stephan Kanthak
  16. %%                         Vittorio De Tomasi
  17. %%
  18. %%         thanks to the authors of:
  19. %%                         FB-translator
  20. %%                         GNU-ispell
  21. %%
  22. %% ------------------------------------------------------------------------------
  23.  
  24. %%TITLE User's Manual for Macro Assembler AS
  25. \documentclass[12pt,twoside]{report}
  26. \usepackage{makeidx}
  27. \usepackage{hyperref}
  28. \usepackage{longtable}
  29. \pagestyle{headings}
  30. \sloppy
  31. %%\textwidth 15cm
  32. %%\evensidemargin 0.5cm
  33. %%\oddsidemargin 0.5cm
  34. \topsep 1mm
  35. \parskip 0.3cm plus0.25cm minus0.25cm
  36. \parindent 0cm
  37.  
  38. \newcommand{\ii}[1]{{\it #1}}
  39. \newcommand{\bb}[1]{{\bf #1}}
  40. \newcommand{\tty}[1]{{\tt #1}}
  41. \newcommand{\tin}[1]{{\scriptsize #1}}
  42. \newcommand{\ttindex}[1]{\index{#1@{\tt #1}}}
  43. \newcommand{\asname}{{AS}}
  44.  
  45. \font\mengft=cmss9 scaled \magstep1
  46. \def \rz{\hbox{\mengft{I \hskip -1.7mm R}}}
  47.  
  48. \makeindex
  49.  
  50. %%===========================================================================
  51.  
  52. \begin{document}
  53.  
  54. \thispagestyle{empty}
  55.  
  56. \
  57. \vspace{7cm}\par
  58.  
  59. \begin{raggedright}
  60. {\large Alfred Arnold, Stefan Hilse, Stephan Kanthak, Oliver
  61. Sellke, Vittorio De Tomasi}
  62. \vspace{1cm}\par
  63. {\huge Macro Assembler \asname{} V1.42}\\
  64. \rule{9.5cm}{0.3mm}\\
  65. \vspace{2mm}\par
  66. {\huge User's Manual}
  67.  
  68. \vspace{1cm}\par
  69.  
  70. {\large Edition Januar 2025}
  71. \end{raggedright}
  72.  
  73. \clearpage
  74. \thispagestyle{empty}
  75.  
  76. \ \vspace{5cm}
  77.  
  78. {\em IBM, PPC403Gx, OS/2, and PowerPC} are registered trademarks of IBM
  79. Corporation.
  80.  
  81. {\em Intel, MCS-48, MCS-51, MCS-251, MCS-96, MCS-196 und MCS-296} are
  82. registered trademarks of Intel Corp. .
  83.  
  84. {\em Motorola and ColdFire} are registered trademarks of Motorola Inc. .
  85.  
  86. {\em MagniV} is a registered trademark of Freescale Semiconductor.
  87.  
  88. {\em PicoBlaze} is a registered trademark of Xilinx Inc.
  89.  
  90. {\em eZ80} and {\em Z80} are registered trademarks of Zilog Inc.
  91.  
  92. {\em UNIX} is a registered trademark of the The Open Group.
  93.  
  94. {\em Linux} is a registered trademark of Linus Thorvalds.
  95.  
  96. {\em Microsoft, Windows, and MS-DOS} are registered trademarks of
  97. Microsoft Corporation.
  98.  
  99. All other trademarks not explicitly mentioned in this section and used in
  100. this manual are properties of their respective owners.
  101.  
  102. \vspace{5cm}
  103.  
  104. This document has been processed with the LaTeX typesetting system, using
  105. the Linux operating system.
  106.  
  107. \clearpage
  108.  
  109. %%===========================================================================
  110.  
  111. {\parskip 0cm plus0.1cm \tableofcontents}
  112.  
  113. %%===========================================================================
  114.  
  115. \cleardoublepage
  116. \chapter{Introduction}
  117.  
  118. This instruction is meant for programmers who are already very familiar
  119. with Assembler and who like to know how to work with \asname{}.  It is rather a
  120. reference than a user's manual and so it neither tries to explain the
  121. ''language assembler'' nor the processors.  I have listed further
  122. literature in the bibliography which was substantial in the implementation
  123. of the different code generators.  There is no book I know where you can
  124. learn Assembler from the start, so I generally learned this by ''trial and
  125. error''.
  126.  
  127. %%After a small discussion on the mailing list, I decided to make an own proposal
  128. %%for a better name: ''ACASM''.  It is good tradition in the open source scene
  129. %%that acronyms may have multiple meanings.  Just some ideas:
  130. %%\begin{itemize}
  131. %%\item{,,AC'' may just refer to my hometown Aachen, since that is what cars
  132. %%      over here have on their license plates;}
  133. %%\item{,,Another CPU'', every time yet another new target was added;}
  134. %%\item{,,All Crap'', if you got frustrated over it...}
  135. %%\item{...or ,,Alfreds Cute Assembler'', if you really want to reference my
  136. %%      name...}
  137. %%\end{itemize}
  138.  
  139. %%---------------------------------------------------------------------------
  140.  
  141. \section{License Agreement}
  142. \label{SectLicense}
  143.  
  144. Before we can go ''in medias res'', first of all the inevitable prologue:
  145.  
  146. As in the present version is licensed according to the Gnu General Public
  147. License (GPL); the details of the GPL may be read in the file COPYING
  148. bundled with this distribution.  If you did not get it with \asname{}, complain
  149. to the one you got \asname{} from!
  150.  
  151. Shortly said, the GPL covers the following points:
  152. \begin{itemize}
  153. \item{Programs based upon \asname{} must also be licensed according to the GPL;}
  154. \item{distribution is explicitly allowed;}
  155. \item{explicit disclaiming of all warranties for damages resulting from
  156.      usage of this program.}
  157. \end{itemize}
  158. ...however, I really urge you to read the file COPYING for the details!
  159.  
  160. To accelerate the error diagnose and correction, please add the
  161. following details to the bug report:
  162. \begin{itemize}
  163. \item{Operating system (DOS, Windows, Linux) and its version}
  164. \item{Version of \asname{} used, resp. dates of the \tty{EXE}-files}
  165. \item{If you compiled the assembler yourself, the compiler used and its version}
  166. \item{If possible, the source file that triggered the bug}
  167. \end{itemize}
  168. You can contact me as follows:
  169. \begin{itemize}
  170. \item{by Surface Mail: \begin{description}
  171.               \item{Alfred Arnold}
  172.               \item{Hirschgraben 29}
  173.               \item{D-52062 Aachen}
  174.               \item{Germany}
  175.               \end{description}}
  176. \item{by E-Mail: \tty{alfred@ccac.rwth-aachen.de}}
  177. \end{itemize}
  178. If someone likes to meet me personally to ask questions and lives
  179. near Aachen (= Aix-la-Chapelle), you will be able to meet me there.
  180. You can do this most probably on thursdays from 8pm to 9pm at the
  181. RWTH Aachen Computer Club (Elisabethstrasse 16, first floor, corridor
  182. on the right).
  183.  
  184. Please don't call me by phone.  First, complex relations are
  185. extremely hard to discuss at phone.  Secondly, the telephone
  186. companies are already rich enough...
  187.  
  188. The latest version of \asname{} (DPMI, Win32, C) is available from
  189. the following Server:
  190. \begin{verbatim}
  191. http://john.ccac.rwth-aachen.de:8000/as
  192. \end{verbatim}
  193. or shortly
  194. \begin{verbatim}
  195. http://www.alfsembler.de
  196. \end{verbatim}
  197.  
  198. Whoever has no access to an FTP-Server can ask me to send the assembler
  199. by mail.  Only requests containing a blank CD-R and a self-addressed,
  200. (correctly) stamped envelope will be answered.  Don't send any money!
  201.  
  202. Now, after this inevitable introduction we can turn to the actual
  203. documentation:
  204.  
  205. %%---------------------------------------------------------------------------
  206.  
  207. \section{General Capabilities of the Assembler}
  208.  
  209. In contrast to ordinary assemblers, \asname{} offers the possibility to
  210. generate code for totally different processors.  At the moment, the
  211. following processor families have been implemented:
  212. \begin{itemize}
  213. \item{Motorola 68000..68040,, 683xx, and Coldfire incl. coprocessor and MMU}
  214. \item{Motorola ColdFire}
  215. \item{Motorola DSP5600x,DSP56300}\item{Motorola M-Core}
  216. \item{Motorola/IBM MPC601/MPC505/PPC403/MPC821}
  217. \item{IBM PALM}
  218. \item{Motorola 6800, 6801, 68(HC)11(K4) and Hitachi 6301}
  219. \item{Motorola/Freescale 6805, 68HC(S)08}
  220. \item{Motorola 6809 / Hitachi 6309}
  221. \item{Motorola/Freescale 68HC12(X) including XGATE}
  222. \item{Freescale/NXP S12Z (''MagniV'')}
  223. \item{Motorola 68HC16}
  224. \item{Freescale 68RS08}
  225. \item{Konami 052001}
  226. \item{Hitachi H8/300(H)}
  227. \item{Hitachi H8/500}
  228. \item{Hitachi SH7000/7600/7700}
  229. \item{Hitachi HMCS400}
  230. \item{Hitachi H16}
  231. \item{Rockwell 6502, 65(S)C02, Commodore 65CE02, WDC W65C02S, Rockwell 65C19, and
  232.      Hudson HuC6280}
  233. \item{Rockwell PPS-4}
  234. \item{CMD 65816}
  235. \item{Mitsubishi MELPS-740}
  236. \item{Mitsubishi MELPS-7700}
  237. \item{Mitsubishi MELPS-4500}
  238. \item{Mitsubishi M16}
  239. \item{Mitsubishi M16C}
  240. \item{DEC PDP-11}
  241. \item{DEC VAX}
  242. \item{Western Digital WD16}
  243. \item{Intel 4004/4040}
  244. \item{Intel MCS-48/41, including Siemens SAB80C382, and the OKI
  245.      variants}
  246. \item{Intel MCS-51/251, Dallas DS80C390}
  247. \item{Intel MCS-96/196(Nx)/296}
  248. \item{Intel 8080/8085}
  249. \item{Intel i960}
  250. \item{Signetics 8X30x}
  251. \item{Signetics 2650}
  252. \item{Philips XA}
  253. \item{Atmel (Mega-)AVR}
  254. \item{AMD 29K}
  255. \item{Siemens 80C166/167}
  256. \item{Zilog Z80 (including undocumented instructions), Z180, Z380, eZ80}
  257. \item{Sharp LR35902 (,,Gameboy Z80'')}
  258. \item{Sharp SC61860}
  259. \item{Sharp SC62015}
  260. \item{Zilog Z8, Super8, Z8 Encore}
  261. \item{Zilog Z8000}
  262. \item{Xilinx KCPSM/KCPSM3 ('PicoBlaze')}
  263. \item{LatticeMico8}
  264. \item{Toshiba TLCS-900(L)}
  265. \item{Toshiba TLCS-90}
  266. \item{Toshiba TLCS-870(/C)}
  267. \item{Toshiba TLCS-47}
  268. \item{Toshiba TLCS-9000}
  269. \item{Toshiba TC9331}
  270. \item{Microchip PIC16C54..16C57}
  271. \item{Microchip PIC16C84/PIC16C64}
  272. \item{Microchip PIC17C42}
  273. \item{Parallax SX20/28}
  274. \item{SGS M380/GI LP8000}
  275. \item{SGS-Thomson ST6}
  276. \item{SGS-Thomson ST7/STM8}
  277. \item{SGS-Thomson ST9}
  278. \item{SGS-Thomson 6804}
  279. \item{Texas Instruments TMS32010/32015}
  280. \item{Texas Instruments TMS3202x}
  281. \item{Texas Instruments TMS320C3x/TMS320C4x}
  282. \item{Texas Instruments TMS320C20x/TMS320C5x}
  283. \item{Texas Instruments TMS320C54x}
  284. \item{Texas Instruments TMS320C6x}
  285. \item{Texas Instruments TMS99xx/99xxx}
  286. \item{Texas Instruments TMS7000}
  287. \item{Texas Instruments TMS1000}
  288. \item{Texas Instruments TMS370xxx}
  289. \item{Texas Instruments MSP430(X)}
  290. \item{National Semiconductor IMP-16}
  291. \item{National Semiconductor IPC-16 ('PACE'), INS8900}
  292. \item{National Semiconductor SC/MP}
  293. \item{National Semiconductor INS807x}
  294. \item{National Semiconductor COP4}
  295. \item{National Semiconductor COP8}
  296. \item{National Semiconductor SC144xx}
  297. \item{National Semiconductor NS32xxx}
  298. \item{Olympia CP-3F (resp. SGS M380, GI LP8000)}
  299. \item{Fairchild ACE}
  300. \item{Fairchild F8}
  301. \item{NEC $\mu$PD78(C)0x/$\mu$PD 78(C)1x}
  302. \item{NEC $\mu$COM-43/44/45}
  303. \item{NEC $\mu$PD75xx}
  304. \item{NEC $\mu$PD 75xxx (alias 75K0)}
  305. \item{NEC 78K0}
  306. \item{NEC 78K2}
  307. \item{NEC 78K3}
  308. \item{NEC 78K4}
  309. \item{NEC $\mu$PD7720/7725}
  310. \item{NEC $\mu$PD77230}
  311. \item{NEC V60}
  312. \item{Fujitsu F$^2$MC8L}
  313. \item{Fujitsu F$^2$MC16L}
  314. \item{OKI OLMS-40}
  315. \item{OKI OLMS-50}
  316. \item{Panafacom MN1610/MN1613}
  317. \item{Renesas RX}
  318. \item{Padauk PMS/PMC/PFSxxx}
  319. \item{Symbios Logic SYM53C8xx (yes, they are programmable!)}
  320. \item{Intersil CDP1802/1804/1805(A)}
  321. \item{Intersil IM6100/6120}
  322. \item{XMOS XS1}
  323. \item{MIL STD 1750}
  324. \item{KENBAK-1}
  325. \item{GI CP-1600}
  326. \item{HP Nano Processor}
  327. \end{itemize}
  328. under work / planned / in consideration :
  329. \begin{itemize}
  330. \item{ARM}
  331. \item{Analog Devices ADSP21xx}
  332. \item{DEC VAX}
  333. \item{SGS-Thomson ST20}
  334. \item{Texas Instruments TMS320C8x}
  335. \item{Zilog eZ80}
  336. \end{itemize}
  337. Unloved, but now, however, present :
  338. \begin{itemize}
  339. \item{Intel 80x86, 80186, Nec V20..V55 incl. coprocessor 8087}
  340. \end{itemize}
  341. The switch to a different code generator is allowed even within one
  342. file, and as often as one wants!
  343.  
  344. The reason for this flexibility is that \asname{} has a history, which may also
  345. be recognized by looking at the version number. \asname{} was created as an
  346. extension of a macro assembler for the 68000 family. On special request, I
  347. extended the original assembler so that it was able to translate 8051
  348. mnemonics.  On this way (decline ?!) from the 68000 to 8051, some other
  349. processors were created as by-products.  All others were added over time
  350. due to user requests.  So At least for the processor-independent core of
  351. \asname{}, one may assume that it is well-tested and free of obvious bugs.
  352. However, I often do not have the chance to test a new code generator in
  353. practice (due to lack of appropriate hardware), so surprises are not
  354. impossible when working with new features.  You see, the things stated in
  355. section \ref{SectLicense} have a reason...
  356.  
  357. This flexibility implies a somewhat exotic code format, therefore I
  358. added some tools to work with it. Their description can be found in
  359. chapter \ref{ChapTools}.
  360.  
  361. \asname{} is a macro assembler, which means that the programmer has the
  362. possibility to define new ''commands'' by means of macros.
  363. Additionally it masters conditional assembling.  Labels inside macros
  364. are automatically processed as being local.
  365.  
  366. For the assembler, symbols may have either integer, string or floating
  367. point values.  These will be stored - like interim values in formulas -
  368. with a width of 32 bits for integer values, 80 or 64 bits for floating
  369. point values, and 255 characters for strings.  For a couple of micro
  370. controllers, there is the possibility to classify symbols by segmentation.
  371. So the assembler has a (limited) possibility to recognize accesses to
  372. wrong address spaces.
  373.  
  374. The assembler does not know explicit limits in the nesting depth of
  375. include files or macros; a limit is only given by the program stack
  376. restricting the recursion depth.  Nor is there a limit for the
  377. symbol length, which is only restricted by the maximum line length.
  378.  
  379. From version 1.38 on, \asname{} is a multipass-assembler.  This pompous term
  380. means no more than the fact that the number of passes through the
  381. source code need not be exactly two. If the source code does not
  382. contain any forward references, \asname{} needs only one pass.  In case \asname{}
  383. recognizes in the second pass that it must use a shorter or longer
  384. instruction coding, it needs a third (fourth, fifth...) pass to
  385. process all symbol references correctly. There is nothing more behind
  386. the term ''multipass'', so it will not be used further more in this
  387. documentation.
  388.  
  389. After so much praise a bitter pill: \asname{} cannot generate linkable code.
  390. An extension with a linker needs considerable effort and is not planned
  391. at the moment.
  392.  
  393. Those who want to take a look at the sources of \asname{} can simply get the
  394. Unix version of \asname{}, which comes as source for self-compiling.  The sources
  395. are definitely not in a format that is targeted at easy understanding -
  396. the original Pascal version still raises its head at a couple of places,
  397. and I do not share a couple of common opinions about 'good' C coding.
  398.  
  399. %%---------------------------------------------------------------------------
  400.  
  401. \section{Supported Platforms}
  402.  
  403. Though \asname{} started as a pure DOS \marginpar{{\em DOS}} program, there are a
  404. couple of versions available that are able to exploit a bit more than the
  405. Real Mode of an Intel CPU.  Their usage is kept as compatible to the DOS
  406. version as possible, but there are of course differences concerning
  407. installation and embedding into the operating system in question.
  408. Sections in this manual that are only valid for a specific version of \asname{}
  409. are marked with a corresponding sidemark (at this paragraph for the DOS
  410. version) aheaded to the paragraph.  In detail, the following further
  411. versions exist (distributed as separate packages):
  412.  
  413. In case you run \marginpar{{\em DPMI}}into memory problems when assembling
  414. large and complex programs under DOS, there is a DOS version that runs in
  415. protected mode via a DOS extender and can therefore make use of the whole
  416. extended memory of an AT.  The assembly becomes significantly slower by
  417. the extender, but at least it works...
  418.  
  419. There is a native OS/2 \marginpar{{\em OS/2}} version of \asname{} for friends of
  420. IBM's OS/2 operating system.  Since version 1.41r8, this is a full 32-bit
  421. OS/2 application, which of course means that OS/2 2.x and at least an
  422. 80386 CPU are mandatory.
  423.  
  424. You can leave \marginpar{{\em UNIX}} the area of PCs-only with the C
  425. version of \asname{} that was designed to be compilable on a large number of UNIX
  426. systems (this includes OS/2 with the emx compiler) without too much of
  427. tweaking.  In contrast to the previously mentioned versions, the C version
  428. is delivered in source code, i.e. one has to create the binaries by
  429. oneself using a C compiler.  This is by far the simpler way (for me) than
  430. providing a dozen of precompiled binaries for machines I sometimes only
  431. have limited access to...
  432.  
  433. %%===========================================================================
  434.  
  435. \cleardoublepage
  436. \chapter{Assembler Usage}
  437.  
  438. \begin{quote}\begin{raggedright}{\it
  439. Scotty: Captain, we din\verb!'! can reference it! \\
  440. Kirk:   Analysis, Mr. Spock? \\
  441. Spock:  Captain, it doesn\verb!'!t appear in the symbol table. \\
  442. Kirk:   Then it\verb!'!s of external origin? \\
  443. Spock:  Affirmative. \\
  444. Kirk:   Mr. Sulu, go to pass two. \\
  445. Sulu:   Aye aye, sir, going to pass two. \\
  446. }\end{raggedright}\end{quote}
  447.  
  448. %%---------------------------------------------------------------------------
  449.  
  450. \section{Hardware Requirements}
  451.  
  452. The hardware requirements of \asname{} vary substantially from version to
  453. version:
  454.  
  455. The DOS version \marginpar{{\em DOS}} will principally run on any
  456. IBM-compatible PC, ranging from a PC/XT with 4-dot-little megahertz up to
  457. a Pentium.  However, similar to other programs, the fun using \asname{} increases
  458. the better your hardware is.  An XT user without a hard drive will
  459. probably have significant trouble placing the overlay file on a floppy
  460. because it is larger than 500 Kbytes...the PC should therefore have at
  461. least a hard drive, allowing acceptable loading times.  \asname{} is not very
  462. advanced in its main memory needs: the program itself allocates less than
  463. 300 Kbytes main memory, \asname{} should therefore work on machines with at least
  464. 512 Kbytes of memory.
  465.  
  466. The version of \asname{} \marginpar{{\em DPMI}} compiled for the DOS Protected
  467. Mode Interface (DPMI) requires at least 1 Mbyte of free extended memory.
  468. A total memory capacity of at least 2 Mbytes is therefore the absolute
  469. minimum given one does not have other tools in the XMS (like disk caches,
  470. RAM disks, or a hi-loaded DOS); the needs will rise then appropriately.
  471. If one uses the DPMI version in a DOS box of OS/2, one has to assure that
  472. DPMI has been enabled via the box's DOS settings (set to \tty{on} or
  473. \tty{auto}) and that a sufficient amount of XMS memory has been assigned
  474. to the box.  The virtual memory management of OS/2 will free you
  475. from thinking about the amount of free real memory.
  476.  
  477. The C version of \asname{} \marginpar{{\em UNIX}} is delivered as source code and
  478. therefore requires a UNIX or OS/2 system equipped with a C compiler.  The
  479. compiler has to fulfill the ANSI standard (GNU-C for example is
  480. ANSI-compliant).  You can look up in the \tty{README} file whether your
  481. UNIX system has already been tested so that the necessary definitions have
  482. been made.  You should reserve about 15 Mbytes of free hard disk space for
  483. compilation; this value (and the amount needed after compilation to store
  484. the compiled programs) strongly differs from system to system, so you
  485. should take this value only as a rough approximation.
  486.  
  487. %%---------------------------------------------------------------------------
  488.  
  489. \section{Delivery}
  490.  
  491. Principally, you can obtain \asname{} in one of two forms: as a {\em binary} or a
  492. {\em source} distribution.  In case of a binary distribution, one gets \asname{},
  493. the accomanying tools and auxiliary files readily compiled, so you can
  494. immediately start to use it after unpacking the archive to the desired
  495. destination on your hard drive.
  496. Binary distibutions are made for widespread platforms, where either the
  497. majority of users does not have a compiler or the compilation is tricky
  498. (currently, this includes DOS and OS/2).  A source distribution in
  499. contrast contains the complete set of C sources to generate \asname{}; it is
  500. ultimately a snapshot of the source tree I use for development on \asname{}.  The
  501. generation of \asname{} from the sources and their structure is described in
  502. detail in appendix \ref{ChapSource}, which is why at this place, only the
  503. contents and installation of a binary distribution will be described:
  504.  
  505. The contents of the archive is separated into several subdirectories,
  506. therefore you get a directory subtree immediately after unpacking without
  507. having to sort out things manually.  The individual directories contain
  508. the following groups of files:
  509. \begin{itemize}
  510. \item{{\tt BIN}: executable programs, text resources;}
  511. \item{{\tt INCLUDE}: include files for assembler programs, e.g. register
  512.      definitions or standard macros;}
  513. \item{{\tt MAN}: quick references for the individual programs in Unix
  514.      'man' format.}
  515. \end{itemize}
  516. A list of the files found in every binary distribution is given in table
  517. \ref{TabCommonPackageList}.  In case a file listed in one of these (or the
  518. following) tables is missing, someone took a nap during copying (probably
  519. me)...
  520.  
  521. \begin{center}\begin{longtable}{|l|l|}
  522. \hline
  523. File              & Function \\
  524. \hline
  525. \hline
  526. \endhead
  527. {\bf Directory BIN} & \\
  528. \hline
  529. AS.EXE            & executable of assembler \\
  530. PLIST.EXE         & lists contents of code files \\
  531. PBIND.EXE         & merges code files \\
  532. P2HEX.EXE         & converts code files to hex files \\
  533. P2BIN.EXE         & converts code files to binary files \\
  534. AS.MSG            & text resources for \asname{} (DOS only) \\
  535. PLIST.MSG         & text resources for PLIST *) \\
  536. PBIND.MSG         & text resources for PBIND *) \\
  537. P2HEX.MSG         & text resources for P2HEX *) \\
  538. P2BIN.MSG         & text resources for P2BIN *) \\
  539. TOOLS.MSG         & common text resources for all tools *) \\
  540. CMDARG.MSG        & common text resources for all programs *) \\
  541. IOERRS.MSG        & \\
  542. \hline
  543. \multicolumn{2}{|l|}{*) DOS only} \\
  544. \hline
  545. {\bf Directory DOC} & \\
  546. \hline
  547. AS\_DE.DOC        & german documentation, ASCII format \\
  548. AS\_DE.HTML       & german documentation, HTML format \\
  549. AS\_DE.TEX        & german documentation, LaTeX format \\
  550. AS\_EN.DOC        & english documentation, ASCII format \\
  551. AS\_EN.HTML       & english documentation, HTML format \\
  552. AS\_EN.TEX        & english documentation, LaTeX format \\
  553. \hline
  554. {\bf Directory INCLUDE} & \\
  555. \hline
  556. BCDIC.INC         & definition of BCDIC/code page 359 \\
  557. BITFUNCS.INC      & functions for bit manipulation \\
  558. CTYPE.INC         & functions for classification of \\
  559.                  & characters \\
  560. EBCDIC.INC        & includes all EBCDIC variants \\
  561. CP037.INC         & definition EBCDIC (code page 037) \\
  562. CP5100.INC        & definition character set IBM 5100 \\
  563. CP5110.INC        & definition EBCDIC (IBM 5110) \\
  564. 80C50X.INC        & register addresses SAB C50x \\
  565. 80C552.INC        & register addresses 80C552 \\
  566. H8\_3048.INC      & register addresses H8/3048 \\
  567. KENBAK.INC        & register addressed Kenbak-1 \\
  568. RADIX50.INC       & definition of RADIX 50 character set \\
  569. REG166.INC        & addresses and instruction macros 80C166/167 \\
  570. REG251.INC        & addresses and bits 80C251 \\
  571. REG29K.INC        & peripheral addresses AMD 2924x \\
  572. REG53X.INC        & register addresses H8/53x \\
  573. REG6303.INC       & register addresses 6303 \\
  574. REG683XX.INC      & register addresses 68332/68340/68360 \\
  575. REG7000.INC       & register addresses TMS70Cxx \\
  576. REG78310.INC      & register addresses \& vectors 78K3 \\
  577. REG78K0.INC       & register addresses 78K0 \\
  578. REG96.INC         & register addresses MCS-96 \\
  579. REGACE.INC        & register addresses ACE \\
  580. REGEZ80.INC       & register addresses eZ80 \\
  581. REGF8.INC         & register and memory addresses F8 \\
  582. REGAVROLD.INC     & register and bit addresses AVR family (old)\\
  583. REGAVR.INC        & register and bit addresses AVR family \\
  584. REGCOLD.INC       & register and bit addresses Coldfire family \\
  585. REGCOP8.INC       & register addresses COP8 \\
  586. REGGP32.INC       & register addresses 68HC908GP32 \\
  587. REGH16.INC        & register addresses H16\\
  588. REGHC12.INC       & register addresses 68HC12 \\
  589. REGM16C.INC       & register addresses Mitsubishi M16C \\
  590. REGMSP.INC        & register addresses TI MSP430 \\
  591. REGPDK.INC        & register and bit addresses PMC/PMS/PFSxxx \\
  592. REGS12Z.INC       & register and bit addresses S12Z family \\
  593. REGST6.INC        & register and macro definitions ST6 \\
  594. REGST7.INC        & register and macro definitions ST7 \\
  595. REGSTM8.INC       & register and macro definitions STM8 \\
  596. REGST9.INC        & register and macro definitions ST9 \\
  597. REGV60.INC        & register addresses NEC V60 \\
  598. REGZ380.INC       & register addresses Z380 \\
  599. STDDEF04.INC      & register addresses 6804 \\
  600. STDDEF16.INC      & instruction macros and register addresses \\
  601.                  & PIC16C5x \\
  602. STDDEF17.INC      & register addresses PIC17C4x \\
  603. STDDEF18.INC      & register addresses PIC16C8x \\
  604. STDDEF2X.INC      & register addresses TMS3202x \\
  605. STDDEF37.INC      & register and bit addresses TMS370xxx \\
  606. STDDEF3X.INC      & peripheral addresses TMS320C3x \\
  607. STDDEF4X.INC      & peripheral addresses TMS320C4x \\
  608. STDDEF47.INC      & instruction macros TLCS-47 \\
  609. STDDEF51.INC      & definition of SFRs and bits for \\
  610.                  & 8051/8052/80515 \\
  611. STDDEF56K.INC     & register addresses DSP56000 \\
  612. STDDEF5X.INC      & peripheral addresses TMS320C5x \\
  613. STDDEF60.INC      & instruction macros and register addresses \\
  614.                  & PowerPC \\
  615. REGSX20.INC       & register and bit addresses Parallax SX20/28 \\
  616. AVR/\*.INC        & register and bit addresses AVR family \\
  617.                  & (do not include directly, use REGAVR.INC) \\
  618. COLDFIRE/\*.INC   & register and bit addresses ColdFire family \\
  619.                  & (do not include directly, use REGCOLD.INC) \\
  620. EZ80/\*.INC       & register and bit addresses eZ80 family \\
  621.                  & (do not include directly, use REGCOLD.INC) \\
  622. PDK/\*.INC        & register and bit addresses PMC/PMS/PFSxxx \\
  623.                  & (do not include directly, use REGPDK.INC) \\
  624. S12Z/\*.INC       & register and bit addresses S12Z family \\
  625.                  & (do not include directly, use REGS12Z.INC) \\
  626. ST6/\*.INC        & register and bit addresses ST6 family \\
  627.                  & (do not include directly, use REGST6.INC) \\
  628. ST7/\*.INC        & register and bit addresses ST7 family \\
  629.                  & (do not include directly, use REGST7.INC) \\
  630. STM8/\*.INC       & register and bit addresses STM8 family \\
  631.                  & (do not include directly, use REGSTM8.INC) \\
  632. STDDEF62.INC      & register addresses and macros ST6 (old)\\
  633. STDDEF75.INC      & register addresses 75K0 \\
  634. STDDEF87.INC      & register and memory addresses TLCS-870 \\
  635. STDDEF90.INC      & register and memory addresses TLCS-90 \\
  636. STDDEF96.INC      & register and memory addresses TLCS-900 \\
  637. STDDEFXA.INC      & SFR and bit addresses Philips XA \\
  638. STDDEFZ8.INC      & register addresses Z8 family (old) \\
  639. REGZ8.INC         & register addresses Z8 family (new) \\
  640. Z8/\*.INC         & register and bit addresses Z8 family \\
  641.                  & (do not include directly, use REGZ8.INC) \\
  642. \hline
  643. {\bf Directory LIB} & \\
  644. \hline
  645. {\bf Directory MAN} & \\
  646. \hline
  647. ASL.1             & Short Reference for \asname{} \\
  648. PLIST.1           & Short Reference for PLIST \\
  649. PBIND.1           & Short Reference for PBIND \\
  650. P2HEX.1           & Short Reference for P2HEX \\
  651. P2BIN.1           & Short Reference for P2BIN \\
  652. \hline
  653. \caption{Standard Contents of a Binary Distribution
  654.         \label{TabCommonPackageList}}
  655. \end{longtable}\end{center}
  656.  
  657.  
  658. Depending on the platform, a binary distribution however may contain more
  659. files to allow operation, like files necessary for DOS extenders. In case
  660. of the DOS DPMI version \marginpar{{\em DPMI}}, the extensions listed in
  661. table \ref{TabDPMIPackageList} result.  Just to mention it: it is
  662. perfectly O.K. to replace the tools with their counterparts from a DOS
  663. binary distribution; on the on hand, they execute significantly faster
  664. without the extender's overhead, and on the other hand, they do not need
  665. the extended memory provided by the extender.
  666.  
  667. \begin{table*}[htp]
  668. \begin{center}\begin{tabular}{|l|l|}
  669. \hline
  670. File              & Function \\
  671. \hline
  672. \hline
  673. {\bf Directory MAN} & \\
  674. \hline
  675. ASL.1             & quick reference for \asname{} \\
  676. PLIST.1           & quick reference for PLIST \\
  677. PBIND.1           & quick reference for PBIND \\
  678. P2HEX.1           & quick reference for P2HEX \\
  679. P2BIN.1           & quick reference for P2BIN \\
  680. \hline
  681. \hline
  682. {\bf Directory BIN} & \\
  683. \hline
  684. DPMI16BI.OVL   & DPMI server for the assembler \\
  685. RTM.EXE        & runtime module of the extender \\
  686. \hline
  687. \end{tabular}\end{center}
  688. \caption{Additional Files in a DPMI Binary Distribution
  689.         \label{TabDPMIPackageList}}
  690. \end{table*}
  691.  
  692. An OS/2 binary distribution \marginpar{{\em OS/2}} contains in addition to
  693. the base files a set of DLLs belonging to the runtime environment of the
  694. emx compiler used to build \asname{} (table \ref{TabOS2PackageList}).  In case
  695. you already have these DLLs (or newer versions of them), you may delete
  696. these and use your ones insted.
  697.  
  698. \begin{table*}[htp]
  699. \begin{center}\begin{tabular}{|l|l|}
  700. \hline
  701. File              & function \\
  702. \hline
  703. \hline
  704. {\bf Directory BIN} & \\
  705. \hline
  706. EMX.DLL           & runtime libraries for \asname{} and \\
  707. EMXIO.DLL         & its tools \\
  708. EMXLIBC.DLL       & \\
  709. EMXWRAP.DLL       & \\
  710. \hline
  711. \end{tabular}\end{center}
  712. \caption{Additional Files in an OS/2 binary distribution
  713.         \label{TabOS2PackageList}}
  714. \end{table*}
  715.  
  716. %%---------------------------------------------------------------------------
  717.  
  718. \section{Installation}
  719.  
  720. There is no need for a \marginpar{{\em DOS}} special installation prior to
  721. usage of \asname{}.  It is sufficient to unpack the archive in a fitting place
  722. and to add a few minor settings.  For example, this is an installation a
  723. user used to UNIX-like operating systems might choose:
  724.  
  725. Create a directory \verb!c:\as! an (I will assume in the following that
  726. you are going to install \asname{} on drive C), change to this directory and
  727. unpack the archiv, keeping the path names stored in the archive (when
  728. using PKUNZIP, the command line option \verb!-d! is necessary for that).
  729. You now should have the following directory tree:
  730. \begin{verbatim}
  731. c:\as
  732. c:\as\bin
  733. c:\as\include
  734. c:\as\lib
  735. c:\as\man
  736. c:\as\doc
  737. c:\as\demos
  738. \end{verbatim}
  739. Now, append the directory \verb!c:\as\bin! to the \tty{PATH} statement in
  740. your \tty{AUTOEXEC.BAT}, which allows the system to find \asname{} and its tools.
  741. With your favourite text editor, create a file named \tty{AS.RC} in the
  742. \tty{lib} directory with the following contents:
  743. \begin{verbatim}
  744. -i c:\as\include
  745. \end{verbatim}
  746. This so-called {\em key file} tells \asname{} where to search for its include
  747. files.  The following statement must be added to your \tty{AUTOEXEC.BAT}
  748. to tell \asname{} to read this file:
  749. \begin{verbatim}
  750. set ASCMD=@c:\as\lib\as.rc
  751. \end{verbatim}
  752. There are many more things you can preset via the key file; they are
  753. listed in the following section.
  754.  
  755. The installation of the DPMI version \marginpar{{\em DPMI}} should
  756. principally take the same course as for the pure DOS version; as soon as
  757. the PATH contains the {\tt bin} directory, the DOS extender's files will
  758. be found automatically and you should not notice anything of this
  759. mechanism (except for the longer startup time...).  When working on an
  760. 80286-based computer, it is theoretically possible tha you get confronted
  761. with the following message upon the first start:
  762. \begin{verbatim}
  763.  machine not in database (run DPMIINST)
  764. \end{verbatim}
  765. Since the DPMIINST tool ins not any more included in newer versions of
  766. Borland's DOS extender, I suppose that this is not an item any more...in
  767. case you run into this, contact me!
  768.  
  769. The installation of the OS/2 version \marginpar{{\em OS/2}} can generally
  770. be done just like for the DOS version, with the addition that the DLLs
  771. have to be made visible for the operating system. In case you do not want
  772. to extend the {\tt LIBPATH} entry in your {\tt CONFIG.SYS}, it is of
  773. course also valid to move the DLLs into a directory already listed in {\tt
  774. LIBPATH}.
  775.  
  776. As already mentioned, the installation instructions in this section limit
  777. themselves to binary distributions.  Since an installation under Unix
  778. \marginpar{{\em UNIX}} is currently alway a source-based installation, the
  779. only hint I can give here is a reference to appendix \ref{ChapSource}.
  780.  
  781. %%---------------------------------------------------------------------------
  782.  
  783. \section{Start-Up Command, Parameters}
  784. \label{SectCallConvention}
  785.  
  786. \asname{} is a command line driven program, i.e. all parameters and file
  787. options are to be given in the command line.
  788.  
  789. A couple of message files belongs to \asname{} (recognizable by their suffix {\tt
  790. MSG}) \asname{} accesses to dynamically load the messages appropriate for the
  791. national language.  \asname{} searches the following directories for these files:
  792. \begin{itemize}
  793. \item{the current directory;}
  794. \item{the EXE-file's directory;}
  795. \item{the directory named in the {\tt AS\_MSGPATH} environment variable,
  796.      or alternitavely the directories listed in the {\tt PATH} environment
  797.      variable;}
  798. \item{the directory compiled into \asname{} via the {\tt LIBDIR} macro.}
  799. \end{itemize}
  800. These files are {\em indispensable} for a proper operation of \asname{}, i.e. \asname{}
  801. will terminate immediately if these files are not found.
  802.  
  803. The language selection (currently only German and English) is based on the
  804. {\tt COUNTRY} setting under DOS and OS/2 respectively on the {\tt LANG}
  805. environment variable under Unix.
  806.  
  807. In order to fulfill \marginpar{{\em DOS}} \asname{}'s memory requirements under
  808. DOS, the various code generator modules of the DOS version were moved into
  809. an overlay which is part of the EXE file.  A separate OVR file like in
  810. earlier versions of \asname{} therefore dose not exist any more, \asname{} will however
  811. still attempt to reduce the overlaying delays by using eventually
  812. available EMS or XMS memory.  In case this results in
  813. trouble, you may suppress usage of EMS or XMS by setting the environment
  814. variable \tty{USEXMS} or \tty{USEEMS} to \tty{n}.  E.g., it is possible to
  815. suppress the using of XMS by the command:
  816. \begin{verbatim}
  817.   SET USEXMS=n
  818. \end{verbatim}
  819. Since \asname{} performs all in- and output via the operating system (and
  820. therefore it should run also on not 100\% compatible DOS-PC's) and
  821. needs some basic display control, it emits ANSI control sequences
  822. during the assembly.
  823. In case you \marginpar{{\em DOS/}} should see strange characters in the
  824. messages displayed by \asname{}, your \tty{CONFIG.SYS} is obviously lacking a
  825. line like this:
  826. \begin{verbatim}
  827.   device=ansi.sys
  828. \end{verbatim}
  829. but the further \marginpar{{\em DPMI}} functions of \asname{} will not be
  830. influenced hereby.  Alternatively you are able to suppress the output of
  831. ANSI sequences completely by setting the environment variable
  832. \tty{USEANSI} to \tty{n}.
  833.  
  834. The DOS extender of the DPMI version \marginpar{{\em DPMI}} can be
  835. influenced in its memory allocation strategies by a couple of environment
  836. variables; if you need to know their settings, you may look up them in the
  837. file \tty{DPMIUSER.DOC}.  It is additionally able to extend the available
  838. memory by a swap file.  To do this, set up an environment variable
  839. \tty{ASXSWAP} in the following way:
  840. \begin{verbatim}
  841.  SET ASXSWAP=<size>[,file name]
  842. \end{verbatim}
  843. The size specification has to be done in megabytes and \bb{has} to be done.
  844. The file name in contrast is optional; if it is missing, the file is
  845. named \tty{ASX.TMP} and placed in the current directory.  In any case, the
  846. swap file is deleted after program end.
  847.  
  848. The command line parameters can roughly be divided into three categories:
  849. switches, key file references (see below) and file specifications.
  850. Parameters of these two categories may be arbitrarily mixed in the command
  851. line.  The assembler evaluates at first all parameters and then assembles
  852. the specified files.  From this follow two things:
  853. \begin{itemize}
  854. \item{the specified switches affect all specified source files. If
  855.      several source files shall be assembled with different switches,
  856.      this has to be done in separate runs.}
  857. \item{it is possible to assemble more than one file in one shot and to
  858.      bring it to the top, it is allowed that the file specs contain
  859.      wildcards.}
  860. \end{itemize}
  861. Parameter switches are recognized by \asname{} by starting with
  862. a slash (/) or hyphen (-).  There are switches that are only one
  863. character long and additionally switches composed of a whole word.
  864. Whenever \asname{} cannot interpret a switch as a whole word, it tries to
  865. interprete every letter as an individual switch.  For example, if you
  866. write
  867. \begin{verbatim}
  868. -queit
  869. \end{verbatim}
  870. instead of
  871. \begin{verbatim}
  872. -quiet
  873. \end{verbatim}
  874. \asname{} will take the letters \tty{q, u, e, i}, and \tty{t} as individual
  875. switches.  Multiple-letter switches additionally have the difference to
  876. single-letter switches that \asname{} will accept an arbitrary mixture of upper
  877. and lower casing, whereas single-letter switches may have a different
  878. meaning depending on whether upper or lower case is used.
  879.  
  880. At the moment, the following switches are defined:
  881. \ttindex{SHARED}
  882. \begin{itemize}
  883. \item{\tty{l}: sends assembler listing to console terminal (mostly screen).
  884.      In case several passes have to be done, the listing of all
  885.      passes will be send to the console (in opposite to the next
  886.      option).}
  887. \item{\tty{L}: writes assembler listing into a file. The list file will get
  888.      the same name as the source file, only the extension is
  889.      replaced by \tty{LST}.  Except one uses... }
  890. \item{\tty{OLIST}: with a fiel name as argument allows to redirect the
  891.      listing to a different file or a different path.  This option may
  892.      be used multiple times in case multiple files are assembled with
  893.      one execution.}
  894. \item{\tty{listline-prefix}: This option allows to modify the data that
  895.      is printed in front of every source line in the listing.  The
  896.      structure of the format string is described in \ref{SectListing}.}
  897. \item{\label{radix}\tty{RADIX}: This option changes the default number system
  898.      to a value between 2 and 36, thereby overriding the default of 10.
  899.      The value given by this switch can itself be overridden in the program
  900.      by the statement odf same name.}
  901. \item{\label{listradix}\tty{LISTRADIX}: By default, all numeric output in the listing
  902.      (addresses, generated code, symbol values) is written in hexadecimal
  903.      notation.  This switch requests usage of a different number system in the
  904.      range of 2 to 36.  For instance, '-listradix 8' requests octal output.
  905.      If the radix value is written with a leading zero (e.g. 08 instead of 8),
  906.      the program counter's current value is prited with leading zeros in
  907.      the listing.}
  908. \item{\tty{SPLITBYTE [character]}: Display numbers in the listing in byte groups,
  909.      separated by the given character.  A period is used as separator if
  910.      no explicit character is given.  This option is usually used in conjunction
  911.      with the \tty{LISTRADIX} option.  For instance, list radix 8 with a
  912.      period as character results in the so-called 'split octal' notation.}
  913. \item{\tty{o}: Sets the new name of the code file generated by \asname{}.  If this
  914.      option is used multiple times, the names will be assigned, one
  915.      after the other, to the source files which have to be
  916.      assembled.  A negation (see below) of this option in
  917.      connection with a name erases this name from the list.  A
  918.      negation without a name erases the whole list.}
  919. \item{\tty{SHAREOUT}:ditto for a SHARE file eventually to be created.}
  920. \item{\tty{c}: SHARED-variables will be written in a format which permits
  921.      an easy integration into a C-source file.  The extension of
  922.      the file is \tty{H}.}
  923. \item{\tty{p}: SHARED-variables will be written in a format which permits
  924.      easy integration into the CONST-block of a Pascal program.
  925.      The extension of the file is \tty{INC}.}
  926. \item{\tty{a}: SHARED-variables will be written in a format which permits
  927.      easy integration into an assembler source file. The
  928.      extension of the file is \tty{INC}.}
  929. \end{itemize}
  930. Concerning effect and function of the SHARED-symbols please see
  931. chapters \ref{ChapShareMain} resp. \ref{ChapShareOrder}.
  932. \begin{itemize}
  933. \item{\tty{g [format]}: This switch instructs \asname{} to create an additional
  934.      file that contains debug information for the program.  Allowed
  935.      formats are the \asname{}-specific MAP format ({\tt format=MAP}), a
  936.      NoICE-compatible command file ({\tt format=NOICE}), and the Atmel
  937.      format used by the AVR tools ({\tt format=ATMEL}). The information
  938.      stored in the MAP format is comprised of a symbol table and a table
  939.      describing the assignment of source lines to machine addresses.  A
  940.      more detailed description of the MAP format can be found in section
  941.      \ref{SectDebugFormat}  The file's extension is \tty{MAP}, \tty{NOI},
  942.      resp. \tty{OBJ}, depending on the chosen format.  If no explicit
  943.      format specification is done, the MAP format is chosen.}
  944. \item{\tty{noicemask [value]}: By default, \asname{} lists only symbols from the
  945.      CODE segment in NoICE debug info files.  With this option and an
  946.      integer value interpreted as a bit mask, symbols fom other segments
  947.      may be added.  The assignment of segments to bit positions may
  948.      be taken from table \ref{TabSegmentNums}.}
  949. \item{\tty{w}: suppress issue of warnings;}
  950. \item{\tty{E [file]}: error messages and warnings produced by \asname{} will be
  951.      redirected to a file. Instead of a file, the 5 standard
  952.      handles (STDIN..STDPRN) can also be specified as
  953.      \tty{!0} to \tty{!4} . Default is \tty{!2}, meaning STDERR.  If the
  954.      file option is left out, the name of the error file
  955.      is the same as of the source file, but with the
  956.      extension \tty{LOG}.}
  957. \item{\tty{q}: This switch suppresses all messages of \asname{}, the exceptions are
  958.      error messages and outputs which are are forced from the
  959.      source file.  The time needed for assembly is slightly reduced
  960.      hereby and if you call \asname{} from a shell there is no redirection
  961.      required.  The disadvantage is that you may ''stay in the dark''
  962.      for several minutes ... It is valid to write \tty{quiet} instead
  963.      of \tty{q}.}
  964. \item{\tty{v}: This is verbose, i.e. the opposite of quiet operation.  The
  965.      only additional information that is currently printed is the version
  966.      info.}
  967. \item{\tty{version}: Prints version information and exits.}
  968. \item{\tty{h}: write hexadecimal numbers in lowercase instead of capital
  969.      letters. This option is primarily a question of personal
  970.      taste.}
  971. \item{\tty{i $<$path list$>$}: issues a list of directories where the
  972.      assembler shall automatically search for include
  973.      files, in case it didn't find a file in the
  974.      current directory.  The different directories
  975.      have to be separated by semicolons.}
  976. \item{\tty{u}: calculate a list of areas which are occupied in the segments.
  977.      This option is effective only in case a listing is
  978.      produced. This option requires considerable additional
  979.      memory and computing performance. In normal operation it
  980.      should be switched off.}
  981. \item{\tty{C}: generates a list of cross references.  It lists which (global)
  982.      symbols are used in files and lines.  This list will also be
  983.      generated only in case a listing is produced.  This option
  984.      occupies, too, additional memory capacity during assembly.}
  985. \item{\tty{s}: issues a list of all sections (see chapter
  986.      \ref{ChapLocSyms}).  The nesting is indicated  by indentations
  987.      (Pascal like).}
  988. \item{\tty{t}: by means of this switch it is possible to separate single
  989.      components of the standard issued assembler-listing.  The assignment
  990.      of bits to parts can be found in the next section, where the exact
  991.      format of the assembly listing is explained.}
  992. \item{\tty{D}: defines symbols.  The symbols which are specified behind this
  993.      option and separated by commas are written to the
  994.      global symbol table before starting the assembly.  As default
  995.      these symbols are written as integer numbers with the
  996.      value TRUE, by means of an appended equal sign, however, you
  997.      can select other values.  The expression following the equals
  998.      sign may include operators or internal functions, but \bb{not}
  999.      any further symbols, even if these should have been defined
  1000.      before in the list!  Together with the commands for
  1001.      conditional assembly (see there) you may produce different
  1002.      program versions out of one source file by command line
  1003.      inputs. {\bf CAUTION!} If the case-sensitive mode is used, this has
  1004.      to be specified in the command line {\em before} any symbol
  1005.      definitions, otherwise symbol names will be converted to upper
  1006.      case at this place!}
  1007. \item{\tty{A}: stores the list of global symbols in another, more compact
  1008.      form.  Use this option if the assembler crashes with a stack
  1009.      overflow because of too long symbol tables.  Sometimes this
  1010.      option can increase the processing speed of the assembler, but
  1011.      this depends on the sources.}
  1012. \item{\tty{x}: Sets the level of detail for error messages.  The level
  1013.      is increased resp. decreased by one each time this option is given.
  1014.      While on level 0 (default) only the error message itself is printed,
  1015.      an extended message is added beginning at level 1 that should
  1016.      simplify the identification of the error's cause.  Appendix
  1017.      \ref{ChapErrMess} lists which error messages carry which extended
  1018.      messages.  At level 2 (maximum), the source line containing the
  1019.      error is additionally printed.}
  1020. \item{\tty{n}: If this option is set, the error messages will be issued
  1021.      additionally with their error number (see appendix
  1022.      \ref{ChapErrMess}).  This is primarily intended for use with shells
  1023.      or IDE's to make the identification of errors easier by those
  1024.      numbers.}
  1025. \item{\tty{U}: This option switches \asname{} to the case-sensitive mode, i.e.
  1026.      upper and lower case in the names of symbols, sections, macros,
  1027.      character sets, and user-defined functions will be distinguished.
  1028.      This is not the case by default.}
  1029. \item{\tty{P}: Instructs \asname{} to write the source text processed by macro
  1030.      processor and conditional assembly into a file.  Additional
  1031.      blank and pure comment lines are missing in this file.  The
  1032.      extension of this file is \tty{I}.}
  1033. \item{\tty{M}: If this switch is given, \asname{} generates a file, that contains
  1034.      definitions of macros defined in the source file that did not
  1035.      use the \tty{NOEXPORT} option.  This new file has the same name as
  1036.      the source file, only the extension is modified into \tty{MAC}.}
  1037. \item{\tty{G}: this switch defines whether \asname{} should produce code or not.
  1038.      If switched off, the processing will be stopped after the macro
  1039.      processor. This switch is activated by default (logically,
  1040.      otherwise you would not get a code file). This switch can be
  1041.      used in conjunction with the \tty{P} switch, if only the macro
  1042.      processor of \asname{} shall be used.}
  1043. \item{\tty{r [n]}: issue warnings if situations occur that force a further
  1044.      pass. This information can be used to reduce the number of
  1045.      passes.  You may optionally specify the number of the
  1046.      first pass where issuing of such messages shall start.
  1047.      Without this argument, warnings will come starting with
  1048.      the first pass.  Be prepared for a bunch of messages!!}
  1049. \item{\tty{bigendian}: This switch sets big endian mode for values placed
  1050.      in memory right from the program's beginning, given the target
  1051.      architecture supports the pseudo instruction of same name (see
  1052.      \ref{SectBIGENDIAN}).}
  1053. \item{\tty{plainbase}: This switch enables omission of an empty index
  1054.      argument right from the program's beginning (see \ref{SectPLAINBASE}).}
  1055. \item{\tty{underscrore-macroargs}: This switch enables usage of underscore characters
  1056.      in macro argument names (see \ref{SectMacros}).}
  1057. \item{\tty{relaxed}: this switch enables the RELAXED mode right from the
  1058.      beginning of the program, which otherwise has to be enabled by the
  1059.      pseudo instruction of sane name(see section \ref{SectRELAXED}).}
  1060. \item{\tty{intsyntax}: this switch allows to augment or reduce the list of
  1061.      allowed integer constant syntaxes right from the beginning of the
  1062.      program.  See section \ref{SectINTSYNTAX} for a list of allowed
  1063.      arguments.}
  1064. \item{\tty{supmode}: this switch enables right from the beginning of the
  1065.      program usage of machine instructions that may only be used in the
  1066.      processor's supervisor mode (see section \ref{SectSUPMODE}).}
  1067. \item{\tty{Y}: This switch instructs \asname{} to to suppress all messages about
  1068.      out-of-branch conditions, once the necessity for another pass is given.
  1069.      See section \ref{ForwRefs} for the (rare) situations that might make
  1070.      use of this switch necessary.}
  1071. \item{\tty{cpu $<$name$>$}: this switch allows to set the target processor
  1072.      \asname{} shall generate code for, in case the source file does not contain
  1073.      a {\tt CPU} instruction.  If the selected target
  1074.      supports CPU arguments (see section \ref{SectCPU}), they may be used
  1075.      on the command line as well.  Using this switch with \verb!?! or {\tt list}
  1076.      as argument lists all implemented targets.}
  1077. \item{\tty{alias $<$new$>$=$<$old$>$}:
  1078.      defines the processor type \tty{$<$new$>$} to be an alias for the
  1079.      type \tty{$<$old$>$}.  See section \ref{SectAlias} for the sense of
  1080.      processor aliases.}
  1081. \item{{\tt gnuerrors}: display messages about errors resp. warnings not
  1082.      in the \asname{} standard format, but instead in a format similar to the
  1083.      GNU C compiler.  This simplifies the integration of \asname{} into
  1084.      environments tuned for this format, however also suppresses the
  1085.      display of precise error positions in macro bodies!}
  1086. \item{{\tt maxerrors [n]}: instructs the assembler to terminate
  1087.      assembly after the given number of errors.}
  1088. \item{{\tt maxerrors [n]}: instructs the assembler to terminate
  1089.      assembly if the include nesting level exceeds the given limit
  1090.      (default is 200).}
  1091. \item{{\tt Werror}: instructs the assembler to treat warnings as errors.}
  1092. \item{{\tt wrelative} resp. {\tt wno-relative}: instructs the assembler
  1093.      to issue warnings if a relative jump instead of an absolute is
  1094.      possible (only for Z80 target).}
  1095. \item{{\tt wsign-extension} resp. {\tt wno-sign-extension}: instructs
  1096.      the assembler to issue warnings about implicit sign extensions
  1097.      (onlx 68K, MOVEQ).}
  1098. \item{\tty{compmode}: This switch instructs the assembler to operate by
  1099.      default in compatibility mode.  See section \ref{SectCompMode} for
  1100.      more information about this mode.}
  1101. \item{\tty{packing}: This switch overrides the architecture specific
  1102.      default of the {\tt PACKING} option (see section \ref{SectPACKING}).}
  1103. \end{itemize}
  1104. As long as switches require no arguments and their concatenation does
  1105. not result in a multi-letter switch, it is possible to specify several
  1106. switches at one time, as in the following example :
  1107. \begin{verbatim}
  1108. as test*.asm firstprog -cl /i c:\as\8051\include
  1109. \end{verbatim}
  1110. All files \tty{TEST*.ASM} as well as the file \tty{FIRSTPROG.ASM} will be
  1111. assembled, whereby listings of all files are displayed on the
  1112. console terminal.  Additional sharefiles will be generated in the C-
  1113. format.  The assembler should search for additional include files
  1114. in the directory \verb!C:\AS\8051\INCLUDE!.
  1115.  
  1116. This example shows that the assembler assumes \tty{ASM} as the default
  1117. extension for source files.
  1118.  
  1119. A bit of caution should be applied when using switches that have
  1120. optional arguments: if a file specification immediately follows such
  1121. a switch without the optional argument, \asname{} will try to interprete the
  1122. file specification as argument - what of course fails:
  1123. \begin{verbatim}
  1124. as -g test.asm
  1125. \end{verbatim}
  1126. The solution in this case would either be to move the -g option the
  1127. end or to specify an explicit MAP argument.
  1128.  
  1129.  
  1130. Beside from specifying options in the command line, permanently
  1131. needed options may be placed in the environment variable \tty{ASCMD}.  For
  1132. example, if someone always wants to have assembly listings and has a
  1133. fixed directory for include files, he can save a lot of typing with
  1134. the following command:
  1135. \begin{verbatim}
  1136. set ascmd=-L -i c:\as\8051\include
  1137. \end{verbatim}
  1138. The environment options are processed before the command line,
  1139. so options in the command line can override contradicting ones in the
  1140. environment variable.
  1141.  
  1142. In the case of very long path names, space in the \tty{ASCMD} variable may
  1143. become a problem.  For such cases a key file may be the alternative,
  1144. in which the options can be written in the same way as in the command
  1145. line or the \tty{ASCMD}-variable.  But this file may contain several lines
  1146. each with a maximum length of 255 characters.  In a key file it is
  1147. important, that for options which require an argument, switches and
  1148. argument have to be written in the \bb{same} line.  \asname{} gets informed of
  1149. the name of the key file by a \tty{@} aheaded in the \tty{ASCMD} variable,
  1150. e.g.
  1151. \begin{verbatim}
  1152. set ASCMD=@c:\as\as.key
  1153. \end{verbatim}
  1154. In order to neutralize options in the \tty{ASCMD} variable (or in the
  1155. key file), prefix the option with a plus sign.  For example, if you
  1156. do not want to generate an assembly listing in an individual case,
  1157. the option can be retracted in this way:
  1158. \begin{verbatim}
  1159. as +L <file>
  1160. \end{verbatim}
  1161. Naturally it is not consequently logical to deny an option by a
  1162. plus sign....  UNIX soit qui mal y pense.
  1163.  
  1164. References to key files may not only come from the {\tt ASCMD} variable,
  1165. but also directly from the command line.  Similarly to the {\tt ASCMD}
  1166. variable, prepend the file's name with a \@ character:
  1167. \begin{verbatim}
  1168. as @<file> ....
  1169. \end{verbatim}
  1170. The options read from a key file in this situation are processed as if
  1171. they had been written out in the command line in place of the reference,
  1172. {\em not} like the key file referenced by the {\tt ASCMD} variable that is
  1173. processed prior to the command line options.
  1174.  
  1175. Referencing a key file from a key file itself is not allowed and will be
  1176. answered wit an error message by \asname{}.
  1177.  
  1178. In case that you like to start \asname{} from another program or a shell and
  1179. this shell hands over only lower-case or capital letters in the
  1180. command line, the following workaround exists: if a tilde (\verb!~!) is put
  1181. in front of an option letter, the following letter is always
  1182. interpreted as a lower-case letter.  Similarly a \tty{\#} demands the
  1183. interpretation as a capital letter.  For example, the following
  1184. transformations result for:
  1185. \begin{verbatim}
  1186. /~I ---> /i
  1187. -#u ---> -U
  1188. \end{verbatim}
  1189. In dependence of the assembly's outcome, the assembler ends with
  1190. the following return codes:
  1191. \begin{description}
  1192. \item[0]{error free run, at maximum warnings occurred}
  1193. \item[1]{The assembler displayed only its command-line parameters and
  1194.         terminated immediately afterwards.}
  1195. \item[2]{Errors occurred during assembly, no code file has been produced.}
  1196. \item[3]{A fatal error occurred what led to immediate termination of the run.}
  1197. \item[4]{An error occurred already while starting the assembler.
  1198.         This may be a parameter error or a faulty overlay file.}
  1199. \item[255]{An internal error occurred during initialization that should not
  1200.         occur in any case...reboot, try again, and contact me if the
  1201.         problem is reproducible!}
  1202. \end{description}
  1203. Similar to UNIX, OS/2 \marginpar{{\em OS/2}} extends an application's data
  1204. segment on demand when the application really needs the memory.
  1205. Therefore, an output like
  1206. \begin{verbatim}
  1207.  511 KByte available memory
  1208. \end{verbatim}
  1209. does not indicate a shortly to come system crash due to memory lack,
  1210. it simply shows the distance to the limit when OS/2 will push up the
  1211. data segment's size again...
  1212.  
  1213. As there is no compatible way in C \marginpar{{\em UNIX}} under different
  1214. operating systens to find out the amount of available memory resp. stack,
  1215. both lines are missing completely from the statistics the C version prints.
  1216.  
  1217. %%---------------------------------------------------------------------------
  1218.  
  1219. \section{Format of the Input Files}
  1220. \label{AttrTypes}
  1221.  
  1222. Like most assemblers, \asname{} expects exactly one instruction per line
  1223. (blank lines are naturally allowed as well).  The lines must not be
  1224. longer than 255 characters, additional characters are discarded.
  1225.  
  1226. A single line has following format:
  1227. \begin{verbatim}
  1228. [label[:]] <mnemonic>[.attr] [param[,param..]] [;comment]
  1229. \end{verbatim}
  1230. A line may also be split over several lines in the source file,
  1231. continuation characters chain these parts together to a single line.  One
  1232. must however consider that, due to the internal buffer structure, the
  1233. total line must not be longer than 256 characters.  Line references in
  1234. error messages always relate to the last line of such a composed source
  1235. line.
  1236. \par
  1237. The colon for the label is optional, in case the label starts in the
  1238. first column (the consequence is that a machine or pseudo
  1239. instruction must not start in column 1).  It is necessary to set the
  1240. colon in case the label does not start in the first column so that \asname{}
  1241. is able to distinguish it from a mnemonic.  In the latter case, there
  1242. must be at least one space between colon and mnemonic if the processor
  1243. belongs to a family that supports an attribute that denotes an
  1244. instruction format and is separated from the mnemonic by a colon.  This
  1245. restriction is necessary to avoid ambiguities: a distinction between a
  1246. mnemonic with format and a label with mnemonic would otherwise be
  1247. impossible.
  1248.  
  1249. Some signal processor families from Texas Instruments optionally use
  1250. a double line (\verb!||!) in place of the label to signify the
  1251. parallel execution with the previous instruction(s).  If these two
  1252. assembler instructions become a single instruction word at machine
  1253. level (C3x/C4x), an additional label in front of the second
  1254. instruction of course does not make sense and is not allowed.  The
  1255. situation is different for the C6x with its instruction packets of
  1256. variable length: If someone wants to jump into the middle of an
  1257. instruction packet (bad style, if you ask me...), he has to place the
  1258. necessary label {\em before} into a separate line.  The same is valid
  1259. for conditions, which however may be combined with the double line in
  1260. a single source line.
  1261.  
  1262. The attribute is used by a couple of processors to specify variations or
  1263. different codings of a certain instruction.  The most prominent usage of
  1264. the attibute is is the specification of the operand size, for example in
  1265. the case of the 680x0 family (table \ref{TabAttrs}).
  1266. \begin{table*}[htb]
  1267. \begin{center}\begin{tabular}{|l|l|l|}
  1268. \hline
  1269. attribute & arithmetic-logic instruction & jump instruction\\
  1270. \hline
  1271. \hline
  1272. B     & byte (8 bits)                       &  8-bit-displacement \\
  1273. W     & word (16 bits)                      &  16-bit-displacement \\
  1274. L     & long word (32 bits)                 &  16-bit-displacement \\
  1275. Q     & quad word (64 bits)                 &  --------- \\
  1276. C     & half precision (16 bits)            &  --------- \\
  1277. S     & single precision (32 bits)          &  8-bit-displacement \\
  1278. D     & double precision (64 bits)          &  --------- \\
  1279. X     & extended precision (80/96 bits)     &  32-bit-displacement \\
  1280. P     & decimal floating point (80/96 bits) &  --------- \\
  1281. \hline
  1282. \end{tabular}\end{center}
  1283. \caption{Allowed Attributes (Example 680x0) \label{TabAttrs}}
  1284. \end{table*}
  1285. \par
  1286. Since this manual is not also meant as a user's manual for the processor
  1287. families supported by \asname{}, this is unfortunately not the place to enumerate
  1288. all possible attributes for all families.  It should however be mentioned
  1289. that in general, not all instructions of a given instruction set allow all
  1290. attributes and that the omission of an attribute generally leads to the
  1291. usage of the ''natural'' operand size of a processor family. For more
  1292. thorough studies, consult a reasonable programmer's manual, e.g.
  1293. \cite{Williams} for the 68K's.
  1294.  
  1295. In the case of TLCS-9000, H8/500, and M16(C), the attribute serves
  1296. both as an operand size specifier (if it is not obvious from the
  1297. operands) and as a description of the instruction format to be used.
  1298. A colon has to be used to separate the format from the operand size,
  1299. e.g. like this:
  1300. \begin{verbatim}
  1301.    add.w:g   rw10,rw8
  1302. \end{verbatim}
  1303. This example does not show that there may be a format specification
  1304. without an operand size.  In contrast, if an operand size is used
  1305. without a format specification, \asname{} will automatically use the
  1306. shortest possible format.  The allowed formats and operand sizes
  1307. again depend on the machine instruction and may be looked up e.g. in
  1308. \cite{Tosh900}, \cite{HitH8_5}, \cite{MitM16}, resp. \cite{MitM16C}.
  1309.  
  1310. The number of instruction parameters depends on the mnemonic and is
  1311. principally located between 0 and 20.  The separation of the parameters
  1312. from each other is to be performed only by commas (exception: DSP56xxx,
  1313. its parallel data transfers are separated with blanks).  Commas that
  1314. are included in brackets or quotes, of course, are not taken into
  1315. consideration.
  1316.  
  1317. Instead of a comment at the end, the whole line can consist of
  1318. comment if it starts in the first column with a semicolon.
  1319.  
  1320. To separate the individual components you may also use tabulators
  1321. instead of spaces.
  1322.  
  1323. %%---------------------------------------------------------------------------
  1324.  
  1325. \section{Format of the Listing}
  1326. \label{SectListing}
  1327.  
  1328. The listing produced by \asname{} using the command line options i or I is
  1329. roughly divisible into the following parts :
  1330. \begin{enumerate}
  1331. \item{augmented reproduction of the source code;}
  1332. \item{symbol list;}
  1333. \item{usage list;}
  1334. \item{cross reference list.}
  1335. \end{enumerate}
  1336. The two last ones are only generated if they have been demanded by
  1337. additional command line options.
  1338.  
  1339. In the first part, \asname{} lists the complete contents of all source files
  1340. including the produced code.  A line of this listing has the following
  1341. form:
  1342. \begin{verbatim}
  1343. [<n>] <line>/<address> <code> <source>
  1344. \end{verbatim}
  1345. In the field \tty{n}, \asname{} displays the include nesting level.  The main file
  1346. (the file where assembly was started) has the depth 0, an included
  1347. file from there has depth 1 etc..  Depth 0 is not displayed: for source lines
  1348. in the main file, this field is replaced by an appropriate amount of spaces,
  1349. or is omitted entirely if no include statements have been used so far.  The
  1350. 'memory' whether there have been include statements and up to which level,
  1351. spans more than one pass.  This way, the assembler 'learns' the maximum
  1352. include depth in the first pass and is able to print this field with
  1353. consistent width throughout the whole listing.
  1354.  
  1355. In the field \tty{line}, the source line number of the referenced file is
  1356. issued. The first line of a file has the number 1.  The address to
  1357. which the code generated from this line is written follows after the
  1358. slash in the field \tty{address}.  The number system used for the address
  1359. is set via the {\tt listradix} command line option (\ref{listradix}), also
  1360. whether the address is printed with leading zeros or not.  The currently
  1361. used target defines the width of this field by the size of the address
  1362. space: for a processor with a 64K address space, four hex digits are
  1363. sufficient, while eight digits are needed if the address space's size
  1364. is 4 GBytes.
  1365.  
  1366. The code produced is written behind \tty{address} in the field \tty{code},
  1367. also in the number system defined by the list radix.  Depending on the processor type and actual
  1368. segment the values are formatted either as bytes or 16/32-bit-words.
  1369. If more code is generated than the field can take, additional lines
  1370. will be  generated, in which case only this field is used.
  1371.  
  1372. Finally, in the field \tty{source}, the line of the source file is issued in
  1373. its original form.
  1374.  
  1375. Internally, the structure of the data in front of every source line
  1376. is controlled by a format string, which may be modified via the
  1377. command line switch {\tt -listline-prefix}.  It supports the
  1378. following placeholders:
  1379. \begin{itemize}
  1380. \item{{\tt \%[c]i}: The current include nesting depth, with an optional
  1381.      field width.  Without an explicit field width, this may be
  1382.      expanded to nothing or an equivalent number of spaces if
  1383.      the depth is zero.}
  1384. \item{{\tt \%[c]n}: The current source line number, with an optional
  1385.      field width.  The number is printed right-aligned within
  1386.      this field. The default for the field width is five characters.}
  1387. \item{{\tt \%[c]a}: Similarly, the current memory address, with a
  1388.      target-specific default field width, as described above.}
  1389. \end{itemize}
  1390. In all cases, a field width with a leading zero results in filling up
  1391. the unused space with zeros instead of blanks.  The default of this
  1392. format string is \verb!%i%n/%a!.  To achieve an output similar to the
  1393. one generated by \asname{} versions previous to 1.42 Build 249,
  1394. \verb!%1i%5n/%8a! may be used as format string.
  1395.  
  1396. The symbol table was designed in a way that it can be displayed on an
  1397. 80-column display whenever possible. For symbols of ''normal length'',
  1398. a double column output is used.  If symbols exceed (with their name
  1399. and value) the limit of 40 columns (characters), they will be issued
  1400. in a separate line. The output is done in alphabetical order.
  1401. Symbols that have been defined but were never used are marked with a
  1402. star (*) as prefix.
  1403.  
  1404. The parts mentioned so far as well as the list of all macros/functions
  1405. defined can be selectively masked out from the listing.
  1406. This can be done by the already mentioned command line switch \tty{-t}.
  1407. There is an internal byte inside \asname{} whose bits represent which parts
  1408. are to be written.  The assignment of bits to parts of the listing is
  1409. listed in table \ref{TabTBits}.
  1410. \par
  1411. \begin{table*}[htb]
  1412. \begin{center}\begin{tabular}{|l|l|}
  1413. \hline
  1414. bit &  part \\
  1415. \hline
  1416. \hline
  1417. 0   & source file(s) + produced code \\
  1418. 1   & symbol table \\
  1419. 2   & macro list \\
  1420. 3   & function list \\
  1421. 4   & line numbering \\
  1422. 5   & register symbol list \\
  1423. 7   & character set table \\
  1424. \hline
  1425. \end{tabular}\end{center}
  1426. \caption{Assignment of Bits to Listing Components\label{TabTBits}}
  1427. \end{table*}
  1428. All bits are set to 1 by default, when using the switch
  1429. \begin{verbatim}
  1430. -t <mask>
  1431. \end{verbatim}
  1432. Bits set in \tty{$<$mask$>$} are cleared, so that the respective listing
  1433. parts are suppressed.  Accordingly it is possible to switch on single
  1434. parts again with a plus sign, in case you had switched off too much
  1435. with the \tty{ASCMD} variable... If someone wants to have, for example,
  1436. only the symbol table, it is enough to write:
  1437. \begin{verbatim}
  1438. -t 2
  1439. \end{verbatim}
  1440. The usage list issues the occupied areas hexadecimally for every
  1441. single segment.  If the area has only one address, only this is written,
  1442. otherwise the first and last address.
  1443.  
  1444. The cross reference list issues any defined symbol in alphabetical
  1445. order and has the following form:
  1446. \begin{verbatim}
  1447. symbol <symbol name> (=<value>,<file>/<line>):
  1448.  file <file 1>:
  1449.  <n1>[(m1)]  ..... <nk>[(mk)]
  1450.  .
  1451.  .
  1452.  file <file l>:
  1453.  <n1>[(m1)]  ..... <nk>[(mk)]
  1454. \end{verbatim}
  1455. The cross reference list lists for every symbol in which files and lines
  1456. it has been used.  If a symbol was used several times in the same line,
  1457. this would be indicated by a number in brackets behind the line number.
  1458. If a symbol was never used, it would not appear in the list; The same is
  1459. true for a file that does not contain any references for the symbol in
  1460. question.
  1461.  
  1462. \bb{CAUTION!}  \asname{} can only print the listing correctly if it was
  1463. previously informed about the output media's page length and width!
  1464. This has to be done with the \tty{PAGE} instruction (see \ref{SectPAGE}).  The
  1465. preset default is a length of 60 lines and an unlimited line width.
  1466.  
  1467. %%---------------------------------------------------------------------------
  1468.  
  1469. \section{Symbol Conventions}
  1470. \label{SectSymConv}
  1471.  
  1472. Symbols are allowed to be up to 255 characters long (as hinted already
  1473. in the introduction) and are being distinguished on the whole
  1474. length, but the symbol names have to meet some conventions:
  1475.  
  1476. Symbol names are allowed to consist of a random combination of
  1477. letters, digits, underlines and dots, whereby the first character must
  1478. not be a digit. The dot is only allowed to meet the MCS-51 notation of
  1479. register bits and should - as far as possible - not be used in own symbol
  1480. names.  To separate symbol names in any case the underline (\tty{\_}) and not
  1481. the dot (\tty{.}) should be used .
  1482.  
  1483. \asname{} is by default not case-sensitive, i.e. it does not matter whether
  1484. one uses upper or lower case characters.  The command line switch \tty{U}
  1485. however allows to switch \asname{} into a mode where upper and lower case
  1486. makes a difference.  The predefined symbol \tty{CASESENSITIVE} signifies
  1487. whether \asname{} has been switched to this mode: TRUE means case-sensitiveness,
  1488. and FALSE its absence.
  1489.  
  1490. Table \ref{TabPredefined} shows the most important symbols which are
  1491. predefined by \asname{}.
  1492. \begin{table*}[htb]
  1493. \begin{center}\begin{tabular}{|l|l|}
  1494. \hline
  1495. name          & meaning \\
  1496. \hline
  1497. \hline
  1498. TRUE          & logically ''true'' \\
  1499. FALSE         & logically ''false'' \\
  1500. CONSTPI       & Pi (3.1415.....) \\
  1501. FLOATMAX      & largest representable floating point number \\
  1502. VERSION       & version of \asname{} in BCD-coding, \\
  1503.              & e.g. 1331 hex for version 1.33p1 \\
  1504. ARCHITECTURE  & target platform \asname{} was compiled for, in \\
  1505.              & the style processor-manufacturer-operating \\
  1506.              & system \\
  1507. DATE          & date and \\
  1508. TIME          & time of the assembly (start) \\
  1509. MOMCPU        & current target CPU \\
  1510.              & (see the CPU instruction) \\
  1511. MOMFILE       & current source file \\
  1512. MOMLINE       & line number in source file \\
  1513. MOMPASS       & number of the currently running pass \\
  1514. MOMSECTION    & name of the current section \\
  1515.              & or an empty string \\
  1516. \verb!*!, ,. \$ resp. PC & current value of program counter \\
  1517. \hline
  1518. \end{tabular}\end{center}
  1519. \caption{Predefined Symbols\label{TabPredefined}}
  1520. \end{table*}
  1521. \bb{CAUTION!}  While it does not matter in case-sensitive mode which
  1522. combination of upper and lower case to use to reference predefined
  1523. symbols, one has to use exactly the version given above (only upper
  1524. case) when \asname{} is in case-sensitive mode!
  1525. Additionally some pseudo instructions define symbols that reflect the
  1526. value that has been set  with these instructions.  Their descriptions
  1527. are explained at the individual commands belonging to them.
  1528. On most platforms, the name {\tt INF} is reserved as infinity in
  1529. floating point format.  It therefore may not be used for user-defined
  1530. symbols.
  1531. A hidden feature (that has to be used with care) is that symbol names
  1532. may be assembled from the contents of string symbols.  This can be
  1533. achieved by framing the string symbol's name with curly braces and
  1534. inserting it into the new symbol's name.  This allows for example to
  1535. define a symbol's name based on the value of another symbol:
  1536. \begin{verbatim}
  1537. cnt             set     cnt+1
  1538. temp            equ     "\{CNT}"
  1539.                jnz     skip{temp}
  1540.                .
  1541.                .
  1542. skip{temp}:     nop
  1543. \end{verbatim}
  1544. \bb{CAUTION:} The programmer has to assure that only valid symbol names
  1545. are generated!
  1546. A complete list of all symbols predefined by \asname{} can be found in
  1547. appendix \ref{AppInternSyms}.
  1548. Apart from its value, every symbol also owns a marker which signifies to
  1549. which {\em segment} it belongs.  Such a distinction is mainly needed for
  1550. processors that have more than one address space.  The additional
  1551. information allows \asname{} to issue a warning when a wrong instruction is used
  1552. to access a symbol from a certain address space.  A segment attribute is
  1553. automatically added to a symbol when is gets defined via a label or a
  1554. special instruction like \tty{BIT}; a symbol defined via the ''allround
  1555. instructions'' \tty{SET} resp. \tty{EQU} is however ''typeless'', i.e. its
  1556. usage will never trigger warnings.  A symbol's segment attribute may be
  1557. queried via the buit-in function \tty{SYMTYPE}, e.g.:
  1558. \begin{verbatim}
  1559. Label:
  1560.        .
  1561.        .
  1562. Attr    equ     symtype(Label)  ; results in 1
  1563. \end{verbatim}
  1564. The individual segment types have the assigned numbers listed in table
  1565. \ref{TabSegNums}.  Register symbols which do not really fit into the order
  1566. of normal symbols are explained in section \ref{SectRegSyms}.  The
  1567. \tty{SYMTYPE} function delivers -1 as result when called with an undefined
  1568. symbol as argument.  However, if all you want to know is whether a symbol
  1569. is defined or not, or whether an expression contains no no symbols that are
  1570. undefined so far, you may as well use the \tty{DEFINED} function.
  1571. \begin{table}[htb]
  1572. \begin{center}
  1573. \begin{tabular}{|l|c|}
  1574. \hline
  1575. segment & return value \\
  1576. \hline
  1577. $<$none$>$ & 0 \\
  1578. CODE & 1 \\
  1579. DATA & 2 \\
  1580. IDATA & 3 \\
  1581. XDATA & 4 \\
  1582. YDATA & 5 \\
  1583. BITDATA & 6 \\
  1584. IO & 7 \\
  1585. REG & 8 \\
  1586. ROMDATA & 9 \\
  1587. EEDATA & 10 \\
  1588. $<$Register Symbol$>$ & 128 \\
  1589. \hline
  1590. \end{tabular}
  1591. \end{center}
  1592. \caption{return values of the \tty{SYMTYPE} function\label{TabSegNums}}
  1593. \end{table}
  1594.  
  1595. %%---------------------------------------------------------------------------
  1596.  
  1597. \section{Temporary Symbols}
  1598.  
  1599. Especially when dealing with programs that contain sequences of loops of
  1600. if-like statements, one is continuously faced with the problem of
  1601. inventing new names for labels - labels of which you know exactly that you
  1602. will never need to reference them again afterwards and you really would
  1603. like to get 'rid' of them somehow.  A simple solution if you don't want to
  1604. swing the large hammer of sections (see chapter \ref{ChapLocSyms}) are
  1605. {\em temporary} symbols which remain valid as long as a new,
  1606. non-temporary symbol gets defined.  Other assemblers offer a similar
  1607. mechanism which is commonly referred as 'local symbols'; however, for the
  1608. sake of a better distinction, I want to stay with the term 'temporary
  1609. symbols'.  \asname{} knows three different types of temporary symbols, in the
  1610. hope to offer everyone 'switching' to \asname{} a solution that makes conversion
  1611. as easy as possible.  However, practically every assembler has its own
  1612. interpretation of this feature, so there will be only few cases where a
  1613. 1:1 solution for existing code:
  1614.  
  1615. \section{Named Temporary Symbols}
  1616.  
  1617. A symbol whose name starts with two dollar signs (something that is
  1618. neither allowed for non-temporary symbols nor for constants) is a named
  1619. temporary symbol.  \asname{} keeps an internal counter which is reset to 0 before
  1620. assembly begins and which gets incremented upon every definition of a
  1621. non-temporary symbol.  When a temporary symbol is defined or referenced,
  1622. both leading dollar signs are discarded and the counter's current value is
  1623. appended.  This way, one regains the used symbol names with every
  1624. definition of a non-temporary symbol - but you also cannot reach the
  1625. previously symbols any more! Temporary symbols are therefore especially
  1626. suited for usage in small instruction blocks, typically a dozen of machine
  1627. instructions, definitely not more than one screen.  Otherwise, one easily
  1628. gets confused...
  1629.  
  1630. Here is a small example:
  1631. \begin{verbatim}
  1632. $$loop: nop
  1633.        dbra    d0,$$loop
  1634. split:
  1635. $$loop: nop
  1636.        dbra    d0,$$loop
  1637. \end{verbatim}
  1638. Without the non-temporary label between the loops, of course an error
  1639. message about a double-defined symbol would be the result.
  1640.  
  1641. \subsection{Nameless Temporary Symbols}
  1642.  
  1643. For all those who regard named temporary symbols still as too complicated,
  1644. there is an even simpler variant: If one places a single puls or minus
  1645. sign as a label, this is converted to symbol names of {\tt \_\_forwnn}
  1646. respectively {\tt \_\_backmm}, with {\tt nn} respectively {\tt mm} being
  1647. counters that start counting at zero.  Those symbols are referenced via
  1648. the special names {\tt - -- ---} respectively {\tt + ++ +++}, which refer
  1649. to the three last 'minus symbols' and the next three 'plus symbols'.
  1650. Therefore, the selection between these two variants depends on whether one
  1651. wants to forward- or backward-reference a symbol.
  1652.  
  1653. Apart from plus and minus, {\em defining} nameless temporary symbols also
  1654. exists in a third variant, namely a slash (/).  A temporary symbol defined
  1655. in this way may be referenced both backward and forward, i.e. it is
  1656. treated either as a plus or a minus, depending on the way it is being
  1657. referenced.
  1658.  
  1659. Nameless temporary symbols are usually used in constructs that fit on one
  1660. screen page, like skipping a few machine instructions or tight loops -
  1661. things would becone to puzzling otherwise (this only a good advice,
  1662. however...).  An example for this is the following piece of code, this
  1663. time as 65xx code:
  1664. \begin{verbatim}
  1665.        cpu     6502
  1666.  
  1667. -       ldx     #00
  1668. -       dex
  1669.        bne     -           ; branch to 'dex'
  1670.        lda     RealSymbol
  1671.        beq     +           ; branch to 'bne --'
  1672.        jsr     SomeRtn
  1673.        iny
  1674. +       bne     --          ; branch to 'ldx #00'
  1675.  
  1676. SomeRtn:
  1677.        rts
  1678.  
  1679. RealSymbol:
  1680.        dfs     1
  1681.  
  1682.         inc     ptr
  1683.         bne     +           ; branch to 'tax'
  1684.         inc     ptr+1
  1685. +       tax
  1686.  
  1687.         bpl     ++          ; branch to 'dex'
  1688.         beq     +           ; branch forward to 'rts'
  1689.         lda     #0
  1690. /       rts                 ; slash used as wildcard.
  1691. +       dex
  1692.         beq     -           ; branch backward to 'rts'
  1693.  
  1694. ptr:    dfs     2
  1695. \end{verbatim}
  1696.  
  1697. \subsection{Composed Temporary Symbols}
  1698.  
  1699. This is maybe the type of temporary symbols that is nearest to the concept
  1700. of local symbols and sections.  Whenever a symbol's name begins with a dot
  1701. (.), the symbol is not directly stored with this name in the symbol table.
  1702. Instead, the name of the most recently-defined symbol not beginning with a
  1703. dot is prepended to the symbols name.  This way, 'non-dotted' symbols take
  1704. the role of section separators and 'dotted' symbol names may be reused
  1705. after a 'non-dotted' symbol has been defined.  Take a look at the
  1706. following little example:
  1707. \begin{verbatim}
  1708. proc1:                          ; non-temporary symbol 'proc1'
  1709.  
  1710. .loop   moveq   #20,d0          ; actually defines 'proc1.loop'
  1711.         dbra    d0,.loop
  1712.         rts
  1713.  
  1714. proc2:                          ; non-temporary symbol 'proc2'
  1715.  
  1716. .loop   moveq   #10,d1          ; actually defines 'proc2.loop'
  1717.         jsr     proc1
  1718.         dbra    d1,.loop
  1719.         rts
  1720. \end{verbatim}
  1721. Note that it is still possible to access all temporary symbols, even
  1722. without being in the same 'area', by simply using the composed name (like
  1723. 'proc2.loop' in the previous example).
  1724.  
  1725. It is principally possible to combine composed temporary symbols with
  1726. sections, which makes them also to local symbols.  Take however into
  1727. account that the most recent non-temporary symbol is not stored
  1728. per-section, but simply globally.  This may change however in a future
  1729. version, so one shouldn't rely on the current behaviour.
  1730.  
  1731. %%---------------------------------------------------------------------------
  1732.  
  1733. \section{Formula Expressions}
  1734.  
  1735. In most places where the assembler expects numeric inputs, it is
  1736. possible to specify not only simple symbols or constants, but also
  1737. complete formula expressions.  The components of these formula
  1738. expressions can be either single symbols and constants.  Constants may be
  1739. either integer, floating point, or string constants.
  1740.  
  1741. \subsection{Integer Constants}
  1742. \label{SectIntConsts}
  1743.  
  1744. Integer constants describe non-fractional numbers.  They are witten as a
  1745. sequence of digits.  This may be done in different numbering systems (see
  1746. table \ref{TabSystems}).
  1747. \par
  1748. \begin{table*}[htb]
  1749. \begin{center}\begin{tabular}{|l|c|c|c|c|}
  1750. \hline
  1751.          & Intel Mode    & Motorola Mode & C Mode    & IBM Mode \\
  1752. \hline
  1753. \hline
  1754. Decimal   & Direct        & Direct      & Direct      & Direct \\
  1755. Hex       & Suffix H      & Prefix \$   & Prefix 0x   & X'..' or H'..' \\
  1756. \ii{Ident}& \tty{hexh}    & \tty{\$hex} & \tty{0xhex} & \tty{x'hex'} \\
  1757.          &               &             &             & \tty{h'hex'} \\
  1758. Binary    & Suffix B      & Prefix \%   & Prefix 0b   & O'..' \\
  1759. \ii{Ident}& \tty{binb}    & \tty{\%bin} & \tty{0bbin} & \tty{b'bin'} \\
  1760. Octal     & Suffix O or Q & Prefix @    & Prefix 0    & B'..' \\
  1761. \ii{Ident}& \tty{octo}    & \tty{@oct}  & \tty{0oct}  & \tty{o'oct'} \\  
  1762.          & \tty{octq}    &             &             & \\
  1763. ASCII     &               &             &             & A'..' \\
  1764. \ii{Ident}&               &             &             & \tty{a'asc'} \\
  1765. \hline
  1766. \end{tabular}\end{center}
  1767. \caption{Defined Numbering Systems and Notations\label{TabSystems}}
  1768. \end{table*}
  1769. In case the numbering system has not been explicitly stated by adding the
  1770. special control characters listed in the table, the number system
  1771. is derived as follows:
  1772. \begin{itemize}
  1773. \item{If a {\tt RADIX} statement was given, use the number system
  1774.      given by it, otherwise:}
  1775. \item{If a {\tt -radix} command line switch was given, use the number
  1776.      system given by it, otherwise:}
  1777. \item{Use decimal (base 10).}
  1778. \end{itemize}
  1779. Both the {\tt RADIX} statement and the  {\tt -radix} command line switch
  1780. also allow to set up 'unusual' numbering systems, i.e. others than 2, 8, 10,
  1781. or 16.
  1782.  
  1783. Valid digits are numbers from 0 to 9 and letters from A to Z (value 10 to
  1784. 35) up to the numbering system's base minus one. An exception from this is
  1785. the ASCII represenation: For this variant, a character's ASCII value (or its
  1786. code in the currently active code page, see section \ref{SectCHARSET})
  1787. describes a whole byte.  Therefore, integer constants written this way
  1788. are identical to multi character constants.  These two expressions:
  1789. \begin{verbatim}
  1790. 'ABCD'
  1791. A'ABCD'
  1792. \end{verbatim}
  1793. are identical, the 'A' prefix is redundant.  One may enable this syntax
  1794. for existing code, because there are a few original assemblers (e.g.
  1795. for the Signetics 2650) that support this syntax.
  1796.  
  1797. Independent of the target, \asname{} implements multi character constants
  1798. in big endian order, which means that 'ABCD' results in an integer
  1799. value of 0x41424344.  Why this? Well, \asname{}'s first target was the
  1800. Motorola 60008, and no one ever objected...the only exception from
  1801. this is the PDP-11 (and the WD16 which uses an LSI-11): For better
  1802. compatibility to DEC's MACRO-11, multi character are little endian
  1803. if this target is used.  For instance, 'AB' results in ain integer
  1804. value of 0x4241.
  1805.  
  1806. The usage of letters in integer constants however brings along some ambiguities
  1807. since symbol names are also sequences of numbers and letters: a symbol name
  1808. however must not start with a character from 0 to 9.  This means that an
  1809. integer constant which is not clearly marked a such with a special prefix
  1810. character must not begin with a letter.  One has to add an additional,
  1811. otherwise superfluous zero in front in such cases.  The most prominent case
  1812. is the writing of hexadecimal constants in Intel mode:  If the leftmost digit
  1813. is between A and F, the trailing H doesn't help to clarify, an additional 0
  1814. has to be prefixed (e.g. 0F0H instead of F0H).  The Motorola and C syntaxes
  1815. which both mark the numbering system at the front of a constant do not have
  1816. this issue.
  1817.  
  1818. Quite tricky is furthermore that the higher the default numbering system
  1819. set via {\tt RADIX} becomes, the more letters used to denote numbering
  1820. systems in Intel and C syntax become 'eaten'.  For example, you cannot
  1821. write binary constants anymore after a {\tt RADIX 16}, and starting at
  1822. {\tt RADIX 18}, the Intel syntax even doesn't allow to write hexadecimal
  1823. constants any more.  Therefore {\bf CAUTION!}
  1824.  
  1825. Appendix \ref{SectPseudoInst} lists which syntax is used by which target
  1826. by default.  Independent of this default, there is always the option to
  1827. add or delete individual syntax variants via the \tty{INTSYNTAX} instruction
  1828. (see section \ref{SectINTSYNTAX}).  The names listed as \ii{Ident},
  1829. prefixed with a plus or minus sign, serve as arguments to this instruction.
  1830.  
  1831. The \tty{RELAXED} instruction (see section \ref{SectRELAXED}) serves as
  1832. a sort 'global enable switch': in relaxed mode, all notations may be used,
  1833. independent of the selected target processor.  The result is that an arbitrary
  1834. syntax may be used (possibly loosing compatibility to standard assemblers).
  1835.  
  1836. Both \tty{INTSYNTAX} and \tty{RELAXED} specifically enable usage of the
  1837. 'IBM syntax' for all targets, which is sometimes found on other assemblers:
  1838.  
  1839. This notation puts the actual value into apostrophes and prepends
  1840. the numbering system ('x' or 'h' for hexadecimal, 'o' for octal and 'b'
  1841. for binary).  So, the integer constant 305419896 can be written in the
  1842. following ways:
  1843. \begin{verbatim}
  1844. x'12345678'
  1845. h'12345678'
  1846. o'2215053170'
  1847. b'00010010001101000101011001111000'
  1848. \end{verbatim}
  1849. Another variant of this notation for some targets is to leave away the
  1850. closing apostrophe, to allow simpler porting of existing code.  It is
  1851. not recommended for new programs.
  1852.  
  1853. \subsection{Floating Point Constants}
  1854.  
  1855. Floating point constants are to be written in the usual scientific
  1856. notation, which is known in the most general form:
  1857. \begin{verbatim}
  1858. [-]<integer digits>[.post decimal positions][E[-]exponent]
  1859. \end{verbatim}
  1860. \bb{CAUTION!} The assembler first tries to interprete a constant as an
  1861. integer constant and makes a floating-point format try only in case
  1862. the first one failed.  If someone wants to enforce the evaluation as
  1863. a floating point number, this can be done by dummy post decimal
  1864. positions, e.g.  \tty{2.0} instead of \tty{2}.
  1865.  
  1866. \subsection{String Constants}
  1867. \label{SectStringConsts}
  1868.  
  1869. String constants have to be enclosed in single or double quotation marks.
  1870. In order to make it possible to include quotation marks or special characters
  1871. in string constants, an ''escape mechanism'' has been implemented, which
  1872. should sound familiar for C programmers:
  1873.  
  1874. The assembler understands a backslash (\verb!\!) with a following decimal
  1875. number of three digits maximum in the string as a character with the
  1876. according decimal ASCII value.  The numerical value may alternitavely be
  1877. written in hexadecimal or octal notation if it is prefixed with an x resp.
  1878. a 0.  In case of hexadecimal notation, the maximum number of digits is
  1879. limited to 2.  For example, it is possible to include an ETC character by
  1880. writing {\tt\verb!\!3}.  But be careful with the definition of NUL
  1881. characters!  The C \marginpar{{\em UNIX}} version currently uses C strings
  1882. to store strings internally.  As C strings use a NUL character for
  1883. termination, the usage of NUL characters in strings is currently not
  1884. portable!
  1885.  
  1886. Some frequently used control characters can also be reached with the
  1887. following abbreviations:
  1888. \begin{verbatim}
  1889. \b : Backspace           \a : Bell         \e : Escape
  1890. \t : Tabulator           \n : Linefeed     \r : Carriage Return
  1891. \\ : Backslash           \' or \H : Apostrophe
  1892. \" or \I : Quotation marks
  1893. \end{verbatim}
  1894. Both upper and lower case characters may be used for the
  1895. identification letters.
  1896.  
  1897. By means of this escape character, you can even work formula
  1898. expressions into a string, if they are enclosed by curly braces: e.g.
  1899. \begin{verbatim}
  1900.     message "root of 81 : \{sqrt(81)}"
  1901. \end{verbatim}
  1902. results in
  1903. \begin{verbatim}
  1904.              root of 81 : 9
  1905. \end{verbatim}
  1906. \asname{} chooses with the help of the formula result type the correct
  1907. output format, further string constants, however, are to be avoided
  1908. in the expression.  Otherwise the assembler will get mixed up at the
  1909. transformation of capitals into lower case letters.  Integer results will
  1910. by default be written in hexadecimal notation, which may be changed via
  1911. the \tty{OUTRADIX} instruction.
  1912.  
  1913. Except for the insertion of formula expressions, you can use this
  1914. ''escape-mechanism'' as well in ASCII defined integer constants,
  1915. like this:
  1916. \begin{verbatim}
  1917.     move.b   #'\n',d0
  1918. \end{verbatim}
  1919. However, everything has its limits, because the parser with higher
  1920. priority, which disassembles a line into op-code and parameters, does
  1921. not know what it is actually working with, e.g. here:
  1922. \begin{verbatim}
  1923.     move.l   #'\'abc',d0
  1924. \end{verbatim}
  1925. After the third apostrophe, it will not find the comma any more,
  1926. because it presumes that it is the start of a further character
  1927. constant. An error message about a wrong parameter number is the result.
  1928. A workaround would be to write e.g., \verb!\i! instead of \verb!\'!.
  1929.  
  1930. \subsection{String to Integer Conversion and Character Constants}
  1931.  
  1932. Earlier versions of \asname{} strictly distinguished between character
  1933. strings and so-called ''character constants'': At first glance, a
  1934. character constant looks like a string, the characters are however
  1935. enclosed in single instead of double quotation marks.  Such an object had
  1936. the data type 'Integer', i.e. it represented a number with the value
  1937. given by the (ASCII) code of the character, and it was something
  1938. completely different:
  1939.  
  1940. \begin{verbatim}
  1941.   move.b   #65,d0
  1942.   move.b   #'A',d0      ; equal to first instruction
  1943.   move.b   #"A",d0      ; not allowed in older versions!
  1944. \end{verbatim}
  1945.  
  1946. This strict differentiation {\em no longer exists}, so it is irrelevant
  1947. whether single or double quotes are used.  If an integer value
  1948. is expected as argument, and a string is used, the conversion via the
  1949. character's (ASCII) value is done ''on the fly'' at this place. This
  1950. means that in the example given, {\em all three lines} result in the
  1951. same machine code.
  1952.  
  1953. Such an implicit conversion to integer values also take place for strings
  1954. consisting of multiple constancs, which are sometimes called ''multi
  1955. character constants'':
  1956. \begin{verbatim}
  1957. 'A'    ==$41
  1958. 'AB'   ==$4142
  1959. 'ABCD' ==$41424344
  1960. \end{verbatim}
  1961. Multi character constants are the only case where using single or double
  1962. quotes still makes a difference.  Many targets define pseudo instructions
  1963. to dispose constants in memory, and which accept different data types.
  1964. In such a case, it is still necessary to use double quotes if a character
  1965. string shall be placed in memory:
  1966. \begin{verbatim}
  1967.    dc.w    "ab"  ; disposes two words (0x0041,0x0042)
  1968.    dc.w    'ab'  ; disposes one word (0x4142)
  1969. \end{verbatim}
  1970. Important: using the correct quotation is not necessary if the character
  1971. string is longer than the used operand size, which is two characters or
  1972. 16 bits in this example.
  1973. \subsection{Evaluation}
  1974. The calculation of intermediary results within formula expressions is
  1975. always done with the highest resolution available on the host system.
  1976. For integer numbers, this is 32 or 64 bits.  For floating point numbers,
  1977. the range is approximately +/-$1.8*10^{308}$ (IEEE Double Precision) or
  1978. +/-$1.1*10^{4932}$ (IEEE Extended Precision). A possible test for value
  1979. range overflows is done only on the final result.
  1980. \subsection{Operators}
  1981. The assembler provides the operands listed in table \ref{TabOps} for
  1982. combination.
  1983. \begin{table*}[htbp]
  1984. \begin{center}\begin{tabular}{|c|l|c|c|c|c|c|c|}
  1985. \hline
  1986. Operand & Function            & \#Args & Int & Float & String & Reg & Rank \\
  1987. \hline
  1988. \hline
  1989. $<>$        & inequality       & 2 & yes   & yes & yes & yes & 14 \\
  1990. $!=$        & alias for $<>$   &   &       &     &     &     &    \\
  1991. $>=$        & greater or equal & 2 & yes   & yes & yes & yes & 14 \\
  1992. $<=$        & less or equal    & 2 & yes   & yes & yes & yes & 14 \\
  1993. $<$         & truly smaller    & 2 & yes   & yes & yes & yes & 14 \\
  1994. $>$         & truly greater    & 2 & yes   & yes & yes & yes & 14 \\
  1995. $=$         & equality         & 2 & yes   & yes & yes & yes & 14 \\
  1996. $==$        & alias for $=$    &   &       &     &     &     &    \\
  1997.            & & & & & &  \\
  1998. $!!$        & log. XOR         & 2 & yes   & no  & no  & no  & 13 \\
  1999. $||$        & log. OR          & 2 & yes   & no  & no  & no  & 12 \\
  2000. \&\&        & log. AND         & 2 & yes   & no  & no  & no  & 11 \\
  2001. \verb! ~~ ! & log. NOT         & 1 & yes   & no  & no  & no  & 2 \\
  2002.            & & & & & &  \\
  2003. -           & difference       & 2 & yes   & yes & no  & no  & 10 \\
  2004. +           & sum              & 2 & yes   & yes & yes & no  & 10 \\
  2005. \#          & modulo division  & 2 & yes   & no  & no  & no  & 9 \\
  2006. /           & quotient         & 2 & yes*) & yes & no  & no  & 9 \\
  2007. \verb! * !  & product          & 2 & yes   & yes & no  & no  & 9 \\
  2008. \verb! ^ !  & power            & 2 & yes   & yes & no  & no  & 8 \\
  2009.            & & & & & &  \\
  2010. $!$         & binary XOR       & 2 & yes   & no  & no  & no  & 7 \\
  2011. $|$         & binary OR        & 2 & yes   & no  & no  & no  & 6 \\
  2012. \&          & binary AND       & 2 & yes   & no  & no  & no  & 5 \\
  2013. $><$        & mirror of bits   & 2 & yes   & no  & no  & no  & 4 \\
  2014. $>>$        & log. shift right & 2 & yes   & no  & no  & no  & 3 \\
  2015. $<<$        & log. shift left  & 2 & yes   & no  & no  & no  & 3 \\
  2016. \verb! ~ !  & binary NOT       & 1 & yes   & no  & no  & no  & 1 \\
  2017. \hline
  2018. \multicolumn{8}{|l|}{*) remainder will be discarded} \\
  2019. \hline
  2020. \end{tabular}\end{center}
  2021. \caption{Operators Predefined by \asname{}\label{TabOps}}
  2022. \end{table*}
  2023. ''Rank'' is the priority of an operator at the separation of expressions
  2024. into subexpressions.  The operator with the highest rank will be
  2025. evaluated at the very end.  The order of evaluation can be defined by
  2026. new bracketing.
  2027. The comparison operators deliver TRUE in case the condition fits,
  2028. and FALSE in case it doesn't.  For the logical operators an expression
  2029. is TRUE in case it is not 0, otherwise it is FALSE.
  2030. For operators with two arguments, the order of operand evaluation
  2031. is undefined.  The only exception from this is the logical AND and
  2032. logical OR: If the result is unambiguously defined by the left
  2033. operand, the right operand is not evaluated at all.
  2034. Two details have to be kept im mind when comparing register symbols.
  2035. First, two register symbols are equal if they refer to the same
  2036. register.  Some processors have alias names for registers, and these
  2037. aliases are regarded as equal.  Fr instance, the {\tt A7} register
  2038. of a 68000 may also be referred to as {\tt SP}, and those two register
  2039. symbols are equal.  On the other hand, some processors have more than
  2040. one set of registers.  The 68040, fo rinstance, has 'normal' (integer)
  2041. and floating point registers.  There is no greater or smaller relation
  2042. between registers from different groups, the corresponding operators
  2043. always return FALSE.  Only a test for equality or inequality makes
  2044. sense.
  2045. The mirroring of bits probably needs a little bit of explanation: the
  2046. operator mirrors the lowest bits in the first operand and leaves the
  2047. higher priority bits unchanged.  The number of bits which is to be
  2048. mirrored is given by the right operand and may be between 1 and 32 .
  2049. A small pitfall is hidden in the binary complement: As the
  2050. computation is always done with 32 resp. 64 bits, its application on
  2051. e.g. 8-bit masks usually results in values taht do not fit into 8-bit
  2052. numbers any more due to the leading ones.  A binary AND with a
  2053. fitting mask is therefore unavoidable!
  2054. \subsection{Functions}
  2055. In addition to the operators, the assembler defines another line of
  2056. primarily transcendental functions with floating point arguments which are
  2057. listed in tables \ref{TabFuncs1} and \ref{TabFuncs2}.
  2058. \begin{table*}[htbp]
  2059. \begin{center}\begin{tabular}{|l|l|l|l|}
  2060. \hline
  2061. name     & meaning              & argument             & result \\
  2062. \hline
  2063. \hline
  2064. SQRT     & square root          & $arg \geq 0$         & floating point \\
  2065.         &                      &                      & \\
  2066. SIN      & sine                 & $arg \in \rz$        & floating point \\
  2067. COS      & cosine               & $arg \in \rz$        & floating point \\
  2068. TAN      & tangent              & $arg \neq (2n+1)*\frac{\pi}{2}$ & floating point \\
  2069. COT      & cotangent            & $arg \neq n*\pi$     & floating point \\
  2070.         &                      &                      & \\
  2071. ASIN     & inverse sine         & $\mid arg \mid \leq 1$ & floating point \\
  2072. ACOS     & inverse cosine       & $\mid arg \mid \leq 1$ & floating point \\
  2073. ATAN     & inverse tangent      & $arg \in \rz$        & floating point \\
  2074. ACOT     & inverse cotangent    & $arg \in \rz$        & floating point \\
  2075.         &                      &                      & \\
  2076. EXP      & exponential function & $arg \in \rz$        & floating point \\
  2077. ALOG     & 10 power of argument & $arg \in \rz$        & floating point \\
  2078. ALD      & 2 power of argument  & $arg \in \rz$        & floating point \\
  2079. SINH     & hyp. sine            & $arg \in \rz$        & floating point \\
  2080. COSH     & hyp. cosine          & $arg \in \rz$        & floating point \\
  2081. TANH     & hyp. tangent         & $arg \in \rz$        & floating point \\
  2082. COTH     & hyp. cotangent       & $arg \neq 0$         & floating point \\
  2083.         &                      &                      & \\
  2084. LN       & nat. logarithm       & $arg > 0$            & floating point \\
  2085. LOG      & dec. logarithm       & $arg > 0$            & floating point \\
  2086. LD       & bin. logarithm       & $arg > 0$            & floating point \\
  2087. ASINH    & inv. hyp. Sine       & $arg \in \rz$        & floating point \\
  2088. ACOSH    & inv. hyp. Cosine     & $arg \geq 1$         & floating point \\
  2089. ATANH    & inv. hyp. Tangent    & $arg < 1$            & floating point \\
  2090. ACOTH    & inv. hyp. Cotangent  & $arg > 1$            & floating point \\
  2091.         &                      &                      & \\
  2092. INT      & integer part         & $arg \in \rz$        & floating point \\
  2093. \hline
  2094. BITCNT   & number of one's      & integer              & integer \\
  2095. FIRSTBIT & lowest 1-bit         & integer              & integer \\
  2096. \hline
  2097. \end{tabular}\end{center}
  2098. \caption{Functions Predefined by \asname{} - Part 1 (Integer and
  2099.         Floating Point Functions \label{TabFuncs1}}
  2100. \end{table*}
  2101. \begin{table*}[htbp]
  2102. \begin{center}\begin{tabular}{|l|l|l|l|}
  2103. \hline
  2104. name        & meaning              & argument & result \\
  2105. \hline
  2106. \hline
  2107. LASTBIT     & highest 1-bit        & integer              & integer \\
  2108. BITPOS      & unique 1-bit         & integer              & integer \\
  2109.            &                      &                      & \\
  2110. SGN         & sign (0/1/-1)        & floating point       & integer \\
  2111.            &                      & or integer           & \\
  2112. ABS         & absolute value       & integer or           & integer or \\
  2113.            &                      & floating point       & floating point \\
  2114. TOUPPER     & matching capital     & integer              & integer \\
  2115. TOLOWER     & matching lower case  & integer              & integer \\
  2116.            &                      &                      & \\
  2117. UPSTRING    & changes all          & string               & string \\
  2118.            & characters           &                      & \\
  2119.            & into capitals        &                      & \\
  2120.            &                      &                      & \\
  2121. LOWSTRING   & changes all          & string               & string \\
  2122.            & characters           &                      & \\
  2123.            & into to lower case   &                      & \\
  2124.            &                      &                      & \\
  2125. STRLEN      & returns the length   & string               & integer \\
  2126.            & of a string          &                      & \\
  2127.            &                      &                      & \\
  2128. SUBSTR      & extracts parts of a  & string,              & string \\
  2129.            & string               & integer,             & \\
  2130.            &                      & integer              & \\
  2131. CHARFROMSTR & extracts a character & string,              & integer \\
  2132.            & from a string        & integer              & \\
  2133. STRSTR      & searches a substring & string,              & integer \\
  2134.            & in a string          & string               & \\
  2135. VAL         & evaluates contents   & string               & depends on \\
  2136.            & as expression        &                      & argument \\
  2137. EXPRTYPE    & delivers type of     & integer,             & 0 \\
  2138.            & argument             & float,               & 1 \\
  2139.            &                      & string               & 2 \\
  2140. \hline
  2141. \end{tabular}\end{center}
  2142. \caption{Functions Predefined by \asname{} - Part 2 (Integer and
  2143.         String Functions \label{TabFuncs2}}
  2144. \end{table*}
  2145. The functions \tty{FIRSTBIT}, \tty{LASTBIT}, and \tty{BITPOS} return -1 as
  2146. result if no resp. not exactly one bit is set.  \tty{BITPOS} additionally
  2147. issues an error message in such a case.
  2148. The string function \tty{SUBSTR} expects the source string as first
  2149. parameter, the start position as second and the number of characters to be
  2150. extracted as third parameter (a 0 means to extract all characters up to
  2151. the end).  Similarly, \tty{CHARFROMSTR} expects the source string as
  2152. first argument and the character position as second argument.  In case the
  2153. position argument is larger or equal to the source string's length,
  2154. \tty{SUBSTR} returns an empty string while \tty{CHARFROMSTR} returns -1.
  2155. A position argument smaller than zero is treated as zero by \tty{SUBSTR},
  2156. while \tty{CHARFROMSTR} will return -1 also in this case.
  2157. Here is an example how to use these both functions.  The task is to put a
  2158. string into memory, with the string end being signified by a set MSB in
  2159. the last character:
  2160. \begin{verbatim}
  2161. dbstr   macro   arg
  2162.        if      strlen(arg) > 1
  2163.         db     substr(arg, 0, strlen(arg) - 1)
  2164.        endif
  2165.        if      strlen(arg) > 0
  2166.         db     charfromstr(arg, strlen(arg) - 1) | 80h
  2167.        endif
  2168.        endm
  2169. \end{verbatim}
  2170. \tty{STRSTR} returns the first occurence of the second string
  2171. within the first one resp. -1 if the search pattern was not found.
  2172. Similarly to \tty{SUBSTR} and  \tty{CHARFROMSTR}, the first character
  2173. has the position 0.
  2174. If a function expects floating point arguments, this does not mean it
  2175. is impossible to write e.g.
  2176. \begin{verbatim}
  2177.    sqr2 equ sqrt(2)
  2178. \end{verbatim}
  2179. In such cases an automatic type conversion is engaged. In the reverse
  2180. case the \tty{INT}-function has to be applied to convert a floating point
  2181. number to an integer.  When using this function, you have to pay
  2182. attention that the result produced always is a signed integer and
  2183. therefore has a value range of approximately +/-2.0E9.
  2184. When \asname{} is switched to case-sensitive mode, predefined functions may be
  2185. accessed with an arbitrary combination of upper and lower case (in
  2186. contrast to predefined symbols).  However, in the case of user-defined
  2187. functions (see section \ref{SectFUNCTION}), a distinction between upper
  2188. and lower case is made.  This has e.g. the result that if one defines a
  2189. function \tty{Sin}, one can afterwards access this function via \tty{Sin}, but all
  2190. other combinations of upper and lower case will lead to the predefined
  2191. function.
  2192. For a correct conversion \marginpar{{\em DOS/DPMI}} of lower case letters
  2193. into capital letters a DOS version $\geq$ 3.30 is required.
  2194.  
  2195. %%---------------------------------------------------------------------------
  2196.  
  2197. \section{Forward References and Other Disasters}
  2198. \label{ForwRefs}
  2199.  
  2200. This section is the result of a significant amount of hate on the
  2201. (legal) way some people program.  This way can lead to trouble in
  2202. conjunction with \asname{} in some cases.  The section will deal with
  2203. so-called 'forward references'.  What makes a forward reference
  2204. different from a usual reference?  To understand the difference, take
  2205. a look at the following programming example (please excuse my bias
  2206. for the 68000 family that is also present in the rest of this
  2207. manual):
  2208. \begin{verbatim}
  2209.        move.l  #10,d0
  2210. loop:   move.l  (a1),d1
  2211.        beq     skip
  2212.        neg.l   d1
  2213. skip:   move.l  d1,(a1+)
  2214.        dbra    d0,loop
  2215. \end{verbatim}
  2216. If one overlooks the loop body with its branch statement, a program
  2217. remains that is extremely simple to assemble: the only reference is
  2218. the branch back to the body's beginning, and as an assembler
  2219. processes a program from the beginning to the end, the symbol's value
  2220. is already known before it is needed the first time.  If one has a
  2221. program that only contains such backward references, one has the nice
  2222. situation that only one pass through the source code is needed to
  2223. generate a correct and optimal machine code.  Some high level
  2224. languages like Pascal with their strict rule that everything has to
  2225. be defined before it is used exploit exactly this property to speed
  2226. up the compilation.
  2227.  
  2228. Unfortunately, things are not that simple in the case of assembler,
  2229. because one sometimes has to jump forward in the code or there are
  2230. reasons why one has to move variable definitions behind the code.
  2231. For our example, this is the case for the conditional branch that is
  2232. used to skip over another instruction.  When the assembler hits the
  2233. branch instruction in the first pass, it is confronted with the
  2234. situation of either leaving blank all instruction fields related to
  2235. the target address or offering a value that ''hurts noone'' via the
  2236. formula parser (which has to evaluate the address argument).  In case
  2237. of a ''simple'' assembler that supports only one target architecture
  2238. with a relatively small number of instructions to treat, one will
  2239. surely prefer the first solution, but the effort for \asname{} with its
  2240. dozens of target architectures would have become extremely high.
  2241. Only the second way was possible: If an unknown symbol is detected in
  2242. the first pass, the formula parser delivers the program counter's
  2243. current value as result!  This is the only value suitable to offer an
  2244. address to a branch instruction with unknown distance length that
  2245. will not lead to errors.  This answers also a frequently asked
  2246. question why a first-pass listing (it will not be erased e.g. when \asname{}
  2247. does not start a second pass due to additional errors) partially
  2248. shows wrong addresses in the generated binary code - they are the
  2249. result of unresolved forward references.
  2250.  
  2251. The example listed above however uncovers an additional difficulty of
  2252. forward references: Depending on the distance of branch instruction
  2253. and target in the source code, the branch may be either long or
  2254. short.  The decision however about the code length - and therefore
  2255. about the addresses of following labels - cannot be made in the first
  2256. pass due to missing knowledge about the target address.  In case the
  2257. programmer did not explicitly mark whether a long or short branch
  2258. shall be used, genuine 2-pass assemblers like older versions of MASM
  2259. from Microsoft ''solve'' the problem by reserving space for the longest
  2260. version in the first pass (all label addresses have to be fixed after
  2261. the first pass) and filling the remaining space with \tty{NOP}s in the
  2262. second pass.  \asname{} versions up to 1.37 did the same before I switched
  2263. to the multipass principle that removes the strict separation into
  2264. two passes and allows an arbitrary number of passes.  Said in detail,
  2265. the optimal code for the assumed values is generated in the first
  2266. pass.  In case \asname{} detects that values of symbols changed in the second
  2267. pass due to changes in code lengths, simply a third pass is done, and
  2268. as the second pass'es new symbol values might again shorten or
  2269. lengthen the code, a further pass is not impossible.  I have seen
  2270. 8086 programs that needed 12 passes to get everything correct and
  2271. optimal.  Unfortunately, this mechanism does not allow to specify a
  2272. maximum number passes; I can only advise that the number of passes
  2273. goes down when one makes more use of explicit length specifications.
  2274.  
  2275. Especially for large programs, another situation might arise: the
  2276. position of a forward directed branch has moved so much in the second
  2277. pass relative to the first pass that the old label value still valid
  2278. is out of the allowed branch distance.  \asname{} knows of such situations
  2279. and suppresses all error messages about too long branches when it is
  2280. clear that another pass is needed.  This works for 99\% of all cases,
  2281. but there are also constructs where the first critical instruction
  2282. appears so early that \asname{} had no chance up to now to recognize that
  2283. another pass is needed.  The following example constructs such a
  2284. situation with the help of a forward reference (and was the reason
  2285. for this section's heading...):
  2286. \begin{verbatim}
  2287.        cpu   6811
  2288.  
  2289.        org     $8000
  2290.        beq     skip
  2291.        rept    60
  2292.         ldd    Var
  2293.        endm
  2294. skip:   nop
  2295. Var     equ     $10
  2296. \end{verbatim}
  2297. Due to the address position, \asname{} assumes long addresses in the first
  2298. pass for the \tty{LDD} instructions, what results in a code length of 180
  2299. bytes and an out of branch error message in the second pass (at the
  2300. point of the \tty{BEQ} instruction, the old value of \tty{skip} is still valid,
  2301. i.e. \asname{} does not know at this point that the code is only 120 bytes
  2302. long in reality) is the result.  The error can be avoided in three
  2303. different ways:
  2304. \begin{enumerate}
  2305. \item{Explicitly tell \asname{} to use short addressing for the \tty{LDD}
  2306.      instructions (\tty{ldd <Var})}
  2307. \item{Remove this damned, rotten forward reference and place the \tty{EQU}
  2308.      statement at the beginning where it has to be (all right, I'm
  2309.      already calming down...)}
  2310. \item{For real die-hards: use the \tty{-Y} command line option.  This
  2311.      option tells \asname{} to forget the error message when the address
  2312.      change has been detected.  Not pretty, but...}
  2313. \end{enumerate}
  2314. Another tip regarding the \tty{EQU} instruction: \asname{} cannot know in which
  2315. context a symbol defined with \tty{EQU} will be used, so an \tty{EQU} containing
  2316. forward references will not be done at all in the first pass.  Thus,
  2317. if the symbol defined with \tty{EQU} gets forward-referenced in the second
  2318. pass:
  2319. \begin{verbatim}
  2320.        move.l  #sym2,d0
  2321. sym2    equ     sym1+5
  2322. sym1    equ     0
  2323. \end{verbatim}
  2324. one gets an error message due to an undefined symbol in the second
  2325. pass...but why on earth do people do such things?
  2326.  
  2327. Admittedly, this was quite a lengthy excursion, but I thought it was
  2328. necessary.  Which is the essence you should learn from this section?
  2329. \begin{enumerate}
  2330. \item{\asname{} always tries to generate the shortest code possible.  A
  2331.      finite number of passes is needed for this.  If you do not tweak
  2332.      \asname{} extremely, \asname{} will know no mercy...}
  2333. \item{Whenever sensible and possible, explicitly specify branch and
  2334.      address lengths.  There is a chance of significantly reducing the
  2335.      number of passes by this.}
  2336. \item{Limit forward references to what is absolutely needed.  You make
  2337.      your and \asname{}'s live much easier this way!}
  2338. \end{enumerate}
  2339.  
  2340. %%---------------------------------------------------------------------------
  2341.  
  2342. \section{Register Symbols}
  2343. \label{SectRegSyms} \ttindex{Register Symbols}
  2344.  
  2345. {\em valid for: PowerPC, M-Core, XGate, 4004/4040, MCS-48/(2)51, 8086,
  2346.     80C16x, AVR, XS1, Z8, KCPSM, Mico8, MSP430(X), ST9, M16, M16C, H8/300,
  2347.     H8/500, SH7x00, H16, i960, XA, 29K, TLCS-9000, KENBAK, SC/MP}
  2348.  
  2349. Sometimes it is desirable not only to assign symbolic names to memory
  2350. addresses or constants, but also to a register, to emphasize its function
  2351. in a certain program section.  This is no problem for processors that
  2352. treat registers simply as another address space, as this allows to use
  2353. numeric expressions and one can use simple \tty{EQU}s to define such
  2354. symbols.  (e.g. for the MCS-96 or TMS70000).  However, for most
  2355. processors, register identifiers are fixed literals which are seperately
  2356. treated by \asname{} for speed reasons.  Therefore, registers symbols (sometime
  2357. also called 'register aliases') are also a separate type of symbols in
  2358. the symbol table.  Just like other symbols, they may be defined or re-defined
  2359. with \tty{EQU} or \tty{SET}, and there is a specialized \tty{REG} instruction
  2360. which accepts only symbols and expressions of this type.
  2361.  
  2362. On the other hand, register symbols are subject of a couple of restrictions: the
  2363. number of literals is limited and depends on the selected target processor, and
  2364. arithmetic operations are not possibl eon registers A construct like tihs:
  2365. \begin{verbatim}
  2366. myreg   reg     r17         ; definition of register symbol
  2367.        addi    myreg+1,3   ; does not work!
  2368. \end{verbatim}
  2369. is {\em not} valid.  Simple assignments are however possible:
  2370. \begin{verbatim}
  2371. myreg   reg     r17         ; definition of register symbol
  2372. myreg2  reg     myreg       ; myreg2 -> r17
  2373. \end{verbatim}
  2374. Furthermore, forward references are even more critical than for other
  2375. types of symbols.  If a symbol is not (yet) defined, \asname{} does not know
  2376. which type it is going to have,a nd will decide for a plain integer number.
  2377. For most target processors, a number is the equivalent of absolute
  2378. memory addressing, and on most processors, usage of memory operands
  2379. is more limited than of registers.  Depending on situation, one will
  2380. get an error message about a non-allowed addressing mode, and no second
  2381. pass will be started...
  2382.  
  2383. Analogous to ordinary symbols, register symbols are local to sections and
  2384. it is possible to access a register symbol from a specific section by
  2385. appending the section's name enclosed in brackets.
  2386.  
  2387. %%---------------------------------------------------------------------------
  2388.  
  2389. \section{Share File}
  2390. \label{ChapShareMain}
  2391. \ttindex{SHARED}
  2392.  
  2393. This function is a by-product from the old pure-68000 predecessors of
  2394. \asname{}, I have kept them in case someone really needs it.  The basic
  2395. problem is to access certain symbols produced during assembly,
  2396. because possibly someone would like to access the memory of the
  2397. target system via this address information.  The assembler allows to
  2398. export symbol values by means of \tty{SHARED} pseudo commands (see there).
  2399. For this purpose, the assembler produces a text file with the required
  2400. symbols and its values in the second pass.  This file may be included
  2401. into a higher-level language or another assembler program.  The
  2402. format of the text file (C, Pascal or Assembler) can be set by the
  2403. command line switches \tty{p, c} or, \tty{a}.
  2404.  
  2405. \bb{CAUTION!} If none of the switches is given, no file will be
  2406. generated and it makes no difference if \tty{SHARED}-commands are in the
  2407. source text or not!
  2408.  
  2409. When creating a Sharefile, \asname{} does not check if a file with the
  2410. same name already exists, such a file  will be simply overwritten.
  2411. In my opinion a request does not make sense, because \asname{} would
  2412. ask at each run if it should overwrite the old version of the
  2413. Sharefile, and that would be really annoying...
  2414.  
  2415. %%---------------------------------------------------------------------------
  2416.  
  2417. \section{Processor Aliases}
  2418. \label{SectAlias}
  2419.  
  2420. Common microcontroller families are like rabbits: They become more at
  2421. a higher speed than you can provide support for them.  Especially the
  2422. development of processor cores as building blocks for ASICs and of
  2423. microcontroller families with user-definable peripherals has led to a
  2424. steeply rising number of controllers that only deviate from a
  2425. well-known type by a slightly modified peripheral set.  But the
  2426. distinction among them is still important, e.g. for the design of
  2427. include files that only define the appropriate subset of peripherals.
  2428. I have struggled up to now to integrate the most important
  2429. reperesentatives of a processor family into \asname{} (and I will continue
  2430. to do this), but sometimes I just cannot keep pace with the
  2431. development...there was an urgent need for a mechanism to extend the
  2432. list of processors by the user.
  2433.  
  2434. The result are processor aliases: the alias command line option allows to
  2435. define a new processor type, whose instruction set is equal to another
  2436. processor built into \asname{}.  After switching to this processor via the
  2437. \tty{CPU} instruction, \asname{} behaves exactly as if the original processor had
  2438. been used, with a single difference: the variables \tty{MOMCPU} resp.
  2439. \tty{MOMCPUNAME} are set to the alias name, which allows to use the new
  2440. name for differentiation, e.g. in include files.
  2441.  
  2442. There were two reasons to realize the definition of aliases by the
  2443. command line and not by pseudo instructions: first, it would anyway be
  2444. difficult to put the alias definitions together with register definitions
  2445. into a single include file, because a program that wants to use such a
  2446. file would have to include it before and after the CPU instruction - an
  2447. imagination that lies somewhere between inelegant and impossible.  Second,
  2448. the definition in the command line allows to put the definitions in a key
  2449. file that is executed automatically at startup via the \tty{ASCMD}
  2450. variable, without a need for the program to take any further care about
  2451. this.
  2452.  
  2453. %%===========================================================================
  2454.  
  2455. \cleardoublepage
  2456. \chapter{Pseudo Instructions}
  2457.  
  2458. Not all pseudo instructions are defined for all processors.  A note
  2459. that shows the range of validity is therefore prepended to every
  2460. individual description.
  2461.  
  2462. %%---------------------------------------------------------------------------
  2463.  
  2464. \section{Definitions}
  2465.  
  2466. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  2467.  
  2468. \subsection{SET, EQU, and CONSTANT}
  2469. \ttindex{SET}\ttindex{EQU}
  2470. \ttindex{.SET}\ttindex{.EQU}
  2471. \ttindex{CONSTANT}
  2472.  
  2473. {\em valid for: all processors, {\tt CONSTANT} only for KCPSM(3)}
  2474.  
  2475. \tty{SET} and \tty{EQU} allow the definition of typeless constants, i.e.  they
  2476. will not be assigned to a segment and their usage will not generate warnings
  2477. because of segment mixing.  \tty{EQU} defines constants which can not be
  2478. modified (by \tty{EQU}) again, but \tty{SET} permits the definition of
  2479. variables, which can be modified during the assembly.  This is useful e.g.
  2480. for the allocation of resources like interrupt vectors, as shown in the
  2481. following example:
  2482. \begin{verbatim}
  2483. VecCnt  set     0       ; somewhere at the beginning
  2484.        .
  2485.        .
  2486.        .
  2487. DefVec  macro   Name    ; allocate a new vector
  2488. Name    equ     VecCnt
  2489. VecCnt  set     VecCnt+4
  2490.        endm
  2491.        .
  2492.        .
  2493.        .
  2494.        DefVec  Vec1    ; results in Vec1=0
  2495.        DefVec  Vec2    ; results in Vec2=4
  2496. \end{verbatim}
  2497. constants and variables are internally stored in the same way, the only
  2498. difference is that they are marked as unchangeable if defined via \tty{EQU}.
  2499. Trying to change a constant with \tty{SET} will result in an error
  2500. message.
  2501.  
  2502. \tty{EQU/SET} allow to define constants of all possible types, e.g.
  2503. \begin{verbatim}
  2504. IntTwo   equ    2
  2505. FloatTwo equ    2.0
  2506. \end{verbatim}
  2507. Some processors unfortunately have already a \tty{SET} instruction. For
  2508. these targets, \tty{EVAL} must be used instead of \tty{SET} if no
  2509. differentiation via the argument count is possible.  As an alternative,
  2510. it is always possible to explicitly invoke the pseudo instruction
  2511. by prepending a period (\tty{.SET} instead of  \tty{SET}).
  2512.  
  2513. A single equation sign or \tty{.EQU} may be used instead of \tty{EQU}.
  2514. Similarly, one may simply write \tty{:=} instead of \tty{SET} resp.
  2515. \tty{EVAL}. Furthermore, there is an 'alternate' syntax that does not
  2516. take the symbol's name from the label field, but instead from the
  2517. first argument.  So for instance, it is valid to write:
  2518. \begin{verbatim}
  2519.          EQU   IntTwo,2
  2520.          EQU   FloatTwo,2.0
  2521. \end{verbatim}
  2522.  
  2523. For compatibility reasons to the original assembler, the KCPSM target also
  2524. knows the {\tt CONSTANT} statement, which - in contrast to \tty{EQU} -
  2525. always expects name and value as arguments.  For example:
  2526. \begin{verbatim}
  2527.      CONSTANT  const1, 2
  2528. \end{verbatim}
  2529. {\tt CONSTANT} is however limited to integer constants.
  2530.  
  2531. Symbols defined with \tty{SET} or \tty{EQU} are typeless by default, but
  2532. optionally a segment name (\tty{CODE, DATA, IDATA, XDATA, YDATA, BITDATA,
  2533. IO}, or \tty{REG}) or \tty{MOMSEGMENT} for the currently active segment
  2534. may be given as a second or third parameter, allowing to assign the symbol to a
  2535. specific address space.  \asname{} does not check at this point if the used
  2536. address space exists on the currently active target processor!
  2537.  
  2538. A little hidden extra feature allows to set the program counter via
  2539. \tty{SET} or \tty{EQU}, something one would ordinarily do via \tty{ORG}.
  2540. To accomplish this, use the special value as symbol name that may also
  2541. be used to query the current program counter's value.  Depending on the
  2542. selected target architecture, this is either an asterisk, a dollar sign,
  2543. a period, or \tty{PC}.
  2544.  
  2545. In case the target architecture supports instruction attributes to define
  2546. the operand size (e.g. on 680x0), those are also allowed for \tty{SET} and
  2547. \tty{EQU}.  The operand size will be stored along with the symbol's value in
  2548. the symbol table.  Its use is architecture-dependant.
  2549.  
  2550. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  2551.  
  2552. \subsection{SFR and SFRB}
  2553. \ttindex{SFR}\ttindex{SFRB}
  2554.  
  2555. {\em valid for: various, \tty{SFRB} only MCS-51}
  2556.  
  2557. These instructions act like \tty{EQU}, but symbols defined with them are
  2558. assigned to the directly addressable data resp. I/O segment, i.e. they are
  2559. preferrably used for the definition of (as the name lets guess) hardware
  2560. registers mapped into the data res. I/O area.  The allowed range of values
  2561. is equal to the range allowed for \tty{ORG} in the data segment (see
  2562. section \ref{SectORG}).  The difference between \tty{SFR} and \tty{SFRB}
  2563. is that \tty{SFRB} marks the register as bit addressable, which is why \asname{}
  2564. generates 8 additional symbols which will be assigned to the bit segment
  2565. and carry the names xx.0 to xx.7, e.g.
  2566. \begin{verbatim}
  2567. PSW     sfr     0d0h    ; results in PSW = D0H (data segment)
  2568.  
  2569. PSW     sfrb    0d0h    ; results in extra PSW.0 = D0H (bit)
  2570.                        ;               to PSW.7 = D7H (bit)
  2571. \end{verbatim}
  2572. The \tty{SFRB} instruction is not any more defined for the 80C251 as it
  2573. allows direct bit access to all SFRs without special bit symbols; bits
  2574. like \tty{PSW.0} to \tty{PSW.7} are automatically present.
  2575.  
  2576. Whenever a bit-addressable register is defined via \tty{SFRB}, \asname{} checks
  2577. if the memory address is bit addressable (range 20h..3fh resp. 80h, 88h,
  2578. 90h, 98h...0f8h).  If it is not bit-addressable, a warning is issued and
  2579. the generated bit symbols are undefined.
  2580.  
  2581. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  2582.  
  2583. \subsection{XSFR and YSFR}
  2584. \ttindex{XSFR}\ttindex{YSFR}
  2585.  
  2586. {\em valid for: DSP56xxx}
  2587.  
  2588. Also the DSP56000 has a few peripheral registers memory-mapped to the RAM,
  2589. but the affair becomes complicated because there are two data areas, the
  2590. X- and Y-area.  This architecture allows on the one hand a higher
  2591. parallelism, but forces on the other hand to divide the normal \tty{SFR}
  2592. instruction into the two above mentioned variations.  They works
  2593. identically to \tty{SFR}, just that \tty{XSFR} defines a symbol in the X-
  2594. addressing space and YSFR a corresponding one in the Y-addressing space.
  2595. The allowed value range is 0..\$ffff.
  2596.  
  2597. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  2598.  
  2599. \subsection{LABEL}
  2600. \ttindex{LABEL}
  2601.  
  2602. {\em valid for: all processors}
  2603.  
  2604. The function of the \tty{LABEL} instruction is identical to \tty{EQU}, but
  2605. the symbol does not become typeless, it gets the attribute ''code''.
  2606. \tty{LABEL} is needed exactly for one purpose: Labels are normally local
  2607. in macros, that means they are not accessible outside of a macro.  With an
  2608. \tty{EQU} instruction you could get out of it nicely, but the phrasing
  2609. \begin{verbatim}
  2610. <name>  label   $
  2611. \end{verbatim}
  2612. generates a symbol with correct attributes.
  2613.  
  2614. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  2615.  
  2616. \subsection{BIT}
  2617. \ttindex{BIT}
  2618.  
  2619. {\em valid for: MCS/(2)51, XA, 80C166, 75K0, ST9, AVR, S12Z, SX20/28, H16,
  2620.                H8/300, H8/500, KENBAK, Padauk}
  2621.  
  2622. \tty{BIT} serves to equate a single bit of a memory cell with a symbolic
  2623. name.  This instruction varies from target platform to target platform due
  2624. to the different ways in which processors handle bit manipulation and
  2625. addressing:
  2626.  
  2627. The MCS/51 family has an own address space for bit operands.  The function
  2628. of \tty{BIT} is therefore quite similar to \tty{SFR}, i.e. a simple integer
  2629. symbol with the specified value is generated and assigned to the
  2630. \tty{BDATA} segment.  For all other processors, bit addressing is done in
  2631. a two-dimensional fashion with address and bit position.  In these cases,
  2632. \asname{} packs both parts into an integer symbol in a way that depends on the
  2633. currently active target processor and separates both parts again when the
  2634. symbol is used.  The latter is is also valid for the 80C251: While an
  2635. instruction like
  2636. \begin{verbatim}
  2637. My_Carry bit    PSW.7
  2638. \end{verbatim}
  2639. would assign the value 0d7h to \tty{My\_Carry} on an 8051, a value of
  2640. 070000d0h would be generated on an 80C251, i.e. the address is located in
  2641. bits 0..7 and the bit position in bits 24..26.  This procedure is equal to
  2642. the way the \tty{DBIT} instruction handles things on a TMS370 and is also
  2643. used on the 80C166, with the only difference that bit positions may range
  2644. from 0..15:
  2645. \begin{verbatim}
  2646. MSB     BIT     r5.15
  2647. \end{verbatim}
  2648. On a Philips XA, the bit's address is located in bits 0..9 just with
  2649. the same coding as used in machine instructions, and the 64K bank of
  2650. bits in RAM memory is placed in bits 16..23.
  2651.  
  2652. The \tty{BIT} instruction of the 75K0 family even goes further: As bit
  2653. expressions may not only use absolute base addresses, even expressions
  2654. like
  2655. \begin{verbatim}
  2656. bit1    BIT     @h+5.2
  2657. \end{verbatim}
  2658. are allowed.
  2659.  
  2660. The ST9 in turn allows to invert bits, what is also allowed in the
  2661. \tty{BIT} instruction:
  2662. \begin{verbatim}
  2663. invbit  BIT     r6.!3
  2664. \end{verbatim}
  2665. More about the ST9's \tty{BIT} instruction can be found in the processor
  2666. specific hints.
  2667.  
  2668. In case of H16, note that the address and bit position arguments are swapped.
  2669. This was done to make the syntax of BIT consistent with the machine instructions
  2670. that maipulate individual bits.
  2671.  
  2672. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  2673.  
  2674. \subsection{DBIT}
  2675. \ttindex{DBIT}
  2676.  
  2677. {\em valid for: TMS 370xxx}
  2678.  
  2679. Though the TMS370 series does not have an explicit bit segment, single bit
  2680. symbols may be simulated with this instruction.  \tty{DBIT} requires two
  2681. operands, the address of the memory cell that contains the bit and the
  2682. exact position of the bit in the byte.  For example,
  2683. \begin{verbatim}
  2684. INT3        EQU  P019
  2685. INT3_ENABLE DBIT 0,INT3
  2686. \end{verbatim}
  2687. defines the bit that enables interrupts via the INT3 pin.  Bits defined
  2688. this way may be used in the instructions \tty{SBIT0, SBIT1, CMPBIT,
  2689. JBIT0}, and \tty{JBIT}.
  2690.  
  2691. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  2692.  
  2693. \subsection{DEFBIT and DEFBITB}
  2694. \ttindex{DEFBIT}
  2695. \ttindex{DEFBITB}
  2696.  
  2697. \subsubsection{S12Z}
  2698.  
  2699. The S12Z family's processor core provides instructions to manipulate
  2700. individual bits in registers or memory cells.  To conveniently
  2701. address bits in the CPU's I/O area (first 4 Kbytes of the address
  2702. space), a bit may be given a symbolic name.  The bit is defined by
  2703. its memory address and the bit position:
  2704. \begin{verbatim}
  2705. <name>         defbit[.size]   <address>,<position>
  2706. \end{verbatim}
  2707. The \tty{address} must be located within the first 4 Kbytes, and the
  2708. operand size may be 8, 16, or 32 bits (\tty{size}=b/w/l).
  2709. Consequently, the \tty{position} may at most be 7, 15 or 31.  If no
  2710. operand size is given, byte size (.b) is assumed.  A bit defined
  2711. this way may be used as argument for the instructions {\tt BCLR,
  2712. BSET, BTGL, BRSET,} and {\tt BRCLR}:
  2713. \begin{verbatim}
  2714. mybit   defbit.b  $200,4
  2715.        bclr.b    $200,#4
  2716.        bclr      mybit
  2717. \end{verbatim}
  2718. Both uses of {\tt bclr} in this example generate identical code.
  2719. Since a bit defined this way ''knows'' its size, the size attribute
  2720. may be omitted when using it.
  2721.  
  2722. It is also possible to define bits that are located within a
  2723. structure's element:
  2724. \begin{verbatim}
  2725. mystruct struct    dots
  2726. reg      ds.w      1
  2727. flag     defbit    reg,4
  2728.         ends
  2729.  
  2730.         org       $100
  2731. data     mystruct
  2732.         bset      data.flag  ; same as bset.w $100,#4
  2733. \end{verbatim}
  2734.  
  2735. \subsubsection{Super8}
  2736.  
  2737. Opposed to the 'classic' Z8, the Super8 core supports instructions to operate
  2738. on bits in working or general registers.  ONe however has to to regard that
  2739. some of them can only operate on bits in one of the 16 working registers.
  2740. The \tty{DEFBIT} instruction allows to define bits of either type:
  2741. \begin{verbatim}
  2742. workbit defbit  r3,#4
  2743. slow    defbit  emt,#6
  2744. \end{verbatim}
  2745. Bits that have been defined this way may be used just like a argument duple of
  2746. register and bit position:
  2747. \begin{verbatim}
  2748.        ldb     r3,emt,#6
  2749.        ldb     r3,slo          ; same result
  2750.  
  2751.        bitc    r3,#4
  2752.        bitc    workbit         ; same result
  2753. \end{verbatim}
  2754.  
  2755. \subsubsection{Z8000}
  2756.  
  2757. The Z8000 features instructions to set and clear bits, however they cannot access
  2758. addresses in I/O space.  For this reason, both {\tt DEFBIT} and {\tt DEFBITB}
  2759. only allow to define bit objects in memory space.  The differentiation in operand
  2760. size is important because the Z8000 is a big endian processor: bit {\em n} of a
  2761. 16 bit word at address {\em m} corresponds to bit {\em n} of an 8-bit byte at
  2762. address {\em m+1}.
  2763.  
  2764. \subsubsection{$\mu$PD7807...$\mu$PD7809}
  2765.  
  2766. The lowest 16 bytes of the working area and special registers with an address
  2767. less than 16 are bit addressable.
  2768.  
  2769. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  2770.  
  2771. \subsection{DEFBITFIELD}
  2772. \ttindex{DEFBITFIELD}
  2773.  
  2774. {\em valid for: S12Z}
  2775.  
  2776. The S12Z family's CPU core not only deals with individual bits, it
  2777. is also able to extract a field of consecutive bits from an
  2778. 8/16/24/32 value or to insert a bit field into such a value. Similar
  2779. to \tty{DEFBIT}, a bit field may be defined symbolically:
  2780. \begin{verbatim}
  2781. <Name>     defbitfield[.size] <address>,<width>:<position>
  2782. \end{verbatim}
  2783. Opposed to individual bits, an operand size of 24 bits (.p) is also
  2784. alloweed.  The range of \tty{position} and \tty{width} is accordingly
  2785. 0 to 23 resp. 1 to 24.  It is also allowed to define bit fields as
  2786. parts of structures:
  2787. \begin{verbatim}
  2788. mystruct struct      dots
  2789. reg      ds.w        1
  2790. clksel   defbitfield reg,4:8
  2791.         ends
  2792.  
  2793.         org       $100
  2794. data     mystruct
  2795.         bfext     d2,data.clksel ; fetch $100.w bits 4..11
  2796.                                  ; to D2 bits 0..7
  2797.         bfins     data.clksel,d2 ; insert D2 bits 0..7 into
  2798.                                  ; $100.w bits 4..11
  2799. \end{verbatim}
  2800. The internal representation of bits defined via \tty{DEFBIT} is
  2801. equivalent to bit fields with a width of one.  Therefore, a
  2802. symbolically defined bit may also be used as argument for
  2803. \tty{BFINS} and \tty{BFEXT}.
  2804.  
  2805. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  2806.  
  2807. \subsection{PORT}
  2808. \ttindex{PORT}
  2809.  
  2810. {\em valid for: PALM, 8008/8080/8085/8086, XA, Z80, Z8000, 320C2x/5x, TLCS-47, AVR,
  2811.     F8, IMP-16}
  2812.  
  2813. \tty{PORT} works similar to \tty{EQU}, just the symbol becomes assigned to the
  2814. I/O-address range.  Allowed values are 0..7 for the 3201x and 8008, 0..15 for the
  2815. 320C2x and PALM, 0..65535 for the 8086, Z8000, and 320C5x, 0..63 for the AVR, and 0..255
  2816. for the rest.
  2817.  
  2818. Example : an 8255 PIO is located at address 20H:
  2819. \begin{verbatim}
  2820. PIO_port_A port 20h
  2821. PIO_port_B port PIO_port_A+1
  2822. PIO_port_C port PIO_port_A+2
  2823. PIO_ctrl   port PIO_port_A+3
  2824. \end{verbatim}
  2825.  
  2826. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  2827.  
  2828. \subsection{REG and NAMEREG}
  2829. \ttindex{REG}\ttindex{NAMEREG}
  2830.  
  2831. {\em valid for: 680x0, AVR, M*Core, ST9, 80C16x, Z8000, KCPSM, \\
  2832.     PDP-11, WD16 \\
  2833.     ({\tt NAMEREG} valid only for KCPSM(3)), LatticeMico8, MSP430(X)}
  2834.  
  2835. Though it always has the same syntax, this instruction has a slightly
  2836. different meaning from processor to processor:  If the processor uses a
  2837. separate addressing space for registers, \tty{REG} has the same effect as
  2838. a simple \tty{EQU} for this address space (e.g. for the ST9).  \tty{REG}
  2839. defines register symbols for all other processors whose function is
  2840. described in section \ref{SectRegSyms}.
  2841.  
  2842. {\tt NAMEREG} exists for compatibility reasons to the original KCPSM
  2843. assembler.  It has an identical function, however both register and
  2844. symbolic name are given as arguments, for example:
  2845. \begin{verbatim}
  2846.     NAMEREG  s08, treg
  2847. \end{verbatim}
  2848.  
  2849. On the PDP-11, \tty{REG} may additionally be used without a name in the
  2850. label field.  It then expects a single \tty{ON} or \tty{OFF} as argument
  2851. and enables or disables the built-in register aliases (\tty{Rn} = \tty{\%n},
  2852. \tty{SP} = \tty{R6}, \tty{PC} = \tty{R7}).  They are available by default,
  2853. and should only be disabled if they conflict with own synmbol names in a
  2854. program. The current setting may be read from the symbol \tty{DEFAULT\_REGSYMS}.
  2855.  
  2856. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  2857.  
  2858. \subsection{LIV and RIV}
  2859. \ttindex{LIV}\ttindex{RIV}
  2860.  
  2861. {\em valid for: 8X30x}
  2862.  
  2863. \tty{LIV} and \tty{RIV} allow to define so-called ''IV bus objects''.
  2864. These are
  2865. groups of bits located in a peripheral memory cell with a length of 1
  2866. up to 8 bits, which can afterwards be referenced symbolically.  The
  2867. result is that one does not anymore have to specify address,
  2868. position, and length separately for instructions that can refer to
  2869. peripheral bit groups.  As the 8X30x processors feature two
  2870. peripheral address spaces (a ''left'' and a ''right'' one), there are two
  2871. separate pseudo instructions.  The parameters of these instructions
  2872. are however equal: three parameters have to be given that specify
  2873. address, start position and length.  Further hints for the usage of
  2874. bus objects can be found in section \ref{8X30xSpec} .
  2875.  
  2876. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  2877.  
  2878. \subsection{CHARSET}
  2879. \label{SectCHARSET}
  2880. \ttindex{CHARSET}\ttindex{CODEPAGE\_VAL}
  2881.  
  2882. {\em valid for: all processors}
  2883.  
  2884. Single board systems, especially when driving LCDs, frequently use
  2885. character sets different to ASCII.  So it is probably purely coincidental
  2886. that the umlaut coding corresponds with the one used by the PC.  And there
  2887. are of course also (historical) systems that use some variant of EBCDIC...to avoid
  2888. error-prone manual encoding in the source code, the assembler contains a translation table
  2889. for characters which assigns a target character to each (ASCII) character
  2890. in the source code.  Use the \tty{CHARSET} instruction to modify this
  2891. table, which initial translates one-to-one.  \tty{CHARSET} may be used with
  2892. a variety of arguments:
  2893.  
  2894. A simple
  2895. \begin{quote}{\tt
  2896.        CHARSET
  2897. }\end{quote}
  2898. without any argument resets the table to the one-to-one default.
  2899.  
  2900. If only a single argument is given, it has to be a string expression which is
  2901. interpreted as a file name by \asname{}:
  2902. \begin{verbatim}
  2903.        CHARSET  "mapping.bin"
  2904. \end{verbatim}
  2905. \asname{} reads the first 256 bytes from this table and copies them into the translation
  2906. table.  This allows to activate complex, externally generated tables with a single
  2907. statement.
  2908.  
  2909. All other variants modify a single entry or a sequence of entries in the
  2910. table.  Use two (integer) arguments to change a single entry:
  2911. \begin{quote}{\tt
  2912.       CHARSET  '\"a',128
  2913. }\end{quote}
  2914. means that the target system codes the '\"a'  into the number 128.  It is
  2915. als possible to define that a certain character is unavailable on the target
  2916. system.  Leave the second argument empty to define this:
  2917. \begin{quote}{\tt
  2918.        CHARSET '[',
  2919. }\end{quote}
  2920. If the 'deleted' character shall be disposed in memory, this reported as
  2921. an error.
  2922.  
  2923. Use three arguments to remap a whole range of characters.  The first and
  2924. second argument define the character range, and the third one defines
  2925. the mapping of the first character.  For instance, if the target system
  2926. does not support lower case characters,
  2927. \begin{verbatim}
  2928.        CHARSET 'a','z','A'
  2929. \end{verbatim}
  2930. translates all lower-case characters automatically into the matching
  2931. capital letters.  Similar to a single character, it is also possible to
  2932. 'unmap' a range of characters:
  2933. \begin{verbatim}
  2934.        CHARSET 'a','z',
  2935. \end{verbatim}
  2936. forbids usage of lower case letters.
  2937.  
  2938. The last variant (again only with two arguments), a string defines the
  2939. mapping of a sequence of characters.  Mapping of lower to upper case may
  2940. therefore also be written like this:
  2941. be written as
  2942. \begin{verbatim}
  2943.        CHARSET 'a',"ABCDEFGHIJKLMNOPQRSTUVWXYZ"
  2944. \end{verbatim}
  2945.  
  2946. \bb{CAUTION!} \tty{CHARSET} not only affects string constants stored in
  2947. memory, but also multi character constants, i.e. integer constants written
  2948. as ''ASCII''.  This means that an already modified translation table can
  2949. lead to different results in the examples mentioned above!
  2950.  
  2951. The built-in function \tty{CODEPAGE\_VAL} allows to query the translation
  2952. of a single character in the current code page.  It will return -1 for
  2953. unmapped characters.
  2954.  
  2955. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  2956.  
  2957. \subsection{CODEPAGE}
  2958. \ttindex{CODEPAGE}
  2959.  
  2960. {\em valid for: all processors}
  2961.  
  2962. Though the \tty{CHARSET} statement gives unlimited freedom in the
  2963. character assignment between host and target platform, switching among
  2964. different character {\em sets} can become quite tedious if several
  2965. character sets have to be supported on the target platform.  The
  2966. \tty{CODEPAGE} instruction however allows to define and keep different
  2967. character sets and to switch with a single statement among them.
  2968. \tty{CODEPAGE} expects one or two arguments: the name of the set to be
  2969. used hereafter and optionally the name of another table that defines its
  2970. initial contents (the second parameter therefore only has a meaning for
  2971. the first switch to the table when \asname{} automatically creates it).  If the
  2972. second parameter is missing, the initial contents of the new table are
  2973. copied from the previously active set.  All subsequent \tty{CHARSET}
  2974. statements {\em only} modify the new set.
  2975.  
  2976. At the beginning of a pass, \asname{} automatically creates a single character
  2977. set with the name \tty{STANDARD} with a one-to-one translation.  If no
  2978. \tty{CODEPAGE} instructions are used, all settings made via \tty{CHARSET}
  2979. refer to this table.
  2980.  
  2981. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  2982.  
  2983. \subsection{ENUM, NEXTENUM, and ENUMCONF}
  2984. \ttindex{ENUM}
  2985. \ttindex{NEXTENUM}
  2986. \ttindex{ENUMCONF}
  2987.  
  2988. {\em valid for: all processors}
  2989.  
  2990. Similar to the same-named instruction known from C, \tty{ENUM} is used to
  2991. define enumeration types, i.e. a sequence of integer constants that
  2992. are assigned sequential values starting at 0.  The parameters are the
  2993. names of the symbols, like in the following example:
  2994. \begin{verbatim}
  2995.        ENUM    SymA,SymB,SymC
  2996. \end{verbatim}
  2997. This instruction will assign the values 0, 1, and 2 to the symbols
  2998. \tty{SymA, SymB,} and \tty{SymC}.
  2999.  
  3000. If you want to split an enumeration over more than one line, use
  3001. \tty{NEXTENUM} instead of \tty{ENUM} for the second and all
  3002. following lines.  The internal counter that assigns sequential
  3003. values to alls symbols will then not be reset to zero, like in the
  3004. following case:
  3005. \begin{verbatim}
  3006.        ENUM     January=1,February,March,April,May,June
  3007.        NEXTENUM July,August,September,October
  3008.        NEXTENUM November,December
  3009. \end{verbatim}
  3010. This example also demonstrates that it is possible to assign
  3011. explicit values to individual symbols.  The internal counter will
  3012. be updated accordingly if this feature is used.
  3013.  
  3014. A definition of a symbol with \tty{ENUM} is equal to a definition with
  3015. \tty{EQU}, i.e. it is not possible to assign a new value to a symbol that
  3016. already exists.
  3017.  
  3018. The \tty{ENUMCONF} statement allows to influence the behaviour of
  3019. \tty{ENUM}.  \tty{ENUMCONF} accepts one or two arguments.  The
  3020. first argument is always the value the internal counter is
  3021. incremented for every symbol in an enumeration.  For instance,
  3022. the statement
  3023. \begin{verbatim}
  3024.      ENUMCONF 2
  3025. \end{verbatim}
  3026. has the effect that symbols get the values 0,2,4,6... instead of
  3027. 0,1,2,3...
  3028.  
  3029. The second (optional) argument of \tty{ENUMCONF} rules which
  3030. address space the defined symbols are assigned to.  By default,
  3031. symbols defined by \tty{ENUM} are typeless.  For instance, the
  3032. statement
  3033. \begin{verbatim}
  3034.      ENUMCONF 1,CODE
  3035. \end{verbatim}
  3036. defines that they should be assigned to the instruction address
  3037. space.  The names of the address spaces are the same as for the
  3038. \tty{SEGMENT} instruction (\ref{SEGMENT}), with the addition of
  3039. \tty{NOTHING} to generate typeless symbols again.
  3040.  
  3041. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  3042.  
  3043. \subsection{PUSHV and POPV}
  3044. \ttindex{PUSHV}\ttindex{POPV}
  3045.  
  3046. {\em valid for: all processors}
  3047.  
  3048. \tty{PUSHV} and \tty{POPV} allow to temporarily save the value of a symbol
  3049. (that is not macro-local) and to restore it at a later point of time.  The
  3050. storage is done on stacks, i.e. Last-In-First-Out memory structures.  A
  3051. stack has a name that has to fulfill the general rules for symbol names
  3052. and it exists as long as it contains at least one element: a stack that
  3053. did not exist before is automatically created upon \tty{PUSHV}, and a
  3054. stack becoming empty upon a \tty{POPV} is deleted automatically.  The name
  3055. of the stack that shall be used to save or restore symbols is the first
  3056. parameter of \tty{PUSH} resp. \tty{POPV}, followed by a list of symbols as
  3057. further parameters.  All symbols referenced in the list already have to
  3058. exist, it is therefore \bb{not} possible to implicitly define symbols with
  3059. a \tty{POPV} instruction.
  3060.  
  3061. Stacks are a global resource, i.e. their names are not local to
  3062. sections.
  3063.  
  3064. It is important to note that symbol lists are \bb{always} processed from
  3065. left to right.  Someone who wants to pop several variables from a stack
  3066. with a \tty{POPV} therefore has to use the exact reverse order used in the
  3067. corresponding \tty{PUSHV}!
  3068.  
  3069. The name of the stack may be left blank, like this:
  3070. \begin{verbatim}
  3071.        pushv   ,var1,var2,var3
  3072.        .
  3073.        .
  3074.        popv    ,var3,var2,var1
  3075. \end{verbatim}
  3076. \asname{} will then use a predefined internal default stack.
  3077.  
  3078. \asname{} checks at the end of a pass if there are stacks that are not empty and
  3079. issues their names together with their ''filling level''.  This allows to
  3080. find out if there are any unpaired \tty{PUSHVs} or \tty{POPVs}.  However,
  3081. it is in no case possible to save values in a stack beyond the end of a
  3082. pass: all stacks are cleared at the beginning of a pass!
  3083.  
  3084. %%---------------------------------------------------------------------------
  3085.  
  3086. \section{Code Modification}
  3087.  
  3088. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  3089.  
  3090. \subsection{ORG}
  3091. \label{SectORG}
  3092. \ttindex{ORG}
  3093.  
  3094. {\em valid for: all processors}
  3095.  
  3096. \tty{ORG} allows to load the internal address counter (of the assembler)
  3097. with a new value. The value range depends on the currently selected
  3098. segment and on the processor type (table \ref{TabORG}).
  3099. The lower bound is always zero, and the upper bound is the given value
  3100. minus 1.
  3101. \par
  3102. {\bf CAUTION}: If the \tty{PHASE} instruction is also used, one
  3103. has to keep in mind that the argument of \tty{ORG} always is the
  3104. {\em load address} of the code.  Expressions using the \$ or \*
  3105. symbol to refer to the current program counter however deliver
  3106. the {\em execution address} of the code and do not yield the
  3107. desired result when used as argument for \tty{ORG}.  The
  3108. \tty{RORG} statement (\ref{SectRORG}) should be used in such cases.
  3109. \hfuzz=60pt
  3110. \small
  3111. \begin{longtable}{|l|c|c|c|c|c|c|c|c|c|c|}
  3112. \hline
  3113. \tin{Target} & \tin{CODE} & \tin{DATA} & \tin{I-}   & \tin{X-}   & \tin{Y-}   & \tin{BIT-} & \tin{IO} & \tin{REG} & \tin{ROM-}  & \tin{EE-}  \\
  3114.             &            &            & \tin{DATA} & \tin{DATA} & \tin{DATA} & \tin{DATA} &          &           & \tin{DATA}  & \tin{DATA} \\
  3115. \hline
  3116. \hline
  3117. \endhead
  3118. \input{../doc_COM/taborg.tex}
  3119. \\ \hline
  3120. \multicolumn{11}{|l|}{$^{1}$ Initial value 80h.} \\
  3121. \multicolumn{11}{|l|}{   As the 8051 does not have any RAM beyond 80h, this value has to be} \\
  3122. \multicolumn{11}{|l|}{   adapted with ORG for the 8051 as target processor!}\\
  3123. \hline
  3124. \multicolumn{11}{|l|}{$^{2}$ As the Z180 still can address only 64K logically, the whole}\\
  3125. \multicolumn{11}{|l|}{   address space can only be reached via \tty{PHASE} instructions!}\\
  3126. \hline
  3127. \multicolumn{11}{|l|}{$^{3}$ initial value 400h.}\\
  3128. \hline
  3129. \multicolumn{11}{|l|}{$^{4}$ initial value 800h resp. 0C00h} \\
  3130. \hline
  3131. \multicolumn{11}{|l|}{$^{5}$ area for program code is limited to 1 MByte} \\
  3132. \hline
  3133. \multicolumn{11}{|l|}{$^{6}$ size depends on target processor} \\
  3134. \hline
  3135. \multicolumn{11}{|l|}{$^{7}$ size and availibility depend on target processor} \\
  3136. \hline
  3137. \multicolumn{11}{|l|}{$^{8}$ only on variants supporting the \tty{MOVX} instruction} \\
  3138. \hline
  3139. \multicolumn{11}{|l|}{$^{9}$ device dependent} \\
  3140. \hline
  3141. \multicolumn{11}{|l|}{$^{10}$ model dependent} \\
  3142. \hline
  3143. \caption{Address Ranges for \tty{ORG}}
  3144. \label{TabORG}
  3145. \end{longtable}
  3146. \normalsize
  3147. \hfuzz=0pt
  3148.  
  3149. In case that different variations in a processor family have address
  3150. spaces of different size, the maximum range is listed for each.
  3151.  
  3152. \tty{ORG} is mostly needed to give the code a new starting address or to
  3153. put different, non-continuous code parts into one source file.  In case
  3154. there is no explicit other value listet in a table entry, the initial
  3155. address for this segment (i.e. the start address used without {\tt ORG})
  3156. is 0.
  3157.  
  3158. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  3159.  
  3160. \subsection{RORG}
  3161. \label{SectRORG}
  3162. \ttindex{RORG}
  3163.  
  3164. {\em valid for: all processors}
  3165.  
  3166. \tty{RORG} modifies the program counter just like \tty{ORG},
  3167. however it does not expect an absolute address as argument.
  3168. Instead, it expects a relative value (positive or negative) that
  3169. is added to the current program counter.  A possible application
  3170. of this statement is the reservation of a certain amount of
  3171. address space, or the use in code parts that are included
  3172. multiple times (e.g. via macros or includes) and that shall be
  3173. position-independent.  Another application is the use in code
  3174. that has an execution address different from the load address
  3175. (i.e. the \tty{PHASE} statement is used).  There is no symbol to
  3176. refer to the current {\em load address}, but it can be referred
  3177. to indirectly via the \tty{RORG} statement.
  3178.  
  3179. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  3180.  
  3181. \subsection{CPU}
  3182. \label{SectCPU}
  3183. \ttindex{CPU}
  3184.  
  3185. \newcounter{cpucounter1}
  3186. \newcounter{cpucounter2}
  3187.  
  3188. \newcommand{\cpu}{
  3189. \stepcounter{cpucounter1}
  3190. \ifnum\value{cpucounter1}>26
  3191.   \setcounter{cpucounter1}{1}
  3192.   \stepcounter{cpucounter2}
  3193. \fi
  3194. \ifnum\value{cpucounter2}>0\alph{cpucounter2}\fi\alph{cpucounter1})
  3195. }
  3196. \newenvironment{cpulist}
  3197. {
  3198. \begin{quote}
  3199. \begin{tabbing}
  3200. \cpu \=
  3201. }
  3202. {
  3203. \end{tabbing}
  3204. \end{quote}
  3205. }
  3206.  
  3207. {\em valid for: all processors}
  3208.  
  3209. This command rules for which processor the further code shall be
  3210. generated.  Instructions of other processor families are not
  3211. accessible afterwards and will produce error messages!
  3212.  
  3213. The processors can roughly be distinguished in families, inside the
  3214. families different types additionally serve for a detailed
  3215. distinction:
  3216. %%-----------
  3217. \begin{cpulist}
  3218.   68008 $\rightarrow$ 68000 $\rightarrow$ 68010 $\rightarrow$ 68012 $\rightarrow$ \\
  3219. \> MCF5202 $\rightarrow$ MCF5204 $\rightarrow$ MCF5206 $\rightarrow$ MCF5208$\rightarrow$ \\
  3220. \> MCF52274 $\rightarrow$ MCF52277 $\rightarrow$ MCF5307 $\rightarrow$ MCF5329 $\rightarrow$ \\
  3221. \> MCF5373 $\rightarrow$ MCF5407 $\rightarrow$ MCF5470 $\rightarrow$ MCF5471 $\rightarrow$ \\
  3222. \> MCF5472 $\rightarrow$ MCF5473 $\rightarrow$ MCF5474 $\rightarrow$ MCF5475 $\rightarrow$ \\
  3223. \> MCF51QM $\rightarrow$ \\
  3224. \> 68332 $\rightarrow$ 68340 $\rightarrow$ 68360 $\rightarrow$ \\
  3225. \> 68020 $\rightarrow$ 68030 $\rightarrow$ 68040
  3226. \end{cpulist}
  3227. The differences in this family are additional instructions and
  3228. addressing modes (starting from the 68020).  A small exception is the step
  3229. to the 68030 that misses two instructions: \tty{CALLM} and \tty{RTM}.  The
  3230. three representatives of the 683xx family have the same processor core (a
  3231. slightly reduced 68020 CPU), however completely different peripherals.
  3232. MCF5xxx represents various ColdFire variants from Motorola/Freescale/NXP,
  3233. RISC processors downwardly binary compatible to the 680x0.  For the 68040,
  3234. additional control registers (reachable via \tty{MOVEC}) and instructions
  3235. for control of the on-chip MMU and caches were added.
  3236. %%-----------
  3237. \begin{cpulist}
  3238.   56000 $\longrightarrow$ 56002 $\longrightarrow$ 56300
  3239. \end{cpulist}
  3240. While the 56002 only adds instructions for incrementing and decrementing
  3241. the accumulators, the 56300 core is almost a new processor: all address
  3242. spaces are enlarged from 64K words to 16M and the number of instructions
  3243. almost has been doubled.
  3244. %%-----------
  3245. \begin{cpulist}
  3246.   PPC403 $\rightarrow$ MPPC403 $\rightarrow$ MPC505 $\rightarrow$ MPC601 \\
  3247. \> $\rightarrow$ MPC821 $\rightarrow$ RS6000
  3248. \end{cpulist}
  3249. The PPC403 is a reduced version of the PowerPC line without a floating
  3250. point unit, which is why all floating point instructions are disabled for
  3251. him; in turn, some microcontroller-specific instructions have been added
  3252. which are unique in this family.  The GC variant of the PPC403
  3253. incorporates an additional MMU and has therefore some additional
  3254. instructions for its control.  The MPC505 (a microcontroller variant
  3255. without a FPU) only differ in its peripheral registers from the 601 as
  3256. long as I do not know it better - \cite{Mot505} is a bit reluctant in this
  3257. respect...  The RS6000 line knows a few instructions more (that are
  3258. emulated on many 601-based systems), IBM additionally uses different
  3259. mnemonics for their pure workstation processors, as a reminiscence of 370
  3260. mainframes...
  3261. %%-----------
  3262. \begin{cpulist}
  3263.   IBM5100, IBM5110, IBM5120
  3264. \end{cpulist}
  3265. These three types currently all reference to the same (PALM)
  3266. prozessor core.
  3267. %%-----------
  3268. \begin{cpulist}
  3269.   MCORE
  3270. \end{cpulist}
  3271. %%-----------
  3272. \begin{cpulist}
  3273.   XGATE
  3274. \end{cpulist}
  3275. %%-----------
  3276. \begin{cpulist}
  3277.   6800 $\rightarrow$ 6801 $\rightarrow$ 6301 $\rightarrow$ 6811
  3278. \end{cpulist}
  3279. While the 6801 only offers a few additional instructions (and the
  3280. 6301 even a few more), the 6811 provides a second index register and
  3281. much more instructions.
  3282. %%-----------
  3283. \begin{cpulist}
  3284.   6809/6309 and 6805/68HC(S)08
  3285. \end{cpulist}
  3286. These processors are partially source-code compatible to the other
  3287. 68xx processors, but they have a different binary code format and a
  3288. significantly reduced (6805) resp. enhanced (6809) instruction set.
  3289. The 6309 is a CMOS version of the 6809 which is officially only
  3290. compatible to the 6809, but inofficially offers more registers and a
  3291. lot of new instructions (see \cite{Kaku}).
  3292. %%-----------
  3293. \begin{cpulist}
  3294.   68HC12 $\longrightarrow$ 68HC12X
  3295. \end{cpulist}
  3296. The 12X core offers a couple of new instructions, and existing
  3297. instructions were were enriched with new addressing modes.
  3298. %%-----------
  3299. \begin{cpulist}
  3300.   S912ZVC19F0MKH, S912ZVC19F0MLF,\\
  3301. \> S912ZVCA19F0MKH, S912ZVCA19F0MLF,\\
  3302. \> S912ZVCA19F0WKH, S912ZVH128F2CLQ,\\
  3303. \> S912ZVH128F2CLL, S912ZVH64F2CLQ,\\
  3304. \> S912ZVHY64F1CLQ, S912ZVHY32F1CLQ,\\
  3305. \> S912ZVHY64F1CLL, S912ZVHY32F1CLL,\\
  3306. \> S912ZVHL64F1CLQ, S912ZVHL32F1CLQ,\\
  3307. \> S912ZVHL64F1CLL, S912ZVHL32F1CLL,\\
  3308. \> S912ZVFP64F1CLQ, S912ZVFP64F1CLL,\\
  3309. \> S912ZVH128F2VLQ, S912ZVH128F2VLL,\\
  3310. \> S912ZVH64F2VLQ, S912ZVHY64F1VLQ,\\
  3311. \> S912ZVHY32F1VLQ, S912ZVHY64F1VL,\\
  3312. \> S912ZVHY32F1VLL, S912ZVHL64F1VLQ
  3313. \end{cpulist}
  3314. All variants contain the same processor core and the same
  3315. instruction set, only the on-chip peripherals and the
  3316. amount of built-in memory (RAM, Flash-ROM, EEPROM)
  3317. vary from device to device.
  3318. %%-----------
  3319. \begin{cpulist}
  3320.   68HC16
  3321. \end{cpulist}
  3322. %%-----------
  3323. \begin{cpulist}
  3324.   052001
  3325. \end{cpulist}
  3326. This chip is an own creation of Konami and similar to the
  3327. Motorola 6809 in architecture an instruction set.  However,
  3328. it is not binary compatible and does not provide all instructions
  3329. and addressing modes of its 'role model'.
  3330. %%-----------
  3331. \begin{cpulist}
  3332.   HD6413308 $\rightarrow$ HD6413309
  3333. \end{cpulist}
  3334. These both names represent the 300 and 300H variants of the H8
  3335. family; the H version owns a larger address space (16 Mbytes instead
  3336. of 64 Kbytes), double-width registers (32 bits), and knows a few more
  3337. instructions and addressing modes.  It is still binary upward
  3338. compatible.
  3339. %%-----------
  3340. \begin{cpulist}
  3341.   HD6475328 $\rightarrow$ HD6475348 $\rightarrow$ HD6475368 $\rightarrow$ HD6475388
  3342. \end{cpulist}
  3343. These processors all share the same CPU core; the different types are
  3344. only needed to include the correct subset of registers in the file
  3345. \tty{REG53X.INC}.
  3346. %%-----------
  3347. \begin{cpulist}
  3348.   SH7000 $\rightarrow$ SH7600 $\longrightarrow$ SH7700
  3349. \end{cpulist}
  3350. The processor core of the 7600 offers a few more instructions that
  3351. close gaps in the 7000's instruction set (delayed conditional and
  3352. relative and indirect jumps, multiplications with 32-bit operands and
  3353. multiply/add instructions).  The 7700 series (also known as SH3)
  3354. furthermore offers a second register bank, better shift instructions, and
  3355. instructions to control the cache.
  3356. %%-----------
  3357. \begin{cpulist}
  3358.   HD614023 $\longrightarrow$ HD614043 $\longrightarrow$ HD614081
  3359. \end{cpulist}
  3360. These three variants of the HMCS400 series differ by the size of
  3361. the internal ROM and RAM.
  3362. %%-----------
  3363. \begin{cpulist}
  3364.   HD641016
  3365. \end{cpulist}
  3366. This is currently the only target with H16 core.
  3367. %%-----------
  3368. \begin{cpulist}
  3369.   6502 $\rightarrow$ 65(S)C02 \\
  3370. \> $\rightarrow$ 65CE02 / W65C02S / 65C19 /\\
  3371. \> MELPS740 / HUC6280 / 6502UNDOC
  3372. \end{cpulist}
  3373. The CMOS version defines some additional instructions, as well as a number of
  3374. some instruction/addressing mode combinations were added which were not
  3375. possible on the 6502.  The W65C02S adds two opcodes to the 65C02 instruction
  3376. set to give more fine-grained control over how to stop the CPU for low power
  3377. modes.  The 65SC02 lacks the bit manipulation instructions of the
  3378. 65C02.  The 65CE02 adds branch instructions with 16-bit displacement, a Z
  3379. register, a 16 bit stack pointer, a programmable base page, and a couple of
  3380. new instructions.
  3381.  
  3382. The 65C19 is {\em not} binary upward compatible to the original
  3383. 6502! Some addressing modes have been replaced by others.
  3384. Furthermore, this processor contains instruction set extensions
  3385. that facilitate digital signal processing.
  3386.  
  3387. The Mitsubishi micro controllers in opposite expand
  3388. the 6502 instruction set primarily to bit operations and multiplication /
  3389. division instructions.  Except for the unconditional jump and instructions
  3390. to increment/decrement the accumulator, the instruction extensions
  3391. have nothing in common.
  3392.  
  3393. For the HuC 6280, the feature that sticks out most is the larger
  3394. address space of 2 MByte instead of 64 KBytes.  This is achieved
  3395. with a buil-tin banking mechanism.  Furthermore, it features some
  3396. special instructions to communicate with a video processor (this
  3397. chip was used in video games) and to copy memory areas.
  3398.  
  3399. The 6502UNDOC processor type enables access to the "undocumented"
  3400. 6502 instructions, i.e. the operations that result from the usage of bit
  3401. combinations in the opcode that are not defined as instructions.  The
  3402. variants supported by \asname{} are listed in the appendix containing processor-specific
  3403. hints.
  3404. %%-----------
  3405. \begin{cpulist}
  3406.   MELPS7700, 65816
  3407. \end{cpulist}
  3408. Apart from a '16-bit-version' of the 6502's instruction set, these
  3409. processors both offer some instruction set extensions.  These are
  3410. however orthogonal as they are oriented along their 8-bit
  3411. predecessors (65C02 resp. MELPS-740).  Partially, different
  3412. mnemonics are used for the same operations.
  3413. %%-----------
  3414. \begin{cpulist}
  3415.   PPS-4
  3416. \end{cpulist}
  3417. %%-----------
  3418. \begin{cpulist}
  3419.   MELPS4500
  3420. \end{cpulist}
  3421. %%-----------
  3422. \begin{cpulist}
  3423.   M16
  3424. \end{cpulist}
  3425. %%-----------
  3426. \begin{cpulist}
  3427.   M16C
  3428. \end{cpulist}
  3429. %%-----------
  3430. \begin{cpulist}
  3431.   PDP-11/03, PDP-11/04, PDP-11/05, PDP-11/10,\\
  3432. \> PDP-11/15, PDP-11/20, PDP-11/23, PDP-11/24,\\
  3433. \> PDP-11/34, PDP-11/35, PDP-11/40, PDP-11/44,\\
  3434. \> PDP-11/45, PDP-11/50, MicroPDP-11/53,\\
  3435. \> PDP-11/55, PDP-11/60, PDP-11/70, MicroPDP-11/73,\\
  3436. \> MicroPDP-11/83, PDP-11/84, MicroPDP-11/93,\\
  3437. \> PDP-11/94, T-11
  3438. \end{cpulist}
  3439. The various models of the PDP-11 series differ in instruction
  3440. set (both in built-in instructions as well as in available extensions)
  3441. and the supported address space (64, 256, or 4096 KBytes).
  3442. %%-----------
  3443. \begin{cpulist}
  3444.   WD16
  3445. \end{cpulist}
  3446. The WD16 uses the same processor as the LSI-11, however
  3447. with different microcode.  As a consequence, register set
  3448. and addressing modes are the same as for a PDP-11, however
  3449. the instruction set is slightly different and instructions
  3450. also available on the PDP-11 have different machine codes.
  3451. %%-----------
  3452. \begin{cpulist}
  3453.   MICROVAX-I, MICROVAX-II, \\
  3454. \> VAX-11/725, VAX-11/730, VAX-11/750, \\
  3455. \> VAX-11/780, VAX-11/782, VAX-11/785, \\
  3456. \> VAX-8200, VAX-8300, VAX-8500, VAX-8600 \\
  3457. \> VAX-8650, VAX-8800
  3458. \end{cpulist}
  3459. All implementations of the VAX architecture share the same
  3460. core instruction set.  However, certain extensions, like
  3461. instructions to process strings, packed decimal numbers or
  3462. certain floating point formats, are not available in hardware.
  3463. %%-----------
  3464. \begin{cpulist}
  3465.   CP-3F, LP8000, M380
  3466. \end{cpulist}
  3467. The chipset's processor element was sold by AEG/Olympia, GI,
  3468. and SGS-Ates under the respective names.  There are no differences
  3469. in the instruction set and address spaces.
  3470. %%-----------
  3471. \begin{cpulist}
  3472.   4004 $\rightarrow$ 4040
  3473. \end{cpulist}
  3474. In comparison to its predecessor, the 4040 features about a dozen
  3475. additional machine instructions.
  3476. %%-----------
  3477. \begin{cpulist}
  3478.   8008 $\rightarrow$ 8008NEW
  3479. \end{cpulist}
  3480. Intel redefined the 8008's mnemonics around 1975, the second variant reflects
  3481. this new instruction set.  A simultaneous support of both sets was not
  3482. possible due to mnemonic conflicts.
  3483. %%-----------
  3484. \begin{cpulist}
  3485.   8021, 8022, \\
  3486. \> 8401, 8411, 8421, 8461, \\
  3487. \> 8039, (MSM)80C39, 8048, (MSM)80C48, 8041, 8042, 80C382
  3488. \end{cpulist}
  3489. For the ROM-less versions 8039 and 80C39, the commands which are
  3490. using the BUS (port 0) are forbidden.  The 8021 and 8022 are special
  3491. versions with a strongly shrinked instruction set, for which the 8022
  3492. has two A/D- converters and the necessary control-commands.  The
  3493. instruction set of the MAB8401 to 8461 (designed by Philips) is
  3494. somewhere in between the 8021/8022 and a ''complete'' MC-48 instruction
  3495. set.  On the other hand, they provide serial ports and up to 8 KBytes
  3496. of program memory.
  3497.  
  3498. It is possible to transfer the CMOS-versions with the \tty{IDL} resp.
  3499. \tty{HALT} command into a stop mode with lower current consumption.
  3500. The 8041 and 8042 have some additional instructions for controlling the
  3501. bus interface, but in turn a few other commands were omitted.
  3502. The code address space of 8041, 8042, 84x1, 8021, and 8022 is not externally
  3503. extendable, and so \asname{} limits the code segment of these processors to
  3504. the size of the internal ROM.  The (SAB)80C382 is a variant especially
  3505. designed by Siemens for usage in telephones.  It also knows a
  3506. \tty{HALT} instruction, plus ist supports indirect addressing for
  3507. \tty{DJNZ} and \tty{DEC}.  In turn, several instructions of the
  3508. 'generic' 8048 were left out.  The OKI variants (MSM...) also
  3509. feature indirect addressing for \tty{DJNZ} and \tty{DEC}, plus
  3510. enhanced control of power-down modes, plus the full basic MCS-48
  3511. instrucion set.
  3512. %%-----------
  3513. \begin{cpulist}
  3514.   87C750 $\rightarrow$ 8051, 8052, 80C320, 80C501, 80C502, \\
  3515. \> 80C504, 80515, and 80517 \\
  3516. \> $\rightarrow$ 80C390 \\
  3517. \> $\rightarrow$ 80C251
  3518. \end{cpulist}
  3519. The 87C750 can only access a maximum of 2 Kbytes program memory which is
  3520. why it lacks the \tty{LCALL} and \tty{LJMP} instructions.  \asname{} does not
  3521. make any distinction among the processors in the middle, instead it only
  3522. stores the different names in the \tty{MOMCPU} variable (see below), which
  3523. allows to query the setting with \tty{IF} instructions.  An exception is
  3524. the 80C504 that has a mask flaw in its current versions.  This flaw shows
  3525. up when an \tty{AJMP} or \tty{ACALL} instruction starts at the second last
  3526. address of a 2K page.  \asname{} will automatically use long instructions or
  3527. issues an error message in such situations.  The 80C251 in contrast
  3528. represents a drastic progress in the the direction 16/32 bits, larger
  3529. address spaces, and a more orthogonal instruction set.  One might call the
  3530. 80C390 the 'small solution': Dallas Semiconductor modified instruction set
  3531. and architecture only as far as it was necessary for the 16 Mbytes large
  3532. address spaces.
  3533. %%-----------
  3534. \begin{cpulist}
  3535.   8096 $\rightarrow$ 80196 $\rightarrow$ 80196N $\rightarrow$ 80296
  3536. \end{cpulist}
  3537. Apart from a different set of SFRs (which however strongly vary from
  3538. version to version), the 80196 knows several new instructions and
  3539. supports a 'windowing' mechanism to access the larger internal RAM.
  3540. The 80196N family extends the address space to 16 Mbytes and
  3541. introduces a set of instructions to access addresses beyond 64Kbytes.
  3542. The 80296 extends the CPU core by instructions for signal processing
  3543. and a second windowing register, however removes the Peripheral
  3544. Transaction Server (PTS) and therefore looses again two machine
  3545. instructions.
  3546. %%-----------
  3547. \begin{cpulist}
  3548.   8080 $\rightarrow$ V30EMU $\rightarrow$ 8085 $\rightarrow$ 8085UNDOC
  3549. \end{cpulist}
  3550. The 8085 knows the additional commands \tty{RIM} and \tty{SIM} for
  3551. controlling the interrupt mask and the two I/O-pins.  The type {\tt
  3552. 8085UNDOC} enables additional instructions that are not documented
  3553. by Intel.  These instructions are documented in section \ref{8085Spec}.
  3554.  
  3555. {\tt V30EMU} as target behaves like an 8080, with the addition of
  3556. the instructions {\tt RETEM} and {\em CALLN}.  These allow to
  3557. end or interrupt the 8080 emulation on a V20/V30/V40/V50.
  3558. %%-----------
  3559. \begin{cpulist}
  3560.   8088,8086 \\
  3561. \> $\rightarrow$ 80188,80186 \\
  3562. \> $\rightarrow$ V20,V30,V40,V50 \\
  3563. \> $\rightarrow$ V33,V53 \\
  3564. \> $\rightarrow$ V25,V35 \\
  3565. \> $\rightarrow$ V55 \\
  3566. \> $\rightarrow$ V55SC \\
  3567. \> $\rightarrow$ V55PI
  3568. \end{cpulist}
  3569. Processors listed in the same line feature an identical CPU core and therefore
  3570. identical instruction set.  Going down the lines, new instructions are added,
  3571. with the NEC CPUs going different 'branches', coming from the 'V20 basic
  3572. instruction set'.
  3573. %%-----------
  3574. \begin{cpulist}
  3575.   80960
  3576. \end{cpulist}
  3577. %%-----------
  3578. \begin{cpulist}
  3579.   8X300 $\rightarrow$ 8X305
  3580. \end{cpulist}
  3581. The 8X305 features a couple of additional registers that miss on the
  3582. 8X300.  Additionally, it can do new operations with these registers
  3583. (like direct writing of 8 bit values to peripheral addresses).
  3584. %%-----------
  3585. \begin{cpulist}
  3586.   XAG1, XAG2, XAG3
  3587. \end{cpulist}
  3588. These processors only differ in the size of their internal ROM which
  3589. is defined in \tty{STDDEFXA.INC}.
  3590. %%-----------
  3591. \begin{cpulist}
  3592.   AT90S1200, AT90S2313, AT90S2323, AT90S233,\\
  3593. \> AT90S2343, AT90S4414, AT90S4433, AT90S4434,\\
  3594. \> AT90S8515, AT90C8534, AT90S8535,\\
  3595. \> ATTINY4, ATTINY5, ATTINY9,\\
  3596. \> ATTINY10, ATTINY11, ATTINY12, ATTINY13, ATTINY13A,\\
  3597. \> ATTINY15, ATTINY20, ATTINY24(A), ATTINY25,\\
  3598. \> ATTINY26, ATTINY28, ATTINY40, ATTINY44(A),\\
  3599. \> ATTINY45, ATTINY48, ATTINY84(A), ATTINY85,\\
  3600. \> ATTINY87, ATTINY88, ATTINY102, ATTINY104,\\
  3601. \> ATTINY167, ATTINY261, ATTINY261A, ATTINY43U,\\
  3602. \> ATTINY441, ATTINY461, ATTINY461A, ATTINY828,\\
  3603. \> ATTINY841, ATTINY861, ATTINY861A, ATTINY1634,\\
  3604. \> ATTINY2313, ATTINY2313A, ATTINY4313, ATMEGA48,\\
  3605. \> ATMEGA8, ATMEGA8515, ATMEGA8535, ATMEGA88,\\
  3606. \> ATMEGA8U2, ATMEGA16U2, ATMEGA32U2,\\
  3607. \> ATMEGA16U4, ATMEGA32U4, ATMEGA32U6, AT90USB646,\\
  3608. \> AT90USB647, AT90USB1286, AT90USB1287, AT43USB355,\\
  3609. \> ATMEGA16, ATMEGA161, ATMEGA162, ATMEGA163,\\
  3610. \> ATMEGA164, ATMEGA165, ATMEGA168, ATMEGA169,\\
  3611. \> ATMEGA32, ATMEGA323, ATMEGA324, ATMEGA325,\\
  3612. \> ATMEGA3250, ATMEGA328, ATMEGA329, ATMEGA3290,\\
  3613. \> ATMEGA406, ATMEGA64, ATMEGA640, ATMEGA644,\\
  3614. \> ATMEGA644RFR2, ATMEGA645, ATMEGA6450,\\
  3615. \> ATMEGA649, ATMEGA6490, ATMEGA103, ATMEGA128,\\
  3616. \> ATMEGA1280, ATMEGA1281, ATMEGA1284,\\
  3617. \> ATMEGA1284RFR2, ATMEGA2560, ATMEGA2561
  3618. \end{cpulist}
  3619. The various AVR chip variants mainly differ in the amount of
  3620. on-chip memory (flash, SRAM, EEPROM) an the set of built-in
  3621. peripherals (GPIO, timers, UART, A/D converter...).  Compared to
  3622. the AT90... predecessors, the ATmega chip also provide additional
  3623. instructions, while the ATtinys do not support the multiplication
  3624. instructions.
  3625. %%-----------
  3626. \begin{cpulist}
  3627.   AM29245 $\rightarrow$ AM29243 $\rightarrow$ AM29240 $\rightarrow$ AM29000
  3628. \end{cpulist}
  3629. The further one moves to the right in this list, the fewer the
  3630. instructions become that have to be emulated in software.  While e.g.
  3631. the 29245 not even owns a hardware multiplier, the two representors in
  3632. the middle only lack the floating point instructions.  The 29000
  3633. serves as a 'generic' type that understands all instructions in
  3634. hardware.
  3635. %%-----------
  3636. \begin{cpulist}
  3637.   80C166 $\rightarrow$ 80C167,80C165,80C163
  3638. \end{cpulist}
  3639. 80C167 and 80C165/163 have an address space of 16 Mbytes instead of 256
  3640. Kbytes, and furthermore they know some additional instructions for
  3641. extended addressing modes and atomic instruction sequences.  They are
  3642. 'second generation' processors and differ from each other only in the
  3643. amount of on-chip peripherals.
  3644. %%-----------
  3645. \begin{cpulist}
  3646.   LR35902/GBZ80 $\rightarrow$ Z80 $\rightarrow$ Z80UNDOC \\
  3647. \> $\rightarrow$ Z180 \\
  3648. \> $\rightarrow$ eZ80190, eZ80L92, eZ80F91, \\
  3649. \> eZ80F92, eZ80F93, \\
  3650. \> $\rightarrow$ Z380
  3651. \end{cpulist}
  3652. While there are only a few additional instructions for the Z180, the
  3653. Z380 owns 32-bit registers, a linear address space of 4 Gbytes, a
  3654. couple of instruction set extensions that make the overall
  3655. instruction set considerably more orthogonal, and new addressing
  3656. modes (referring to index register halves, stack relative).  These
  3657. extensions partially already exist on the Z80 as undocumented
  3658. extensions and may be switched on via the Z80UNDOC variant.  A list
  3659. with the additional instructions can be found in the chapter
  3660. with processor specific hints.
  3661.  
  3662. The processor built into the Gameboy (official designation LR35092,
  3663. commonly referred to as ''Gameboy Z80'') is a mixture of an 8080
  3664. and Z80.  It lacks the IX/IY registers, the I/O address space,
  3665. the second register bank and a couple of 16 bit instructions.
  3666.  
  3667. The Zilog eZ80 variants extend the Z80 architecture with a 16
  3668. MByte address space, 24 bit registers and moderate additions to
  3669. the instruction set.  Some variants feature an I register that
  3670. is only 8 bits wide, and the eZ80190 additionally lacks a few
  3671. string I/O instructios.  Otherwise, they only differ in the
  3672. amonut of on-chip memory and peripherals.
  3673. %%-----------
  3674. \begin{cpulist}
  3675.   Z8601, Z8603, z86C03, z86E03, Z86C06, Z86E06, \\
  3676. \> Z86C08, Z86C21, Z86E21, Z86C30, Z86C31, Z86C32 Z86C40 \\
  3677. \> $\rightarrow$ Z88C00, Z88C01 \\
  3678. \> $\rightarrow$ eZ8, Z8F0113, Z8F011A, Z8F0123, Z8F012A, \\
  3679. \> Z8F0130, Z8F0131, Z8F0213, Z8F021A, Z8F0223, Z8F022A, \\
  3680. \> Z8F0230, Z8F0231, Z8F0411, Z8F0412, Z8F0413, Z8F041A, \\
  3681. \> Z8F0421, Z8F0422, Z8F0423, Z8F042A, Z8F0430, Z8F0431, \\
  3682. \> Z8F0811, Z8F0812, Z8F0813, Z8F081A, Z8F0821, Z8F0822, \\
  3683. \> Z8F0823, Z8F082A, Z8F0830, Z8F0831, Z8F0880, Z8F1232, \\
  3684. \> Z8F1233, Z8F1621, Z8F1622, Z8F1680, Z8F1681, Z8F1682, \\
  3685. \> Z8F2421, Z8F2422, Z8F2480, Z8F3221, Z8F3222, Z8F3281, \\
  3686. \> Z8F3282, Z8F4821, Z8F4822, Z8F4823, Z8F6081, Z8F6082, \\
  3687. \> Z8F6421, Z8F6422, Z8F6423, Z8F6481, Z8F6482
  3688. \end{cpulist}
  3689. The variants with Z8 core only differ in internal memory size and
  3690. on-chip peripherals, i.e. the choice does not have an effect on the
  3691. supported instruction set.  Super8 and eZ8 are substantially different,
  3692. each with an instruction set that was vastly extended (into different
  3693. directions), and they are not fully upward-compatible on source code
  3694. level as well.
  3695. %%-----------
  3696. \begin{cpulist}
  3697.   Z8001, Z8002, Z8003, Z8004
  3698. \end{cpulist}
  3699. The operation mode (segmented for Z8001 and Z8003, non-segmented for
  3700. Z8002 and Z8004) is selected via the processor type.  There is currently
  3701. no further differentiation between Z8001/8002 and Z8003/8004.
  3702. %%-----------
  3703. \begin{cpulist}
  3704.   KCPSM, KCPSM3
  3705. \end{cpulist}
  3706. Both processor cores are not available as standalone components, they are
  3707. provided as logic cores for gate arrays made by Xilinx The -3 variant
  3708. offers a larger address space and some additional instructions.  Note that
  3709. it is not binary upward-compatible!
  3710. %%-----------
  3711. \begin{cpulist}
  3712.   MICO8\_05, MICO8\_V3, MICO8\_V31
  3713. \end{cpulist}
  3714. Lattice unfortunately changed the machine instructions more than once, so
  3715. different targets became necessary to provide continued support for older
  3716. projects.  The first variant is the one described in the 2005 manual, the
  3717. two other ones represent versions 3.0 resp. 3.1.
  3718. %%-----------
  3719. \begin{cpulist}
  3720.   96C141, 93C141
  3721. \end{cpulist}
  3722. These two processors represent the two variations of the processor
  3723. family: TLCS-900 and TLCS-900L.  The differences of these two variations
  3724. will be discussed in detail in section \ref{TLCS900Spec}.
  3725. %%-----------
  3726. \begin{cpulist}
  3727.   90C141
  3728. \end{cpulist}
  3729. %%-----------
  3730. \begin{cpulist}
  3731.   87C00, 87C20, 87C40, 87C70
  3732. \end{cpulist}
  3733. The processors of the TLCS-870 series have an identical CPU core, but
  3734. different peripherals depending on the type.  In part registers with
  3735. the same name are located at different addresses.  The file
  3736. \tty{STDDEF87.INC} uses, similar to the MCS-51-family, the distinction
  3737. possible by different types to provide the correct symbol set
  3738. automatically.
  3739. %%-----------
  3740. \begin{cpulist}
  3741.   TLCS-870/C
  3742. \end{cpulist}
  3743. Currently, only the processor core of the TLCS-870/C family is
  3744. implemented.
  3745. %%-----------
  3746. \begin{cpulist}
  3747.   47C00 $\rightarrow$ 470C00 $\rightarrow$ 470AC00
  3748. \end{cpulist}
  3749. These three variations of the TLCS-47-family have on-chip RAM and ROM
  3750. of different size, which leads to several bank switching instructions
  3751. being added or suppressed.
  3752. %%-----------
  3753. \begin{cpulist}
  3754.   97C241
  3755. \end{cpulist}
  3756. %%-----------
  3757. \begin{cpulist}
  3758.   TC9331
  3759. \end{cpulist}
  3760. %%-----------
  3761. \begin{cpulist}
  3762.   16C54 $\rightarrow$ 16C55 $\rightarrow$ 16C56 $\rightarrow$ 16C57
  3763. \end{cpulist}
  3764. These processors differ by the available code area, i.e. by the address
  3765. limit after which \asname{} reports overruns.
  3766. %%-----------
  3767. \begin{cpulist}
  3768.   16C84, 16C64
  3769. \end{cpulist}
  3770. Analog to the MCS-51 family, no distinction is made in the code generator,
  3771. the different numbers only serve to include the correct SFRs in
  3772. \tty{STDDEF18.INC}.
  3773. %%-----------
  3774. \begin{cpulist}
  3775.   17C42
  3776. \end{cpulist}
  3777. %%-----------
  3778. \begin{cpulist}
  3779.   SX20, SX28
  3780. \end{cpulist}
  3781. The SX20 uses a smaller housing and lacks port C.
  3782. %%-----------
  3783. \begin{cpulist}
  3784.   ST6200, ST6201, ST6203, ST6208, ST6209,\\
  3785. \> ST6210, ST6215, ST6218, ST6220, ST6225,\\
  3786. \> ST6228, ST6230, ST6232, ST6235, ST6240,\\
  3787. \> ST6242, ST6245, ST6246, ST6252, ST6253,\\
  3788. \> ST6255, ST6260, ST6262, ST6263, ST6265,\\
  3789. \> ST6280, ST6285
  3790. \end{cpulist}
  3791. The various ST6 derivates differ in the amount of
  3792. on-chip peripherals and built-in memory.
  3793. %%-----------
  3794. \begin{cpulist}
  3795.   ST7 \\
  3796. \> ST72251G1, ST72251G2, ST72311J2, ST72311J4, \\
  3797. \> ST72321BR6, ST72321BR7, ST72321BR9, ST72325S4, \\
  3798. \> ST72325S6, ST72325J7, ST72325R9, ST72324J6, \\
  3799. \> ST72324K6, ST72324J4, ST72324K4, ST72324J2, \\
  3800. \> ST72324JK21, ST72325S4, ST72325J7, ST72325R9, \\
  3801. \> ST72521BR6, ST72521BM9, ST7232AK1, ST7232AK2, \\
  3802. \> ST7232AJ1, ST7232AJ2, ST72361AR4, ST72361AR6, \\
  3803. \> ST72361AR7, ST72361AR9, ST7FOXK1, ST7FOXK2, \\
  3804. \> ST7LITES2Y0, ST7LITES5Y0, ST7LITE02Y0, \\
  3805. \> ST7LITE05Y0, ST7LITE09Y0 \\
  3806. \> ST7LITE10F1, ST7LITE15F1, ST7LITE19F1, \\
  3807. \> ST7LITE10F0, ST7LITE15F0, ST7LITE15F1, \\
  3808. \> ST7LITE19F0, ST7LITE19F1, \\
  3809. \> ST7LITE20F2, ST7LITE25F2, ST7LITE29F2, \\
  3810. \> ST7LITE30F2, ST7LITE35F2, ST7LITE39F2, \\
  3811. \> ST7LITE49K2, \\
  3812. \> ST7MC1K2, ST7MC1K4, ST7MC2N6, ST7MC2S4, \\
  3813. \> ST7MC2S6, ST7MC2S7, ST7MC2S9, ST7MC2R6, \\
  3814. \> ST7MC2R7, ST7MC2R9, ST7MC2M9, \\
  3815. \> STM8 \\
  3816. \> STM8S001J3, STM8S003F3, STM8S003K3, STM8S005C6,\\
  3817. \> STM8S005K6, STM8S007C8, STM8S103F2, STM8S103F3,\\
  3818. \> STM8S103K3, STM8S105C4, STM8S105C6, STM8S105K4,\\
  3819. \> STM8S105K6, STM8S105S4, STM8S105S6, STM8S207MB,\\
  3820. \> STM8S207M8, STM8S207RB, STM8S207R8, STM8S207R6,\\
  3821. \> STM8S207CB, STM8S207C8, STM8S207C6, STM8S207SB,\\
  3822. \> STM8S207S8, STM8S207S6, STM8S207K8, STM8S207K6,\\
  3823. \> STM8S208MB, STM8S208RB, STM8S208R8, STM8S208R6,\\
  3824. \> STM8S208CB, STM8S208C8, STM8S208C6, STM8S208SB,\\
  3825. \> STM8S208S8, STM8S208S6, STM8S903K3, STM8S903F3,\\
  3826. \> STM8L050J3, STM8L051F3, STM8L052C6, STM8L052R8,\\
  3827. \> STM8L001J3, STM8L101F1, STM8L101F2, STM8L101G2,\\
  3828. \> STM8L101F3, STM8L101G3, STM8L101K3, STM8L151C2,\\
  3829. \> STM8L151K2, STM8L151G2, STM8L151F2, STM8L151C3,\\
  3830. \> STM8L151K3, STM8L151G3, STM8L151F3, STM8L151C4,\\
  3831. \> STM8L151C6, STM8L151K4, STM8L151K6, STM8L151G4,\\
  3832. \> STM8L151G6, STM8L152C4, STM8L152C6, STM8L152K4,\\
  3833. \> STM8L152K6, STM8L151R6, STM8L151C8, STM8L151M8,\\
  3834. \> STM8L151R8, STM8L152R6, STM8L152C8, STM8L152K8,\\
  3835. \> STM8L152M8, STM8L152R8, STM8L162M8, STM8L162R8,\\
  3836. \> STM8AF6366, STM8AF6388, STM8AF6213, STM8AF6223,\\
  3837. \> STM8AF6226, STM8AF6246, STM8AF6248, STM8AF6266,\\
  3838. \> STM8AF6268, STM8AF6269, STM8AF6286, STM8AF6288,\\
  3839. \> STM8AF6289, STM8AF628A, STM8AF62A6, STM8AF62A8,\\
  3840. \> STM8AF62A9, STM8AF62AA, STM8AF5268, STM8AF5269,\\
  3841. \> STM8AF5286, STM8AF5288, STM8AF5289, STM8AF528A,\\
  3842. \> STM8AF52A6, STM8AF52A8, STM8AF52A9, STM8AF52AA,\\
  3843. \> STM8AL3136, STM8AL3138, STM8AL3146, STM8AL3148,\\
  3844. \> STM8AL3166, STM8AL3168, STM8AL3L46, STM8AL3L48,\\
  3845. \> STM8AL3L66, STM8AL3L68, STM8AL3188, STM8AL3189,\\
  3846. \> STM8AL318A, STM8AL3L88, STM8AL3L89, STM8AL3L8A,\\
  3847. \> STM8TL52F4, STM8TL52G4, STM8TL53C4, STM8TL53F4,\\
  3848. \> STM8TL53G4
  3849. \end{cpulist}
  3850. The STM8 core extends the address space to 16 Mbytes and introduces
  3851. a couple of new instructions.  Though many instructions have the same
  3852. machine code as for ST7, it is not binary upward compatible.
  3853. %%-----------
  3854. \begin{cpulist}
  3855.   ST9020, ST9030, ST9040, ST9050
  3856. \end{cpulist}
  3857. These 4 names represent the four ''sub-families'' of the ST9 family,
  3858. which only differ in their on-chip peripherals.  Their processor
  3859. cores are identical, which is why this distinction is again only used
  3860. in the include file containing the peripheral addresses.
  3861. %%-----------
  3862. \begin{cpulist}
  3863.   6804
  3864. \end{cpulist}
  3865. %%-----------
  3866. \begin{cpulist}
  3867.   32010$\rightarrow$32015
  3868. \end{cpulist}
  3869. The TMS32010 owns just 144 bytes of internal RAM, and so \asname{} limits
  3870. addresses in the data segment just up to this amount.  This restriction
  3871. does not apply for the 32015, the full range from 0..255 can be used.
  3872. %%-----------
  3873. \begin{cpulist}
  3874.   320C25 $\rightarrow$ 320C26 $\rightarrow$ 320C28
  3875. \end{cpulist}
  3876. These processors only differ slightly in their on-chip peripherals
  3877. and in their configuration instructions.
  3878. %%-----------
  3879. \begin{cpulist}
  3880.   320C30, 320C31 $\rightarrow$ 320C40, 320C44
  3881. \end{cpulist}
  3882. The 320C31 is a reduced version with the same instruction set,
  3883. however fewer peripherals.  The distinction is exploited in
  3884. \tty{STDDEF3X.INC}.  The C4x variants are sourcecode upward
  3885. compatible, the machine codes of some instructions are however
  3886. slightly different.  Once again, the C44 is a stripped-down
  3887. version of the C40, with less peripherals and a smaller address
  3888. space.
  3889. %%-----------
  3890. \begin{cpulist}
  3891.   320C203 $\rightarrow$ 320C50, 320C51, 320C53
  3892. \end{cpulist}
  3893. The first one represents the C20x family of signal processors which
  3894. implement a subset of the C5x instruction set.  The distinction among the
  3895. C5x processors is currently not used by \asname{}.
  3896. %%-----------
  3897. \begin{cpulist}
  3898.   320C541
  3899. \end{cpulist}
  3900. This one at the moment represents the TMS320C54x family...
  3901. %%-----------
  3902. \begin{cpulist}
  3903.   TI990/4, TI990/10, TI990/12 \\
  3904. \> TMS9900, TMS9940, TMS9995, TMS99105, TMS99110
  3905. \end{cpulist}
  3906. The TMS99xx/99xxx processors are basically single chip implementations
  3907. of the TI990 minicomputers.  Some TI990 models are even based on such
  3908. a processor instead of a discrete CPU.  The individual models differ in their
  3909. instruction set (the TI990/12 has the largest one) and the presence of a
  3910. privileged mode.
  3911. %%-----------
  3912. \begin{cpulist}
  3913.   TMS70C00, TMS70C20, TMS70C40,\\
  3914. \> TMS70CT20, TMS70CT40,\\
  3915. \> TMS70C02, TMS70C42, TMS70C82,\\
  3916. \> TMS70C08, TMS70C48
  3917. \end{cpulist}
  3918. All members of this family share the same CPU core, they therefore do not
  3919. differ in their instruction set.  The differences manifest only in the
  3920. file \tty{REG7000.INC} where address ranges and peripheral addresses are
  3921. defined.  Types listed in the same row have the same amount of internal
  3922. RAM and the same on-chip peripherals, they differ only in the amount of
  3923. integrated ROM.
  3924. %%-----------
  3925. \begin{cpulist}
  3926.  370C010, 370C020, 370C030, 370C040 and 370C050
  3927. \end{cpulist}
  3928. Similar to the MCS-51 family, the different types are only used to
  3929. differentiate the peripheral equipment in \tty{STDDEF37.INC}; the
  3930. instruction set is always the same.
  3931. %%-----------
  3932. \begin{cpulist}
  3933.   MSP430 $\rightarrow$ MSP430X
  3934. \end{cpulist}
  3935. The X variant of the CPU core extends the address space from 64
  3936. KiBytes to 1 MiByte and augments the instruction set, e.g. by
  3937. prefixed to repeat instructions.
  3938. %%-----------
  3939. \begin{cpulist}
  3940.   TMS1000, TMS1100, TMS1200, TMS1300
  3941. \end{cpulist}
  3942. TMS1000 and TMS1200 each provide 1 KByte of ROM and 64 nibbles of
  3943. RAM, while TMS1100 and TMS1300 provide twice the amount of RAM
  3944. and ROM.  Furthermore, TI has defined a significantly different
  3945. default instruction set fot TMS1100 and TMS1300(\asname{} only knows the
  3946. default instruction sets!)
  3947. %%-----------
  3948. \begin{cpulist}
  3949.   IMP-16C/200, IMP-16C/300, IMP-16P/200, IMP-16P/300, IMP-16L
  3950. \end{cpulist}
  3951. The IMP-16L defines a few additional bits in its status register,
  3952. plus more branch conditions.  It supports the extended instruction
  3953. set just like the /300 variants.
  3954. %%-----------
  3955. \begin{cpulist}
  3956.   IPC-16, INS8900
  3957. \end{cpulist}
  3958. The INS8900 is just a re-implementation of PACE in a more modern
  3959. NMOS manufacturing process; there are no differences in instruction
  3960. set.
  3961. %%-----------
  3962. \begin{cpulist}
  3963.   SC/MP
  3964. \end{cpulist}
  3965. %%-----------
  3966. \begin{cpulist}
  3967.   8070
  3968. \end{cpulist}
  3969. This processor represents the whole 807x family (which consists at least
  3970. of the 8070, 8072, and 8073), which however shares identical CPU cores.
  3971. %%-----------
  3972. \begin{cpulist}
  3973.   COP87L84
  3974. \end{cpulist}
  3975. This is the only member of National Semiconductor's COP8 family that
  3976. is currently supported.  I know that the family is substantially
  3977. larger and that there are representors with differently large
  3978. instruction sets which will be added when a need occurs.  It is a
  3979. beginning, and National's documentation is quite extensive...
  3980. %%-----------
  3981. \begin{cpulist}
  3982.   COP410 $\rightarrow$ COP420 $\rightarrow$ COP440 $\rightarrow$ COP444
  3983. \end{cpulist}
  3984. The COP42x derivates offer some additional instructions, plus other
  3985. instructions have an extended operand range.
  3986. %%-----------
  3987. \begin{cpulist}
  3988.   SC14400, SC14401, SC14402, SC14404, SC14405, \\
  3989. \> SC14420, SC14421, SC14422, SC14424
  3990. \end{cpulist}
  3991. This series of DECT controllers differentiates itself by the amount of
  3992. instructions, since each of them supports different B field formats and
  3993. their architecture has been optimized over time.
  3994. %%-----------
  3995. \begin{cpulist}
  3996.   NS16008, NS32008, NS08032, NS16032, NS32016, NS32032, \\
  3997. \> NS32332, NS32CG16, NS32532
  3998. \end{cpulist}
  3999. National renamed the first-generation CPUs several times in the early
  4000. years, NS16008/NS32008/NS08032 resp. NS16032/NS32016 are the same chips.
  4001. NS32332 and NS32532 support an address space of  4 GBytes instead of 16
  4002. MBytes, and the NS32CG16 is an embedded variant with additional instructions
  4003. for bit block transfers.
  4004. %%-----------
  4005. \begin{cpulist}
  4006.   ACE1101, ACE1202
  4007. \end{cpulist}
  4008. %%-----------
  4009. \begin{cpulist}
  4010.   F3850, MK3850, \\
  4011. \> MK3870, MK3870/10, MK3870/12, "MK3870/20, MK3870/22, \\
  4012. \> MK3870/30, MK3870/32, MK3870/40, MK3870/42, \\
  4013. \> MK3872, MK3873, MK3873/10, MK3873/12, MK3873/20, \\
  4014. \> MK3873/22, MK3874, MK3875, MK3875/22, MK3875/42, \\
  4015. \> MK3876, MK38P70/02, MK38C70, MK38C70/10, \\
  4016. \> MK38C70/20, MK97400, MK97410, MK97500, MK97501, \\
  4017. \> MK97503
  4018. \end{cpulist}
  4019. This huge amount of variants partially results from the fact that
  4020. Mostek renamed some variants in the early 80s.  The new naming scheme
  4021. allows to deduce the amount of internal ROM (0 to 4 for 0 to 4 Kbytes)
  4022. and executable RAM (0 or 2 for 0 or 64 bytes) from the suffix.  3850
  4023. and MK975xx support a 64K address space, which is only 4 Kbytes for all
  4024. other variants.  P variants have an EEPROM piggyback socket for prototyping,
  4025. C variants are fabricated in CMOS technology and feature two new machine
  4026. instructions (HET and HAL). The MK3873's feature is a built-in serial port,
  4027. while the MK3875 offers a second supply voltage pin to buffer the internal
  4028. memory in standby mode.
  4029. %%-----------
  4030. \begin{cpulist}
  4031.   7800, 7801, 7802 \\
  4032. \> 78C05, 78C06 \\
  4033. \> 7807, 7808, 7809 \\
  4034. \> 7810$\rightarrow$78C10, 78C11, 78C12, 78C14, 78C17, 78C18
  4035. \end{cpulist}
  4036. $\mu$PD7800 to $\mu$PD7802 represent the ''first generation'' of the
  4037. uCOM87 family from NEC.  $\mu$PD78C05 and $\mu$PD78C06 are reduced
  4038. variants that implement only a subset of the instruction set. 7807 to
  4039. 7809 represent the uCOM87 series, whose instruction set was vastly
  4040. extended.  All $\mu$PD781x variants belong to the uCOM87AD series, which
  4041. adds an A/D converter - however, instructions for bit processing were
  4042. again removed.  \bb{NOTE:} The instruction set is in general only
  4043. partially binary upward compatible! The NMOS version $\mu$PD7810 has
  4044. no stop-mode; the respective command and the ZCM register are omitted.
  4045. \bb{CAUTION!} NMOS and CMOS version partially differ in the reset
  4046. values of some registers!
  4047. %%-----------
  4048. \begin{cpulist}
  4049.   uPD550, uPD554, uPD652, \\
  4050. \> uPD547, uPD552, uPD651, \\
  4051. \> uPD546, uPD553, uPD556, uPD557, uPD650
  4052. \end{cpulist}
  4053. These three groups of controllers belong to the $\mu$COM-45,
  4054. $\mu$COM-44, amd $\mu$COM-43 family.  The first two families
  4055. implement a subset of the $\mu$COM-43 instruction set.  Otherwise,
  4056. the chips differ by the amount of on-chip ROM and RAM.
  4057. %%-----------
  4058. \begin{cpulist}
  4059.   7500 $\leftrightarrow$ 7508
  4060. \end{cpulist}
  4061. There are two different types of CPU cores in the $\mu$PD75xx
  4062. family: the 7566 represents the the 'instruction set B', which
  4063. provides less instructions, less registers and smaller address
  4064. spaces.  The 7508 represents the 'full' instruction set A.  {\bf
  4065. CAUTION!} These instruction sets are not 100\% binary compatible!
  4066. %%-----------
  4067. \begin{cpulist}
  4068.   75402,\\
  4069. \> 75004, 75006, 75008,\\
  4070. \> 75268,\\
  4071. \> 75304, 75306, 75308, 75312, 75316,\\
  4072. \> 75328,\\
  4073. \> 75104, 75106, 75108, 75112, 75116,\\
  4074. \> 75206, 75208, 75212, 75216,\\
  4075. \> 75512, 75516
  4076. \end{cpulist}
  4077. This 'cornucopia' of processors differs only by the RAM size in one
  4078. group; the groups themselves again differ by their on-chip
  4079. peripherals on the one hand and by their instruction set's power on
  4080. the other hand.
  4081. %%-----------
  4082. \begin{cpulist}
  4083.   78070
  4084. \end{cpulist}
  4085. This is currently the only member of NEC's 78K0 family I am familiar
  4086. with.  Similar remarks like for the COP8 family apply!
  4087. %%-----------
  4088. \begin{cpulist}
  4089.   78214
  4090. \end{cpulist}
  4091. This is currently the representor of NEC's 78K2 family.
  4092. %%-----------
  4093. \begin{cpulist}
  4094.   78310
  4095. \end{cpulist}
  4096. This is currently the representor of NEC's 78K3 family.
  4097. %%-----------
  4098. \begin{cpulist}
  4099.   784026
  4100. \end{cpulist}
  4101. This is currently the representor of NEC's 78K4 family.
  4102. %%-----------
  4103. \begin{cpulist}
  4104.   7720 $\rightarrow$ 7725
  4105. \end{cpulist}
  4106. The $\mu$PD7725 offers larger address spaces and som more instructions
  4107. compared to his predecessor. {\bf CAUTION!}  The processors are not binary
  4108. compatible to each other!
  4109. %%-----------
  4110. \begin{cpulist}
  4111.   77230
  4112. \end{cpulist}
  4113. %%-----------
  4114. \begin{cpulist}
  4115.   70616
  4116. \end{cpulist}
  4117. This is currently the representor of NEC's V60 family.
  4118. %%-----------
  4119. \begin{cpulist}
  4120.   SYM53C810, SYM53C860, SYM53C815, SYM53C825, \\
  4121. \> SYM53C875, SYM53C895
  4122. \end{cpulist}
  4123. The simpler members of this family of SCSI processors lack some
  4124. instruction variants, furthermore they are different in their set of
  4125. internal registers.
  4126. %%-----------
  4127. \begin{cpulist}
  4128.   MB89190
  4129. \end{cpulist}
  4130. This processor type represents Fujitsu's F$^{2}$MC8L series...
  4131. %%-----------
  4132. \begin{cpulist}
  4133.   MB9500
  4134. \end{cpulist}
  4135. ...just like this one does it currently for the 16-bit variants from
  4136. Fujitsu!
  4137. %%-----------
  4138. \begin{cpulist}
  4139.   MSM5840, MSM5842, MSM58421, MSM58422, MSM5847
  4140. \end{cpulist}
  4141. These variants of the OLMS-40 family differ in their instruction
  4142. set and in the amount of internal program and data memory.
  4143. %%-----------
  4144. \begin{cpulist}
  4145.   MSM5054, MSM5055, MSM5056, MSM6051, MSM6052
  4146. \end{cpulist}
  4147. The as for the OLMS-40 family: differences in instruction
  4148. set and the amount of internal program and data memory.
  4149. %%-----------
  4150. \begin{cpulist}
  4151.   MN1610[ALT] $\rightarrow$ MN1613[ALT]
  4152. \end{cpulist}
  4153. In addition to its predecessor's features, the MN1613 offers a larger
  4154. address space, a floating point unit and a couple of new machine
  4155. instructions.
  4156. %%-----------
  4157. \begin{cpulist}
  4158.   RXV1, RX110, RX111, RX113, RX130, RX210,\\
  4159. \> RX21A, RX220, RX610, RX621, RX62N, RX630,\\
  4160. \> RX631 $\longrightarrow$ \\
  4161. \> RXV2, RX140, RX230, RX231, RX64M,\\
  4162. \> RX651 $\longrightarrow$ \\
  4163. \> RXV3, RX660, RX671, RX72M, RX72N
  4164. \end{cpulist}
  4165. Controllers of the RX series can coarsely be classified
  4166. into three groups or generations.  From generation to
  4167. generation (RXv1, RXv2, RXv3), new machine instructions
  4168. were added.
  4169. %%-----------
  4170. \begin{cpulist}
  4171.   PMC150, PMS150, PFS154, PMC131, PMS130, PMS131 \\
  4172. \> PMS132, PMS132B, PMS152, PMS154B, PMS154C, PFS173 \\
  4173. \> PMS133, PMS134, DF69, MCS11, PMC232, PMC234, PMC251 \\
  4174. \> PMC271,PMC884, PMS232, PMS234, PMS271
  4175. \end{cpulist}
  4176. The Padauk controllers differ in the size of the internal
  4177. (ROM/RAM) memory, the type of internal ROM (erasable or OTP),
  4178. the built-in peripherals, and their instruction set (both
  4179. extent and binary coding).
  4180. %%-----------
  4181. \begin{cpulist}
  4182.   1802 $\rightarrow$ 1804, 1805, 1806 $\rightarrow$ 1804A,
  4183. 1805A, 1806A
  4184. \end{cpulist}
  4185. 1804, 1805, and 1806 feature an instruction set that is slightly
  4186. enhanced, compared to the 'original' 1802, plus on-chip RAM and
  4187. an integrated timer.  The A variants extend the instruction set by
  4188. \tty{DSAV}, \tty{DBNZ}, and instructions for addition and
  4189. subtraction in BCD format.
  4190. %%-----------
  4191. \begin{cpulist}
  4192.   XS1
  4193. \end{cpulist}
  4194. This type represents the XCore-"family".
  4195. %%-----------
  4196. \begin{cpulist}
  4197.   1750
  4198. \end{cpulist}
  4199. MIL STD 1750 is a standard, therefore there is only one
  4200. (standard) variant...
  4201. %%-----------
  4202. \begin{cpulist}
  4203.   KENBAK
  4204. \end{cpulist}
  4205. Since there has never been a KENBAK-2, the target is simply KENBAK...
  4206. %%-----------
  4207. \begin{cpulist}
  4208.   CP-1600
  4209. \end{cpulist}
  4210. %%-----------
  4211. \begin{cpulist}
  4212.   HPNANO
  4213. \end{cpulist}
  4214. %%-----------
  4215. \begin{cpulist}
  4216.   6100 $\rightarrow$ 6120
  4217. \end{cpulist}
  4218. The IM6120 supports a larger address space (32K
  4219. instead of 4K) and additional machine instructions.
  4220. \begin{cpulist}
  4221.   SC61860
  4222. \end{cpulist}
  4223. This is the processor used in the Sharp PC-12xx...PC-15xx pocket computers.
  4224. %%-----------
  4225. \begin{cpulist}
  4226.   SC62015
  4227. \end{cpulist}
  4228. This is the processor used in the  Sharp PC-E500.
  4229.  
  4230. NONE is a special target that has not been mentioned so far.  This is the
  4231. default target if no target has been defined on the command line via
  4232. {\tt -cpu}, and if no {\tt CPU} statement has been encountered so far.
  4233. target independent pseudo instructions are still possible in this situation,
  4234. however it is not possible to create any code, neither via machine
  4235. instructions, nor via placing data in memory.  In principle, it is
  4236. also possible to explicitly select this target via {\tt -cpu} or
  4237. {\tt CPU}.  The practical use of this is however limited.
  4238.  
  4239. The \tty{CPU} instruction needs the processor type as a simple literal, a
  4240. calculation like:
  4241. \begin{verbatim}
  4242.        CPU     68010+10
  4243. \end{verbatim}
  4244. is not allowed.  Valid calls are e.g.
  4245. \begin{verbatim}
  4246.        CPU     8051
  4247. \end{verbatim}
  4248. or
  4249. \begin{verbatim}
  4250.        CPU     6800
  4251. \end{verbatim}
  4252. Regardless of the processor type currently set, the integer variable
  4253. \tty{MOMCPU} contains the current status as a hexadecimal number.  For
  4254. example, \tty{MOMCPU}=\$68010 for the 68010 or \tty{MOMCPU}=80C48H for the
  4255. 80C48.  As one cannot express all letters as hexadecimal digits (only A..F
  4256. are possible), all other letters must must be omitted in the hex notation;
  4257. for example, \tty{MOMCPU}=80H for the Z80.
  4258. You can take advantage of this feature to generate different code
  4259. depending on the processor type.  For example, the 68000 does not have a
  4260. machine instruction for a subroutine return with stack correction.  With
  4261. the variable \tty{MOMCPU} you can define a macro that uses the machine
  4262. instruction or emulates it depending on the processor type:
  4263. \begin{verbatim}
  4264. myrtd   macro   disp
  4265.        if      MOMCPU<$68010 ; emulate for 68008 & 68000
  4266.         move.l (sp),disp(sp)
  4267.         lea    disp(sp),sp
  4268.         rts
  4269.        elseif
  4270.         rtd    #disp         ; direct use on >=68010
  4271.        endif
  4272.        endm
  4273.  
  4274.  
  4275.        cpu     68010
  4276.        myrtd   12            ; results in RTD #12
  4277.  
  4278.        cpu     68000
  4279.        myrtd   12            ; results in MOVE../LEA../RTS
  4280. \end{verbatim}
  4281. As not all processor names are built only out of numbers and letters
  4282. from A..F, the full name is additionally stored in the string
  4283. variable named \tty{MOMCPUNAME}.
  4284.  
  4285. The assembler implicitly switches back to the \tty{CODE} segment when a
  4286. \tty{CPU} instruction is executed.  This is done because \tty{CODE} is the
  4287. only segment all processors support.
  4288.  
  4289. Note that 68008 is no longer the default target.  If no {\tt -cpu}
  4290. command line argument has been given, the target is set to the reserved
  4291. value \tty{NONE} up to the first \tty{CPU} statement.  Target-independent
  4292. pseudo instructions are still allowed in this situation, like defining
  4293. constants or macros.  It is however not possible to generate any code,
  4294. neither by machine instructions nor by disposing data in memory.
  4295.  
  4296. Some targets define options or variants that are so fundamental for
  4297. operation, that they have to be selected with the \tty{CPU} instruction.
  4298. Such options are appended to the argument, separated by double
  4299. colons:
  4300. \begin{verbatim}
  4301.  CPU <CPU Name>:<var1>=<val1>:<var2>=<val2>:...
  4302. \end{verbatim}
  4303. See the respective section with processor-specific hints to check whether a
  4304. certain target supports such options.
  4305.  
  4306. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4307.  
  4308. \subsection{SUPMODE, FPU, PMMU, CUSTOM}
  4309. \ttindex{SUPMODE}\ttindex{FPU}\ttindex{PMMU}\ttindex{CUSTOM}
  4310. \label{SectSUPMODE}
  4311.  
  4312. {\em
  4313. \begin{itemize}
  4314. \item{SUPMODE valid for: 680x0, NS32xxx, PDP-11, i960, TLCS-900,
  4315.      SH7000, i960, 29K, XA, PowerPC, M*Core, V60, and TMS9900}
  4316. \item{FPU valid for: 680x0, NS32xxx, 80x86}
  4317. \item{PMMU valid for: 680x0, NS32xxx}
  4318. \item{CUSTOM valid for: NS32xxx}
  4319. \end{itemize}
  4320. }
  4321.  
  4322. These three switches allow to define which parts of the instruction set
  4323. shall be disabled because the necessary preconditions are not valid for
  4324. the following piece of code.  The parameter for these instructions may be
  4325. either \tty{ON} or \tty{OFF}, the current status can be read out of a
  4326. variable which is either TRUE or FALSE.
  4327.  
  4328. The commands have the following meanings in detail:
  4329. \begin{itemize}
  4330. \item{\tty{SUPMODE}: allows or prohibits commands, for whose execution the
  4331.      processor has to be within the supervisor mode.  The status
  4332.      variable is called \tty{INSUPMODE}.}
  4333. \item{\tty{FPU}: allows or prohibits the commands of the numerical
  4334.      coprocessors 8087, NS32081/32381 resp. 68881 or 68882.  The status
  4335.      variable is called \tty{FPUAVAIL}.  For NS32xxx as target, specifying
  4336.      the explicit FPU type (\tty{NS32081}, \tty{NS32181}, \tty{NS32381},
  4337.      or \tty{NS32580}) is also possible, to enable or disable the additional
  4338.      registers and instructions.}
  4339. \item{\tty{PMMU}: allows or prohibits the commands of the memory
  4340.      management unit 68851 resp. of  the built-in MMU of the 68030.
  4341.      \bb{CAUTION!} The 68030-MMU supports only a relatively small subset
  4342.      of the 68851 instructions.  This is controlled via the \tty{FULLPMMU}
  4343.      statement. The status variable is called \tty{PMMUAVAIL}. For NS32xxx
  4344.      as target, specifying the explicit MMU type as target (\tty{NS32082},
  4345.      \tty{NS32381}, or \tty{NS32352}) is also possible, to enable access to
  4346.      the MMU-type-specific register set.}
  4347. \item{\tty{CUSTOM}: allows or prohibits the commands reserved for custom
  4348.      slave processors.}
  4349. \end{itemize}
  4350. The usage of of instructions prohibited in this manner will generate a
  4351. warning at \tty{SUPMODE}, at \tty{PMMU} and \tty{FPU} a real error
  4352. message.
  4353.  
  4354. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4355.  
  4356. \subsection{ACCMODE}
  4357. \ttindex{ACCMODE}
  4358.  
  4359. {\em
  4360. \begin{itemize}
  4361. \item{valid for: VAX}
  4362. \end{itemize}
  4363. }
  4364.  
  4365. The VAX not only knows a user and supervisor mode, it supports four privilege
  4366. levels of this type.  Going from more to less rights, these are named Kernel,
  4367. Executive, Supervisor, and User.  The {\tt ACCMODE} instruction informs the
  4368. assembler about the access mode the following code is executed within.  Not
  4369. all machine instructions are allowed in all modes.  Valid arguments are either
  4370. the mode names mentioned before, or a number between zero (kernel mode) to
  4371. three (user mode).  As default, user mode is assumed, and the current setting
  4372. (as numeric value) may be read from a symbol of same name.
  4373.  
  4374. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4375.  
  4376. \subsection{CIS, EIS, FIS and FP11}
  4377. \ttindex{CIS}\ttindex{EIS}\ttindex{FIS}\ttindex{FP11}
  4378.  
  4379. {\em
  4380. \begin{itemize}
  4381. \item{valid for: PDP-11}
  4382. \end{itemize}
  4383. }
  4384.  
  4385. These statements enable or disable the availibility of certain PDP-11
  4386. instruction set extensions.  For one of these statements to be available,
  4387. the respective instructions must not be part of the machine's basic
  4388. instruction set, and there must have been an upgrade option to add them.
  4389. In detail:
  4390.  
  4391. \begin{itemize}
  4392. \item{{\tt CIS}: ,,Commercial Instruction Set'', i.e. instructions to
  4393.      operate on packed and non-packed BCD numbers with variable length.
  4394.      They were available as an option on the LSI-11 and the PDP-11/44.}
  4395. \item{{\tt EIS}: The instructions {\tt MUL, DIV, ASH} und {\tt ASHC},
  4396.      which were not part of the base instruction set on older or
  4397.      smaller PDP-11 systems.  They were available as an option on the
  4398.      LSI-11 resp. the PDP-11/35 and PDP-11/40.}
  4399. \item{{\tt FIS}: Stack oriented instructions implementing the basic
  4400.      mathematic operations on floating point numbers in F format (32 bits).
  4401.      They were available as an option on the LSI-11 resp. the PDP-11/35
  4402.      and PDP-11/40.}
  4403. \item{{\tt FP11}: Full floating point support with separate FPU registers
  4404.      in F and D format (32/64 bits).}
  4405. \end{itemize}
  4406.  
  4407. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4408.  
  4409. \subsection{FULLPMMU}
  4410. \ttindex{FULLPMMU}
  4411.  
  4412. {\em valid for: 680x0}
  4413.  
  4414. Motorola integrated the MMU into the processor starting with the 68030, but
  4415. the built-in FPU is equipped only with a relatively small subset of the
  4416. 68851 instruction set.  \asname{} will therefore disable all extended MMU
  4417. instructions when the target processor is 68030 or higher.  It is however
  4418. possible that the internal MMU has been disabled in a 68030-based system
  4419. and the processor operates with an external 68851.  One can the use a
  4420. \tty{FULLPMMU ON} to tell \asname{} that the complete MMU instruction set is
  4421. allowed.  Vice versa, one may use a \tty{FULLPMMU OFF} to disable all
  4422. additional instruction in spite of a 68020 target platform to assure that
  4423. portable code is written.  The switch between full and reduced instruction
  4424. set may be done as often as needed, and the current setting may be read
  4425. from a symbol with the same name.  \bb{CAUTION!} The \tty{CPU} instruction
  4426. implicitly sets or resets this switch when its argument is a 68xxx
  4427. processor!  \tty{FULLPMMU} therefore has to be written after the \tty{CPU}
  4428. instruction!
  4429.  
  4430. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4431.  
  4432. \subsection{PADDING}
  4433. \ttindex{PADDING}
  4434.  
  4435. {\em valid for: 680x0, 68xx, M*Core, XA, H8, SH7000, MSP430(X), TMS9900,\\
  4436.      ST7/STM8, AVR (only if code segment granularity is 8 bits)}
  4437.  
  4438. Various processor families have a requirement that objects of more than
  4439. one byte length must be located on a n even address.  Aside from data
  4440. objects, this may also include instruction words.  For instance, word
  4441. accesses to an odd address result in an exception on a 68000, while other
  4442. processors like the H8 force the lowest address bit to zero.
  4443.  
  4444. The \tty{PADDING} instruction allows to activate a mechanism that tries to
  4445. avoid such misalignments.  If the situation arises that an instruction
  4446. word, or a data object of 16 bits or more (created e.g. via \tty{DC}) would
  4447. be stored on an odd address, a padding byte is automatically inserted before.
  4448. Such a padding byte is displayed in the listing in a separate line that
  4449. contains the remark
  4450. \begin{verbatim}
  4451. <padding>
  4452. \end{verbatim}
  4453. If the source line also contained a label, the label still points to the
  4454. address of the code or data object, i.e. right behind the pad byte.  The same
  4455. is true for a label in a source line immediately before, as long as this
  4456. line {\em} only holds the label and no other instruction.  So, in the
  4457. follwing example:
  4458. \begin{verbatim}
  4459.       padding  on
  4460.       org      $1000
  4461.  
  4462.       dc.b     1
  4463. adr1:  nop
  4464.  
  4465.       dc.b     1
  4466. adr2:
  4467.       nop
  4468.  
  4469.       dc.b     1
  4470. adr3:  equ      *
  4471.       nop
  4472. \end{verbatim}
  4473. the labels \tty{adr1} and \tty{adr2} hold the addresses of the respective
  4474. \tty{NOP} instructions, which were made even by inserting a pad byte.
  4475. \tty{adr3} in contrast holds the address of the pad byte preceding the
  4476. third \tty{NOP}.
  4477.  
  4478. Similar to the previous instructions, the argument to \tty{PADDING} may be
  4479. either \tty{ON} or \tty{OFF}, and the current setting may be read from a
  4480. symbol with the same name.  \tty{PADDING} is by default only enabled for
  4481. the 680x0 family, it has to be turned on explicitly for all other families.
  4482.  
  4483. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4484.  
  4485. \subsection{PACKING}
  4486. \ttindex{PACKING}\label{SectPACKING}
  4487.  
  4488. {\em valid for: 56000, AVR, TMS3203x/4x, TMS3206x, MN1610, CP1600,
  4489.     $\mu$PD7720/7725, $\mu$PD77230}
  4490.  
  4491. In some way, {\tt PACKING} is similar to {\tt PADDING}, it just has a
  4492. somewhat opposite effect: While {\tt PADDING} extends the disposed data to
  4493. get full words and keep a possible alignment, {\tt PACKING} squeezes
  4494. several values into a single word.  This makes sense for the AVR's code
  4495. segment since the CPU has a special instruction ({\tt LPM}) to access
  4496. single bytes within a 16-bit word.  In case this option is turned on
  4497. (argument {\tt ON}), two byte values are packed into a single word by {\tt
  4498. DATA}, similar to the single characters of string arguments.  The value
  4499. range of course reduces to -128...+255.  If this option is turned off
  4500. (argument {\tt OFF}), each integer argument obtains its own word and may
  4501. take values from -32768...+65535.
  4502.  
  4503. This distinction is only made for integer arguments of {\tt DATA}, strings
  4504. will always be packed..  Keep further in mind that packing of values only
  4505. works within the arguments of a {\tt DATA} statement; if one has
  4506. subsequent {\tt DATA} statements, there will still be half-filled words
  4507. when the argument count is odd!
  4508.  
  4509. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4510.  
  4511. \subsection{WARNRELATIVE}
  4512.  
  4513. {\em valid for:  Zx80}
  4514.  
  4515. This switch instructs the assembler whether to issue warnings when a relative jump
  4516. instead of an absolute one would be possible.  The default is OFF respectively
  4517. what was defined via the command line arguments {\tt -wrelative} and {\tt -wno-relative}.
  4518.  
  4519. The current setting may be read from a symbol of same name.
  4520.  
  4521. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4522.  
  4523. \subsection{MAXMODE}
  4524. \ttindex{MAXMODE}
  4525.  
  4526. {\em valid for: TLCS-900, H8}
  4527.  
  4528. The processors of the TLCS-900-family are able to work in 2 modes, the
  4529. minimum and maximum mode.  Depending on the actual mode, the execution
  4530. environment and the assembler are a little bit different. Along with this
  4531. instruction and the parameter \tty{ON} or \tty{OFF}, \asname{} is informed that the
  4532. following code will run in maximum resp. minimum mode.  The actual setting
  4533. can be read from the variable \tty{INMAXMODE}.  Presetting is \tty{OFF},
  4534. i.e. minimum mode.
  4535.  
  4536. Similarly, one uses this instruction to tell \asname{} in H8 mode whether the
  4537. address space is 64K or 16 Mbytes.  This setting is always \tty{OFF} for
  4538. the 'small' 300 version and cannot be changed.
  4539.  
  4540. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4541.  
  4542. \subsection{EXTMODE and LWORDMODE}
  4543. \ttindex{EXTMODE}\ttindex{LWORDMODE}
  4544.  
  4545. {\em valid for: Z380}
  4546.  
  4547. The Z380 may operate in altogether 4 modes, which are the result of
  4548. setting two flags: The XM flag rules whether the processor shall operate
  4549. wit an address space of 64 Kbytes or 4 Gbytes and it may only be set to 1
  4550. (after a reset, it is set to 0 for compatibility with the Z80).  The LW
  4551. flag in turn rules whether word operations shall work with a word size of
  4552. 16 or 32 bits.  The setting of these two flags influences range checks of
  4553. constants and addresses, which is why one has to tell \asname{} the setting of
  4554. these two flags via these instructions.  The default assumption is that
  4555. both flags are 0, the current setting (\tty{ON} or \tty{OFF}) may be read
  4556. from the predefined symbols \tty{INEXTMODE} resp. \tty{INLWORDMODE.}
  4557.  
  4558. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4559.  
  4560. \subsection{SRCMODE}
  4561. \ttindex{SRCMDE}
  4562.  
  4563. {\em valid for: MCS-251}
  4564.  
  4565. Intel substantially extended the 8051 instruction set with the 80C251, but
  4566. unfortunately there was only a single free opcode for all these new
  4567. instructions.  To avoid a processor that will be eternally crippled by a
  4568. prefix, Intel provided two operating modes: the binary and the source
  4569. mode.  The new processor is fully binary compatible to the 8051 in binary
  4570. mode, all new instructions require the free opcode as prefix.  In source
  4571. mode, the new instructions exchange their places in the code tables with
  4572. the corresponding 8051 instructions, which in turn then need a prefix.
  4573. One has to inform \asname{} whether the processor operates in source mode
  4574. (\tty{ON}) or binary mode (\tty{OFF}) to enable \asname{} to add prefixes when
  4575. required.  The current setting may be read from the variable
  4576. \tty{INSRCMODE}.  The default is \tty{OFF}.
  4577.  
  4578. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4579. \subsection{PLAINBASE}
  4580. \ttindex{PLAINBASE}\label{SectPLAINBASE}
  4581.  
  4582. {\em valid for: 6809}
  4583.  
  4584. Historically, \asname{} allows to omit an empty first argument on indexed
  4585. address expressions.  An
  4586. \begin{verbatim}
  4587.  lda  x
  4588. \end{verbatim}
  4589. for instance was equivalent to
  4590. \begin{verbatim}
  4591.  lda  ,x
  4592. \end{verbatim}
  4593. Though meant as a feature, this wa occasionally rather seen as a bug.  Current
  4594. versios therefore no longer allow to omit an empty index argument and will
  4595. instead emit a wrong argument count error message.  If this feature is still
  4596. desired or needed for existing code, it may be enabled via a
  4597. \begin{verbatim}
  4598.  plainbase on
  4599. \end{verbatim}
  4600. statement.  The current setting may be read from a symbol of same name.
  4601.  
  4602. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4603.  
  4604. \subsection{BIGENDIAN}
  4605. \ttindex{ENDIAN}\ttindex{BIGENDIAN}\label{SectBIGENDIAN}
  4606.  
  4607. {\em valid for: MCS-51/251, PowerPC, SC/MP, 2650, NS32000}
  4608.  
  4609. Intel broke with its own principles when the 8051 series was designed: in
  4610. contrast to all traditions, the processor uses big-endian ordering for all
  4611. multi-byte values!  While this was not a big deal for MCS-51 processors
  4612. (the processor could access memory only in 8-bit portions, so everyone was
  4613. free to use whichever endianess one wanted), it may be a problem for the
  4614. 251 as it can fetch whole (long-)words from memory and expects the MSB to
  4615. be first.  As this is not the way of constant disposal earlier versions of
  4616. \asname{} used, one can use this instruction to toggle between big and
  4617. little endian mode for the instructions \tty{DB, DW, DD, DQ, DT,} and
  4618. \tty{DO}.  \tty{BIGENDIAN OFF} (the default) puts the LSB first into
  4619. memory as it used to be on earlier versions of \asname{}, \tty{BIGENDIAN ON}
  4620. engages the big-endian mode compatible to the MCS-251.  One may of course
  4621. change this setting as often as one wants; the current setting can be read
  4622. from the symbol with the same name.
  4623.  
  4624. The Renesas RX as target also supports a selectable endianess.  For
  4625. compatibility to the original assembler, the statement is named \tty{ENDIAN}
  4626. and accepts \tty{LITTLE} or \tty{BIG} as argument.
  4627.  
  4628. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4629.  
  4630. \subsection{WRAPMODE}
  4631. \ttindex{WRAPMODE}
  4632.  
  4633. {\em valid for: Atmel AVR}
  4634.  
  4635. After this switch has been set to {\tt ON}, \asname{} will assume that the
  4636. processor's program counter does not have the full length of 16 bits given
  4637. by the architecture, but instead a length that is exactly sufficient to
  4638. address the internal ROM.  For example, in case of the AT90S8515, this
  4639. means 12 bits, corresponding to 4 Kwords or 8 Kbytes.  This assumption
  4640. allows relative branches from the ROM's beginning to the end and vice
  4641. versa which would result in an out-of-branch error when using strict
  4642. arithmetics.  Here, they work because the carry bits resulting from the
  4643. target address computation are discarded.  Assure that the target
  4644. processor you are using works in the outlined way before you enable this
  4645. option!  In case of the abovementioned AT90S8515, this option is even
  4646. necessary because it is the only way to perform a direct jump through
  4647. the complete address space...
  4648.  
  4649. This switch is set to {\tt OFF} by default, and its current setting may be
  4650. read from a symbol with same name.
  4651.  
  4652. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4653.  
  4654. \subsection{PANEL}
  4655. \ttindex{PANEL}
  4656.  
  4657. {\em valid for: IM61x0}
  4658.  
  4659. This switch is used to inform the assembler whether the following code is
  4660. executet with a set or cleared {\em Control Panel Flip-Flop}.  A couple
  4661. of {\tt IOT} instructions are only allowed if the flip-flop has a certain
  4662. state.  Usage of these instructions in the other state will be reported
  4663. as an error by the assembler.
  4664.  
  4665. The current setting may be read from the symbol {\tt INPANEL}.
  4666.  
  4667. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4668.  
  4669. \subsection{SEGMENT}
  4670. \ttindex{SEGMENT}
  4671. \label{SEGMENT}
  4672.  
  4673. {\em valid for: all processors}
  4674.  
  4675. Some microcontrollers and signal processors know various address ranges,
  4676. which do not overlap with each other and require also different
  4677. instructions and addressing modes for access.  To manage these ones also,
  4678. the assembler provides various program counters, you can switch among
  4679. them to and from by the use of the \tty{SEGMENT} instruction.  For subroutines
  4680. included with \tty{INCLUDE}, this e.g. allows to define data used by the
  4681. main program or subroutines near to the place they are used.  In detail,
  4682. the following segments with the following names are supported:
  4683. \begin{itemize}
  4684. \item{\tty{CODE}: program code;}
  4685. \item{\tty{DATA}: directly addressable data (including SFRs);}
  4686. \item{\tty{XDATA}: data in externally connected RAM or
  4687.      X-addressing space of the DSP56xxx or ROM data for the $\mu$PD772x;}
  4688. \item{\tty{YDATA}: Y-addressing space of the DSP56xxx;}
  4689. \item{\tty{IDATA}: indirectly addressable (internal) data; }
  4690. \item{\tty{BITDATA}: the part of the 8051-internal RAM that is bitwise
  4691.      addressable;}
  4692. \item{\tty{IO}: I/O-address range;}
  4693. \item{\tty{REG}: register bank of the ST9;}
  4694. \item{\tty{ROMDATA}: constant ROM of the NEC signal processors;}
  4695. \item{\tty{EEDATA}: built-in EEPROM.}
  4696. \end{itemize}
  4697. See also section \ref{SectORG} (\tty{ORG}) for detailed information about
  4698. address ranges and initial values of the segments. Depending on the
  4699. processor family, not all segment types will be permitted.
  4700.  
  4701. The bit segment is managed as if it would be a byte segment, i.e. the
  4702. addresses will be incremented by 1 per bit.
  4703.  
  4704. Labels get the same type as attribute as the segment that was active
  4705. when the label was defined.  So the assembler has a limited ability
  4706. to check whether you access symbols of a certain segment with wrong
  4707. instructions.  In such cases the assembler issues a warning.
  4708.  
  4709. Example:
  4710. \begin{verbatim}
  4711.        CPU     8051    ; MCS-51-code
  4712.  
  4713.        segment code    ; test code
  4714.  
  4715.        setb    flag    ; no warning
  4716.        setb    var     ; warning : wrong segment
  4717.  
  4718.        segment data
  4719.  
  4720. var     db      ?
  4721.  
  4722.        segment bitdata
  4723.  
  4724. flag    db      ?
  4725. \end{verbatim}
  4726.  
  4727. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4728.  
  4729. \subsection{PHASE and DEPHASE}
  4730. \ttindex{PHASE}\ttindex{DEPHASE}
  4731.  
  4732. {\em valid for: all processors}
  4733.  
  4734. For some applications (especially on Z80 systems), the code must be moved
  4735. to another address range before execution.  If the assembler didn't know
  4736. about this, it would align all labels to the load address (not the start
  4737. address).  The programmer is then forced to write jumps within this area
  4738. either independent of location or has to add the offset at each symbol
  4739. manually.  The first one is not possible for some processors, the last one
  4740. is extremely error-prone.  With the commands \tty{PHASE} and
  4741. \tty{DEPHASE}, it is possible to inform the assembler at which address the
  4742. code will really be executed on the target system:
  4743. \begin{verbatim}
  4744.        phase   <address>
  4745. \end{verbatim}
  4746. informs the assembler that the following code shall be executed at the
  4747. specified address.  The assembler calculates thereupon the difference to
  4748. the real program counter and adds this difference for the following
  4749. operations:
  4750. \begin{itemize}
  4751. \item{address values in the listing}
  4752. \item{filing of label values}
  4753. \item{program counter references in relative jumps and address expressions}
  4754. \item{readout of the program counter via the symbols * or \$}
  4755. \end{itemize}
  4756. By using the instruction
  4757. \begin{verbatim}
  4758.        DEPHASE
  4759. \end{verbatim}
  4760. , this ''shifting'' is reverted to the value previous to the most
  4761. recent \tty{PHASE} instruction.  \tty{PHASE} und \tty{DEPHASE} may be used
  4762. in a nested manner.
  4763. \par
  4764. The assembler keeps phase values for all defined segments, although
  4765. this instruction pair only makes real sense in the code segment.
  4766.  
  4767. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4768.  
  4769. \subsection{SAVE and RESTORE}
  4770. \ttindex{SAVE}\ttindex{RESTORE}
  4771. \ttindex{.SAVE}\ttindex{.RESTORE}
  4772. \ttindex{SAVEENV}\ttindex{RESTOREENV}
  4773.  
  4774. {\em valid for: all processors}
  4775.  
  4776. The command \tty{SAVE} forces the assembler to push the contents of
  4777. following variables onto an internal stack:
  4778. \begin{itemize}
  4779. \item{currently selected processor type (set by \tty{CPU});}
  4780. \item{currently active memory area (set by \tty{SEGMENT});}
  4781. \item{the flag whether listing is switched on or off (set by \tty{LISTING});}
  4782. \item{the flags that define which part of expanded macros shall be
  4783.      printed in the assembly listing (set by
  4784.      \tty{/MACEXP\_DFT/MACEXP\_OVR}).}
  4785. \item{currently active character translation table (set by
  4786.      \tty{CODEPAGE}).}
  4787. \end{itemize}
  4788. The counterpart \tty{RESTORE} pops the values saved last from this stack.
  4789. These two commands were primarily designed for include files, to change
  4790. the above mentioned variables in any way inside of these files, without
  4791. loosing their original content.  This may be helpful e.g. in include files
  4792. with own, fully debugged subroutines, to switch the listing generation
  4793. off:
  4794. \begin{verbatim}
  4795.        SAVE            ; save old status
  4796.  
  4797.        LISTING OFF     ; save paper
  4798.  
  4799.        .               ; the actual code
  4800.        .
  4801.  
  4802.        RESTORE         ; restore
  4803. \end{verbatim}
  4804. In opposite to a simple \tty{LISTING OFF .. ON}-pair, the correct status
  4805. will be restored, in case the listing generation was switched off already
  4806. before.
  4807.  
  4808. The assembler checks if the number of \tty{SAVE}-and
  4809. \tty{RESTORE}-commands corresponds and issues error messages in the
  4810. following cases:
  4811. \begin{itemize}
  4812. \item{\tty{RESTORE}, but the internal stack is empty;}
  4813. \item{the stack not empty at the end of a pass.}
  4814. \end{itemize}
  4815. In case the currently used target has machine instructions named \tty{SAVE} or
  4816. \tty{RESTORE}, this functionality may be reached via \tty{SAVEENV} resp.
  4817. \tty{RESTOREENV}.  As an alternative, it is always possible to explicitly invoke
  4818. the pseudo instructions by prepending a period (\tty{.SAVE} resp. \tty{.RESTORE}).
  4819.  
  4820. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  4821.  
  4822. \subsection{ASSUME}
  4823. \ttindex{ASSUME}
  4824.  
  4825. {\em valid for: various}
  4826.  
  4827. This instruction allows to tell \asname{} the current setting of certain
  4828. registers whose contents cannot be described with a simple \tty{ON} or
  4829. \tty{OFF}.  These are typically registers that influence addressing modes
  4830. and whose contents are important to know for \asname{} in order to generate
  4831. correct addressing.  It is important to note that \tty{ASSUME} only
  4832. informs \asname{} about these, \bb{no} machine code is generated that actually
  4833. loads these values into the appropriate registers!
  4834.  
  4835. A value defined with \tty{ASSUME} can be queried or integrated
  4836. into expressions via the built-in function \tty{ASSUMEDVAL}.
  4837. This is the case for all architectures listed in the following
  4838. sub-sections except for the 8086.
  4839.  
  4840. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  4841.  
  4842. \subsubsection{65CE02}
  4843.  
  4844. The 65CE02 features a a register named 'B' that is used to set the 'base page'.
  4845. In comparison to the original 6502, this allows the programmer to place the
  4846. memory page addressable with short (8 bit) addresses anywhere in the 64K address
  4847. space.  This register is set to zero after a reset, so the 65CE02 behaves like
  4848. its predecessor.  A base page at zero is also the default assumption of the
  4849. assembler.  It may be informed about its actual contents via a \tty{ASSUME B:xx}
  4850. statement.  Addresses located in this page will then automatically be addressed
  4851. via short addressing modes.
  4852.  
  4853. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  4854.  
  4855. \subsubsection{6809}
  4856.  
  4857. In contrast to its 'predecessors' like the 6800 and 6502, the position of
  4858. the direct page, i.e. the page of memory that can be reached with
  4859. single-byte addresses, can be set freely.  This is done via the 'direct
  4860. page register' that sets the page number.  One has to assign a
  4861. corresponding value to this register via \tty{ASSUME} is the contents are
  4862. different from the default of 0, otherwise wrong addresses will be
  4863. generated!
  4864.  
  4865. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  4866.  
  4867. \subsubsection{68HC11K4}
  4868.  
  4869. Also for the HC11, the designers finally weren't able to avoid banking, to
  4870. address more than 64 Kbytes with only 16
  4871. address lines.  The registers {\tt MMSIZ}, {\tt MMWBR}, {\tt MM1CR}, and
  4872. {\tt MM2CR} control whether and how the additional 512K address ranges are
  4873. mapped into the CPU's address space.  \asname{} initially assumes the reset
  4874. state of these registers, i.e. all are set to \$00 and windowing is
  4875. disabled.
  4876.  
  4877. Furthermore, the settings of the registers {\tt CONFIG}, {\tt INIT}, and
  4878. {\tt INIT2} may be specified.  This enables the assembler to deduce the mapping
  4879. of I/O registers, internal RAM and EEPROM into CPU address space, which
  4880. has priority over mapping of memory via windowing.
  4881.  
  4882. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  4883.  
  4884. \subsubsection{68HC12X}
  4885.  
  4886. Similar to its cousin without the appended 'X', the HC12X supports a short
  4887. direct addressing mode.  In this case however, it can be used to address
  4888. more than just the first 256 bytes of the address space.  The {\tt DIRECT}
  4889. register specifices which 256 byte page of the address space is addressed
  4890. by this addressing mode.  {\tt ASSUME} is used to tell \asname{} the current
  4891. value of this register, so it is able to automatically select the most
  4892. efficient address ing mode when absolute addresses are used.  The default
  4893. is 0, which corresponds to the reset state.
  4894.  
  4895. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  4896.  
  4897. \subsubsection{68HC16}
  4898.  
  4899. The 68HC16 employs a set of bank registers to address a space of 1
  4900. Mbyte with its registers that are only 16 bits wide.  These registers
  4901. supply the upper 4 bits.  Of these, the EK register is responsible
  4902. for absolute data accesses (not jumps!).  \asname{} checks for each absolute
  4903. address whether the upper 4 bits of the address are equal to the
  4904. value of EK specified via \tty{ASSUME}.  \asname{} issues a warning if they
  4905. differ.  The default for EK is 0.
  4906.  
  4907. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  4908.  
  4909. \subsubsection{H8/500}
  4910.  
  4911. In maximum mode, the extended address space of these processors is
  4912. addressed via a couple of bank registers.  They carry the names DP
  4913. (registers from 0..3, absolute addresses), EP (register 4 and 5), and TP
  4914. (stack).  \asname{} needs the current value of DP to check if absolute addresses
  4915. are within the currently addressable bank; the other two registers are
  4916. only used for indirect addressing and can therefore not be monitored; it
  4917. is a question of personal taste whether one specifies their values or not.
  4918. The BR register is in contrast important because it rules which 256-byte
  4919. page may be accessed with short addresses.  It is common for all registers
  4920. that \asname{} does not assume \bb{any} default value for them as they are
  4921. undefined after a CPU reset.  Everyone who wants to use absolute addresses
  4922. must therefore assign values to at least DR and DP!
  4923.  
  4924. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  4925.  
  4926. \subsubsection{MELPS740}
  4927.  
  4928. Microcontrollers of this series know a ''special page'' addressing mode
  4929. for the \tty{JSR} instruction that allows a shorter coding for jumps into
  4930. the last page of on-chip ROM.  The size of this ROM depends of course
  4931. on the exact processor type, and there are more derivatives than it
  4932. would be meaningful to offer via the CPU instruction...we therefore
  4933. have to rely on \tty{ASSUME} to define the address of this page, e.g.
  4934. \begin{verbatim}
  4935.        ASSUME  SP:$1f
  4936. \end{verbatim}
  4937. in case the internal ROM is 8K.
  4938.  
  4939. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  4940.  
  4941. \subsubsection{MELPS7700/65816}
  4942.  
  4943. These processors contain a lot of registers whose contents \asname{} has to know
  4944. in order to generate correct machine code.  These are the registers
  4945. in question:
  4946. \begin{center}\begin{tabular}{|l|l|l|l|}
  4947. \hline
  4948. name   & function             & value range   & default \\
  4949. \hline
  4950. \hline
  4951. DT/DBR & data bank            & 0-\$ff        &  0 \\
  4952. PG/PBR & code Bank            & 0-\$ff        &  0 \\
  4953. DPR    & directly addr. page  & 0-\$ffff      &  0 \\
  4954. X      & index register width & 0 or 1        &  0 \\
  4955. M      & accumulator width    & 0 or 1        &  0 \\
  4956. \hline
  4957. \end{tabular}\end{center}
  4958. \par
  4959. To avoid endless repetitions, see section \ref{MELPS7700Spec} for
  4960. instructions how to use these registers.  The handling is otherwise
  4961. similar to the 8086, i.e. multiple values may be set with one instruction
  4962. and no code is generated that actually loads the registers with the given
  4963. values.  This is again up to the programmer!
  4964.  
  4965. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  4966.  
  4967. \subsubsection{MCS-196/296}
  4968.  
  4969. Starting with the 80196, all processors of the MCS-96 family have a
  4970. register 'WSR' that allows to map memory areas from the extended
  4971. internal RAM or the SFR range into areas of the register file which
  4972. may then be accessed with short addresses.  If one informs \asname{} about
  4973. the value of the WSR register, it can automatically find out whether
  4974. an absolute address can be addressed with a single-byte address via
  4975. windowing; consequently, long addresses will be automatically generated
  4976. for registers covered by windowing.  The 80296 contains an additional
  4977. register WSR1 to allow simultaneous mapping of two memory areas into
  4978. the register file.  In case it is possible to address a memory cell
  4979. via both areas, \asname{} will always choose the way via WSR!
  4980.  
  4981. For indirect addressing, displacements may be either short (8 bits,
  4982. -128 to +127) or long (16 bits).  The assembler will automatically
  4983. use the shortest possible encoding for a given displacement.  It
  4984. is however possible to enforce a 16-bit coding by prefixing the
  4985. displacement argument with a bigger sign ((\verb!>!).  Similarly,
  4986. absolute addresses in the area from 0ff80h to 0ffffh may be reached
  4987. via a short offset relative to the "null register".
  4988.  
  4989. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  4990.  
  4991. \subsubsection{8086}
  4992.  
  4993. The 8086 is able to address data from all segments in all
  4994. instructions, but it however needs so-called ''segment prefixes'' if
  4995. another segment register than DS shall be used.  In addition it is
  4996. possible that the DS register is adjusted to another segment, e.g. to
  4997. address data in the code segment for longer parts of the program.  As
  4998. \asname{} cannot analyze the code's meaning, it has to informed via this
  4999. instruction to what segments the segment registers point at the
  5000. moment, e.g.:
  5001. \begin{verbatim}
  5002.        ASSUME  CS:CODE, DS:DATA    .
  5003. \end{verbatim}
  5004. It is possible to assign assumptions to all four segment registers in
  5005. this way.  This instruction produces \bb{no} code, so the program itself
  5006. has to do the actual load of the registers with the values.
  5007.  
  5008. The usage of this instruction has on the one hand the result that \asname{} is
  5009. able to automatically put ahead prefixes at sporadic accesses into the
  5010. code segment, or on the other hand, one can inform \asname{} that the DS-register
  5011. was modified and you can save explicit \tty{CS:}-instructions.
  5012.  
  5013. Valid arguments behind the colon are \tty{CODE}, \tty{DATA} and
  5014. \tty{NOTHING}.  The latter value informs \asname{} that a segment register
  5015. contains no usable value (for \asname{}).  The following values are
  5016. preinitialized:
  5017. \begin{verbatim}
  5018.  CS:CODE, DS:DATA, ES:NOTHING, SS:NOTHING
  5019. \end{verbatim}
  5020.  
  5021. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5022.  
  5023. \subsubsection{Z180}
  5024.  
  5025. The Z180 contains a built-in MMU whicht maps the CPU core's ''logical''
  5026. address space of 64 KBytes to a physical address space of 512 KBytes.  The
  5027. precise mappig is defined via the the registers {\tt CBAR}, {\tt CBR} and
  5028. {\tt BBR}.  Opposed to the 68HC11K4, the assembler will not perform any
  5029. automatic translations of physical to logical addresses; only an internal
  5030. mapping table is kept.  It is however possible to access this table via
  5031. the {\tt phys2cpu()} function.
  5032.  
  5033. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5034.  
  5035. \subsubsection{eZ80}
  5036.  
  5037. The eZ80 mode can operate in two modes:
  5038. \begin{itemize}
  5039. \item{In Z80 mode, the BC, DE, HL, IX, IY, and SP registers are 16 bits wide,
  5040.      and only the 64K page defined by the MBASE register is addressable.
  5041.      For instructions with an absolute address or a non-8-bit immediate value
  5042.      as argument, two bytes are fetched.}
  5043. \item{In ADL mode, the mentioned registers are 24 bits wide, and the whole
  5044.      16 MByte address space can be addressed.  For instructions with an absolute
  5045.      address or a non-8-bit immediate value, three bytes are fetched.}
  5046. \end{itemize}
  5047. Since instruction encoding and range checking depends on the operating mode,
  5048. the assembler needs to know which mode the CPU currently uses.  By using
  5049. {\tt ASSUME} to set {\tt ADL} either to 0 or 1, the assembler is told about
  5050. the default operating mode, i.e. the mode if no suffixes are given.  Furthermore,
  5051. the assembler can be told about the current value of MBASE (0 to 0ff hex) as
  5052. well.  The default assumption for both values is zero, same as to the values
  5053. set in the CPU after a reset.
  5054.      
  5055.  
  5056. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5057.  
  5058. \subsubsection{XA}
  5059.  
  5060. The XA family has a data address space of 16 Mbytes, a process however
  5061. can always address within a 64K segment only that is given by the DS
  5062. register.  One has to inform \asname{} about the current value of this
  5063. register in order to enable it to check accesses to absolute
  5064. addresses.
  5065.  
  5066. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5067.  
  5068. \subsubsection{29K}
  5069.  
  5070. The processors of the 29K family feature a register RBP that allows
  5071. to protect banks of 16 registers against access from user mode.  The
  5072. corresponding bit has to be set to achieve the protection.  \tty{ASSUME}
  5073. allows to tell \asname{} which value RBP currently contains.  \asname{} can warn
  5074. this way in case a try to access protected registers from user mode
  5075. is made.
  5076.  
  5077. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5078.  
  5079. \subsubsection{80C166/167}
  5080.  
  5081. Though none of the 80C166/167's registers is longer than sixteen bits,
  5082. this processor has 18/24 address lines and can therefore address up
  5083. to 256Kbytes/16Mbytes.  To resolve this contradiction, it neither
  5084. uses the well-known (and ill-famed) Intel method of segmentation nor
  5085. does it have inflexible bank registers...no, it uses paging!  To accomplish
  5086. this, the logical address space of 64 Kbytes is split into 4 pages of
  5087. 16 Kbytes, and for each page there is a page register (named
  5088. DPP0..DPP3) that rules which of the 16/1024 physical pages shall be
  5089. mapped to this logical page.  \asname{} always tries to present the address
  5090. space with a size of 256Kbytes/16MBytes in the sight of the
  5091. programmer, i.e. the physical page is taken for absolute accesses and
  5092. the setting of bits 14/15 of the logical address is deduced.  If no
  5093. page register fits, a warning is issued.  \asname{} assumes by default that
  5094. the four registers linearly map the first 64 Kbytes of memory, in the
  5095. following style:
  5096. \begin{verbatim}
  5097.        ASSUME  DPP0:0,DPP1:1,DPP2:2,DPP3:3
  5098. \end{verbatim}
  5099. The 80C167 knows some additional instructions that can override the
  5100. page registers' function.  The chapter with processor-specific hints
  5101. describes how these instructions influence the address generation.
  5102. \par
  5103. Some machine instructions have a shortened form that can be used if
  5104. the argument is within a certain range:
  5105. \begin{itemize}
  5106. \item{\verb!MOV Rn,#<0..15>!}
  5107. \item{\verb!ADD/ADDC/SUB/SUBC/CMP/XOR/AND/OR Rn, #<0..7>!}
  5108. \item{\verb!LOOP Rn,#<0..15>!}
  5109. \end{itemize}
  5110. The assembler automatically uses to the shorter coding if possible.
  5111. If one wants to enforce the longer coding, one may place a 'bigger'
  5112. character right before the expression (behind the double cross character!).
  5113. Vice versa, a 'smaller' character can be used to assure the shorter
  5114. coding is used.  In case the operand does not fulfill the range
  5115. restrictions for the shorter coding, an error is generated.  This syntax
  5116. may also be used for branches and calls which may either have a short
  5117. displacement or a long absolute argument.
  5118.  
  5119. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5120.  
  5121. \subsubsection{TLCS-47}
  5122.  
  5123. The direct data address space of these processors (it makes no
  5124. difference whether you address directly or via the HL register) has a
  5125. size of only 256 nibbles.  Because the ''better'' family members have
  5126. up to 1024 nibbles of RAM on chip, Toshiba was forced to introduce a
  5127. banking mechanism via the DMB register.  \asname{} manages the data segment
  5128. as a continuous addressing space and checks at any direct addressing
  5129. if the address is in the currently active bank.  The bank \asname{}
  5130. currently expects can be set by means of
  5131. \begin{verbatim}
  5132.        ASSUME  DMB:<0..3>
  5133. \end{verbatim}
  5134. The default value is 0.
  5135.  
  5136. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5137.  
  5138. \subsubsection{IPC-16/INS8900}
  5139. \label{PACEAssume}
  5140.  
  5141. The processor provides an input pin named {\tt BPS} to select which address
  5142. range shall be directly addressable: either the first 256 words, or both
  5143. the lowest and topmost 128 words.  The first variant is the default, an
  5144. {\tt ASSUME BPS:1} switches to the second variant.
  5145.  
  5146. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5147.  
  5148. \subsubsection{ST6}
  5149. \label{ST6Assume}
  5150.  
  5151. The microcontrollers of the ST62 family are able to map a part (64 bytes)
  5152. of the code area into the data area, e.g. to load constants from the ROM.
  5153. This means also that at one moment only one part of the ROM can be
  5154. addressed.  A special register rules which part it is.  \asname{} cannot check
  5155. the contents of this register directly, but it can be informed by this
  5156. instruction that a new value has been assigned to the register.  \asname{} then
  5157. can test and warn if necessary, in case addresses of the code segment are
  5158. accessed, which are not located in the ''announced'' window.  If, for
  5159. example, the variable \tty{VARI} has the value 456h, so
  5160. \begin{verbatim}
  5161.        ASSUME  ROMBASE:VARI>>6
  5162. \end{verbatim}
  5163. sets the \asname{}-internal variable to 11h, and an access to \tty{VARI}
  5164. generates an access to address 56h in the data segment.
  5165.  
  5166. It is possible to assign a simple \tty{NOTHING} instead of a value, e.g.
  5167. if the bank register is used temporarily as a memory cell.  This value is
  5168. also the default.
  5169.  
  5170. The program counter of these controller only has a width of 12 bits.  This
  5171. means that some sort of banking scheme had to be introduced if a device
  5172. includes more than 4 KBytes of program memory.  The banking scheme splits
  5173. both proram space and program memory in pages of 2 KBytes.  Page one of the
  5174. program space always accesses page one of program memory.  The \tty{PRPR}
  5175. register present on such devices selects which page of program memory is
  5176. accessed via addresses 000h to 7ffh of program space.  As an initial
  5177. approcimation, \asname{} regards program space to be linear and of the size of
  5178. program memory.  If a jump or call from page one is made to code in one
  5179. of the other pages, it checks whether the assumed contents of the \tty{PRPR}
  5180. register match the destination address.  If a jump or call is done from
  5181. one of the other pages to an address outside of page one, it checks whether
  5182. the destination address is within the same page.  {\bf IMPORTANT}: The
  5183. program counter itself is only 12 bits wide.  It is therefore not possible
  5184. to jump from one page to another one, without an intermediate step of
  5185. jumping back to page one.  Changing the \tty{PRPR} register while operating
  5186. outside of page one would result in ''pulling out'' the code from under
  5187. one's feet.
  5188.  
  5189. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5190.  
  5191. \subsubsection{ST9}
  5192.  
  5193. The ST9 family uses exactly the same instructions to address code and
  5194. data area.  It depends on the setting of the flag register's DP flag
  5195. which address space is referenced.  To enable \asname{} to check if one
  5196. works with symbols from the correct address space (this of course
  5197. \bb{only} works with absolute accesses!), one has to inform \asname{} whether the
  5198. DP flag is currently 0 (code) or 1 (data).  The initial value of this
  5199. assumption is 0.
  5200.  
  5201. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5202.  
  5203. \subsubsection{78K2}
  5204.  
  5205. 78K2 is an 8/16 bit architecture, which has later been extended to a
  5206. one-megabyte addres space via banking.  Banking is realized with the
  5207. registers PM6 (normal case) resp. P6 (alternate case with \verb!&! as
  5208. prefix) that supply the missing upper four address bits.  At least for
  5209. absolute addresses, \asname{} can check whether the current, linear 20-bit
  5210. address is within the given 64K window.
  5211.  
  5212. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5213.  
  5214. \subsubsection{78K3}
  5215.  
  5216. Processors witrh a 78K3 core have register banks that consist of
  5217. 16 registers.  These registers may be used via their numbers
  5218. (\tty{R0} to \tty{R15}) or their symbolic names (\tty{X=R0, A=R1,
  5219. C=R2, B=R3, VPL=R8, VPH=R9, UPL=R10, UPH=R11, E=R12,
  5220. D=R13, L=R14, H=R15}).  The processor core has a register select
  5221. bit (\tty{RSS}) to switch the mapping of A/X and B/C from R0..R3
  5222. to R4..R7.  This is mainly important for instructions that
  5223. implicitly use one of these registers (i.e. instruction that do
  5224. not encode the register number in the machine code).  However, it
  5225. is also possible to inform the assembler about the changed
  5226. mapping via a
  5227.  
  5228. \begin{verbatim}
  5229.  assume rss:1
  5230. \end{verbatim}
  5231.  
  5232. The assmebler will then insert the alternate register numbers
  5233. into machine instructions that explicitly encode the register
  5234. numbers.  Vice versa, \tty{R5} will be treated like \tty{A} instead
  5235. of \tty{R1} in the source code.
  5236.  
  5237. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5238.  
  5239. \subsubsection{78K4}
  5240.  
  5241. 78K4 was designed as an 'upgrade path' from 78K3, which is why
  5242. this processor core contains the same RSS bit to control the
  5243. mapping of registers AX and BC (though NEC discourages use of it
  5244. in new code).
  5245.  
  5246. Aside from many new instructins and addressing modes, the most
  5247. significant extension is the larger address space of 16 MBytes,
  5248. of which only the first MByte may be used for program code.  The
  5249. CPU-internal RAM and all special function registers may be
  5250. positioned either at the top of the first MByte or the top of the
  5251. first 64 KByte page.  Choice is made via the \tty{LOCATION}
  5252. machine instruction that either takes a 0 or 15 as argument.
  5253. Together with remapping RAM and SFRs, the processor also switches
  5254. the address ranges that may be reached with short (8 bit)
  5255. addresses.  Parallel to using \tty{LOCATION}, one has to inform
  5256. the assembler about this setting via a \tty{ASSUME LOCATION:..}
  5257. statement.  It will then use short addressing for the proper
  5258. ranges.  The assembler will assume a default of 0 for LOCATION.
  5259.  
  5260. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5261.  
  5262. \subsubsection{320C3x/C4x}
  5263.  
  5264. As all instruction words of this processor family are only 32 bits
  5265. long (of which only 16 bits were reserved for absolute addresses),
  5266. the missing upper 8/16 bits have to be added from the DP register.  It
  5267. is however still possible to specify a full 24/32-bit address when
  5268. addressing, \asname{} will check then whether the upper 8 bits are equal to
  5269. the DP register's assumed values.  \tty{ASSUME} is different to the
  5270. \tty{LDP} instruction in the sense that one cannot specify an arbitrary
  5271. address out of the bank in question, one has to extract the upper bits by
  5272. hand:
  5273. \begin{verbatim}
  5274.        ldp     @addr
  5275.        assume  dp:addr>>16
  5276.        .
  5277.        .
  5278.        ldi     @addr,r2
  5279. \end{verbatim}
  5280.  
  5281. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5282.  
  5283. \subsubsection{uPD78(C)10}
  5284.  
  5285. These processors have a register (V) that allows to move the ''zero
  5286. page'', i.e. page of memory that is addressable by just one byte,
  5287. freely in the address space, within page limits.  By reasons of
  5288. comforts you don't want to work with expressions such as
  5289. \begin{verbatim}
  5290.        inrw    Lo(counter)
  5291. \end{verbatim}
  5292. so \asname{} takes over this job, but only under the premise that it is informed
  5293. via the \tty{ASSUME}-command about the contents of the V register.  If an
  5294. instruction with short addressing is used, it will be checked if the upper
  5295. half of the address expression corresponds to the expected content.  A
  5296. warning will be issued if both do not match.
  5297.  
  5298. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5299.  
  5300. \subsubsection{75K0}
  5301.  
  5302. As the whole address space of 12 bits could not be addressed even by
  5303. the help of register pairs (8 bits), NEC had to introduce banking
  5304. (like many others too...): the upper 4 address bits are fetched from
  5305. the MBS register (which can be assigned values from 0 to 15 by the
  5306. \tty{ASSUME} instruction), which however will only be regarded if the MBE
  5307. flag has been set to 1.  If it is 0 (default), the lowest and highest
  5308. 128 nibbles of the address space can be reached without banking.  The
  5309. \tty{ASSUME} instruction is undefined for the 75402 as it contains neither
  5310. a MBE flag nor an MBS register; the initial values cannot be changed
  5311. therefore.
  5312.  
  5313. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5314.  
  5315. \subsubsection{F$^2$MC16L}
  5316.  
  5317. Similar to many other families of microcontrollers, this family suffers
  5318. somewhat from its designers miserliness: registers of only 16 bits width
  5319. are faced with an address space of 24 bits.  Once again, bank registers
  5320. had to fill the gap.  In detail, these are PCB for the progam code, DTB
  5321. for all data accesses, ADB for indirect accesses via RW2/RW6, and SSB/USB
  5322. for the stacks.  They may all take values from 0 to 255 and are by default
  5323. assumed to be 0, with the exception of 0ffh for PCB.
  5324.  
  5325. Furthermore, a DPR register exists that specifies which memory page within
  5326. the 64K bank given by DTB may be reached with 8 bit addresses.  The
  5327. default for DPR is 1, resulting in a default page of 0001xxh when one
  5328. takes DTB's default into account.
  5329.  
  5330. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5331.  
  5332. \subsubsection{MN1613}
  5333.  
  5334. The MN1613 is an extension of an architecture with 16 bit addresses.  The
  5335. address extension is done by a set of "segment registers" (CSBR, SSBR, TSR0, and
  5336. TSR1), each of which is four bits wide.  The contents of a segment register,
  5337. left-shifted by 14 bits, is added to the 16 bit addresses.  This way, a process may
  5338. access a memory window of 64 KWords within the address space of 256 KWords. The
  5339. assembler uses segment register values reported via \tty{ASSUME} to warn whether
  5340. an absolute address is outside the window defined by the used segment register.
  5341. If the address is within the window, it will compute the correc t16-bit offset.
  5342. Naturally, this cannot be done when indirect addressing is used.
  5343.  
  5344. %%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  5345.  
  5346. \subsubsection{IM61x0}
  5347.  
  5348. These micro processors implement the instruction set of a PDP/8 and therefore
  5349. fundamentally support an address space of 4 KWords. Banking allows to extend this
  5350. address to eight ''fields' of 4 KWords. Addressing of data and jumps are principally
  5351. only possible within the same field, with one exception: The IB register allows
  5352. to perform a jump to another 4K field.  It provides the upper three bits of the
  5353. 15 bit target address, if IB has been set to a value unequal to \tty{NOTHING} via
  5354. \tty{ASSUME}.
  5355.  
  5356. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5357.  
  5358. \subsection{CKPT}
  5359. \ttindex{CKPT}
  5360.  
  5361. {\em valid for: TI990/12}
  5362.  
  5363. Type 12 instructions require a {\em checkpoint register} for execution.  This
  5364. register may either be specified explicitly as fourth argument, or a default for
  5365. all following code may be given via this instruction.  If neither a \tty{CKPT}
  5366. instruction nor an explicit checkpoint register was used, an error
  5367. is reported.  The default of no default register may be restored by using
  5368. {\tt NOTHING} as argument to \tty{CKPT}.
  5369.  
  5370. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5371.  
  5372. \subsection{EMULATED}
  5373.  
  5374. {\em valid for: 29K}
  5375.  
  5376. AMD defined the 29000's series exception handling for undefined
  5377. instructions in a way that there is a separate exception vector for
  5378. each instruction.  This allows to extend the instruction set of a
  5379. smaller member of this family by a software emulation.  To avoid that
  5380. \asname{} quarrels about these instructions as being undefined, the
  5381. \tty{EMULATED} instruction allows to tell \asname{} that certain instructions are
  5382. allowed in this case.  The check if the currently set processors knows the
  5383. instruction is then skipped.  For example, if one has written a module
  5384. that supports 32-bit IEEE numbers and the processor does not have a FPU,
  5385. one writes
  5386. \begin{verbatim}
  5387.        EMULATED FADD,FSUB,FMUL,FDIV
  5388.        EMULATED FEQ,FGE,FGT,SQRT,CLASS
  5389. \end{verbatim}
  5390.  
  5391. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5392.  
  5393. \subsection{BRANCHEXT}
  5394. \ttindex{BRANCHEXT}
  5395.  
  5396. {\em valid for: XA}
  5397.  
  5398. {\tt BRANCHEXT} with either \tty{ON} or \tty{OFF} as argument tells \asname{}
  5399. whether short branches that are only available with an 8-bit displacement
  5400. shall automatically be 'extended', for example by replacing a single
  5401. instruction like
  5402. \begin{verbatim}
  5403.        bne     target
  5404. \end{verbatim}
  5405. with a longer sequence of same functionality, in case the branc target is
  5406. out of reach for the instruction's displacement.  For example, the
  5407. replacement sequence for {\tt bne} would be
  5408. \begin{verbatim}
  5409.        beq     skip
  5410.        jmp     target
  5411. skip:
  5412. \end{verbatim}
  5413. In case there is no fitting 'opposite' for an instruction, the sequence
  5414. may become even longer, e.g. for {\tt jbc}:
  5415. \begin{verbatim}
  5416.        jbc     dobr
  5417.        bra     skip
  5418. dobr:   jmp     target
  5419. skip:
  5420. \end{verbatim}
  5421. This feature however has the side effect that there is no unambigious
  5422. assignment between machine and assembly code any more.  Furthermore,
  5423. additional passes may be the result if there are forward branches.  One
  5424. should therefore use this feature with caution!
  5425.  
  5426. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5427.  
  5428. \subsection{Z80SYNTAX}
  5429. \ttindex{Z80SYNTAX}
  5430.  
  5431. {\em G"ultigkeit: 8008, 8080/8085, $\mu$PD78xx}
  5432.  
  5433. With \tty{ON} as argument, one can optionally write machine
  5434. assembler instructions in the form Zilog defined them for the Z80.
  5435. For instance, you simply use \tty{LD} with self-explaining
  5436. operands instead of \tty{MVI, LXI, MOV, STA, LDA, SHLD, LHLD,
  5437. LDAX, STAX} or \tty{SPHL}.
  5438.  
  5439. Since some mnemonics have a different meaning in 8008/8080 and Z80
  5440. syntax, it is not possible to program in 'Z80 style' all the
  5441. time, unless the '8080 syntax' is turned off entirely by using
  5442. \tty{EXCLUSIVE} as argument.  The details of this operation mode
  5443. can be looked up in section \ref{8080Spec}.
  5444.  
  5445. A built-in symbol of same name allows to query the operation mode.
  5446. The mapping is \tty{0=OFF}, \tty{1=ON}, and \tty{2=EXCLUSIVE}.
  5447.  
  5448. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5449.  
  5450. \subsection{EXPECT and ENDEXPECT}
  5451. \ttindex{EXPECT}
  5452. \ttindex{ENDEXPECT}
  5453.  
  5454. This pair of instructions may be used to frame a piece of code that
  5455. is {\em expected} to trigger one or more error or warning messages.
  5456. If the errors or warnings (identified by their numbers, see chapter
  5457. \ref{ChapErrMess}) do occur, they are suppressed and assembly continues
  5458. without any error (naturally, without creating code at the erroneous
  5459. places).  However, if warnings or errors that were expected do not
  5460. occur, \tty{ENDEXPECT} will emit errors about them.  The main usage
  5461. scenario of these instructions are the self tests in the tests/
  5462. subdirectory.  For instance, one may check this way if range
  5463. checking of operands works as expected:
  5464. \begin{verbatim}
  5465.       cpu      68000
  5466.       expect   1320     ; immediate shift only for 1..8
  5467.       lsl.l    #10,d0
  5468.       endexpect
  5469. \end{verbatim}
  5470.  
  5471.  
  5472. %%---------------------------------------------------------------------------
  5473.  
  5474. \section{Data Definitions}
  5475.  
  5476. The instructions described in this section partially overlap in their
  5477. functionality, but each processor family defines other names for the
  5478. same function.  To stay compatible with the standard assemblers, this
  5479. way of implementation was chosen.
  5480.  
  5481. If not explicitly mentioned otherwise, all instructions for data
  5482. deposition (not those for reservation of memory!) allow an arbitrary
  5483. number of parameters which are being processed from left to right.
  5484.  
  5485. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5486.  
  5487. \subsection{DC[.Size]}
  5488. \ttindex{DC}
  5489.  
  5490. {\em valid for: 680x0, M*Core, 68xx, H8, SH7x00, DSP56xxx, XA,
  5491.  ST7/STM8, MN161x, IM61x0, CP-3F, SC61860}
  5492.  
  5493. This instruction places one or several constants of the type
  5494. specified by the attribute into memory.  The attributes are the same ones as
  5495. defined in section \ref{AttrTypes}, and there is additionally the
  5496. possibility for byte constants to place string constants in memory, like
  5497. \begin{verbatim}
  5498. String  dc.B "Hello world!\0"
  5499. \end{verbatim}
  5500. The parameter count may be between 1 and 20.  A repeat count enclosed
  5501. in brackets may additionally be prefixed to each parameter; for
  5502. example, one can for example fill the area up to the next page
  5503. boundary with zeroes with a statement like
  5504. \begin{verbatim}
  5505.        dc.b    [(*+255)&$ffffff00-*]0
  5506. \end{verbatim}
  5507. \bb{CAUTION!}  This function easily allows to reach the limit of 1 Kbyte
  5508. of generated code per line!
  5509.  
  5510. The assembler can automatically add another byte of data in case the byte sum
  5511. should become odd, to keep the word alignment.  This behaviour may be
  5512. turned on and off via the \tty{PADDING} instruction.
  5513.  
  5514. Decimal floating point numbers stored with this instruction (\tty{DC.P...})
  5515. can cover the whole range of extended precision, one however has to
  5516. pay attention to the detail that the coprocessors currently available
  5517. from Motorola (68881/68882) ignore the thousands digit of the
  5518. exponent at the read of such constants!
  5519.  
  5520. The default attribute is \tty{W}, that means 16-bit-integer numbers.
  5521.  
  5522. For the DSP56xxx, the data type is fixed to integer numbers (an attribute is
  5523. therefore neither necessary nor allowed), which may be in the range
  5524. of -8M up to 16M-1.  String constants are also allowed, whereby three characters
  5525. are packed into each word.
  5526.  
  5527. Opposed to the standard Motorola assembler, it is also valid to reserve
  5528. memory space with this statement, by using a question mark as operand.
  5529. This is an extension added by some third-party suppliers for 68K
  5530. assemblers, similar to what Intel assemblers provide.  However, it should
  5531. be clear that usage of this feature may lead to portability problems.
  5532. Furthermore, question marks as operands must not be mixed with 'normal'
  5533. constants in a single statement.
  5534.  
  5535. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5536.  
  5537. \subsection{DS[.Size]}
  5538. \ttindex{DS}
  5539.  
  5540. {\em valid for: 680x0, M*Core, 68xx, H8, SH7x00, DSP56xxx, XA, ST7/STM8,
  5541.  MN161x, IM61x0, CP-3F, PPS-4, SC61860}
  5542.  
  5543. On the one hand, this instruction enables to reserve memory space for
  5544. the specified count of numbers of the type given by the attribute.
  5545. Therefore,
  5546. \begin{verbatim}
  5547.        DS.B    20
  5548. \end{verbatim}
  5549. for example reserves 20 bytes of memory, but
  5550. \begin{verbatim}
  5551.        DS.X    20
  5552. \end{verbatim}
  5553. reserves 240 bytes!
  5554.  
  5555. The other purpose is the alignment of the program counter which is
  5556. achieved by a count specification of 0.  In this way, with a
  5557. \begin{verbatim}
  5558.        DS.W    0  ,
  5559. \end{verbatim}
  5560. the program counter will be rounded up to the next even address, with
  5561. a
  5562. \begin{verbatim}
  5563.        DS.D 0
  5564. \end{verbatim}
  5565. in contrast to the next double word boundary.  Memory cells possibly
  5566. staying unused thereby are neither zeroed nor filled with NOPs, they
  5567. simply stay undefined.
  5568.  
  5569. The default for the operand length is - as usual - \tty{W}, i.e. 16 bits.
  5570.  
  5571. For the 56xxx, the operand length is fixed to words (of 24 bit),
  5572. attributes therefore do not exist just as in the case of \tty{DC}.
  5573.  
  5574. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5575.  
  5576. \subsection{BLKB, BLKW, BLKL, BLKD}
  5577. \ttindex{BLKB}\ttindex{BLKW}\ttindex{BLKL}\ttindex{BLKD}
  5578.  
  5579. {\em valid for: Renesas RX}
  5580.  
  5581. These statements are used to reserve memory on Renesas RX. The total amount
  5582. of memory reserved is the instruction's argument times the operand size
  5583. given by the instruction (1 byte for \tty{BLKB}, 2 bytes for \tty{BLKW}, 4
  5584. bytes for \tty{BLKL}, and 8 bytes for \tty{BLKD}).
  5585.  
  5586. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5587.  
  5588. \subsection{DN,DB,DW,DD,DQ,DT, and DO}
  5589. \ttindex{DN}\ttindex{DB}\ttindex{DW}\ttindex{DD}
  5590. \ttindex{DQ}\ttindex{DT}\ttindex{DO}
  5591.  
  5592. {\em\begin{tabbing}
  5593. valid for: \= Intel (except for 4004/4040), Zilog, Toshiba,\\
  5594.           \> NEC, TMS370, Siemens, AMD, MELPS7700/65816,\\
  5595.           \> M16(C), National, ST9, Atmel, TMS70Cxx, TMS1000,\\
  5596.           \> Signetics, $\mu$PD77230, Fairchild, Intersil,\\
  5597.           \> XS1, SC62015
  5598. \end{tabbing}}
  5599.  
  5600. These commands are - one could say - the Intel counterpart to \tty{DS} and
  5601. \tty{DC}, and as expected, their logic is a little bit different: First,
  5602. the specification of the operand length is moved into the mnemonic:
  5603. \begin{itemize}
  5604. \item{\tty{DN}: 4-bit integer}
  5605. \item{\tty{DB}: 8-bit byte or ASCII string similar to \tty{DC.B}}
  5606. \item{\tty{DW}: 16-bit integer or half precision floating point}
  5607. \item{\tty{DD}: 32-bit integer or single precision floating point}
  5608. \item{\tty{DQ}: 64-bit integer or double precision floating point}
  5609. \item{\tty{DT}: packed BCD integer or extended precision floating point (80 bits)}
  5610. \item{\tty{DO}: quad precision floating point (128 bits)}
  5611. \end{itemize}
  5612. Second, the distinction between constant definition and memory
  5613. reservation is done by the operand.  A reservation of memory is
  5614. marked by a \tty{?} :
  5615. \begin{verbatim}
  5616.        db      ?       ; reserves a byte
  5617.        dw      ?,?     ; reserves memory for 2 words (=4 byte)
  5618.        dd      -1      ; places the constant -1 (FFFFFFFFH) !
  5619. \end{verbatim}
  5620. Reserved memory and constant definitions \bb{must not} be mixed within one
  5621. instruction:
  5622. \begin{verbatim}
  5623.        db      "hello",?       ; --> error message
  5624. \end{verbatim}
  5625. Additionally, the \tty{DUP} Operator permits the repeated placing of
  5626. constant sequences or the reservation of whole memory blocks:
  5627. \begin{verbatim}
  5628.        db      3 dup (1,2)     ; --> 1 2 1 2 1 2
  5629.        dw      20 dup (?)      ; reserves 40 bytes of memory
  5630. \end{verbatim}
  5631. As you can see, the \tty{DUP}-argument must be enclosed in parentheses,
  5632. which is also why it may consist of several components, that may
  5633. themselves be \tty{DUP}s...the stuff therefore works recursively.
  5634.  
  5635. \tty{DUP} is however also a place where one can get in touch with another
  5636. limit of the assembler: a maximum of 1024 bytes of code or data may be
  5637. generated in one line.  This is not valid for the reservation of memory,
  5638. only for the definition of constant arrays!
  5639.  
  5640. The \tty{DUP} operator only gets recognized if it is itself not enclosed
  5641. in parentheses, and if there is a non-empty argument to its left.  This
  5642. way, it is possible to use a symbol of same name as argument.
  5643.  
  5644. \tty{DB} and \tty{DW} on 65xx and 68xx targets additionally support
  5645. the 'Motorola variant' of the \tty{DUP} operator, namely a prefix
  5646. that holds the number of repetitions in square brackets.
  5647.  
  5648. Several platforms define pseudo instructions with same functionality,
  5649. but different names:
  5650. \begin{itemize}
  5651. \ttindex{DEFB}\ttindex{DEFW}
  5652. \item{In order to be compatible to the M80, \tty{DEFB/DEFW} may be used
  5653.      instead of \tty{DB/DW} in Z80-mode.}
  5654. \ttindex{BYTE}\ttindex{WORD}\ttindex{ADDR}\ttindex{ADDRW}
  5655. \item{\tty{BYTE/ADDR} resp. \tty{WORD/ADDRW} in COP4/8 mode are an
  5656.      alias for \tty{DB} resp. \tty{DW}, with the pairs differing in byte
  5657.      order: instructions defined by National for address storage use big
  5658.      endian, \tty{BYTE} resp. \tty{WORD} in contrast use little endian.}
  5659. \ttindex{BYTE}\ttindex{WORD}
  5660. \item{\tty{BYTE} resp. \tty{WORD} on PDP-11, VAX and WD16 work like \tty{DB}
  5661.      resp. \tty{DW}, however only accept integer arguments.}
  5662. \item{\tty{LWORD} resp. \tty{QUAD} on VAXwork like \tty{DD} resp. \tty{DQ},
  5663.      however only accept integer arguments.}
  5664. \ttindex{BYTE}\ttindex{WORD}\ttindex{LWORD}\ttindex{QUAD}
  5665. \ttindex{FLOAT}\ttindex{DOUBLE}
  5666. \item{The Renesas RX target provides:
  5667.      \begin{itemize}
  5668.      \item{\tty{BYTE} (like \tty{DB})}
  5669.      \item{\tty{WORD} (like \tty{DW}, only integer arguments)}
  5670.      \item{\tty{LWORD} (like \tty{DD}, only integer arguments)}
  5671.      \item{\tty{FLOAT} (like \tty{DD}, only floating point arguments)}
  5672.      \item{\tty{DOUBLE} (like \tty{DQ}, only floating point arguments)}
  5673.      \end{itemize}}
  5674. \end{itemize}
  5675.  
  5676. If \tty{DB} is used in an address space that is not byte addressable (like
  5677. the Atmel AVR's \tty{CODE} segment), bytes are packed in pairs into 16 bit
  5678. words, according to the endianess given by the architecture: for little
  5679. endian, the LSB is filled first.  If the total number of bytes is odd, one
  5680. half of the last word remains unused, just like the argument list had been
  5681. padded.  It will also not be used if another \tty{DB} immediately follows
  5682. in source code.  The analogous is true for \tty{DN}, just with the difference
  5683. that two or four nibbles are packet into a byte or 16 bit word.
  5684.  
  5685. The NEC 77230 is special with its \tty{DW} instruction: It more works like
  5686. the \tty{DATA} statement of its smaller brothers, but apart from string
  5687. and integer arguments, it also accepts floating point values (and stores
  5688. them in the processor's proprietary 32-bit format). There is {\em no}
  5689. \tty{DUP} operator!
  5690.  
  5691. When floating point constants are stored, they cannot have a larger
  5692. precision or range than the floating point type used on the host system.
  5693. For instance, if the common 64 bit IEEE 754 format is used on the host side,
  5694. the value range is limited to roughly +/-$1.8*10^{308}$ (see the variable \tty{FLOATMAX}),
  5695. and the lowest two resp. eight bytes of \tty{DT} resp. \tty{DO} are filled
  5696. with zeros.
  5697.  
  5698. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5699.  
  5700. \subsection{FLT2, FLT3, FLT4}
  5701. \ttindex{FLT2}\ttindex{FLT3}\ttindex{FLT4}
  5702.  
  5703. {\em\begin{tabbing}
  5704. valid for: \= PDP-11 (\tty{FLT2, FLT4}),\\
  5705.           \> WD16 (\tty{FLT3})
  5706. \end{tabbing}}
  5707.  
  5708. \tty{FLT2} and \tty{FLT4} are similar in function to \tty{DD} bzw. \tty{DQ}.
  5709. However, they only store floating point numbers (in DEC's own F and D formats)
  5710. in memory.  The WD16 uses an own, 48 bits (three machine words) long format.
  5711. Floating point numbers in this format can be stored in memory with the \tty{FLT3}
  5712. instruction.
  5713.  
  5714. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5715.  
  5716. \subsection{x\_FLOATING}
  5717. \ttindex{F\_FLOATING}\ttindex{FLOAT}
  5718. \ttindex{D\_FLOATING}\ttindex{DOUBLE}
  5719. \ttindex{G\_FLOATING}
  5720. \ttindex{H\_FLOATING}
  5721.  
  5722. {\em valid for: VAX}
  5723.  
  5724. These instructions store floating point constants in DEC format in memory.
  5725. {\tt x} represents one of the four supported formats (F, D, G and H). {\tt FLOAT}
  5726. is an alias for {\tt F\_FLOATING}, and {\tt DOUBLE} is an alias for {\tt D\_FLOATING}.
  5727. Otherwise, these instructions work like \tty{DD} and \tty{DQ}.
  5728.  
  5729. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5730.  
  5731. \subsection{DS, DS8}
  5732. \ttindex{DS}
  5733. \ttindex{DS8}
  5734.  
  5735. {\em\begin{tabbing}
  5736. valid for: \= Intel, Zilog, Toshiba, NEC, TMS370, Siemens, AMD, \\
  5737.           \> M16(C), National, ST9, TMS7000, TMS1000, Intersil, \\
  5738.           \> 6502, 68xx \\
  5739. \end{tabbing}}
  5740.  
  5741. With this instruction, you can reserve a memory area:
  5742. \begin{verbatim}
  5743.        DS      <count>
  5744. \end{verbatim}
  5745. It is an abbreviation of
  5746. \begin{verbatim}
  5747.        DB      <count> DUP (?)
  5748. \end{verbatim}
  5749. Although this could easily be made by a macro, some people grown up
  5750. with Motorola CPUs (Hi Michael!) suggest \tty{DS} to be a built-in
  5751. instruction...I hope they are satisfied now \tty{;-)}
  5752.  
  5753. {\tt DS8} is defined as an alias for {\tt DS} on the National SC14xxx.
  5754. Beware that the code memory of these processors is organized in words of
  5755. 16 bits, it is therefore impossible to reserve individual bytes.  In case
  5756. the argument of {\tt DS} is odd, it will be rounded up to the next even
  5757. number.
  5758.  
  5759. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5760.  
  5761. \subsection{BLKx}
  5762. \ttindex{BLKB}\ttindex{BLKW}\ttindex{BLKL}\ttindex{BLKQ}\ttindex{BLKO}
  5763. \ttindex{BLKF}\ttindex{BLKD}\ttindex{BLKG}\ttindex{BLKH}
  5764.  
  5765. {\em valid for: VAX}
  5766.  
  5767. These instructions reserve storage space for the given number of elements,
  5768. with the element size coded into the instruction's last character.  Therefore,
  5769. the size of the reserved area in bytes is equal to the element count for {\tt BLKB},
  5770. double the count for {\tt BLKW}, and sixteen times the count for {\tt BLKO} and
  5771. {\tt BLKH}.
  5772.  
  5773. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5774.  
  5775. \subsection{BYT or FCB}
  5776. \ttindex{BYT}\ttindex{FCB}
  5777.  
  5778. {\em valid for: 6502, 68xx, SC61860}
  5779.  
  5780. By this instruction, byte constants or ASCII strings are placed in
  5781. 65xx/68xx-mode, it therefore corresponds to \tty{DC.B} on the 68000 or
  5782. \tty{DB} on Intel (which ias also allowed).  Similarly to \tty{DC}, a
  5783. repetition factor enclosed in brackets ([..]) may be prepended to every
  5784. single parameter.
  5785.  
  5786. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5787.  
  5788. \subsection{BYTE}
  5789. \ttindex{BYTE}
  5790.  
  5791. {\em valid for: ST6, 320C2(0)x, 320C5x, MSP, TMS9900, CP-1600}
  5792.  
  5793. Ditto.  Note that when in 320C2(0)x/5x mode, the assembler assumes that
  5794. a label on the left side of this instruction has no type, i.e. it
  5795. belongs to no address space. This behaviour is explained in the
  5796. processor-specific hints.
  5797.  
  5798. The \tty{PADDING} instruction allows to set whether odd counts of bytes
  5799. shall be padded with a zero byte in MSP/TMS9900 mode.
  5800.  
  5801. The operation of {\tt BYTE} on CP-1600 is somewhat different: the 16-bit
  5802. integer arguments are stored byte-wise in two consecutive words of memory
  5803. (LSB first).  If individual 8-bit values shall be stored in memor (optionally
  5804. packed), use the {\tt TEXT} instruction!
  5805.  
  5806. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5807.  
  5808. \subsection{DC8}
  5809. \ttindex{DC8}
  5810.  
  5811. {\em valid for: SC144xx}
  5812.  
  5813. This statement is an alias for {\tt DB}, i.e. it may be used to dump byte
  5814. constants or strings to memory.
  5815.  
  5816. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5817.  
  5818. \subsection{ADR or FDB}
  5819. \ttindex{ADR}\ttindex{FDB}
  5820.  
  5821. {\em valid for: 6502, 68xx, SC61860}
  5822.  
  5823. \tty{ADR} resp. \tty{FDB} stores word constants when in 65xx/68xx mode.
  5824. It is therefore the equivalent to \tty{DC.W} on the 68000 or \tty{DW} on
  5825. Intel platforms (which is also allowed).  Similarly to \tty{DC}, a repetition
  5826. factor enclosed in brackets ([..]) may be prepended to every single parameter.
  5827.  
  5828. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5829.  
  5830. \subsection{DDB}
  5831. \ttindex{DDB}
  5832.  
  5833. {\em valid for: 6502, MELPS-7700}
  5834.  
  5835. This instructions works similar to \tty{ADR}, just with the difference that
  5836. the 16 bit values are stored in big endian order.
  5837.  
  5838. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5839.  
  5840. \subsection{DCM}
  5841. \ttindex{DCM}
  5842.  
  5843. {\em valid for: 6502}
  5844.  
  5845. This instructions allows to dispose floating point constants in memory, in
  5846. the format that described in \cite{AppleFloat}: An exponent of eight bits
  5847. and a mantissa of 24 bits in two's complement representation, stored in
  5848. big-endian order.
  5849.  
  5850. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5851.  
  5852. \subsection{WORD}
  5853. \ttindex{WORD}
  5854.  
  5855. {\em valid for: ST6, i960, 320C2(0)x, 320C3x/C4x/C5x, MSP, CP-1600,\\
  5856.      IMP-16, IPC-16}
  5857.  
  5858. If assembling for the 320C3x/C4x or i960, this command stores 32-bit words,
  5859. 16-bit words for the other families.  Note that when in 320C2(0)x/5x mode,
  5860. the assembler assumes that a label on the left side of this instruction
  5861. has no type, i.e. it belongs to no address space.  This behaviour is
  5862. explained at the discussion on processor-specific hints.
  5863.  
  5864. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5865.  
  5866. \subsection{DW16}
  5867. \ttindex{DW16}
  5868.  
  5869. {\em valid for: SC144xx}
  5870.  
  5871. This instruction is for SC144xx targets a way to dump word (16 bit)
  5872. constants to memory. {\tt CAUTION!!}  It is therefore an alias for {\tt
  5873. DW}.
  5874.  
  5875. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5876.  
  5877. \subsection{ACON}
  5878. \ttindex{ACON}
  5879.  
  5880. {\em valid for: 2650}
  5881.  
  5882. {\tt ACON} works the same way as {\tt DW}, the 16 bit numbers are however
  5883. stored in big endian format.
  5884.  
  5885. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5886.  
  5887. \subsection{LONG}
  5888. \ttindex{LONG}
  5889.  
  5890. {\em valid for: 320C2(0)x, 320C5x}
  5891.  
  5892. LONG stores a 32-bit integer to memory with the order LoWord-HiWord.
  5893. Note that when in 320C2(0)x/5x mode, the assembler assumes that a label
  5894. on the left side of this instruction has no type, i.e. it belongs to
  5895. no address space. This behaviour is explained in the
  5896. processor-specific hints.
  5897.  
  5898. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5899.  
  5900. \subsection{SINGLE, DOUBLE, and EXTENDED}
  5901. \ttindex{SINGLE}\ttindex{DOUBLE}\ttindex{EXTENDED}
  5902.  
  5903. {\em valid for: 320C3x/C4x (not {\tt DOUBLE}), 320C6x (not {\tt EXTENDED})}
  5904.  
  5905. Both commands store floating-point constants to memory.  In case of the
  5906. 320C3x/C4x, they are \bb{not} stored in IEEE-format.  Instead the
  5907. processor-specific formats with 32 and 40 bit are used.  In case of
  5908. \tty{EXTENDED} the resulting constant occupies two memory words.  The most
  5909. significant 8 bits (the exponent) are written to the first word while the
  5910. other ones (the mantissa) are copied into the second word.
  5911.  
  5912. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5913.  
  5914. \subsection{FLOAT and DOUBLE}
  5915. \ttindex{FLOAT}\ttindex{DOUBLE}
  5916.  
  5917. {\em valid for: 320C2(0)x, 320C5x}
  5918.  
  5919. These two commands store floating-point constants in memory using the
  5920. standard IEEE 32-bit and 64-bit IEEE formats.  The least significant
  5921. byte is copied to the first allocated memory location.  Note that
  5922. when in 320C2(0)x/5x mode the assembler assumes that all labels on the
  5923. left side of an instruction have no type, i.e. they belong to no
  5924. address space.  This behaviour is explained in the processor-specific
  5925. hints.
  5926.  
  5927. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5928.  
  5929. \subsection{SINGLE and DOUBLE}
  5930. \ttindex{SINGLE}\ttindex{DOUBLE}
  5931.  
  5932. {\em valid for: TMS99xxx}
  5933.  
  5934. These two commands store floating-point constants in memory using the
  5935. processor's floating point format, which is equal to the IBM/360
  5936. floating point format.
  5937.  
  5938. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5939.  
  5940. \subsection{EFLOAT, BFLOAT, and TFLOAT}
  5941. \ttindex{EFLOAT}\ttindex{BFLOAT}\ttindex{TFLOAT}
  5942.  
  5943. {\em valid for: 320C2(0)x, 320C5x}
  5944.  
  5945. Another three floating point commands.  All of them support non-IEEE
  5946. formats, which should be easily applicable on signal processors:
  5947. \begin{itemize}
  5948. \item{\tty{EFLOAT}: mantissa with 16 bits, exponent with 16 bits}
  5949. \item{\tty{BFLOAT}: mantissa with 32 bits, exponent with 16 bits}
  5950. \item{\tty{TFLOAT}: mantissa with 64 bits, exponent with 32 bits}
  5951. \end{itemize}
  5952. The three commands share a common storage strategy.  In all cases the
  5953. mantissa precedes the exponent in memory, both are stored as 2's
  5954. complement with the least significant byte first.  Note that when in
  5955. 320C2(0)x/5x mode the assembler assumes that all labels on the left side
  5956. of an instruction have no type, i.e.  they belong to no address
  5957. space. This behaviour is explained in the processor-specific hints.
  5958.  
  5959. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5960.  
  5961. \subsection{Qxx and LQxx}
  5962. \ttindex{Qxx}\ttindex{LQxx}
  5963.  
  5964. {\em valid for: 320C2(0)x, 320C5x}
  5965.  
  5966. \tty{Qxx} and \tty{LQxx} can be used to generate constants in a fixed
  5967. point format. \tty{xx} denotes a 2-digit number.  The operand is first
  5968. multiplied by $2^{xx}$ before converting it to binary notation.  Thus
  5969. \tty{xx} can be viewed as the number of bits which should be reserved for
  5970. the fractional part of the constant in fixed point format.  \tty{Qxx}
  5971. stores only one word (16 bit) while \tty{LQxx} stores two words (low word
  5972. first):
  5973. \begin{verbatim}
  5974.        q05     2.5     ; --> 0050h
  5975.        lq20    ConstPI ; --> 43F7h 0032h
  5976. \end{verbatim}
  5977. Please do not flame me in case I calculated something wrong on my
  5978. HP28...
  5979.  
  5980. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5981.  
  5982. \subsection{DATA}
  5983. \ttindex{DATA}
  5984.  
  5985. {\em valid for: PIC, 320xx, AVR, MELPS-4500, H8/500,
  5986.     HMCS400, 4004/4040, $\mu$PD772x, OLMS-40/50, Padauk}
  5987.  
  5988. This command stores data in the current segment.  Both integer
  5989. values as well as character strings are supported.  On
  5990. 16C5x/16C8x, 17C4x in data segment, and on the 4500, 4004, and
  5991. HMCS400 in code segment, characters occupy one word.  On AVR,
  5992. 17C4x in code segment, $\mu$PD772x in the data segments, and on
  5993. 3201x/3202x, in general two characters fit into one word (LSB
  5994. first).  The $\mu$PD77C25 can hold three bytees per word in the
  5995. code segment.  When in 320C3x/C4x, mode the assembler puts four
  5996. characters into one word (MSB first).  In contrast to this
  5997. characters occupy two memory locations in the data segment of the
  5998. 4500, similar in the 4004 and HMCS400.  The range of integer
  5999. values corresponds to the word width of each processor in a
  6000. specific segment.  This means that \tty{DATA} has the same result
  6001. than \tty{WORD} on a 320C3x/C4x (and that of \tty{SINGLE} if \asname{}
  6002. recognizes the operand as a floating-point constant).
  6003.  
  6004. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6005.  
  6006. \subsection{ZERO, CP-1600}
  6007. \ttindex{ZERO}
  6008.  
  6009. {\em valid for: PIC}
  6010.  
  6011. Generates a continuous string of zero words in memory (which equals a NOP
  6012. on PIC).
  6013.  
  6014. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6015.  
  6016. \subsection{FB and FW}
  6017. \ttindex{FB}\ttindex{FW}
  6018.  
  6019. {\em valid for: COP4/8}
  6020.  
  6021. These instruction allow to fill memory blocks with a byte or word
  6022. constant. The first operand specifies the size of the memory block
  6023. while the second one sets the filling constant itself.
  6024.  
  6025. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6026.  
  6027. \subsection{ASCII, ASCIC, and ASCIZ}
  6028. \ttindex{ASCII}\ttindex{ASCIC}\ttindex{ASCIZ}
  6029.  
  6030. {\em\begin{tabbing}
  6031. valid for: \= ST6, PDP-11, VAX, IMP-16, IPC-16 ({\tt ASCII}) \\
  6032.           \> ST6, PDP-11, VAX ({\tt ASCIZ}) \\
  6033.             \> PDP-11, VAX ({\tt ASCIC}) \\
  6034. \end{tabbing}}
  6035.  
  6036. These commands store string constants to memory.  While \tty{ASCII} writes
  6037. the character information only, \tty{ASCIZ} additionally appends a zero to
  6038. the end of the string, and \tty{ASCIC} prepends a length byte.
  6039.  
  6040. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6041.  
  6042. \subsection{STRING and RSTRING}
  6043. \ttindex{STRING}\ttindex{RSTRING}
  6044.  
  6045. {\em valid for: 320C2(0)x, 320C5x}
  6046.  
  6047. These commands are functionally equivalent to \tty{DATA}, but integer
  6048. values are limited to the range of byte values. This enables two
  6049. characters or numbers to be packed together into one word. Both commands
  6050. only differ in the order they use to write bytes: \tty{STRING} stores the
  6051. upper one first then the lower one, \tty{RSTRING} does this vice versa.
  6052. Note that when in 320C2(0)x/5x mode the assembler assumes that a label on the
  6053. left side of this instruction has no type, i.e. it belongs to no address
  6054. space.  This behaviour is explained in the processor-specific hints.
  6055.  
  6056. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6057.  
  6058. \subsection{PACKED}
  6059.  
  6060. {\em valid for: PDP-11, VAX}
  6061.  
  6062. This instruction may be use to put numbers in packed decimal format into
  6063. mmemory. Ist argument is either a (signed) integer number, or a string.  Of
  6064. course, the latter may only contain characters from 0 to 9 and an optional
  6065. plus or minus sign at the beginning.  The maximum number of digits is 31,
  6066. and the sign is appended as last digit.  The values 12 resp. 13 represent
  6067. a plus resp. minus sign. If the number of digits plus sign is odd, a zero
  6068. digit is inserted at the beginning.
  6069.  
  6070. Optionally, a symbol's name may be given as second argument.  The number of
  6071. digits, excluding the sign and the optional null pad, is stored in this
  6072. symbol.
  6073.  
  6074. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6075.  
  6076. \subsection{RADIX50}
  6077. \ttindex{RADIX50}
  6078.  
  6079. {\em valid for: diverse}
  6080.  
  6081. This instruction may be used to put strings in packed RADIX50 format into
  6082. memory.  This coding was common for file names in DEC environments and packs
  6083. three characters into one 16 bit word.  {\tt RADIX50} is not a built-in
  6084. instruction.  Instead, it is defined as a macro in the {\tt radix50.inc}
  6085. include file.
  6086.  
  6087. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6088.  
  6089. \subsection{FCC}
  6090. \ttindex{FCC}
  6091.  
  6092. {\em valid for: 6502, 68xx}
  6093.  
  6094. When in 65xx/68xx mode, string constants are generated using this
  6095. instruction. In contrast to the original assembler AS11 from Motorola
  6096. (this is the main reason why \asname{} understands this command, the
  6097. functionality is contained within the \tty{BYT} instruction) you must
  6098. enclose the string argument by double quotation marks instead of single
  6099. quotation marks or slashes.  Similarly to \tty{DC}, a repetition factor
  6100. enclosed in brackets ([..]) may be prepended to every single parameter.
  6101.  
  6102. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6103.  
  6104. \subsection{TEXT}
  6105.  
  6106. In CP-1600 mode, This instruction is used to store string constants in
  6107. packed format, i.e. two characters per word.
  6108.  
  6109. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6110.  
  6111. \subsection{DFS or RMB}
  6112. \ttindex{DFS}\ttindex{RMB}
  6113.  
  6114. {\em valid for: 6502, 68xx}
  6115.  
  6116. Reserves a memory block when in 6502/68xx mode.  It is therefore the
  6117. equivalent to \tty{DS.B} on the 68000 or \tty{DB ?} on Intel platforms.
  6118.  
  6119. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6120.  
  6121. \subsection{BLOCK}
  6122. \ttindex{BLOCK}
  6123.  
  6124. {\em valid for: ST6}
  6125.  
  6126. Ditto.
  6127.  
  6128. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6129.  
  6130. \subsection{SPACE}
  6131. \ttindex{SPACE}
  6132.  
  6133. {\em valid for: i960}
  6134.  
  6135. Ditto.
  6136.  
  6137. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6138.  
  6139. \subsection{RES}
  6140. \ttindex{RES}
  6141.  
  6142. {\em valid for: PIC, MELPS-4500, HMCS400, 3201x, 320C2(0)x, 320C5x, AVR,
  6143. $\mu$PD772x, OLMS-40/50, Padauk, CP-1600, PPS-4, 2650}
  6144.  
  6145. This command allocates memory.  When used in code segments the
  6146. argument counts words (10/12/14/16 bit).  In data segments it counts
  6147. bytes for PICs, nibbles for 4500, PPS-4, and OLMS-40/50 and words for the
  6148. TI devices.
  6149.  
  6150. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6151.  
  6152. \subsection{BSS}
  6153. \ttindex{BSS}
  6154.  
  6155. {\em valid for: 320C2(0)x, 320C3x/C4x/C5x/C6x, MSP}
  6156.  
  6157. \tty{BSS} works like \tty{RES}, but when in 320C2(0)x/5x mode, the assembler
  6158. assumes that a label on the left side of this instruction has no type, i.e
  6159. it belongs to no address space. This behaviour is explained in the
  6160. processor-specific hints.
  6161.  
  6162. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6163.  
  6164. \subsection{DSB and DSW}
  6165. \ttindex{DSB}\ttindex{DSW}
  6166.  
  6167. {\em valid for: COP4/8}
  6168.  
  6169. Both instructions allocate memory and ensure compatibility to ASMCOP from
  6170. National.  While \tty{DSB} takes the argument as byte count, \tty{DSW}
  6171. uses it as word count (thus it allocates twice as much memory than
  6172. \tty{DSB}).
  6173.  
  6174. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6175.  
  6176. \subsection{DS16}
  6177. \ttindex{DS16}
  6178.  
  6179. {\em valid for: SC144xx}
  6180.  
  6181. This instruction reserves memory in steps of full words, i.e. 16 bits.  It
  6182. is an alias for {\tt DW}.
  6183.  
  6184. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6185.  
  6186. \subsection{ALIGN}
  6187. \ttindex{ALIGN}
  6188.  
  6189. {\em valid for: all processors}
  6190.  
  6191. Takes the argument to align the program counter to a certain address
  6192. boundary.  \asname{} increments the program counter to the next multiple of the
  6193. argument.  So, \tty{ALIGN} corresponds to \tty{DS.x} on 68000, but is much
  6194. more flexible at the same time.
  6195.  
  6196. Example:
  6197. \begin{verbatim}
  6198.        align     2
  6199. \end{verbatim}
  6200. aligns to an even address (PC mod 2 = 0).  If Align is used in this form with
  6201. only one argument, the contents of the skipped memory space is not defined.
  6202. An optinal second argument may be used to define the (byte) value
  6203. used to fill the area.
  6204.  
  6205. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6206.  
  6207. \subsection{LTORG}
  6208. \ttindex{LTORG}
  6209.  
  6210. {\em valid for: SH7x00, IM61x0, IMP-16, IPC-16}
  6211.  
  6212. Although the SH7000 processor can do an immediate register load with
  6213. 8 bit only, \asname{} shows up with no such restriction.  This behaviour is
  6214. instead simulated through constants in memory.  Storing them in
  6215. the code segment (not far away from the register load instruction)
  6216. would require an additional jump.  \asname{} Therefore gathers the constants
  6217. an stores them at an address specified by \tty{LTORG}.  Details are
  6218. explained in the processor-specific section somewhat later.
  6219.  
  6220. %%---------------------------------------------------------------------------
  6221.  
  6222. \section{Macro Instructions}
  6223.  
  6224. {\em valid for: all processors}
  6225.  
  6226. Now we finally reach the things that make a macro assembler different
  6227. from an ordinary assembler: the ability to define macros (guessed
  6228. it !?).
  6229.  
  6230. When speaking about 'macros', I generally mean a sequence of (machine
  6231. or pseudo) instructions which are united to a block by special
  6232. statements and can then be treated in certain ways.  The assembler
  6233. knows the following statements to work with such blocks:
  6234.  
  6235. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6236.  
  6237. \subsection{MACRO}
  6238. \ttindex{MACRO}\ttindex{ENDM}
  6239. \label{SectMacros}
  6240.  
  6241. is probably the most important instruction for macro programming.
  6242. The instruction sequence
  6243. \begin{verbatim}
  6244. <name>  MACRO   [parameter list]
  6245.        <instructions>
  6246.        ENDM
  6247. \end{verbatim}
  6248. defines the macro \tty{$<$name$>$} to be the enclosed instruction sequence.
  6249. This definition by itself does not generate any code!  In turn, from
  6250. now on the instruction sequence can simply be called by the name, the
  6251. whole construct therefore shortens and simplifies programs.  A
  6252. parameter list may be added to the macro definition to make things
  6253. even more useful.
  6254. \par
  6255. While a macro's name only has to conform to the usual rules for symbol
  6256. names (see section \ref{SectSymConv}), there is the additional restriction
  6257. that parameter names may not contain underscore characters.  This may
  6258. be changed via the \tty{-underscore-macroargs} command line argument,
  6259. but sinve it has additional side effects, it should only be used if
  6260. absolutely necessary.
  6261. \par
  6262. A switch to case-sensitive mode influences both macro names and
  6263. parameters.
  6264.  
  6265. Similar to symbols, macros are local, i.e. they are only known in a
  6266. section and its subsections when the definition is done from within
  6267. a section.  This behaviour however can be controlled in wide limits
  6268. via the options \tty{PUBLIC} and \tty{GLOBAL} described below.
  6269.  
  6270. A default value may be provided for each macro parameter
  6271. (appended via an equal sign).  This value is used if there is no
  6272. argument for this parameter at macro call or if the positional
  6273. argument (see below) for this parameter is empty.
  6274.  
  6275. Apart from the macro parameters themselves, the parameter list may
  6276. contain control parameters which influence the processing of the
  6277. macro.  These parameters are distinguished from normal parameters by
  6278. being enclosed in curly braces.  The following control parameters are
  6279. defined:
  6280. \begin{itemize}
  6281. \item{\tty{EXPAND/NOEXPAND}: rule whether the enclosed code shall
  6282.      be written to the listing when the macro is expanded.  The
  6283.      default is the value set by the pseudo instruction
  6284.      \tty{MACEXP\_DFT}.}
  6285. \item{\tty{EXPIF/NOEXPIF}: rule whether instructions for
  6286.      conditional assembly and code excluded by it shall
  6287.      be written to the listing when the macro is expanded.  The
  6288.      default is the value set by the pseudo instruction
  6289.      \tty{MACEXP\_DFT}.}
  6290. \item{\tty{EXPMACRO/NOEXPMACRO}: rule whether macros defined in
  6291.      the macro's body shall be written to the listing when the macro
  6292.      is expanded.  The default is the value set by the pseudo instruction
  6293.      \tty{MACEXP\_DFT}.}
  6294. \item{\tty{EXPREST/NOEXPREST} : rule whether a macro body's lines
  6295.      not fitting into the first two categories shall be written to the
  6296.      listing when the macro is expanded. The default is the value set by
  6297.      the pseudo instruction \tty{MACEXP\_DFT}.}
  6298. \item{\tty{PUBLIC[:section name]}: assigns the macro to a parent section
  6299.      instead of the current section.  A section can make macros
  6300.      accessible for the outer code this way.  If the section
  6301.      specification is missing, the macro becomes completely global, i.e.
  6302.      it may be referenced from everywhere.}
  6303. \item{\tty{GLOBAL[:section name]}: rules that in addition to the macro
  6304.      itself, another macro shall be generated that has the same contents
  6305.      but is assigned to the specified section.  Its name is constructed by
  6306.      concatenating the current section's name to the macro name.  The
  6307.      section specified must be a parent section of the current section;
  6308.      if the specification is missing, the additional macro becomes
  6309.      globally visible.  For example, if a macro \tty{A} is defined in a
  6310.      section \tty{B} that is a child section of section \tty{C}, an additional
  6311.      global macro named \tty{C\_B\_A} would be generated.  In contrast, if
  6312.      \tty{C} had been specified as target section, the macro would be named \tty{B\_A}
  6313.      and be assigned to section \tty{C}.  This option is turned off by default
  6314.      and it only has an effect when it is used from within a section.
  6315.      The macro defined locally is not influenced by this option.}
  6316. \item{\tty{EXPORT/NOEXPORT}: rules whether the definition of this macro
  6317.      shall be written to a separate file in case the \tty{-M} command line
  6318.      option was given.  This way, definitions of 'private' macros may
  6319.      be mapped out selectively.  The default is FALSE, i.e. the
  6320.      definition will not be written to the file.  The macro will be
  6321.      written with the concatenated name if the \tty{GLOBAL} option was
  6322.      additionally present.}
  6323. \item{\tty{INTLABEL/NOINTLABEL} : rules whether a label defined in a line
  6324.      that calls this macro may be used as an additional parameter inside
  6325.      the label or not, instead of simply 'labeling' the line.}
  6326. \item{\tty{GLOBALSYMBOLS/NOGLOBALSYMBOLS} : rules whether labels
  6327.      defined in the macro's body shall be local to this macro or
  6328.      also be available outside the macro.  The default is to
  6329.      keep them local, since using a macro multiple time would be
  6330.      difficult otherwise.}
  6331. \end{itemize}
  6332. The control parameters described above are removed from the parameter
  6333. list by \asname{}, i.e. they do not have a further influence on processing
  6334. and usage.
  6335.  
  6336. When a macro is called, the parameters given for the call are
  6337. textually inserted into the instruction block and the resulting
  6338. assembler code is assembled as usual.  Zero length parameters are
  6339. inserted in case too few parameters are specified.  It is important
  6340. to note that string constants are not protected from macro
  6341. expansions.  The old IBM rule:
  6342. \begin{quote}{\it
  6343. It's not a bug, it's a feature!
  6344. }\end{quote}
  6345. applies for this detail.  The gap was left to allow checking of
  6346. parameters via string comparisons.  For example, one can analyze a
  6347. macro parameter in the following way:
  6348. \begin{verbatim}
  6349. mul     MACRO   para,parb
  6350.        IF      UpString("PARA")<>"A"
  6351.         MOV    a,para
  6352.        ENDIF
  6353.        IF      UpString("PARB")<>"B"
  6354.         MOV    b,parb
  6355.        ENDIF
  6356.        !mul     ab
  6357.        ENDM
  6358. \end{verbatim}
  6359. It is important for the example above that the assembler converts all
  6360. parameter names to upper case when operating in case-insensitive
  6361. mode, but this conversion never takes place inside of string constants.
  6362. Macro parameter names therefore have to be written in upper case when
  6363. they appear in string constants.
  6364.  
  6365. Macro parameter expansion furthermore depends on whether
  6366. parameter names may contain underscores or not.  If not
  6367. (the default), underscores in the macro body also have
  6368. a function of 'limiters' to detect parameter names.  So
  6369. in the following example:
  6370. \begin{verbatim}
  6371. setled  macro led,value
  6372.        out   led,value
  6373.        ld    led_shadow,value
  6374.        endm
  6375. \end{verbatim}
  6376. the parameter 'led' would be replaced in both source lines, whereas
  6377. only in the first one if the command line switch \tty{underscore-macroargs}
  6378. is used.  Several of the include files shipped with \asname{}
  6379. rely on the default behaviour.  This switch should therefore only
  6380. be used if absolutely necessary.
  6381.  
  6382. Macro arguments may be given in either of two forms: {\em
  6383. positional} or {\em keyword} arguments.
  6384.  
  6385. For positional arguments, the assignment of arguments to macro
  6386. parameters simply results from the position of arguments, i.e.
  6387. the first argument is assigned to the first parameter, the second
  6388. argument to the second parameter and so on.  If the number of
  6389. arguments is smaller than the number of parameters, eventually
  6390. defined default values or simply an empty string are inserted.
  6391. The same is valid for empty arguments in the argument list.
  6392.  
  6393. Keyword arguments on the other hand explicitly define which
  6394. parameter they relate to, by being prefixed with the parameter's
  6395. name:
  6396. \begin{verbatim}
  6397.       mul  para=r0,parb=r1
  6398. \end{verbatim}
  6399. Again, non-assigned parameters will use an eventually defined
  6400. default or an empty string.
  6401.  
  6402. As a difference to positional arguments, keyword arguments allow
  6403. to assign an empty string to a parameter with a non-empty
  6404. default.
  6405.  
  6406. Mixing of positional and keyword arguments in one macro call is
  6407. possible, however it is not allowed to use positional arguments
  6408. after the first keyword argument.
  6409.  
  6410. The same naming rules as for usual symbols also apply for macro
  6411. parameters, with the exception that only letters and numbers are
  6412. allowed, i.e. dots and underscores are forbidden.  This constraint
  6413. has its reason in a hidden feature: the underscore allows to
  6414. concatenate macro parameter names to a symbol, like in the following
  6415. example:
  6416. \begin{verbatim}
  6417. concat  macro   part1,part2
  6418.        call    part1_part2
  6419.        endm
  6420. \end{verbatim}
  6421. The call
  6422. \begin{verbatim}
  6423.        concat  module,function
  6424. \end{verbatim}
  6425. will therefore result in
  6426. \begin{verbatim}
  6427.        call    module_function
  6428. \end{verbatim}
  6429. Apart from the parameters explicitly declared for a macro, four more
  6430. 'implicitly' declared parameters exist.   Since they are always present,
  6431. they cannot not be redeclared as explicit parameters:
  6432. \begin{itemize}
  6433. \item{{\tt ATTRIBUTE} refers to the attribute appended to the macro call,
  6434.      in case the currently active architecture supports attributes for
  6435.      machine instructions.  See below for an example!}
  6436. \item{{\tt ALLARGS} refers to a comma-separated list of all arguments
  6437.      passed to a macro, usable e.g. to pass them on to a IRP statement.}
  6438. \item{{\tt ARGCOUNT} refers to the actual count of parameters passed to
  6439.      a macro.  Note however that this number is never lower than the
  6440.      formal parameter count of the macro, since \asname{} will fill up missing
  6441.      arguments with empty strings!}
  6442. \item{{\tt \_\_LABEL\_\_} refers to a label present in a line that calls the
  6443.      macro. This replacement only takes place if the {\tt INTLABEL}
  6444.      option was set for this macro!}
  6445. \end{itemize}
  6446. {\bf IMPORTANT:} the names of these implicit parameters are also
  6447. case-insensitive if \asname{} was told to operate case-sensitive!
  6448.  
  6449. The purpose of being able to 'internally' use a label in a macro is surely
  6450. not immediately obvious.  There might be cases where moving the macro's
  6451. entry point into its body may be useful.  The most important application
  6452. however are TI signal processors that use a double pipe symbol in the
  6453. label's column to mark parallelism, like this:
  6454. \begin{verbatim}
  6455.    instr1
  6456. ||  instr2
  6457. \end{verbatim}
  6458. (since both instructions merge into a single word of machine code, you
  6459. cannot branch to the second instruction - so occupying the label's
  6460. position doesn't hurt).  The problem is however that some 'convenience
  6461. instructions' are realized as macros.  A parallelization symbol written in
  6462. front of a macro call normally would be assigned to the macro itself, {\it
  6463. not to the macro body's first instruction}.  However, things work with
  6464. this trick:
  6465. \begin{verbatim}
  6466. myinstr    macro {INTLABEL}
  6467. __LABEL__  instr2
  6468.           endm
  6469.  
  6470.           instr1
  6471. ||         myinstr
  6472. \end{verbatim}
  6473. The result after expanding {\tt myinstr} is identical to the previous
  6474. example without macro.
  6475.  
  6476. Recursion of macros, i.e. the repeated call of a macro from within its own
  6477. body is completely legal.  However, like for any other sort of recursion,
  6478. one has to assure that there is an end at someplace.  For cases where one
  6479. forgot this, \asname{} keeps an internal counter for every macro that is
  6480. incremented when an expansion of this macro is begun and decremented again
  6481. when the expansion is completed.  In case of recursive calls, this counter
  6482. reaches higher and higher values, and at a limit settable via {\tt
  6483. NESTMAX}, \asname{} will refuse to expand. Be careful when you turn off this
  6484. emergency brake: the memory consumption on the heap may go beyond all
  6485. limits and even shut down a Unix system...
  6486.  
  6487. A small example to remove all clarities ;-)
  6488.  
  6489. A programmer braindamaged by years of programming Intel processors
  6490. wants to have the instructions \tty{PUSH/POP} also for the 68000.  He
  6491. solves the 'problem' in the following way:
  6492. \begin{verbatim}
  6493. push    macro   op
  6494.        move.ATTRIBUTE op,-(sp)
  6495.        endm
  6496.  
  6497. pop     macro   op
  6498.        move.ATTRIBUTE (sp)+,op
  6499.        endm
  6500. \end{verbatim}
  6501. If one writes
  6502. \begin{verbatim}
  6503.        push    d0
  6504.        pop.l   a2    ,
  6505. \end{verbatim}
  6506. this results in
  6507. \begin{verbatim}
  6508.        move.   d0,-(sp)
  6509.        move.l  (sp)+,a2
  6510. \end{verbatim}
  6511. A macro definition must not cross include file boundaries.
  6512.  
  6513. Labels defined in macros always are regarded as being local,
  6514. unless the \tty{GLOBALSYMBOLS} was used in the macro's
  6515. definition.  If a single label shall be made public in a macro
  6516. that uses local labels otherwise, it may be defined with a
  6517. \tty{LABEL} statement which always creates global symbols
  6518. (similar to \tty{BIT, SFR...}):
  6519. \begin{verbatim}
  6520. <Name>  label   $
  6521. \end{verbatim}
  6522. When parsing a line, the assembler first checks the macro list
  6523. afterwards looks for processor instructions, which is why macros
  6524. allow to redefine processor instructions.  However, the definition
  6525. should appear previously to the first invocation of the instruction
  6526. to avoid phase errors like in the following example:
  6527. \begin{verbatim}
  6528.        bsr     target
  6529.  
  6530. bsr     macro   targ
  6531.        jsr     targ
  6532.        endm
  6533.  
  6534.        bsr     target
  6535. \end{verbatim}
  6536. In the first pass, the macro is not known when the first \tty{BSR}
  6537. instruction is assembled; an instruction with 4 bytes of length is
  6538. generated.  In the second pass however, the macro definition is
  6539. immediately available (from the first pass), a \tty{JSR} of 6 bytes length
  6540. is therefore generated.  As a result, all labels following are too low
  6541. by 2 and phase errors occur for them.  An additional pass is
  6542. necessary to resolve this.
  6543.  
  6544. Because a machine or pseudo instruction becomes hidden when a macro
  6545. of same name is defined, there is a backdoor to reach the original
  6546. meaning: the search for macros is suppressed if the name is prefixed
  6547. with an exclamation mark (!).  This may come in handy if one wants to
  6548. extend existing instructions in their functionality, e.g. the
  6549. TLCS-90's shift instructions:
  6550. \begin{verbatim}
  6551. srl     macro   op,n            ; shift by n places
  6552.        rept    n               ; n simple instructions
  6553.         !srl   op
  6554.        endm
  6555.        endm
  6556. \end{verbatim}
  6557. From now on, the \tty{SRL} instruction has an additional parameter...
  6558.  
  6559. \subsubsection{Macro Expansion in the Listing}
  6560.  
  6561. If a macro is being called, the macro's body is included in the assembly
  6562. listing, after arguemnts have been expanded.  This can significantly increase
  6563. the listing's size and make it hard to read.  It is therefore possible to
  6564. suppress this expansion totally or in parts.  Fundamentally, \asname{} divides
  6565. the source lines contained in a macro's body into three classes:
  6566. \begin{itemize}
  6567. \item{Macro definitions, i.e. the macro is used to define another macro,
  6568.      or it contains \tty{REPT/IRP/IRPC/WHILE} blocks.}
  6569. \item{Instructions for conditional assembly plus any source lines that have
  6570.      {\it not} been assembled due to conditional assembly.  Since conditional
  6571.      assembly may depend on macro arguments, this subset may also vary.}
  6572. \item{All remaining sourc elines that do not fall under the first two
  6573.      categories.}
  6574. \end{itemize}
  6575. Which parts occur in the listing may be defined individually for every macro.
  6576. When defining a macro, the default is the set defined by the most recent
  6577. \tty{MACEXP\_DFT} instruction (\ref{MACEXPDFT}).  If one of the \tty{EXPAND/NOEXPAND},
  6578. \tty{EXPIF/NOEXPIF} \tty{EXPMACRO/NOEXPMACRO}, or \tty{EXPREST/NOEXPREST}
  6579. directives is used in the macro's definition, they act {\em additionally},
  6580. but with higher preference.  For instance, if expansion had been disabled
  6581. completely (\tty{MACEXP\_DFT OFF}), adding the directive \tty{EXPREST} has the
  6582. effect that when using this macro, only lines are written to the listing
  6583. that remain after conditional assembly and are no macro definitions themselves.
  6584.  
  6585. In consequence, changing the set via \tty{MACEXP\_DFT} has no effect on macros
  6586. that have been {\it defined before} this statement.  The listing's section shows
  6587. for defined macros the effective set of expansion directives.  The list given
  6588. in curly braces is shorted so that it only conatins the last (and therefore
  6589. valid) directive for a certain class of source lines.  A \tty{NOIF} given
  6590. via \tty{MACEXP\_DFT} will therefore not show up if the directive \tty{EXPIF}
  6591. had been given specifically for this macro.
  6592.  
  6593. There might be cases where it is useful to override the expansion rules for
  6594. a certain macro, regardless whether they were given by \tty{MACEXP\_DFT} or
  6595. individual directives.  The statement \tty{MACEXP\_OVR} (\ref{MACEXPOVR})
  6596. exists for such cases.  It only has an effects on macros subsequently being
  6597. {\it expanded}.  Once again, directives given by this instruction are regarded
  6598. in addition to a macro's rules, and they do with higher priority.  A \tty{MACEXP\_OVR}
  6599. without any arguments disables such an override.
  6600.  
  6601. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6602.  
  6603. \subsection{IRP}
  6604. \ttindex{IRP}
  6605.  
  6606. is a simplified macro definition for the case that an instruction sequence
  6607. shall be applied to a couple of operands and the the code is not needed
  6608. any more afterwards.  \tty{IRP} needs a symbol for the operand as its
  6609. first parameter, and an (almost) arbitrary number of parameters that are
  6610. sequentially inserted into the block of code.  For example, one can write
  6611. \begin{verbatim}
  6612.        irp     op, acc,b,dpl,dph
  6613.        push    op
  6614.        endm
  6615. \end{verbatim}
  6616. to push a couple of registers to the stack, what results in
  6617. \begin{verbatim}
  6618.        push    acc
  6619.        push    b
  6620.        push    dpl
  6621.        push    dph
  6622. \end{verbatim}
  6623. Analog to a macro definition, the argument list may contain the
  6624. following control parameters (marked as such by being enclosed in curly
  6625. braces):
  6626. \begin{itemize}
  6627. \item{\tty{GLOBALSYMBOLS} resp. \tty{NOGLOBALSYMBOLS} control whether
  6628.      defined labels are local for every individual pass or not.}
  6629. \item{\tty{EXPAND} resp. \tty{NOEXPAND}}
  6630. \item{\tty{EXPIF} resp. \tty{NOEXPIF}}
  6631. \item{\tty{EXPMACRO} resp. \tty{NOEXPMACRO}}
  6632. \item{\tty{EXPREST} resp. \tty{NOEXPREST}}
  6633. \end{itemize}
  6634.  
  6635.  
  6636. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6637.  
  6638. \subsection{IRPC}
  6639. \ttindex{IRPC}
  6640.  
  6641. \tty{IRPC} is a variant of \tty{IRP} where the first argument's occurences
  6642. in the lines up to \tty{ENDM} are successively replaced by the characters
  6643. of a string instead of further parameters.  For example, an especially
  6644. complicated way of placing a string into memory would be:
  6645. \begin{verbatim}
  6646.        irpc    char,"Hello World"
  6647.        db      'CHAR'
  6648.        endm
  6649. \end{verbatim}
  6650. \bb{CAUTION!} As the example already shows, \tty{IRPC} only inserts the
  6651. pure character; it is the programmer's task to assure that valid code
  6652. results (in this example by inserting quotes, including the detail that no
  6653. automatic conversion to uppercase characters is done).
  6654.  
  6655. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6656.  
  6657. \subsection{REPT}
  6658. \ttindex{REPT}
  6659.  
  6660. is the simplest way to employ macro constructs.  The code between
  6661. \tty{REPT} and \tty{ENDM} is assembled as often as the integer argument of
  6662. \tty{REPT} specifies.  This statement is commonly used in small loops to
  6663. replace a programmed loop to save the loop overhead.
  6664.  
  6665. An example for the sake of completeness:
  6666. \begin{verbatim}
  6667.        rept    3
  6668.        rr      a
  6669.        endm
  6670. \end{verbatim}
  6671. rotates the accumulator to the right by three digits.
  6672.  
  6673. The allowed control directives are the same as for \tty{IRP}.
  6674.  
  6675. In case \tty{REPT}'s argument is equal to or smaller than 0, no expansion
  6676. at all is done.  This is different to older versions of \asname{} which used to
  6677. be a bit 'sloppy' in this respect and always made a single expansion.
  6678.  
  6679. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6680.  
  6681. \subsection{WHILE}
  6682. \ttindex{WHILE}
  6683.  
  6684. \tty{WHILE} operates similarly to \tty{REPT}, but the fixed number of
  6685. repetitions given as an argument is replaced by a boolean expression.  The
  6686. code framed by \tty{WHILE} and \tty{ENDM} is assembled until the
  6687. expression becomes logically false.  This may mean in the extreme case
  6688. that the enclosed code is not assembled at all in case the expression was
  6689. already false when the construct was found.  On the other hand, it may
  6690. happen that the expression stays true forever and \asname{} will run
  6691. infinitely...one should apply therefore a bit of accuracy when one uses
  6692. this construct, i.e. the code must contain a statement that influences the
  6693. condition, e.g. like this:
  6694. \begin{verbatim}
  6695. cnt     set     1
  6696. sq      set     cnt*cnt
  6697.        while   sq<=1000
  6698.         dc.l    sq
  6699. cnt      set     cnt+1
  6700. sq       set     cnt*cnt
  6701.        endm
  6702. \end{verbatim}
  6703. This example stores all square numbers up to 1000 to memory.
  6704.  
  6705. The allowed control directives are the same as for \tty{IRP} and
  6706. \tty{REPT}.
  6707.  
  6708. Currently there exists a little ugly detail for \tty{WHILE}: an additional
  6709. empty line that was not present in the code itself is added after the last
  6710. expansion.  This is a 'side effect' based on a weakness of the macro
  6711. processor and it is unfortunately not that easy to fix.  I hope noone
  6712. minds...
  6713.  
  6714. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6715.  
  6716. \subsection{EXITM}
  6717. \ttindex{EXITM}
  6718.  
  6719. \tty{EXITM} offers a way to terminate a macro expansion or one of the
  6720. instructions \tty{REPT, IRP,} or \tty{WHILE} prematurely.  Such an option
  6721. helps for example to replace encapsulations with \tty{IF-ENDIF}-ladders in
  6722. macros by something more readable.  Of course, an \tty{EXITM} itself
  6723. always has to be conditional, what leads us to an important detail: When
  6724. an \tty{EXITM} is executed, the stack of open \tty{IF} and
  6725. \tty{SWITCH} constructs is reset to the state it had just before the macro
  6726. expansion started.  This is imperative for conditional \tty{EXITM}'s as
  6727. the \tty{ENDIF} resp. \tty{ENDCASE} that frames the \tty{EXITM} statement
  6728. will not be reached any more; \asname{} would print an error message without this
  6729. trick.  Please keep also in mind that \tty{EXITM} always only terminates
  6730. the innermost construct if macro constructs are nested!  If one want to
  6731. completely break out of a nested construct, one has to use additional
  6732. \tty{EXITM}'s on the higher levels!
  6733.  
  6734. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6735.  
  6736. \subsection{SHIFT}
  6737. \ttindex{SHIFT}\ttindex{.SHIFT}\ttindex{SHFT}
  6738.  
  6739. {\tt SHIFT} is a tool to construct macros with variable argument lists: it
  6740. discards the first parameter, with the result that the second parameter
  6741. takes its place and so on.  This way one could process a variable argument
  6742. list...if you do it the right way.  For example, the following does not
  6743. work...
  6744. \begin{verbatim}
  6745. pushlist  macro reg
  6746.          rept  ARGCOUNT
  6747.          push  reg
  6748.          shift
  6749.          endm
  6750.          endm
  6751. \end{verbatim}
  6752. ...because the macro gets expanded {\tt once}, its output is captured by
  6753. {\tt REPT} and then executed n times.  Therefore, the first argument is
  6754. saved n times...the following approach works better:
  6755. \begin{verbatim}
  6756. pushlist  macro reg
  6757.          if      "REG"<>""
  6758.           push    reg
  6759.           shift
  6760.           pushlist ALLARGS
  6761.          endif
  6762.          endm
  6763. \end{verbatim}
  6764. Effectively, this is a recursion that shortens the argument list once per
  6765. step.  The important trick is that a new macro expansion is started in
  6766. each step...
  6767.  
  6768. In case {\tt SHIFT} ist already a machine instruction for a certain target,
  6769. {\tt SHFT} may be used instead, or the pseudo instruction is referenced
  6770. explicitly by prepending a period (\tty{.SHIFT} instead of \tty{SHIFT}).
  6771.  
  6772. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6773.  
  6774. \subsection{MAXNEST}
  6775. \ttindex{MAXNEST}
  6776.  
  6777. {\tt MAXNEST} allows to adjust how often a mcro may be called recursively
  6778. before \asname{} terminates with an error message.  The argument may be an
  6779. arbitrary positive integer value, with the special value 0 turning the
  6780. this security brake completely off (be careful with that...).  The default
  6781. value for the maximum nesting level is 256; its current value may be read
  6782. from the integer symbol of same name.
  6783.  
  6784. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6785.  
  6786. \subsection{FUNCTION}
  6787. \label{SectFUNCTION}
  6788. \ttindex{FUNCTION}
  6789.  
  6790. Though \tty{FUNCTION} is not a macro statement in the inner sense, I will
  6791. describe this instruction at this place because it uses similar principles
  6792. like macro replacements.
  6793.  
  6794. This instruction is used to define new functions that may then be
  6795. used in formula expressions like predefined functions.  The
  6796. definition must have the following form:
  6797. \begin{verbatim}
  6798. <name>  FUNCTION <arg>,..,<arg>,<expression>
  6799. \end{verbatim}
  6800. The arguments are the values that are 'fed into' the function.  The
  6801. definition uses symbolic names for the arguments.  The assembler
  6802. knows by this that where to insert the actual values when the
  6803. function is called.  This can be seen from the following example:
  6804. \begin{verbatim}
  6805. isdigit FUNCTION ch,(ch>='0')&&(ch<='9')
  6806. \end{verbatim}
  6807. This function checks whether the argument (interpreted as a character) is
  6808. a number in the currently valid character set (the character set can be
  6809. modified via \tty{CHARSET}, therefore the careful wording).
  6810.  
  6811. The arguments' names (\tty{CH} in this case) must conform to the stricter
  6812. rules for macro parameter names, i.e. the special characters . and \_
  6813. are not allowed.
  6814.  
  6815. User-defined functions can be used in the same way as builtin
  6816. functions, i.e. with a list of parameters, separated by commas,
  6817. enclosed in parentheses:
  6818. \begin{verbatim}
  6819.        IF isdigit(char)
  6820.         message "\{char} is a number"
  6821.        ELSEIF
  6822.         message "\{char} is not a number"
  6823.        ENDIF
  6824. \end{verbatim}
  6825. When the function is called, all parameters are calculated once and
  6826. are then inserted into the function's formula.  This is done to
  6827. reduce calculation overhead and to avoid side effects.  The
  6828. individual arguments have to be separated by commas when a function
  6829. has more than one parameter.
  6830.  
  6831. \bb{CAUTION!}  Similar to macros, one can use user-defined functions to
  6832. override builtin functions.  This is a possible source for phase
  6833. errors.  Such definitions therefore should be done before the first
  6834. call!
  6835.  
  6836. The result's type may depend on the type of the input arguments.
  6837. For example, the function
  6838. \begin{verbatim}
  6839. double  function x,x+x
  6840. \end{verbatim}
  6841. may have an integer, a float, or even a string as result, depending
  6842. on the argument's type!
  6843.  
  6844. When \asname{} operates in case-sensitive mode, the case matters when
  6845. defining or referencing user-defined functions, in contrast to
  6846. builtin functions!
  6847.  
  6848. %%---------------------------------------------------------------------------
  6849.  
  6850. \section{Structures}
  6851. \ttindex{STRUCT}\ttindex{ENDSTRUCT}\ttindex{UNION}\ttindex{ENDUNION}
  6852. \ttindex{STRUC}\ttindex{ENDSTRUC}\ttindex{ENDS}
  6853. \ttindex{DOTTEDSTRUCTS}
  6854.  
  6855. {\em valid for: all processors}
  6856.  
  6857. Even in assembly language programs, there is sometimes the necessity to
  6858. define composed data structures, similar to high-level languages.  \asname{}
  6859. supports both the definition and usage of structures with a couple of
  6860. statements.  These statements shall be explained in the following section.
  6861.  
  6862. \subsection{Definition}
  6863.  
  6864. The definiton of a structure is begun with the statement
  6865. \tty{STRUCT} and ends with \tty{ENDSTRUCT} (lazy people may also
  6866. write {\tt STRUC} resp.  {\tt ENDSTRUC} or {\tt ENDS} instead).
  6867. A optional label preceding these instructions is taken as the
  6868. name of the structure to be defined; it is optional at the end of
  6869. the definition and may be used to redefine the length symbol's
  6870. name (see below).  The remaining procedure is simple: Together
  6871. with \tty{STRUCT}, the cuurent program counter is saved and reset
  6872. to zero.  All labels defined between \tty{STRUCT} and
  6873. \tty{ENDSTRUCT} therefore are the offsets of the structure's data
  6874. fields.  Reserving space is done via the same instructions that
  6875. are also otherwise used for reserving space, like e.g.
  6876. \tty{DS.x} for Motorola CPUs or \tty{DB} \& co.  for Intel-style
  6877. processors.  The rules for rounding up lengths to assure certain
  6878. alignments also apply here - if one wants to define 'packed'
  6879. structures, a preceding {\tt PADDING OFF} may be necessary.  Vice
  6880. versa, alignments may be forced with {\tt ALIGN} or similar
  6881. instructions.
  6882.  
  6883. Since such a definition only represents a sort of 'prototype', only
  6884. instructions that reserve memory may be used, no instructions that dispose
  6885. constants or generate code.
  6886.  
  6887. Labels defined inside structures (i.e. the elements' names) are not
  6888. stored as-is.  Instead, the structure's name is prepended to them,
  6889. separated with a special character.  By default, this is the underbar
  6890. (\_).  This behaviour however may be modified with two arguments passed
  6891. to the
  6892. \tty{STRUCT} statement:
  6893. \begin{itemize}
  6894. \item{\tty{NOEXTNAMES} suppressed the prepending of the structure's name.
  6895.      In this case, it is the programmer's responsibility to assure that
  6896.      field names are not used more than once.}
  6897. \item{\tty{DOTS} instructs \asname{} to use the dot as connecting character
  6898.      instead of the underbar.  It should however be pointed out that
  6899.      on certain target architectures, the dot has a special meaning
  6900.      for bit addressing, which may lead to problems!}
  6901. \end{itemize}
  6902. It is futhermore possible to turn the usage of a dot on resp. off for all
  6903. following structures:
  6904. \begin{verbatim}
  6905.        dottedstructs <on|off>
  6906. \end{verbatim}
  6907.  
  6908. Aside from the element names, \asname{} also defines a further symbol with the
  6909. structure's overall length when the definition has been finished.  This
  6910. symbol has the name {\tt LEN}, which is being extended with the
  6911. structure's name via the same rules - or alternitavely with the label name
  6912. given with the \tty{ENDSTRUCT} statement.
  6913.  
  6914. In practice, this may things may look like in this example:
  6915. \begin{verbatim}
  6916. Rec     STRUCT
  6917. Ident   db      ?
  6918. Pad     db      ?
  6919. Pointer dd      ?
  6920. Rec     ENDSTRUCT
  6921. \end{verbatim}
  6922. In this example, the symbol {\tt REC\_LEN} would be assigned the value 6.
  6923.  
  6924. \subsection{Usage}
  6925.  
  6926. Once a structure has been assigned, usage is as simple as possible and
  6927. similar to a macro: a simple
  6928. \begin{verbatim}
  6929. thisrec Rec
  6930. \end{verbatim}
  6931. reserves as much memory as needed to hold an instance of the structure,
  6932. and additionally defines a symbol for every element of the structure with
  6933. its address, in this case {\tt THISREC\_IDENT, THISREC\_PAD}, and {\tt
  6934. THISREC\_POINTER}.  A label naturally must not be omitted when calling a
  6935. structure; if it is missing, an error will be emitted.
  6936.  
  6937. Additional arguments allow to reserve memory for a whole array of structures.
  6938. The dimensions (up to three) are defined via arguments in square brackets:
  6939. \begin{verbatim}
  6940. thisarray Rec [10],[2]
  6941. \end{verbatim}
  6942. In this example, space for $2*10=20$ structures is reserved. For each individual
  6943. structure in the array, proper symbols are generated that have the array
  6944. indices in their name.
  6945.  
  6946. \subsection{Nested Structures}
  6947.  
  6948. Is is perfectly valid to call an already defined structure within the
  6949. definition of another structure.  The procedure that is taking place then
  6950. is a combination of the definition and calling described in the previous
  6951. two sections: elements of the substructure are being defined, the name of
  6952. the instance is being prepended, and the name of the super-structure is
  6953. once again geing prepended to this concatenated name.  This may look like
  6954. the following:
  6955. \begin{verbatim}
  6956. TreeRec struct
  6957. left    dd         ?
  6958. right   dd         ?
  6959. data    Rec
  6960. TreeRec endstruct
  6961. \end{verbatim}
  6962.  
  6963. It is also allowed to define one structure inside of another
  6964. structure:
  6965. \begin{verbatim}
  6966. TreeRec struct
  6967. left    dd         ?
  6968. right   dd         ?
  6969. TreeData struct
  6970. name      db         32 dup(?)
  6971. id        dw         ?
  6972. TreeData endstruct
  6973. TreeRec endstruct
  6974. \end{verbatim}
  6975.  
  6976. \subsection{Unions}
  6977.  
  6978. A union is a special form of a structure whose elements are not laid out
  6979. sequentially in memory.  Instead all elements occupy the {\em same}
  6980. memory and are located at offset 0 in the structure.  Naturally, such a
  6981. definition basically does nothing more than to assign the value of zero to
  6982. a couple of symbols.  It may however be useful to clarify the overlap in a
  6983. program and therefore to make it more 'readable'.  The size of a union is
  6984. the maximum of all elements' lengths.
  6985.  
  6986. \subsection{Nameless Structures}
  6987.  
  6988. The name of a structure or union is optional if it is part of
  6989. another (named) structure or union.  Elements of this structure
  6990. will then become part of of the 'next higher' named structure.
  6991. For example,
  6992. \begin{verbatim}
  6993. TreeRec struct
  6994. left    dd         ?
  6995. right   dd         ?
  6996.        struct
  6997. name      db         32 dup(?)
  6998. id        dw         ?
  6999.        endstruct
  7000. TreeRec endstruct
  7001. \end{verbatim}
  7002. generates the symbols {\tt TREEREC\_NAME} and {\tt TREEREC\_ID}.
  7003.  
  7004. Futhermore, no symbol holding its length is generated for an
  7005. unnamed structure or union.
  7006.  
  7007. \subsection{Structures and Sections}
  7008.  
  7009. Symbols that are created in the course of defining or usage of structures
  7010. are treated just like normal symbols, i.e. when used within a section,
  7011. these symbols are local to the section.  The same is however also true for
  7012. the structures themselves, i.e. a structure defined within a section
  7013. cannot be used outside of the section.
  7014.  
  7015. \subsection{Structures and Macros}
  7016.  
  7017. If one wants to instantiate structures via macros, one has to use
  7018. the \tty{GLOBALSYMBOLS} options when defining the macro to make
  7019. the defined symbols visible outside the macro.  For instance, a
  7020. list of structures can be defined in the following way:
  7021.  
  7022. \begin{verbatim}
  7023.        irp     name,{GLOBALSYMBOLS},rec1,rec2,rec3
  7024. name    Rec
  7025.        endm
  7026. \end{verbatim}
  7027.  
  7028. %%---------------------------------------------------------------------------
  7029.  
  7030. \section{Conditional Assembly}
  7031.  
  7032. {\em valid for: all processors}
  7033.  
  7034. The assembler supports conditional assembly with the help of statements
  7035. like \tty{IF...} resp. \tty{SWITCH...} .  These statements work at
  7036. assembly time allowing or disallowing the assembly of program parts based
  7037. on conditions.  They are therefore not to be compared with IF statements
  7038. of high-level languages (though it would be tempting to extend assembly
  7039. language with structurization statements of higher level languages...).
  7040.  
  7041. The following constructs may be nested arbitrarily (until a memory
  7042. overflow occurs).
  7043.  
  7044. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7045.  
  7046. \subsection{IF / ELSEIF / ENDIF}
  7047. \ttindex{IF}
  7048. \ttindex{ENDIF}
  7049. \ttindex{ELSEIF}\ttindex{ELSE}
  7050.  
  7051. \tty{IF} is the most common and most versatile construct.  The general
  7052. style of an \tty{IF} statement is as follows:
  7053. \begin{verbatim}
  7054.        IF      <expression 1>
  7055.        .
  7056.        .
  7057.        <block 1>
  7058.        .
  7059.        .
  7060.        ELSEIF  <expression 2>
  7061.        .
  7062.        .
  7063.        <block 2>
  7064.        .
  7065.        .
  7066.        (possibly more ELSEIFs)
  7067.  
  7068.        .
  7069.        .
  7070.        ELSEIF
  7071.        .
  7072.        .
  7073.        <block n>
  7074.        .
  7075.        .
  7076.        ENDIF
  7077. \end{verbatim}
  7078. \tty{IF} serves as an entry, evaluates the first expression, and assembles
  7079. block 1 if the expression is true (i.e. not 0).  All further
  7080. \tty{ELSEIF}-blocks will then be skipped.  However, if the expression is
  7081. false, block 1 will be skipped and expression 2 is evaluated.  If this
  7082. expression turns out to be true, block 2 is assembled.  The number of
  7083. \tty{ELSEIF} parts is variable and results in an \tty{IF-THEN-ELSE} ladder
  7084. of an arbitrary length.  The block assigned to the last \tty{ELSEIF}
  7085. (without argument) only gets assembled if all previous expressions
  7086. evaluated to false; it therefore forms a 'default' branch.  It is
  7087. important to note that only \bb{one} of the blocks will be assembled: the
  7088. first one whose \tty{IF/ELSEIF} had a true expression as argument.
  7089.  
  7090. The \tty{ELSEIF} parts are optional, i.e. \tty{IF} may directly be
  7091. followed by an \tty{ENDIF}.  An \tty{ELSEIF} without parameters must be
  7092. the last branch.
  7093.  
  7094. \tty{ELSEIF} always refers to the innermost, unfinished \tty{IF} construct
  7095. in case \tty{IF}'s are nested.
  7096.  
  7097. \ttindex{IFDEF}\ttindex{IFNDEF}\ttindex{IFUSED}\ttindex{IFNUSED}
  7098. \ttindex{IFEXIST}\ttindex{IFNEXIST}\ttindex{IFB}\ttindex{IFNB}
  7099. In addition to \tty{IF}, the following further conditional statements are
  7100. defined:
  7101. \begin{itemize}
  7102. \item{\tty{IFDEF $<$expressionl$>$}: true if the expression does not contain
  7103.      any symbols that are so far undefined.}
  7104. \item{\tty{IFNDEF $<$expression$>$}: counterpart to \tty{IFDEF}.}
  7105. \item{\tty{IFUSED $<$symbol$>$}: true if if the given symbol has been
  7106.      referenced at least once up to now.}
  7107. \item{\tty{IFNUSED $<$symbol$>$}: counterpart to \tty{IFUSED}.}
  7108. \item{\tty{IFEXIST $<$name$>$}: true if the given file exists.  The same
  7109.           rules for search paths and syntax apply as for the
  7110.           \tty{INCLUDE} instruction (see section \ref{SectInclude}).}
  7111. \item{\tty{IFNEXIST $<$name$>$}: counterpart to \tty{IFEXIST}.}
  7112. \item{\tty{IFB $<$arg-list$>$}: true if all arguments of the parameter
  7113.           list are empty strings.}
  7114. \item{\tty{IFNB $<$arg-list$>$}: counterpart to \tty{IFB}.}
  7115. \end{itemize}
  7116.  
  7117. It is valid to write {\tt ELSE} instead of {\tt ELSEIF} since everybody
  7118. seems to be used to it...
  7119.  
  7120. For every {IF...} statement, there has to be a corresponding {\tt ENDIF}.
  7121. 'Open' constructs will lead to an error message at the end of an assembly
  7122. path.  The way \asname{} has 'paired' {\tt ENDIF} statements with {\tt IF}s may
  7123. be deduced from the assembly listing: for {\tt ENDIF}, the line number of
  7124. the corresponding {\tt IF...} will be shown.
  7125.  
  7126. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7127.  
  7128. \subsection{SWITCH / CASE / ELSECASE / ENDCASE}
  7129. \ttindex{SWITCH}\ttindex{.SWITCH}\ttindex{SELECT}
  7130. \ttindex{CASE}\ttindex{ELSECASE}\ttindex{ENDCASE}
  7131.  
  7132. \tty{CASE} is a special case of \tty{IF} and is designed for situations
  7133. when an expression has to be compared with a couple of values.  This could
  7134. of course also be done with a series of \tty{ELSEIF}s, but the following
  7135. form
  7136. \begin{verbatim}
  7137.        SWITCH  <expression>
  7138.        .
  7139.        .
  7140.        CASE    <value 1>
  7141.        .
  7142.        <block 1>
  7143.        .
  7144.        CASE    <value 2>
  7145.        .
  7146.        <block 2>
  7147.        .
  7148.        (further CASE blocks)
  7149.        .
  7150.        CASE    <value n-1>
  7151.        .
  7152.        <block n-1>
  7153.        .
  7154.        ELSECASE
  7155.        .
  7156.        <block n>
  7157.        .
  7158.        ENDCASE
  7159. \end{verbatim}
  7160. has the advantage that the expression is only written once and also only
  7161. gets evaluated once.  It is therefore less error-prone and slightly faster
  7162. than an \tty{IF} chain, but obviously not as flexible.
  7163.  
  7164. It is possible to specify multiple values separated by commas to a
  7165. \tty{CASE} statement in order to assemble the following block in multiple
  7166. cases.  The \tty{ELSECASE} branch again serves as a 'trap' for the case
  7167. that none of the \tty{CASE} conditions was met.  \asname{} will issue a warning
  7168. in case it is missing and all comparisons fail.
  7169.  
  7170. Even when value lists of \tty{CASE} branches overlap, only \bb{one} branch
  7171. is executed, which is the first one in case of ambiguities.
  7172.  
  7173. \tty{SWITCH} only serves to open the whole construct; an arbitrary number
  7174. of statements may be between \tty{SWITCH} and the first \tty{CASE} (but
  7175. don't leave other \tty{IF}s open!), for the sake of better readability
  7176. this should however not be done.
  7177.  
  7178. In case that \tty{SWITCH} is already a machine instruction on the
  7179. selected processor target, the  construct may be openend via \tty{SELECT},
  7180. or by a leading period to explicitly invoke the pseudo instruction
  7181. (\tty{.SWITCH} instead of \tty{SWITCH}).
  7182.  
  7183. Similarly to {\tt IF} constructs, there must be exactly one {\tt ENDCASE}
  7184. for every {\tt SWITCH}.  Analogous to {\tt ENDIF}, for {\tt ENDCASE} the
  7185. line number of the corresponding {\tt SWITCH} is shown in the listing.
  7186.  
  7187. %%---------------------------------------------------------------------------
  7188.  
  7189. \section{Listing Control}
  7190.  
  7191. {\em valid for: all processors}
  7192.  
  7193. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7194.  
  7195. \subsection{PAGE, PAGESIZE}
  7196. \label{SectPAGE}
  7197. \ttindex{PAGE}\ttindex{.PAGE}\ttindex{PAGESIZE}
  7198.  
  7199. \tty{PAGE} is used to tell \asname{} the dimensions of the paper that is used to
  7200. print the assembly listing.  The first parameter is thereby the
  7201. number of lines after which \asname{} shall automatically output a form
  7202. feed.  One should however take into account that this value does \bb{not}
  7203. include heading lines including an eventual line specified with
  7204. \tty{TITLE}.  The minimum number of lines is 5, and the maximum value is
  7205. 255.  A specification of 0 has the result that \asname{} will not do any form
  7206. feeds except those triggered by a \tty{NEWPAGE} instruction or those
  7207. implicitly engaged at the end of the assembly listing (e.g. prior to the
  7208. symbol table).
  7209.  
  7210. The specification of the listing's length in characters is an
  7211. optional second parameter and serves two purposes: on the one hand,
  7212. the internal line counter of \asname{} will continue to run correctly when a
  7213. source line has to be split into several listing lines, and on
  7214. the other hand there are printers (like some laser printers) that do
  7215. not automatically wrap into a new line at line end but instead simply
  7216. discard the rest.  For this reason, \asname{} does line breaks by itself,
  7217. i.e. lines that are too long are split into chunks whose lengths are
  7218. equal to or smaller than the specified width.  This may lead to
  7219. double line feeds on printers that can do line wraps on their own if
  7220. one specifies the exact line width as listing width.  The solution
  7221. for such a case is to reduce the assembly listing's width by 1.  The
  7222. specified line width may lie between 5 and 255 characters; a line
  7223. width of 0 means similarly to the page length that \asname{} shall not do
  7224. any splitting of listing lines; lines that are too long of course
  7225. cannot be taken into account of the form feed then any more.
  7226.  
  7227. The default setting for the page length is 60 lines, the default for the
  7228. line width is 0; the latter value is also assumed when \tty{PAGE} is
  7229. called with only one parameter.
  7230.  
  7231. In case \tty{PAGE} is already a machine instruction on the
  7232. selected processor target, use instead \tty{PAGESIZE} to define
  7233. the paper size.  As an alternative, it is always possible to explicitly
  7234. invoke the pseudo instruction by prepending a period (\tty{.PAGE} instead
  7235. of \tty{PAGE}).
  7236.  
  7237. \bb{CAUTION!}  There is no way for \asname{} to check whether the specified
  7238. listing length and width correspond to the reality!
  7239.  
  7240. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7241.  
  7242. \subsection{NEWPAGE}
  7243. \ttindex{NEWPAGE}
  7244.  
  7245. \tty{NEWPAGE} can be used to force a line feed though the current line is
  7246. not full up to now.  This might be useful to separate program parts
  7247. in the listing that are logically different.  The internal line
  7248. counter is reset and the page counter is incremented by one.  The
  7249. optional parameter is in conjunction with a hierarchical page
  7250. numbering \asname{} supports up to a chapter depth of 4.  0 always refers to
  7251. the lowest depth, and the maximum value may vary during the assembly
  7252. run.  This may look a bit puzzling, as the following example shows:
  7253. \begin{quote}\begin{tabbing}
  7254. \hspace{2.5cm} \= \hspace{4.5cm} \= \kill
  7255. page 1,   \> instruction \tty{NEWPAGE 0} \>  $\rightarrow$ page 2 \\
  7256. page 2,   \> instruction \tty{NEWPAGE 1} \>  $\rightarrow$ page 2.1 \\
  7257. page 2.1, \> instruction \tty{NEWPAGE 1} \>  $\rightarrow$ page 3.1 \\
  7258. page 3.1, \> instruction \tty{NEWPAGE 0} \>  $\rightarrow$ page 3.2 \\
  7259. page 3.2, \> instruction \tty{NEWPAGE 2} \>  $\rightarrow$ page 4.1.1 \\
  7260. \end{tabbing}\end{quote}
  7261. \tty{NEWPAGE $<$number$>$} may therefore result in
  7262. changes in different digits, depending on the current chapter depth.  An
  7263. automatic form feed due to a line counter overflow or a \tty{NEWPAGE}
  7264. without parameter is equal to \tty{NEWPAGE 0}.  Previous to the output of
  7265. the symbol table, an implicit \tty{NEWPAGE $<$maximum up to now$>$} is
  7266. done to start a new 'main chapter'.
  7267.  
  7268. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7269.  
  7270. \subsection{MACEXP\_DFT and MACEXP\_OVR}
  7271. \ttindex{MACEXP}
  7272. \ttindex{MACEXP\_DFT}
  7273. \ttindex{MACEXP\_OVR}
  7274. \label{MACEXPDFT}
  7275. \label{MACEXPOVR}
  7276.  
  7277. Once a macro is tested and 'done', one might not want to see it
  7278. in the listing when it is used.  As described in the section about
  7279. defining and using macros (\ref{SectMacros}), additional arguments to
  7280. the \tty{MACRO} statement allow to control whether a macro's body is
  7281. expanded upon its usage and if yes, which parts of it.  In case that
  7282. several macros are defined in a row, it is not necessary to give
  7283. these directives for every single macro.  The pseudo instruction
  7284. \tty{MACEXP\_DFT} defines for all following macros which parts shall
  7285. be expanded upon invocation of the macro:
  7286. \begin{itemize}
  7287. \item{\tty{ON} resp. \tty{OFF} enable or disable expansion
  7288.      completely.}
  7289. \item{The arguments \tty{IF} resp. \tty{NOIF} enable or disable
  7290.      expansion of instructions for conditional assembly, plus
  7291.      the expansion of code parts the were excluded because of
  7292.      conditional assembly.}
  7293. \item{Macro definitions (which includes \tty{REPT}, \tty{WHILE}
  7294.      and \tty{IRP(C)}) may be excluded from or included in the
  7295.      expanded parts via the arguments \tty{MACRO} resp.
  7296.      \tty{NOMACRO}.}
  7297. \item{All other lines not fitting into the first two categories
  7298.      may be excluded from or included in the expanded parts via
  7299.      the arguments \tty{REST} resp. \tty{NOREST}.}
  7300. \end{itemize}
  7301. The default is \tty{ON}, i.e. defined macros will be expanded
  7302. completely, of course unless specific expansion arguments were given
  7303. to individual macros.  Furthermore, arguments given to
  7304. \tty{MACEXP\_DFT} work relative to the current setting: for instance,
  7305. if expansion is turned on completely initially, the statement
  7306. \begin{verbatim}
  7307.         MACEXP_DFT  noif,nomacro
  7308. \end{verbatim}
  7309. has the result that for macros defined in succession, only code parts
  7310. that are no macro definition and that are not excluded via
  7311. conditional assembly will be listed.
  7312. \par
  7313. This instruction plus the per-macro directives provide fine-grained
  7314. per-macro over the parts being expanded.  However, there may be cases
  7315. in practice where one wants to see the expanded code of a macro at
  7316. one place and not at the other.  This is possible by using the
  7317. statement \tty{MACEXP\_OVR}: it accepts the same arguemnts like
  7318. \tty{MACEXP\_DFT}, these however act as overrides for all macros being
  7319. {\em expanded} in the following code.  This is in contrast to
  7320. \tty{MACEXP\_DFT} which influences macros being {\em defined} in the
  7321. following code.  For instance, if one defined for a macro that
  7322. neither macro definitions nor conditional assembly shall be expanded
  7323. in the listing, a
  7324. \begin{verbatim}
  7325.         MACEXP_OVR  MACRO
  7326. \end{verbatim}
  7327. re-enables expansion of macro definitions for its following usages,
  7328. while a
  7329. \begin{verbatim}
  7330.         MACEXP_OVR  ON
  7331. \end{verbatim}
  7332. forces expansion of the complete macro body in the listing.
  7333. \tty{MACEXP\_OVR} without arguments again disables all overrides,
  7334. macros will again behave as individually specified upon definition.
  7335. \par
  7336. Both statements also have an effect on other macro-like constructs
  7337. (\tty{REPT, IRP, IRPC WHILE}).  However, since these are expanded
  7338. only one and ,,in-place'', the functional difference of these two
  7339. statements becomes minimal.  In case of differences, the override set
  7340. via \tty{MACEXP\_OVR} has a higher priority.
  7341.  
  7342. The Setting currently made via \tty{MACEXP\_DFT} may be read from the
  7343. predefined symbol \tty{MACEXP}.  For backward compatibility reasons,
  7344. it is possible to use the statement \tty{MACEXP} instead of
  7345. \tty{MACEXP\_DFT}.  However, one should not make use of this in new
  7346. programs.
  7347.  
  7348. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7349.  
  7350. \subsection{LISTING}
  7351. \ttindex{LISTING}
  7352.  
  7353. works like \tty{MACEXP} and accepts the same parameters, but is much more
  7354. radical: After a
  7355. \begin{verbatim}
  7356.        listing off   ,
  7357. \end{verbatim}
  7358. nothing at all will be written to the listing.  This directive makes sense
  7359. for tested code parts or include files to avoid a paper consumption going
  7360. beyond all bounds.  \bb{CAUTION!} If one forgets to issue the counterpart
  7361. somewhere later, even the symbol table will not be written any more!  In
  7362. addition to \tty{ON} and \tty{OFF}, \tty{LISTING} also accepts
  7363. \tty{NOSKIPPED} and \tty{PURECODE} as arguments.  Program parts that were
  7364. not assembled due to conditional assembly will not be written to the
  7365. listing when \tty{NOSKIPPED} is set, while \tty{PURECODE} - as the name
  7366. indicates - even suppresses the \tty{IF} directives themselves in the
  7367. listing.  These options are useful if one uses macros that act differently
  7368. depending on parameters and one only wants to see the used parts in the
  7369. listing.
  7370.  
  7371. The current setting may be read from the symbol \tty{LISTING} (0=\tty{OFF},
  7372. 1=\tty{ON}, 2=\tty{NOSKIPPED}, 3=\tty{PURECODE}).
  7373.  
  7374. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7375.  
  7376. \subsection{PRTINIT and PRTEXIT}
  7377. \ttindex{PRTINIT}\ttindex{PRTEXIT}
  7378.  
  7379. Quite often it makes sense to switch to another printing mode (like
  7380. compressed printing) when the listing is sent to a printer and to
  7381. deactivate this mode again at the end of the listing.  The output of
  7382. the needed control sequences can be automated with these instructions
  7383. if one specifies the sequence that shall be sent to the output device
  7384. prior to the listing with \tty{PRTINIT $<$string$>$} and similarly the
  7385. deinitialization string with \tty{PRTEXIT $<$string$>$}.
  7386. \tty{$<$string$>$} has to be a string expression in both cases.  The syntax
  7387. rules for string constants allow to insert control characters into the
  7388. string without too much tweaking.
  7389.  
  7390. When writing the listing, the assembler does \bb{not} differentiate where
  7391. the listing actually goes, i.e. printer control characters are sent to the
  7392. screen without mercy!
  7393.  
  7394. Example:
  7395.  
  7396. For Epson printers, it makes sense to switch them to compressed
  7397. printing because listings are so wide.  The lines
  7398. \begin{verbatim}
  7399.        prtinit "\15"
  7400.        prtexit "\18"
  7401. \end{verbatim}
  7402. assure that the compressed mode is turned on at the beginning of the
  7403. listing and turned off afterwards.
  7404.  
  7405. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7406.  
  7407. \subsection{TITLE}
  7408. \ttindex{TITLE}
  7409.  
  7410. The assembler normally adds a header line to each page of the listing
  7411. that contains the source file's name, date, and time.  This
  7412. statement allows to extend the page header by an arbitrary additional
  7413. line.  The string that has to be specified is an arbitrary string
  7414. expression.
  7415.  
  7416. Example:
  7417.  
  7418. For the Epson printer already mentioned above, a title line shall be
  7419. written in wide mode, which makes it necessary to turn off the
  7420. compressed mode before:
  7421. \begin{verbatim}
  7422.        title   "\18\14Wide Title\15"
  7423. \end{verbatim}
  7424. (Epson printers automatically turn off the wide mode at the end of a
  7425. line.)
  7426.  
  7427. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7428.  
  7429. \subsection{RADIX}
  7430. \ttindex{RADIX}
  7431. \ttindex{DECIMAL}
  7432. \ttindex{OCTAL}
  7433.  
  7434. \tty{RADIX} with a numerical argument between 2 and 36 sets the default
  7435. numbering system for integer constants, i.e. the numbering system used if
  7436. nothing else has been stated explicitly.  The default is 10, and there are
  7437. some possible pitfalls to keep in mind which are described in section
  7438. \ref{SectIntConsts}.
  7439.  
  7440. Independent of the current setting, the argument of {\tt RADIX} is {\em
  7441. always decimal}; furthermore, no symbolic or formula expressions may be
  7442. used as argument. Only use simple constant numbers!
  7443.  
  7444. A {\tt RADIX} statement overrides a setting given by a {\tt -radix}
  7445. command line switch.
  7446.  
  7447. If the IM61x0 is the current target, the instructions \tty{DECIMAL} and
  7448. \tty{OCTAL} are available as shortforms for \tty{RADIX 10} respectively
  7449. \tty{RADIX 8}.
  7450.  
  7451. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7452.  
  7453. \subsection{OUTRADIX}
  7454. \ttindex{OUTRADIX}
  7455.  
  7456. \tty{OUTRADIX} can in a certain way be regarded as the opposite to
  7457. \tty{RADIX}: This statement allows to configure which numbering system to
  7458. use for integer results when \verb!\{...}! constructs are used in string
  7459. constants (see section \ref{SectStringConsts}).  Valid arguments range
  7460. again from 2 to 36, while the default is 16.
  7461.  
  7462. %%---------------------------------------------------------------------------
  7463.  
  7464. \section{Local Symbols}
  7465. \label{ChapLocSyms}
  7466.  
  7467. {\em valid for: all processors}
  7468.  
  7469. local symbols and the section concept introduced with them are a
  7470. completely new function that was introduced with version 1.39.  One
  7471. could say that this part is version ''1.0'' and therefore probably not
  7472. the optimum.  Ideas and (constructive) criticism are therefore
  7473. especially wanted.  I admittedly described the usage of sections how
  7474. I imagined it.  It is therefore possible that the reality is not
  7475. entirely equal to the model in my head.  I promise that in case of
  7476. discrepancies, changes will occur that the reality gets adapted to
  7477. the documentation and not vice versa (I was told that the latter
  7478. sometimes takes place in larger companies...).
  7479.  
  7480. \asname{} does not generate linkable code (and this will probably not change
  7481. in the near future \tty{:-(}).  This fact forces one to always assemble a
  7482. program in a whole.  In contrast to this technique, a separation into
  7483. linkable modules would have several advantages:
  7484. \begin{itemize}
  7485. \item{shorter assembly times as only the modified modules have to be
  7486.      reassembled;}
  7487. \item{the option to set up defined interfaces among modules by definition
  7488.      of private and public symbols;}
  7489. \item{the smaller length of the individual modules reduces the number of
  7490.      symbols per module and therefore allows to use shorter symbol names
  7491.      that are still unique.}
  7492. \end{itemize}
  7493. Especially the last item was something that always nagged me: once
  7494. there was a label's name defined at the beginning of a 2000-lines
  7495. program, there was no way to reuse it somehow - even not at the
  7496. file's other end where routines with a completely different context
  7497. were placed.  I was forced to use concatenated names in the style of
  7498. \begin{verbatim}
  7499.   <subprogram name>_<symbol name>
  7500. \end{verbatim}
  7501. that had lengths ranging from 15 to 25 characters and made the
  7502. program difficult to overlook.  The concept of section described in
  7503. detail in the following text was designed to cure at least the second
  7504. and third item of the list above.  It is completely optional: if you
  7505. do not want to use sections, simply forget them and continue to work
  7506. like you did with previous versions of \asname{}.
  7507.  
  7508. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7509.  
  7510. \subsection{Basic Definition (SECTION/ENDSECTION)}
  7511. \ttindex{SECTION}\ttindex{ENDSECTION}
  7512.  
  7513. A section represents a part of the assembler program enclosed by
  7514. special statements and has a unique name chosen by the programmer:
  7515. \begin{verbatim}
  7516.        .
  7517.        .
  7518.        <other code>
  7519.        .
  7520.        .
  7521.        SECTION <section's name>
  7522.        .
  7523.        .
  7524.        <code inside of the section>
  7525.        .
  7526.        .
  7527.        ENDSECTION [section's name]
  7528.        .
  7529.        .
  7530.        <other code>
  7531.        .
  7532.        .
  7533. \end{verbatim}
  7534. The name of a section must conform to the conventions for s symbol
  7535. name; \asname{} stores section and symbol names in separate tables which is
  7536. the reason why a name may be used for a symbol and a section at the
  7537. same time.  Section names must be unique in a sense that there must
  7538. not be more than one section on the same level with the same name (I
  7539. will explain in the next part what ''levels'' mean).  The argument of
  7540. \tty{ENDSECTION} is optional, it may also be omitted; if it is omitted, \asname{}
  7541. will show the section's name that has been closed with this
  7542. \tty{ENDSECTION}.  Code inside a section will be processed by \asname{} exactly
  7543. as if it were outside, except for three decisive differences:
  7544. \begin{itemize}
  7545. \item{Symbols defined within a section additionally get an internally
  7546.      generated number that corresponds to the section.  These symbols
  7547.      are not accessible by code outside the section (this can be
  7548.      changed by pseudo instructions, later more about this).}
  7549. \item{The additional attribute allows to define symbols of the same
  7550.      name inside and outside the section; the attribute makes it
  7551.      possible to use a symbol name multiple times without getting error
  7552.      messages from \asname{}.}
  7553. \item{If a symbol of a certain name has been defined inside and outside
  7554.      of a section, the ''local'' one will be preferred inside the
  7555.      section, i.e. \asname{} first searches the symbol table for a symbol of
  7556.      the referenced name that also was assigned to the section.  A
  7557.      search for a global symbol of this name only takes place if the
  7558.      first search fails.}
  7559. \end{itemize}
  7560. This mechanism e.g. allows to split the code into modules as one
  7561. might have done it with linkable code.  A more fine-grained approach
  7562. would be to pack every routine into a separate section.  Depending on
  7563. the individual routines' lengths, the symbols for internal use may
  7564. obtain very short names.
  7565.  
  7566. \asname{} will by default not differentiate between upper and lower case in
  7567. section names; if one however switches to case-sensitive mode, the
  7568. case will be regarded just like for symbols.
  7569.  
  7570. The organization described up to now roughly corresponds to what is
  7571. possible in the C language that places all functions on the same
  7572. level.  However, as my ''high-level'' ideal was Pascal and not C, I
  7573. went one step further:
  7574.  
  7575. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7576.  
  7577. \subsection{Nesting and Scope Rules}
  7578.  
  7579. It is valid to define further sections within a section.  This is
  7580. analog to the option given in Pascal to define procedures inside a
  7581. procedure or function.  The following example shows this:
  7582. \begin{verbatim}
  7583. sym     EQU        0
  7584.  
  7585.        SECTION    ModuleA
  7586.  
  7587.         SECTION    ProcA1
  7588.  
  7589. sym       EQU        5
  7590.  
  7591.         ENDSECTION ProcA1
  7592.  
  7593.         SECTION    ProcA2
  7594.  
  7595. sym       EQU        10
  7596.  
  7597.         ENDSECTION ProcA2
  7598.  
  7599.        ENDSECTION ModuleA
  7600.  
  7601.  
  7602.        SECTION    ModuleB
  7603.  
  7604. sym      EQU        15
  7605.  
  7606.         SECTION    ProcB
  7607.  
  7608.         ENDSECTION ProcB
  7609.  
  7610.        ENDSECTION ModuleB
  7611. \end{verbatim}
  7612. When looking up a symbol, \asname{} first searches for a symbol assigned to
  7613. the current section, and afterwards traverses the list of parent
  7614. sections until the global symbols are reached.  In our example, the
  7615. individual sections see the values given in table \ref{TabSymErg} for
  7616. the symbol \tty{sym}:
  7617. \begin{table*}[htb]
  7618. \begin{center}\begin{tabular}{|l|l|l|}
  7619. \hline
  7620. section        &   value &   from section... \\
  7621. \hline
  7622. \hline
  7623. Global         &     0   &   Global \\
  7624. \hline
  7625. \tty{ModuleA}  &     0   &   Global \\
  7626. \hline
  7627. \tty{ProcA1}   &     5   &   \tty{ProcA1} \\
  7628. \hline
  7629. \tty{ProcA2}   &    10   &   \tty{ProcA2} \\
  7630. \hline
  7631. \tty{ModuleB}  &    15   &   \tty{ModuleB} \\
  7632. \hline
  7633. \tty{ProcB}    &    15   &   \tty{ModuleB} \\
  7634. \hline
  7635. \end{tabular}\end{center}
  7636. \caption{Valid values for the Individual Sections\label{TabSymErg}}
  7637. \end{table*}
  7638. This rule can be overridden by explicitly appending a section's name
  7639. to the symbol's name.  The section's name has to be enclosed in
  7640. brackets:
  7641. \begin{verbatim}
  7642.        move.l  #sym[ModulB],d0
  7643. \end{verbatim}
  7644. Only sections that are in the parent section path of the current
  7645. section may be used.  The special values \tty{PARENT0..PARENT9} are allowed
  7646. to reference the n-th ''parent'' of the current section; \tty{PARENT0} is
  7647. therefore equivalent to the current section itself, \tty{PARENT1} the
  7648. direct parent and so on.  \tty{PARENT1} may be abbreviated as \tty{PARENT}.  If
  7649. no name is given between the brackets, like in this example:
  7650. \begin{verbatim}
  7651.        move.l  #sym[],d0 ,
  7652. \end{verbatim}
  7653. one reaches the global symbol.  \bb{CAUTION!}  If one explicitly
  7654. references a symbol from a certain section, \asname{} will only seek for
  7655. symbols from this section, i.e. the traversal of the parent sections
  7656. path is omitted!
  7657.  
  7658. Similar to Pascal, it is allowed that different sections have
  7659. subsections of the same name; the principle of locality avoids
  7660. irritations.  One should IMHO still use this feature as seldom as
  7661. possible: Symbols listed in the symbol resp. cross reference list are
  7662. only marked with the section they are assigned to, not with the
  7663. ''section hierarchy'' lying above them (this really would have busted
  7664. the available space); a differentiation is made very difficult this
  7665. way.
  7666.  
  7667. As a \tty{SECTION} instruction does not define a label by itself, the
  7668. section concept has an important difference to Pascal's concept of
  7669. nested procedures: a pascal procedure can automatically ''see'' its
  7670. subprocedures(functions), \asname{} requires an explicit definition of an
  7671. entry point.  This can be done e.g. with the following macro pair:
  7672. \begin{verbatim}
  7673. proc    MACRO   name
  7674.        SECTION name
  7675. name    LABEL   $
  7676.        ENDM
  7677.  
  7678. endp    MACRO   name
  7679.        ENDSECTION name
  7680.        ENDM
  7681. \end{verbatim}
  7682. This example also shows that the locality of labels inside macros
  7683. is not influenced by sections.  It makes the trick with the \tty{LABEL}
  7684. instruction necessary.
  7685.  
  7686. This does of course not solve the problem completely.  The label is
  7687. still local and not referencable from the outside.  Those who think
  7688. that it would suffice to place the label in front of the \tty{SECTION}
  7689. statement should be quiet because they would spoil the bridge to the
  7690. next theme:
  7691.  
  7692. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7693.  
  7694. \subsection{PUBLIC and GLOBAL}
  7695. \ttindex{PUBLIC}\ttindex{GLOBAL}
  7696.  
  7697. The \tty{PUBLIC} statement allows to change the assignment of a symbol to
  7698. a certain section.  It is possible to treat multiple symbols with one
  7699. statement, but I will use an example with only one symbol in the following
  7700. (not hurting the generality of this discussion).  In the simplest case,
  7701. one declares a symbol to be global, i.e. it can be referenced from
  7702. anywhere in the program:
  7703. \begin{verbatim}
  7704.        PUBLIC  <name>
  7705. \end{verbatim}
  7706. As a symbol cannot be moved in the symbol table once it has been sorted
  7707. in, this statement has to appear \bb{before} the symbol itself is
  7708. defined.  \asname{} stores all \tty{PUBLICs} in a list and removes an entry from
  7709. this list when the corresponding symbol is defined.  \asname{} prints errors at
  7710. the end of a section in case that not all \tty{PUBLICs} have been
  7711. resolved.
  7712.  
  7713. Regarding the hierarchical section concept, the method of defining a
  7714. symbol as purely global looks extremely brute.  There is fortunately
  7715. a way to do this in a bit more differentiated way: by appending a
  7716. section name:
  7717. \begin{verbatim}
  7718.        PUBLIC  <name>:<section>
  7719. \end{verbatim}
  7720. The symbol will be assigned to the referenced section and therefore also
  7721. becomes accessible for all its subsections (except they define a symbol of
  7722. the same name that hides the ''more global'' symbol).  \asname{} will naturally
  7723. protest if several subsections try to export a symbol of same name to the
  7724. same level.  The special \tty{PARENTn} values mentioned in the previous
  7725. section are also valid for \tty{$<$section$>$} to export a symbol exactly
  7726. \tty{n} levels up in the section hierarchy.  Otherwise only sections that
  7727. are parent sections of the current section are valid for
  7728. \tty{$<$section$>$}.  Sections that are in another part of the section
  7729. tree are not allowed.  If several sections in the parent section path
  7730. should have the same name (this is possible), the lowest level will be
  7731. taken.
  7732.  
  7733. This tool lets the abovementioned macro become useful:
  7734. \begin{verbatim}
  7735. proc    MACRO   name
  7736.        SECTION name
  7737.        PUBLIC  name:PARENT
  7738. name    LABEL   $
  7739.        ENDM
  7740. \end{verbatim}
  7741. This setting is equal to the Pascal model that also only allows the
  7742. ''father'' to see its children, but not the ''grandpa''.
  7743.  
  7744. \asname{} will quarrel about double-defined symbols if more than one section
  7745. attempts to export a symbol of a certain name to the same upper section.
  7746. This is by itself a correct reaction, and one needs to ''qualify'' symbols
  7747. somehow to make them distinguishable if these exports were deliberate.  A
  7748. \tty{GLOBAL} statement does just this.  The syntax of \tty{GLOBAL} is
  7749. identical to \tty{PUBLIC}, but the symbol stays local instead of being
  7750. assigned to a higher section.  Instead, an additional symbol of the same
  7751. value but with the subsection's name appended to the symbol's name is
  7752. created, and only this symbol is made public according to the section
  7753. specification.  If for example two sections \tty{A} and \tty{B} both
  7754. define a symbol named \tty{SYM} and export it with a \tty{GLOBAL}
  7755. statement to their parent section, the symbols are sorted in under the
  7756. names \tty{A\_SYM} resp. \tty{B\_SYM} .
  7757.  
  7758. In case that source and target section are separated by more than one
  7759. level, the complete name path is prepended to the symbol name.
  7760.  
  7761. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7762.  
  7763. \subsection{FORWARD}
  7764. \ttindex{FORWARD}
  7765.  
  7766. The model described so far may look beautiful, but there is an
  7767. additional detail not present in Pascal that may spoil the happiness:
  7768. Assembler allows forward references.  Forward references may lead to
  7769. situations where \asname{} accesses a symbol from a higher section in the
  7770. first pass.  This is not a disaster by itself as long as the correct
  7771. symbol is used in the second pass, but accidents of the following
  7772. type may happen:
  7773. \begin{verbatim}
  7774. loop:   .
  7775.        <code>
  7776.        .
  7777.        .
  7778.        SECTION sub
  7779.        .               ; ***
  7780.        .
  7781.        bra.s   loop
  7782.        .
  7783.        .
  7784. loop:   .
  7785.        .
  7786.        ENDSECTION
  7787.        .
  7788.        .
  7789.        jmp     loop    ; main loop
  7790. \end{verbatim}
  7791. \asname{} will take the global label \tty{loop} in the first pass and will
  7792. quarrel about an out-of-branch situation if the program part at
  7793. \tty{$<$code$>$} is long enough.  The second pass will not be
  7794. started at all.  One way to avoid the ambiguity would be to
  7795. explicitly specify the symbol's section:
  7796. \begin{verbatim}
  7797.        bra.s   loop[sub]
  7798. \end{verbatim}
  7799. If a local symbol is referenced several times, the brackets can be saved
  7800. by using a \tty{FORWARD} statement.  The symbol is thereby explicitly
  7801. announced to be local, and \asname{} will only look in the local symbol table
  7802. part when this symbol is referenced.  For our example, the statement
  7803. \begin{verbatim}
  7804.        FORWARD loop
  7805. \end{verbatim}
  7806. should be placed at the position marked with \tty{***}.
  7807.  
  7808. \tty{FORWARD} must not only be stated prior to a symbol's definition, but
  7809. also prior to its first usage in a section to make sense.  It does not
  7810. make sense to define a symbol private and public; this will be regarded as
  7811. an error by \asname{}.
  7812.  
  7813. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7814.  
  7815. \subsection{Performance Aspects}
  7816.  
  7817. The multi-stage lookup in the symbol table and the decision to which
  7818. section a symbol shall be assigned of course cost a bit of time to
  7819. compute.  An 8086 program of 1800 lines length for example took 34.5
  7820. instead of 33 seconds after a modification to use sections (80386 SX,
  7821. 16MHz, 3 passes).  The overhead is therefore limited.  As it has
  7822. already been stated at the beginning, is is up to the programmer if
  7823. (s)he wants to accept it.  One can still use \asname{} without sections.
  7824.  
  7825. %%---------------------------------------------------------------------------
  7826.  
  7827. \section{Miscellaneous}
  7828.  
  7829. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7830.  
  7831. \subsection{SHARED}
  7832. \label{ChapShareOrder}
  7833. \ttindex{SHARED}
  7834.  
  7835. {\em valid for: all processors}
  7836.  
  7837. This statement instructs \asname{} to write the symbols given in the
  7838. parameter list (regardless if they are integer, float or string
  7839. symbols) together with their values into the share file.  It depends
  7840. upon the command line parameters described in section
  7841. \ref{SectCallConvention} whether such a file is generated at all and in
  7842. which format it is written.  If \asname{} detects this instruction and no share
  7843. file is generated, a warning is the result.
  7844.  
  7845. \bb{CAUTION!}  A comment possibly appended to the statement itself will be
  7846. copied to the first line outputted to the share file (if \tty{SHARED}'s
  7847. argument list is empty, only the comment will be written).  In case a
  7848. share file is written in C or Pascal format, one has to assure that
  7849. the comment itself does not contain character sequences that close
  7850. the comment (''*/'' resp. ''*)'').  \asname{} does not check for this!
  7851.  
  7852. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7853.  
  7854. \subsection{INCLUDE}
  7855. \label{SectInclude}
  7856. \ttindex{INCLUDE}
  7857.  
  7858. {\em valid for: all processors}
  7859.  
  7860. This instruction inserts the file given as a parameter into the just as
  7861. if it would have been inserted with an editor (the file name may
  7862. optionally be enclosed with '' characters).  This instruction is
  7863. useful to split source files that would otherwise not fit into the
  7864. editor or to create ''tool boxes''.
  7865.  
  7866. In case that the file name does not have an extension, an extension
  7867. of \tty{INC} is assumed in a firstg step.  Only if no sch file
  7868. exists, or if the specified name contains a period (and therefore an
  7869. extension), a file of exactly this name is searched for.
  7870.  
  7871. The assmebler primarily tries to open the file in the directory
  7872. containing the source file with the \tty{INCLUDE} statenemt.  This
  7873. means that a path contained in the file specification is relative
  7874. to this file's directory, not to the directory the assembler was
  7875. called from.  Via the \tty{-i $<$path list$>$} option, one can
  7876. specify a list of directories that will automatically be searched
  7877. for the file.  If the file is not found, a \bb{fatal} error occurs,
  7878. i.e. assembly terminates immediately.
  7879.  
  7880. For compatibility reasons, it is valid to enclose the file name in ''
  7881. characters, i.e.
  7882. \begin{verbatim}
  7883.        include stddef51
  7884. \end{verbatim}
  7885. and
  7886. \begin{verbatim}
  7887.        include "stddef51.inc"
  7888. \end{verbatim}
  7889. are equivalent.  \bb{CAUTION!} This freedom of choice is the reason why
  7890. only a string constant but no string expression is allowed!
  7891.  
  7892. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7893.  
  7894. \subsection{BINCLUDE}
  7895. \ttindex{BINCLUDE}
  7896.  
  7897. {\em valid for: all processors}
  7898.  
  7899. \tty{BINCLUDE} can be used to embed binary data generated by other programs
  7900. into the code generated by \asname{} (this might theoretically even be code
  7901. created by \asname{} itself...).  \tty{BINCLUDE} has three forms:
  7902. \begin{verbatim}
  7903.        BINCLUDE <file>
  7904. \end{verbatim}
  7905. This way, the file is completely included.
  7906. \begin{verbatim}
  7907.        BINCLUDE <file>,<offset>
  7908. \end{verbatim}
  7909. This way, the file's contents are included starting at \tty{<offset>} up to
  7910. the file's end.
  7911. \begin{verbatim}
  7912.        BINCLUDE <file>,<offset>,<length>
  7913. \end{verbatim}
  7914. This way, \tty{$<$length$>$} bytes are included starting at
  7915. \tty{$<$offset$>$}.
  7916.  
  7917. The same rules regarding search paths and assumed suffixes apply as for
  7918. \tty{INCLUDE}.
  7919.  
  7920. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7921.  
  7922. \subsection{MESSAGE, WARNING, ERROR, and FATAL}
  7923. \ttindex{MESSAGE}\ttindex{WARNING}\ttindex{ERROR}\ttindex{FATAL}
  7924. {\em valid for: all processors}
  7925.  
  7926. Though the assembler checks source files as strict as possible and
  7927. delivers differentiated error messages, it might be necessary from
  7928. time to time to issue additional error messages that allow an
  7929. automatic check for logical error.  The assembler distinguishes
  7930. among three different types of error messages that are accessible to
  7931. the programmer via the following three instructions:
  7932. \begin{itemize}
  7933. \item{\tty{WARNING}: Errors that hint at possibly wrong or inefficient
  7934.      code.  Assembly continues and a code file is generated.}
  7935. \item{\tty{ERROR}: True errors in a program.  Assembly continues to
  7936.      allow detection of possible further errors in the same pass.
  7937.      A code file is not generated.}
  7938. \item{\tty{FATAL}: Serious errors that force an immediate termination
  7939.      of assembly.  A code file may be generated but will be incomplete.}
  7940. \end{itemize}
  7941. All three instructions have the same format for the message that shall
  7942. be issued: an arbitrary string expression, which may be a simple string
  7943. constant, but as well a complex expression that evaluates to a string.
  7944. It also includes the feature to embed symbol values in strings, which
  7945. is described in \ref{SectSymConv}:
  7946. \begin{verbatim}
  7947.       message "Start Address is \{start_address}"
  7948. \end{verbatim}
  7949. Instructions generating warnings or errors typically only make sense
  7950. in conjunction wit conditional assembly.  For example, if there is
  7951. only a limited address space for a program, one can test for overflow
  7952. in the following way:
  7953. \begin{verbatim}
  7954. ROMSize equ     8000h   ; 27256 EPROM
  7955.  
  7956. ProgStart:
  7957.        .
  7958.        .
  7959.        <the program itself>
  7960.        .
  7961.        .
  7962. ProgEnd:
  7963.  
  7964.        if      ProgEnd-ProgStart>ROMSize
  7965.         error  "\athe program is too long!"
  7966.        endif
  7967. \end{verbatim}
  7968. Apart from the instructions generating errors, there is also an
  7969. instruction \tty{MESSAGE} that simply prints a message to the assembly
  7970. listing and th ecosole (the latter only if the quiet mode is not used).
  7971. Its usage is equal to the other three instructions.
  7972.  
  7973. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  7974.  
  7975. \subsection{READ}
  7976. \ttindex{READ}
  7977.  
  7978. {\em valid for: all processors}
  7979.  
  7980. One could say that \tty{READ} is the counterpart to the previous
  7981. instruction group: it allows to read values from the keyboard during
  7982. assembly.  You might ask what this is good for.  I will break with
  7983. the previous principles and put an example before the exact
  7984. description to outline the usefulness of this instruction:
  7985.  
  7986. A program needs for data transfers a buffer of a size that should be
  7987. set at assembly time.  One could store this size in a symbol defined
  7988. with \tty{EQU}, but it can also be done interactively with \tty{READ}:
  7989. \begin{verbatim}
  7990.        IF      MomPass=1
  7991.         READ    "buffer size",BufferSize
  7992.        ENDIF
  7993. \end{verbatim}
  7994. Programs can this way configure themselves dynamically during assembly
  7995. and one could hand over the source to someone who can assemble it
  7996. without having to dive into the source code.  The \tty{IF} conditional
  7997. shown in the example should always be used to avoid bothering the
  7998. user multiple times with questions.
  7999.  
  8000. \tty{READ} is quite similar to \tty{SET} with the difference that the
  8001. value is read from the keyboard instead of the instruction's arguments.
  8002. This for example also implies that \asname{} will automatically set the symbol's
  8003. type (integer, float or string) or that it is valid to enter formula
  8004. expressions instead of a simple constant.
  8005.  
  8006. \tty{READ} may either have one or two parameters because the prompting
  8007. message is optional.  \asname{} will print a message constructed from the
  8008. symbol's name if it is omitted.
  8009.  
  8010. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  8011.  
  8012. \subsection{INTSYNTAX}
  8013. \label{SectINTSYNTAX}
  8014. \ttindex{INTSYNTAX}
  8015.  
  8016. {\em valid for: all processors}
  8017.  
  8018. This instruction allows to modify the set of notations for integer constants
  8019. in various number systems. - After selection of a CPU target, a certain default
  8020. set is installed (see section \ref{SectPseudoInst}).  This set may be augmented
  8021. with other notations, or notations may be removed from it.  \tty{INTSYNTAX}
  8022. takes an arbitrary list of arguments which either begin with a plus or minus
  8023. character, followed by the notation's identifier.  For instance, the following
  8024. statement
  8025. \begin{verbatim}
  8026.       INTSYNTAX    -0oct,+0hex
  8027. \end{verbatim}
  8028. has the result that a leading zero marks a hexadecimal instead of an octal
  8029. constant, a common usage on some assemblers for the SC/MP.  The identifiers
  8030. for all notations can be found in table \ref{TabSystems}.  There is no limit on
  8031. combining notations, except when they contradict each other.  For instance, it
  8032. would not be allowed to enable \tty{0oct} and \tty{0hex} at the same time.
  8033.  
  8034. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  8035.  
  8036. \subsection{RELAXED}
  8037. \label{SectRELAXED}
  8038. \ttindex{RELAXED}
  8039.  
  8040. {\em valid for: all processors}
  8041.  
  8042. By default, \asname{} assigns a distinct syntax for integer constants to a
  8043. processor family (which is in general equal to the manufacturer's
  8044. specifications, as long as the syntax is not too bizarre...).
  8045. Everyone however has his own preferences for another syntax and may
  8046. well live with the fact that his programs cannot be translated any
  8047. more with the standard assembler.  If one places the instruction
  8048. \begin{verbatim}
  8049.        RELAXED ON
  8050. \end{verbatim}
  8051. right at the program's beginning, one may furtherly use any syntax
  8052. for integer constants, even mixed in a program.  \asname{} tries to guess
  8053. automatically for every expression the syntax that was used.  This
  8054. automatism does not always deliver the result one might have in mind,
  8055. and this is also the reason why this option has to be enable
  8056. explicitly: if there are no prefixes or postfixes that unambiguously
  8057. identify either Intel or Motorola syntax, the C mode will be used.
  8058. Leading zeroes that are superfluous in other modes have a meaning in
  8059. this mode:
  8060. \begin{verbatim}
  8061.        move.b  #08,d0
  8062. \end{verbatim}
  8063. This constant will be understood as an octal constant and will result
  8064. in an error message as octal numbers may only contain digits from 0
  8065. to 7.  One might call this a lucky case; a number like 077 would
  8066. result in trouble without getting a message about this.  Without the
  8067. relaxed mode, both expressions unambiguously would have been
  8068. identified as decimal constants.
  8069.  
  8070. The current setting may be read from a symbol with the same name.
  8071.  
  8072. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  8073.  
  8074. \subsection{COMPMODE}
  8075. \label{SectCompMode}
  8076. \ttindex{COMPMODE}
  8077.  
  8078. {\em valid for: various processors}
  8079.  
  8080. Though the assember strives to behave like the correspondig "original
  8081. assemblers", there are cases when emulating the original assembler's
  8082. behaviour would forbid code optimizations which are valid and useful in
  8083. my opinion.  Use the statement
  8084. \begin{verbatim}
  8085.        compmode on
  8086. \end{verbatim}
  8087. to switch to a 'compatibility mode' which prioritizes 'original behaviour'
  8088. to most efficient code.  See the respective section with processor-specific
  8089. hints whether there are any situations for the specific target.
  8090. \par
  8091. Compatibility mode is disabled by default, unless it was activated by the
  8092. command line switch of same name.  The current setting may be read from a
  8093. symbol with the same name.
  8094.  
  8095. %%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  8096.  
  8097. \subsection{END}
  8098. \ttindex{END}
  8099.  
  8100. {\em valid for: all processors}
  8101.  
  8102. \tty{END} marks the end of an assembler program.  Lines that eventually
  8103. follow in the source file will be ignored.  \bb{IMPORTANT:} \tty{END} may
  8104. be called from within a macro, but the \tty{IF}-stack for conditional
  8105. assembly is not cleared automatically.  The following construct therefore
  8106. results in an error:
  8107. \begin{verbatim}
  8108.        IF      DontWantAnymore
  8109.         END
  8110.        ELSEIF
  8111. \end{verbatim}
  8112. \tty{END} may optionally have an integer expression as argument that marks
  8113. the program's entry point.  \asname{} stores this in the code file with a special
  8114. record and it may be post-processed e.g. with P2HEX.
  8115.  
  8116. \tty{END} has always been a valid instruction for \asname{}, but the only reason
  8117. for this in earlier releases of \asname{} was compatibility; \tty{END} had no
  8118. effect.
  8119.  
  8120. %%===========================================================================
  8121.  
  8122. \cleardoublepage
  8123. \chapter{Processor-specific Hints}
  8124.  
  8125. When writing the individual code generators, I strived for a maximum
  8126. amount of compatibility to the original assemblers.  However, I only did this
  8127. as long as it did not mean an unacceptable additional amount of work.
  8128. I listed important differences, details and pitfalls in the following
  8129. chapter.
  8130.  
  8131. %%---------------------------------------------------------------------------
  8132.  
  8133. \section{6811}
  8134.  
  8135. ''Where can I buy such a beast, a HC11 in NMOS?'', some of you might
  8136. ask.  Well, of course it does not exist, but an H cannot be
  8137. represented in a hexadecimal number (older versions of \asname{} would not
  8138. have accepted such a name because of this), and so I decided to omit
  8139. all the letters...
  8140. \par
  8141. \begin{quote}{\it
  8142. ''Someone stating that something is impossible should be at least as
  8143. cooperative as not to hinder the one who currently does it.''
  8144. }\end{quote}
  8145. From time to time, one is forced to revise one's opinions.  Some versions
  8146. earlier, I stated at his place that I couldn't use \asname{}'s parser in a way
  8147. that it is also possible to to separate the arguments of \tty{BSET/BCLR}
  8148. resp. \tty{BRSET/BRCLR} with spaces.  However, it seems that it can do
  8149. more than I wanted to believe...after the n+1th request, I sat down once
  8150. again to work on it and things seem to work now.  You may use either
  8151. spaces or commas, but not in all variants, to avoid ambiguities: for
  8152. every variant of an instruction, it is possible to use only commas or a
  8153. mixture of spaces and commas as Motorola seems to have defined it (their
  8154. data books do not always have the quality of the corresponding
  8155. hardware...):
  8156. \begin{verbatim}
  8157. Bxxx  abs8 #mask         is equal to Bxxx  abs8,#mask
  8158. Bxxx  disp8,X #mask      is equal to Bxxx  disp8,X,#mask
  8159. BRxxx abs8 #mask addr    is equal to BRxxx abs8,#mask,addr
  8160. BRxxx disp8,X #mask addr is equal to BRxxx disp8,X,#mask,addr
  8161. \end{verbatim}
  8162. In this list, \tty{xxx} is a synonym either for \tty{SET} or \tty{CLR};
  8163. \tty{\#mask} is the bit mask to be applied (the \# sign is optional).  Of
  8164. course, the same statements are also valid for Y-indexed expression (not
  8165. listed here).
  8166.  
  8167. With the K4 version  of the HC11, Motorola has introduced a banking
  8168. scheme, which one one hand easily allows to once again extend an
  8169. architecture that has become 'too small', but on the other hand not really
  8170. makes programmers' and tool developers' lifes simpler...how does one
  8171. sensibly map something like this on a model for a programmer?
  8172.  
  8173. The K4 architecture {\em extends} the HC11 address space by 2x512 Kbytes,
  8174. which means that we now have a total address space of 64+1024=1088 Kbytes.
  8175. \asname{} acts like this were one large unified addres space, with the following
  8176. layout:
  8177. \begin{itemize}
  8178. \item{\$000000...\$00ffff: the old HC11 address space}
  8179. \item{\$010000...\$08ffff: Window 1}
  8180. \item{\$090000...\$10ffff: Window 2}
  8181. \end{itemize}
  8182. Via the {\tt ASSUME} statement, one tells \asname{} how the banking registers are
  8183. set up, which in turn describes which extended areas are mapped to which
  8184. physical addresses.  For absolute addresses modes with addresses beyond
  8185. \$10000, \asname{} automatically computes the address within the first 64K that
  8186. is to be used.  Of course this only works for direct addressing modes, it
  8187. is the programmer's responsibility to keep the overview for indirect or
  8188. indexed addressing modes!
  8189. In case one is not really sure if the current mapping is really the
  8190. desired one, the pseudo instruction {\tt PRWINS} may be used, which prints
  8191. the assumes MMxxx register contents plus the current mapping(s), like
  8192. this:
  8193. \begin{verbatim}
  8194. MMSIZ $e1 MMWBR $84 MM1CR $00 MM2CR $80
  8195. Window 1: 10000...12000 --> 4000...6000
  8196. Window 1: 90000...94000 --> 8000...c000
  8197. \end{verbatim}
  8198. An instruction
  8199. \begin{verbatim}
  8200.        jmp     *+3
  8201. \end{verbatim}
  8202. located at \$10000 would effectively result in a jump to address \$4003.
  8203.  
  8204. %%---------------------------------------------------------------------------
  8205.  
  8206. \section{PowerPC}
  8207.  
  8208. Of course, it is a bit crazy idea to add support in \asname{} for a
  8209. processor that was mostly designed for usage in work stations.
  8210. Remember that \asname{} mainly is targeted at programmers of single board
  8211. computers.  But things that today represent the absolute high end in
  8212. computing will be average tomorrow and maybe obsolete the next day,
  8213. and in the meantime, the Z80 as the 8088 have been retired as CPUs
  8214. for personal computers and been moved to the embedded market;
  8215. modified versions are marketed as microcontrollers.  With the
  8216. appearance of the MPC505 and PPC403, my suspicion has proven to be
  8217. true that IBM and Motorola try to promote this architecture in as
  8218. many fields as possible.
  8219.  
  8220. However, the current support is a bit incomplete: Temporarily, the
  8221. Intel-style mnemonics are used to allow storage of data and the more
  8222. uncommon RS/6000 machine instructions mentioned in \cite{Mot601} are
  8223. missing (hopefully noone misses them!).  I will finish this as soon
  8224. as information about them is available!
  8225.  
  8226. %%---------------------------------------------------------------------------
  8227.  
  8228. \section{IBM PALM}
  8229.  
  8230. IBM's PALM processor has been ''Terra Incognita'' for long time, because
  8231. it never has been used outside of IBM.  Furthermore, the IBM 5100 to
  8232. 5120 that were equipped with it were exotic and expensive, and were
  8233. quickly forgotten over the success of the IBM PC.  Only Christian
  8234. Corti's extensive reverse engineering made it possible to implement
  8235. this target \cite{CortPalm}.
  8236.  
  8237. When Christian began to reverse engineer the PALM processor, he did
  8238. not know the assembler mnemonics defined by IBM, so he had to choose
  8239. his own ones.  He of course did this with the background knowledge about
  8240. decades of other processor architectures that were developed from 1973
  8241. (when PALM was constructed) until today.
  8242.  
  8243. If you compare his mnemonics with the ones from IBM (a document about
  8244. them was finally published in \cite{IBMPalm}), I see parallels to the
  8245. assembly language of the Intel 8080/8085 on the one side, and the Zilog
  8246. Z80 on the other side.  ''Intel Mnemonics'' pack the addressing mode
  8247. into the mnemonic's name (like {\tt MVI} for ''MoVe Immediate'' or {\tt
  8248. LDHD} for ''LoaD Halfword Direct'').  This is significantly easier to
  8249. parse and transform into machine language for an assembler.
  8250.  
  8251. The other mnemonics group all machine instructions doing a certain
  8252. operation under the same mnemonic, like {\tt LD} for ''LoaD'' or {\tt
  8253. MOVE} for a (16 bit) data move.  This makes usage for a programmer much
  8254. simpler, parsing the different addressing modes however results in some
  8255. more work for an assembler.
  8256.  
  8257. So, both sets of mnemonics have their justification: The IBM ones
  8258. simply because they are ''the original'' ones and are use in all vendor
  8259. documentation, and the new ones because they are simply more
  8260. understandable and easier to use.  I therefore decided to support {\em
  8261. both} sets in my assembler, and this was fortunately possible without
  8262. creating any conflicts.  Support includes the ''macro instructions''
  8263. {\tt CALL, RCALL, JMP, BRA, LWI} and {\tt RET}.  And there are a few
  8264. things I added myself:
  8265. \begin{itemize}
  8266. \item{{\tt AND} and {\tt OR} also accept an immediate operand as second
  8267.      argument. This is mapped to the {\tt SET} resp. {\tt CLR} instructions,
  8268.      and of course the value gets inverted for {\tt AND}.}
  8269. \item{{\tt MOVE} also accepts an immediate argument as source and generates
  8270.      the same machine code as {\tt LWI}.  The same is true for {\tt MOVB}
  8271.      and {\tt LBI}.}
  8272. \end{itemize}
  8273. Macro instructions consisting of more than one (half) word however
  8274. create a new problem: The only form of conditional execution supported
  8275. by the PALM processor is a conditional skip of the following
  8276. instruction word.  If such a skip is followed by a macro instruction,
  8277. it would only partially be skipped.  I have therefore added a small
  8278. state machine that attempts to detect such sequences and will issue a
  8279. warning.
  8280.  
  8281. The IBM 5110 and 5120 do not use the ASCII character set, but instead
  8282. EBCDIC as known from IBM mainframes.  The include subdirectory holds
  8283. a file that may be used to convert from ASCII to EBCDIC. IMPORTANT:
  8284. This file defines EBCDIC as an extra code page, so the translation
  8285. has to be activated with the statement
  8286. \begin{verbatim}
  8287.        codepage        cp037
  8288. \end{verbatim}
  8289.  
  8290. One more word about integer constant syntax: Christian Corti had
  8291. decided to use the ''Motorola Syntax'', i.e.  hexadecimal constants
  8292. must be prefixed with a dollar sign.  As the PALM is an IBM design, I
  8293. decided to use the ''IBM Syntax'' by default, which means that numeric
  8294. constants are enclosed in apostrophes and prefixed with an {\tt X} for
  8295. hexadecimal values.  To assemble the code examples from Christian's
  8296. pages without modifying them, add the following statement at the
  8297. program's beginning:
  8298. \begin{verbatim}
  8299.        intsyntax       +$hex,-x'hex'
  8300. \end{verbatim}
  8301.  
  8302. %%---------------------------------------------------------------------------
  8303.  
  8304. \section{DSP56xxx}
  8305.  
  8306. Motorola, which devil rode you!  Which person in your company had the
  8307. ''brilliant'' idea to separate the parallel data transfers with spaces!
  8308. In result, everyone who wants to make his code a bit more readable,
  8309. e.g. like this:
  8310. \begin{verbatim}
  8311.        move    x:var9 ,r0
  8312.        move    y:var10,r3   ,
  8313. \end{verbatim}
  8314. is p****ed because the space gets recognized as a separator for
  8315. parallel data transfers!
  8316.  
  8317. Well...Motorola defined it that way, and I cannot change it.  Using
  8318. tabs instead of spaces to separate the parallel operations is also
  8319. allowed, and the individual operations' parts are again separated
  8320. with commas, as one would expect it.
  8321.  
  8322. \cite{Mot56} states that instead of using \tty{MOVEC, MOVEM, ANDI} or
  8323. \tty{ORI}, it is also valid to use the more general Mnemonics \tty{MODE,
  8324. AND} or \tty{OR}.
  8325. \asname{} (currently) does not support this.
  8326.  
  8327. %%---------------------------------------------------------------------------
  8328.  
  8329. \section{H8/300}
  8330.  
  8331. Regarding the assembler syntax of these processors, Hitachi generously
  8332. copied from Motorola (that wasn't by far the worst choice...),
  8333. unfortunately the company wanted to introduce its own format for
  8334. hexadecimal numbers.  To make it even worse, it is a format that uses
  8335. unbalanced single quotes, just like Microchip does:
  8336. \begin{verbatim}
  8337.   mov.w #h'ff,r0
  8338. \end{verbatim}
  8339. This format is not supported by default.  Instead, one has to write
  8340. hexadecimal numbers in the well-known Motorola syntax: with a leading
  8341. dollar sign.  If you really need the 'Hitachi Syntax', e.g. to assemble
  8342. existing code, enable the RELAXED mode.  Bear in mind that this syntax has
  8343. received few testing so far.  I can therefore not guarantee that it will
  8344. work in all cases!
  8345.  
  8346. %%---------------------------------------------------------------------------
  8347.  
  8348. \section{H8/500}
  8349.  
  8350. The H8/500's {\tt MOV} instruction features an interesting and uncommon
  8351. optimization: If the target operand has a size of 16 bits, it is still possible
  8352. to use an 8-bit (immediate) source operand.  For example, for an instruction
  8353. like this:
  8354. \begin{verbatim}
  8355.   mov.w #$ffff,@$1234
  8356. \end{verbatim}
  8357. it is possible to encode the immediate source code operand just as a single
  8358. \$ff and to save one byte in code size.  The processor automatically performs
  8359. a sign extension, which turns \$ff into the desired value \$ffff.  \asname{} is aware
  8360. of this optimization and will use it, unless it was explicitly forbidden via
  8361. a \tty{:16} suffix at the immediate operand.
  8362. Feedback from users trying to assemble existing code has revealed that the
  8363. original Hitachi assembler implements this optimization in a different way:
  8364. it assumes a zero instead of a sign extension.  This means that immediate
  8365. values from 0 to 255 (\$0000 to \$00ff) and not from -128 to +127 (\$ff80 to
  8366. \$007f) are encoded as one byte.  Tests with physical hardware brought the
  8367. result that the Programmers Manual is correct: The processor performs a sign
  8368. extension.  \asname{} will therefore by default only use the shorter encoding if
  8369. a value ranging from -128 to +127 respectively \$ff80 to \$007f is used.
  8370. If you have existing code that assumes values from \$80 to \$ff are encoded
  8371. as one byte, you may activate a 'compatibility mode', either by the
  8372. statement
  8373. \begin{verbatim}
  8374.  compmode on
  8375. \end{verbatim}
  8376. in the source code or by the command line switch of same name.
  8377.  
  8378. Aside from this, the same remarks regarding hexadecimal number syntax apply
  8379. as for H8/500.
  8380.  
  8381. %%---------------------------------------------------------------------------
  8382.  
  8383. \section{SH7000/7600/7700}
  8384.  
  8385. Unfortunately, Hitachi once again used their own format for
  8386. hexadecimal numbers, and once again I was not able to reproduce this
  8387. with \asname{}...please use Motorola syntax!
  8388.  
  8389. When using literals and the \tty{LTORG} instruction, a few things have to
  8390. be kept in mind if you do not want to suddenly get confronted with strange
  8391. error messages:
  8392.  
  8393. Literals exist due to the fact that the processor is unable to load
  8394. constants out of a range of -128 to 127 with immediate addressing.
  8395. \asname{} (and the Hitachi assembler) hide this inability by the automatic
  8396. placement of constants in memory which are then referenced via
  8397. PC-relative addressing.  The question that now arises is where to
  8398. locate these constants in memory.  \asname{} does not automatically place a
  8399. constant in memory when it is needed; instead, they are collected
  8400. until an LTORG instruction occurs.  The collected constants are then
  8401. dumped en bloc, and their addresses are stored in ordinary labels
  8402. which are also visible in the symbol table.  Such a label's name is
  8403. of the form
  8404. \begin{verbatim}
  8405.    LITERAL_s_xxxx_n  .
  8406. \end{verbatim}
  8407. In this name, \tty{s} represents the literal's type.  Possible values are
  8408. \tty{W} for 16-bit constants, \tty{L} for 32-bit constants and \tty{F} for
  8409. forward references where \asname{} cannot decide in anticipation which size is
  8410. needed.  In case of \tty{s=W} or \tty{L}, \tty{xxxx} denotes the
  8411. constant's value in a hexadecimal notation, whereas \tty{xxxx} is a simple
  8412. running number for forward references (in a forward reference, one does
  8413. not know the value of a constant when it is referenced, so one obviously
  8414. cannot incorporate its value into the name).  \tty{n} is a counter that
  8415. signifies how often a literal of this value previously occurred in the
  8416. current section.  Literals follow the standard rules for localization by
  8417. sections.  It is therefore absolutely necessary to place literals that
  8418. were generated in a certain section before the section is terminated!
  8419.  
  8420. The numbering with \tty{n} is necessary because a literal may occur
  8421. multiple times in a section.  One reason for this situation is that
  8422. PC-relative addressing only allows positive offsets; Literals that
  8423. have once been placed with an \tty{LTORG} can therefore not be referenced
  8424. in the code that follows.  The other reason is that the displacement
  8425. is generally limited in length (512 resp. 1024 bytes).
  8426.  
  8427. An automatic \tty{LTORG} at the end of a program or previously to
  8428. switching to a different target CPU does not occur; if \asname{} detects unplaced
  8429. literals in such a situation, an error message is printed.
  8430.  
  8431. As the PC-relative addressing mode uses the address of the current
  8432. instruction plus 4, it is not possible to access a literal that is
  8433. stored directly after the instruction, like in the following example:
  8434. \begin{verbatim}
  8435.        mov     #$1234,r6
  8436.        ltorg
  8437. \end{verbatim}
  8438. This is a minor item since the CPU anyway would try to execute the
  8439. following data as code.  Such a situation should not occur in a real
  8440. program...another pitfall is far more real: if PC-relative addressing
  8441. occurs just behind a delayed branch, the program counter is already
  8442. set to the destination address, and the displacement is computed
  8443. relative to the branch target plus 2.  Following is an example where
  8444. this detail leads to a literal that cannot be addressed:
  8445. \begin{verbatim}
  8446.        bra     Target
  8447.        mov     #$12345678,r4        ; is executed
  8448.        .
  8449.        .
  8450.        ltorg                        ; here is the literal
  8451.        .
  8452.        .
  8453. Target: mov     r4,r7                ; execution continues here
  8454. \end{verbatim}
  8455. As \tty{Target}+2 is on an address behind the literal, a negative
  8456. displacement would result.  Things become especially hairy when one
  8457. of the branch instructions \tty{JMP, JSR, BRAF, or BSRF} is used: as \asname{}
  8458. cannot calculate the target address (it is generated at runtime from
  8459. a register's contents), a PC value is assumed that should never fit,
  8460. effectively disabling any PC-relative addressing at this point.
  8461.  
  8462. It is not possible to deduce the memory usage from the count and size
  8463. of literals.  \asname{} might need to insert a padding word to align a long
  8464. word to an address that is evenly divisible by 4; on the other hand,
  8465. \asname{} might reuse parts of a 32-bit literal for other 16-bit literals.
  8466. Of course multiple use of a literal with a certain value will create
  8467. only one entry.  However, such optimizations are completely
  8468. suppressed for forward references as \asname{} does not know anything about
  8469. their value.
  8470.  
  8471. As literals use the PC-relative addressing which is only allowed for
  8472. the \tty{MOV} instruction, the usage of literals is also limited to
  8473. \tty{MOV} instructions.  The way \asname{} uses the operand size is a bit tricky:
  8474. A specification of a byte or word move means to generate the shortest
  8475. possible instruction that results in the desired value placed in the
  8476. register's lowest 8 resp. 16 bits.  The upper 24 resp. 16 bits are treated
  8477. as ''don't care''.  However, if one specifies a longword move or omits the
  8478. size specification completely, this means that the complete 32-bit
  8479. register should contain the desired value.  For example, in the following
  8480. sequence
  8481. \begin{verbatim}
  8482.        mov.b   #$c0,r0
  8483.        mov.w   #$c0,r0
  8484.        mov.l   #$c0,r0   ,
  8485. \end{verbatim}
  8486. the first instruction will result in true immediate addressing, the
  8487. second and third instruction will use a word literal:  As bit 7 in
  8488. the number is set, the byte instruction will effectively create the
  8489. value \$FFFFFFC0 in the register.  According to the convention, this
  8490. wouldn't be the desired value in the second and third example.
  8491. However, a word literal is also sufficient for the third case because
  8492. the processor will copy a cleared bit 15 of the operand to bits
  8493. 16..31.
  8494.  
  8495. As one can see, the whole literal stuff is rather complex; I'm sorry but
  8496. there was no chance of making things simpler.  It is unfortunately a
  8497. part of its nature that one sometimes gets error messages about
  8498. literals that were not found, which logically should not occur because
  8499. \asname{} does the literal processing completely on his own.  However, if
  8500. other errors occur in the second pass, all following labels will move
  8501. because \asname{} does not generate any code any more for statements that
  8502. have been identified as erroneous.  As literal names are partially built
  8503. from other symbols' values, other errors might follow because literal
  8504. names searched in the second pass differ from the names stored in the
  8505. first pass and \asname{} quarrels about undefined symbols...if such errors
  8506. should occur, please correct all other errors first before you start
  8507. cursing on me and literals...
  8508.  
  8509. People who come out of the Motorola scene and want to use PC-relative
  8510. addressing explicitly (e.g. to address variables in a position-independent
  8511. way) should know that if this addressing mode is written like in the
  8512. programmer's manual:
  8513. \begin{verbatim}
  8514.        mov.l   @(Var,PC),r8
  8515. \end{verbatim}
  8516. \bb{no} implicit conversion of the address to a displacement will occur,
  8517. i.e. the operand is inserted as-is into the machine code (this will
  8518. probably generate a value range error...).  If you want to use
  8519. PC-relative addressing on the SH7x00, simply use ''absolute''
  8520. addressing (which does not exist on machine level):
  8521. \begin{verbatim}
  8522.        mov.l   Var,r8
  8523. \end{verbatim}
  8524. In this example, the displacement will be calculated correctly (of
  8525. course, the same limitations apply for the displacement as it was the
  8526. case for literals).
  8527.  
  8528. %%---------------------------------------------------------------------------
  8529.  
  8530. \section{HMCS400}
  8531.  
  8532. The instruction set of these 4 bit processors spontaneously reminded
  8533. me of the 8080/8085 - many mnemonics, the addressing mode (e.g.
  8534. direct or indirect) is coded into the instruction, and the
  8535. instructions are sometimes hard to memorize.  \asname{} or course
  8536. supports this syntax as Hitachi defined it.  I however
  8537. implemented another variant for most instructions that is - in my
  8538. opinion - more beautiful and better to read.  The approach is
  8539. similar to what Zilog did back then for the Z80.  For instance,
  8540. all machine instructions that transfer data in some form, may the
  8541. operands be constants, registers, or memory cells, may be used
  8542. via the \tty{LD} instruction.  Similar 'meta instructions' exist
  8543. for arithmetic and logical instructions.  A complete list of all
  8544. meta instructions and their operands can be found in the tables
  8545. \ref{TabHMCS400Meta} and \ref{TabHMCS400MetaOps}, their practical
  8546. use can be seen in the file \tty{t\_hmcs4x.asm}.
  8547.  
  8548. \begin{table*}
  8549. \begin{center}\begin{tabular}{|l|l|}
  8550. \hline
  8551. Meta Instruction          & Replaces \\
  8552. \hline
  8553. \tty{LD} {\em src, dest}        & \tty{LAI, LBI, LMID, LMIIY,} \\
  8554.                                & \tty{LAB, LBA, LAY, LASPX, LASPY, LAMR,} \\
  8555.                                & \tty{LWI, LXI, LYI, LXA, LYA, LAM, LAMD} \\
  8556.                                & \tty{LBM, LMA, LMAD, LMAIY, LMADY} \\
  8557. \tty{XCH} {\em src, dest}       & \tty{XMRA, XSPX, XSPY, XMA, XMAD, XMB} \\
  8558. \tty{ADD} {\em src, dest}       & \tty{AYY, AI, AM, AMD} \\
  8559. \tty{ADC} {\em src, dest}       & \tty{AMC, AMCD} \\
  8560. \tty{SUB} {\em src, dest}       & \tty{SYY} \\
  8561. \tty{SBC} {\em src, dest}       & \tty{SMC, SMCD} \\
  8562. \tty{OR}  {\em src, dest}       & \tty{OR, ORM, ORMD} \\
  8563. \tty{AND} {\em src, dest}       & \tty{ANM, ANMD} \\
  8564. \tty{EOR} {\em src, dest}       & \tty{EORM, EORMD} \\
  8565. \tty{CP}  {\em cond, src, dest} & \tty{INEM, INEMD, ANEM, ANEMD, BNEM,} \\
  8566.                                & \tty{YNEI, ILEM, ILEMD, ALEM, ALEMD,} \\
  8567.                                & \tty{BLEM, ALEI} \\
  8568. \tty{BSET} {\em bit}            & \tty{SEC, SEM, SEMD} \\
  8569. \tty{BCLR} {\em bit}            & \tty{REC, REM, REMD} \\
  8570. \tty{BTST} {\em bit}            & \tty{TC, TM, TMD} \\
  8571. \hline
  8572. \end{tabular}\end{center}
  8573. \caption{Meta Instructions HMCS400}
  8574. \label{TabHMCS400Meta}
  8575. \end{table*}
  8576.  
  8577. \begin{table*}
  8578. \begin{center}\begin{tabular}{|l|l|}
  8579. \hline
  8580. Operand                 & Types \\
  8581. \hline
  8582. {\em src, dest}         & \tty{A, B, X, Y, W, SPX, SPY} (register) \\
  8583.                        & \tty{M} (memory addressed by X/Y/W) \\
  8584.                        & \tty{M+} (ditto, with auto increment) \\
  8585.                        & \tty{M-} (ditto, with auto decrement) \\
  8586.                        & \tty{\#val} (2/4 bits immediate) \\
  8587.                        & \tty{addr10} (memory direct) \\
  8588.                        & \tty{MRn} (memory register 0..15) \\
  8589. {\em cond}              & \tty{NE} (unequal) \\
  8590.                        & \tty{LE} (less or equal) \\
  8591. {\em bit}               & \tty{CA} (carry) \\
  8592.                        & {\em bitpos},\tty{M} \\
  8593.                        & {\em bitpos},\tty{addr10} \\
  8594. {\em bitpos}            & \tty{0..3} \\
  8595. \hline
  8596. \end{tabular}\end{center}
  8597. \caption{Operand Types for HMCS400 Meta Instructions}
  8598. \label{TabHMCS400MetaOps}
  8599. \end{table*}
  8600.  
  8601. %%---------------------------------------------------------------------------
  8602.  
  8603. \section{H16}
  8604.  
  8605. The instruction set of the H16's core well deserves the label ''CISC'': complex
  8606. addressing modes, instructions of extremely variable length, and
  8607. there are many shortforms for instructions with common operands.  For
  8608. instance, several instructions know different ''formats'', depending
  8609. on the type of source and destination operand.  The general rule is
  8610. that \asname{} will always use the shortest possible format, unless it was
  8611. specified explicitly:
  8612. angegeben:
  8613. \begin{verbatim}
  8614.       mov.l     r4,r7     ; uses R format
  8615.       mov.l     #4,r7     ; uses RQ format
  8616.       mov.l     #4,@r7    ; uses Q format
  8617.       mov.l     @r4,@r7   ; uses G format
  8618.       mov:q.l   #4,r7     ; forces Q instead of RQ format
  8619.       mov:g.l   #4,r7     ; forces G instead of RQ format
  8620. \end{verbatim}
  8621. For immediate arguments, the ''natural' argument length is used, e.g.
  8622. 2 bytes for 16 bits.  Shorter or longer arguments may be forced by an
  8623. appended operand size (.b, .w, .l or :8, :16, :32).  However, the
  8624. rule for displacements and absolute addresses is that the shortest
  8625. form will be used if no explicit size is given.  This includes
  8626. exploiting that the processor does not output the uppermost eight
  8627. bits of an address.  Therefore, an absolute address of \$ffff80 can
  8628. be coded as a single byte (\$80).
  8629.  
  8630. Furthermore, \asname{} knows the ''accumulator bit'', i.e. the second
  8631. operand of a two-operand instruction my be left away if the
  8632. destination is register zero.  There is currently no override this
  8633. behaviour.
  8634.  
  8635. Additionally, the following optimizations are performed:
  8636. \begin{itemize}
  8637. \item{\tty{MOV R0,<ea>} gets optimized to \tty{MOVF <ea>}, unless
  8638.      \tty{<ea>} is a PC-relative expression and the size of the
  8639.      displacement would change.  This optimization may be disabled
  8640.      by specifying an explicit format.}
  8641. \item{\tty{SUB} does not support the Q format, however it may be
  8642.      replaced by \tty{ADD:Q} with a negated immediate argument,
  8643.      given the argument is in the range -127...+128.  This
  8644.      optimization may as well be disabled by specifying an explicit
  8645.      format.}
  8646. \end{itemize}
  8647.  
  8648. %%---------------------------------------------------------------------------
  8649.  
  8650. \section{OLMS-40}
  8651.  
  8652. Similar to the HMCS400, addressing modes are largely encoded (or
  8653. rather encrypted..) into into the mnemonics, and also here I
  8654. decided to provide an alternate notation that is more modern and
  8655. better to read.  A complete list of all meta instructions and
  8656. their operands can be found in the tables \ref{TabOLMS40Meta} and
  8657. \ref{TabOLMS40MetaOps}, their practical use can be seen in the
  8658. file \tty{t\_olms4.asm}.
  8659.  
  8660. \begin{table*}
  8661. \begin{center}\begin{tabular}{|l|l|}
  8662. \hline
  8663. Meta Instruction          & Replaces \\
  8664. \hline
  8665. \tty{LD} {\em dest, src}        & \tty{LAI, LLI, LHI, L,} \\
  8666.                                & \tty{LAL, LLA, LAW, LAX, LAY, LAZ,} \\
  8667.                                & \tty{LWA, LXA, LYA, LPA, LTI, RTH, RTL} \\
  8668. \tty{DEC} {\em dest}            & \tty{DCA, DCL, DCM, DCW, DCX, DCY, DCZ, DCH} \\
  8669. \tty{INC} {\em dest}            & \tty{INA, INL, INM, INW, INX, INY, INZ} \\
  8670. \tty{BSET} {\em bit}            & \tty{SPB, SMB, SC} \\
  8671. \tty{BCLR} {\em bit}            & \tty{RPB, RMB, RC} \\
  8672. \tty{BTST} {\em bit}            & \tty{TAB, TMB, Tc} \\
  8673. \hline
  8674. \end{tabular}\end{center}
  8675. \caption{Meta Instructions OLMS-40}
  8676. \label{TabOLMS40Meta}
  8677. \end{table*}
  8678.  
  8679. \begin{table*}
  8680. \begin{center}\begin{tabular}{|l|l|}
  8681. \hline
  8682. Operand                 & Types \\
  8683. \hline
  8684. {\em src, dest}         & \tty{A, W, X, Y, Z, DPL, DPH} (Register) \\
  8685.                        & \tty{T, TL, TH} (Timer, obere/untere H"alfte) \\
  8686.                        & \tty{(DP), M} (Speicher adressiert durch DPH/DPL) \\
  8687.                        & \tty{\#val} (4/8 bit immediate) \\
  8688.                        & \tty{PP} (Port-Pointer) \\
  8689. {\em bit}               & \tty{C} (Carry) \\
  8690.                        & \tty{(PP)},{\em bitpos} \\
  8691.                        & \tty{(DP)},{\em bitpos} \\
  8692.                        & \tty{(A)},{\em bitpos} \\
  8693. {\em bitpos}            & \tty{0..3} \\
  8694. \hline
  8695. \end{tabular}\end{center}
  8696. \caption{Operand Types for OLMS-40 Meta Instructions}
  8697. \label{TabOLMS40MetaOps}
  8698. \end{table*}
  8699.  
  8700. %%---------------------------------------------------------------------------
  8701.  
  8702. \section{OLMS-50}
  8703.  
  8704. The data memory of these 4 bit controllers consists of up to 128
  8705. nibbles.  However, only a very small subset of the machine
  8706. instructions have enough space to accomodate seven address bits,
  8707. which menas that - once again - banking must help out.  The
  8708. majority of instructions that address memory only contain the
  8709. lower four bits of the RAM address, and unless the lowest 16
  8710. nibbles of the memory shall be addressed, the P register delivers
  8711. the necessary upper address bits. The assembler is told about its
  8712. current value via an
  8713. \begin{verbatim}
  8714.   assume  p:<value>
  8715. \end{verbatim}
  8716. statement, e.g. directly after a \tty{PAGE} instruction.
  8717.  
  8718. Speaking of \tty{PAGE}: both \tty{PAGE} and \tty{SWITCH} are
  8719. machine instructions on these controllers, i.e. the do not have
  8720. the function known from other targets.  The pseudo instruction to
  8721. start a \tty{SWITCH/CASE} construct is \tty{SELECT} in OLMS-50
  8722. mode, and the listing's page size is set via \tty{PAGESIZE}.
  8723.  
  8724. %%---------------------------------------------------------------------------
  8725.  
  8726. \section{MELPS-4500}
  8727.  
  8728. The program memory of these microcontrollers is organized in pages of
  8729. 128 words.  Honestly said, this organization only exists because there
  8730. are on the one hand branch instructions with a target that must lie
  8731. within the same page, and on the other hand ''long'' branches that can
  8732. reach the whole address space.  The standard syntax defined by
  8733. Mitsubishi demands that page number and offset have to be written as
  8734. two distinct arguments for the latter instructions.  As this is
  8735. quite inconvenient (except for indirect jumps, a programmer has no
  8736. other reason to deal with pages), \asname{} also allows to write the target
  8737. address in a ''linear'' style, for example
  8738. \begin{verbatim}
  8739.        bl      $1234
  8740. \end{verbatim}
  8741. instead of
  8742. \begin{verbatim}
  8743.        bl      $24,$34 .
  8744. \end{verbatim}
  8745.  
  8746. %%---------------------------------------------------------------------------
  8747.  
  8748. \section{6502UNDOC}
  8749.  
  8750. Since the 6502's undocumented instructions naturally aren't listed in
  8751. any data book, they shall be listed shortly at this place.  Of
  8752. course, you are using them on your own risk.  There is no guarantee
  8753. that all mask revisions will support all variants!  They anyhow do
  8754. not work for the CMOS successors of the 6502, since they allocated
  8755. the corresponding bit combinations with "official" instructions...
  8756.  
  8757. The following symbols are used:
  8758.  
  8759. \begin{tabbing}
  8760. \hspace{2cm} \= \kill
  8761. \&           \> binary AND \\
  8762. |            \> binary OR \\
  8763. \verb!^!     \> binary XOR \\
  8764. $<<$         \> logical shift left \\
  8765. $>>$         \> logical shift right \\
  8766. $<<<$        \> rotate left \\
  8767. $>>>$        \> rotate right \\
  8768. $\leftarrow$ \> assignment \\
  8769. (..)        \> contents of .. \\
  8770. {..}        \> bits .. \\
  8771. A           \> accumulator \\
  8772. X,Y         \> index registers X,Y \\
  8773. S           \> stack pointer \\
  8774. An          \> accumulator bit n \\
  8775. M           \> operand \\
  8776. C           \> carry \\
  8777. PCH         \> upper half of program counter \\
  8778. \end{tabbing}
  8779.  
  8780. \begin{tabbing}
  8781. Addressing Modes \= : \= \kill
  8782. Instruction      \> : \> \tty{JAM} or \tty{KIL} or \tty{CRS} \\
  8783. Function         \> : \> none, prozessor is halted \\
  8784. Addressing Modes \> : \> implicit \\
  8785. \end{tabbing}
  8786.  
  8787. \begin{tabbing}
  8788. Addressing Modes \= : \= \kill
  8789. Instruction      \> : \> \tty{SLO} \\
  8790. Function         \> : \> $M\leftarrow((M)<<1)|(A)$ \\
  8791. Addressing Modes \> : \> absolute long/short, X-indexed long/short, \\
  8792.                 \>   \> Y-indexed long, X/Y-indirect \\
  8793. \end{tabbing}
  8794.  
  8795. \begin{tabbing}
  8796. Addressing Modes \= : \= \kill
  8797. Instruction      \> : \> \tty{ANC} \\
  8798. Function         \> : \> $A\leftarrow(A)\&(M), C\leftarrow A7$ \\
  8799. Addressing Modes \> : \> immediate \\
  8800. \end{tabbing}
  8801.  
  8802. \begin{tabbing}
  8803. Addressing Modes \= : \= \kill
  8804. Instruction      \> : \> \tty{RLA} \\
  8805. Function         \> : \> $M\leftarrow((M)<<1)\&(A)$ \\
  8806. Addressing Modes \> : \> absolute long/short, X-indexed long/short, \\
  8807.                 \>   \> Y-indexed long, X/Y-indirect \\
  8808. \end{tabbing}
  8809.  
  8810. \begin{tabbing}
  8811. Addressing Modes \= : \= \kill
  8812. Instruction      \> : \> \tty{SRE} \\
  8813. Function         \> : \> $M\leftarrow((M)>>1)$\verb!^!$(A)$ \\
  8814. Addressing Modes \> : \> absolute long/short, X-indexed long/short, \\
  8815.                 \>   \> Y-indexed long, X/Y-indirect \\
  8816. \end{tabbing}
  8817.  
  8818. \begin{tabbing}
  8819. Addressing Modes \= : \= \kill
  8820. Instruction      \> : \> \tty{ASR} \\
  8821. Function         \> : \> $A\leftarrow((A)\&(M))>>1$ \\
  8822. Addressing Modes \> : \> immediate \\
  8823. \end{tabbing}
  8824.  
  8825. \begin{tabbing}
  8826. Addressing Modes \= : \= \kill
  8827. Instruction      \> : \> \tty{RRA} \\
  8828. Function         \> : \> $M\leftarrow((M)>>>1)+(A)+(C)$ \\
  8829. Addressing Modes \> : \> absolute long/short, X-indexed long/short, \\
  8830.                 \>   \> Y-indexed long, X/Y-indirect \\
  8831. \end{tabbing}
  8832.  
  8833. \begin{tabbing}
  8834. Addressing Modes \= : \= \kill
  8835. Instruction      \> : \> \tty{ARR} \\
  8836. Function         \> : \> $A\leftarrow((A)\&(M))>>>1$ \\
  8837. Addressing Modes \> : \> immediate \\
  8838. \end{tabbing}
  8839.  
  8840. \begin{tabbing}
  8841. Addressing Modes \= : \= \kill
  8842. Instruction      \> : \> \tty{SAX} \\
  8843. Function         \> : \> $M\leftarrow(A)\&(X)$ \\
  8844. Addressing Modes \> : \> absolute long/short, Y-indexed short, \\
  8845.                 \>   \> Y-indirect \\
  8846. \end{tabbing}
  8847.  
  8848. \begin{tabbing}
  8849. Addressing Modes \= : \= \kill
  8850. Instruction      \> : \> \tty{ANE} \\
  8851. Function         \> : \> $M\leftarrow((A)\&\$ee)|((X)\&(M))$ \\
  8852. Addressing Modes \> : \> immediate \\
  8853. \end{tabbing}
  8854. \begin{tabbing}
  8855. Addressing Modes \= : \= \kill
  8856. Instruction      \> : \> \tty{SHA} \\
  8857. Function         \> : \> $M\leftarrow(A)\&(X)\&(PCH+1)$ \\
  8858. Addressing Modes \> : \> X/Y-indexed long \\
  8859. \end{tabbing}
  8860. \begin{tabbing}
  8861. Addressing Modes \= : \= \kill
  8862. Instruction      \> : \> \tty{SHS} \\
  8863. Function         \> : \> $X\leftarrow(A)\&(X), S\leftarrow(X), M\leftarrow(X)\&(PCH+1)$ \\
  8864. Addressing Modes \> : \> Y-indexed long \\
  8865. \end{tabbing}
  8866. \begin{tabbing}
  8867. Addressing Modes \= : \= \kill
  8868. Instruction      \> : \> \tty{SHY} \\
  8869. Function         \> : \> $M\leftarrow(Y)\&(PCH+1)$ \\
  8870. Addressing Modes \> : \> Y-indexed long \\
  8871. \end{tabbing}
  8872. \begin{tabbing}
  8873. Addressing Modes \= : \= \kill
  8874. Instruction      \> : \> \tty{SHX} \\
  8875. Function         \> : \> $M\leftarrow(X)\&(PCH+1)$ \\
  8876. Addressing Modes \> : \> X-indexed long \\
  8877. \end{tabbing}
  8878. \begin{tabbing}
  8879. Addressing Modes \= : \= \kill
  8880. Instruction      \> : \> \tty{LAX} \\
  8881. Function         \> : \> $A,X\leftarrow(M)$ \\
  8882. Addressing Modes \> : \> absolute long/short, Y-indexed long/short, \\
  8883.                 \>   \> X/Y-indirect \\
  8884. \end{tabbing}
  8885. \begin{tabbing}
  8886. Addressing Modes \= : \= \kill
  8887. Instruction      \> : \> \tty{LXA} \\
  8888. Function         \> : \> $X{04}\leftarrow(X){04}\&(M){04}$, \\
  8889.                 \>   \> $A{04}\leftarrow(A){04}\&(M){04}$ \\
  8890. Addressing Modes \> : \> immediate \\
  8891. \end{tabbing}
  8892. \begin{tabbing}
  8893. Addressing Modes \= : \= \kill
  8894. Instruction      \> : \> \tty{LAE} \\
  8895. Function         \> : \> $X,S,A\leftarrow((S)\&(M))$ \\
  8896. Addressing Modes \> : \> Y-indexed long \\
  8897. \end{tabbing}
  8898. \begin{tabbing}
  8899. Addressing Modes \= : \= \kill
  8900. Instruction      \> : \> \tty{DCP} \\
  8901. Function         \> : \> $M\leftarrow(M)-1, Flags\leftarrow((A)-(M))$ \\
  8902. Addressing Modes \> : \> absolute long/short, X-indexed long/short, \\
  8903.                 \>   \> Y-indexed long, X/Y-indirect \\
  8904. \end{tabbing}
  8905. \begin{tabbing}
  8906. Addressing Modes \= : \= \kill
  8907. Instruction      \> : \> \tty{SBX} \\
  8908. Function         \> : \> $X\leftarrow((X)\&(A))-(M)$ \\
  8909. Addressing Modes \> : \> immediate \\
  8910. \end{tabbing}
  8911. \begin{tabbing}
  8912. Addressing Modes \= : \= \kill
  8913. Instruction      \> : \> \tty{ISB} \\
  8914. Function         \> : \> $M\leftarrow(M)+1, A\leftarrow(A)-(M)-(C)$ \\
  8915. Addressing Modes \> : \> absolute long/short, X-indexed long/short, \\
  8916.                 \>   \> Y-indexed long, X/Y-indirect \\
  8917. \end{tabbing}
  8918.  
  8919. %%---------------------------------------------------------------------------
  8920.  
  8921. \section{MELPS-740}
  8922.  
  8923. Microcontrollers of this family have a quite nice, however well-hidden
  8924. feature: If one sets bit 5 of the status register with the \tty{SET}
  8925. instruction, the accumulator will be replaced with the memory cell
  8926. addressed by the X register for all load/store and arithmetic
  8927. instructions.  An attempt to integrate this feature cleanly into the
  8928. assembly syntax has not been made so far, so the only way to use it
  8929. is currently the ''hard'' way (\tty{SET}...instructions with accumulator
  8930. addressing...\tty{CLT}).
  8931.  
  8932. Not all MELPS-740 processors implement all instructions.  This is a
  8933. place where the programmer has to watch out for himself that no
  8934. instructions are used that are unavailable for the targeted
  8935. processor; \asname{} does not differentiate among the individual processors
  8936. of this family.  For a description of the details regarding special
  8937. page addressing, see the discussion of the \tty{ASSUME} instruction.
  8938.  
  8939. %%---------------------------------------------------------------------------
  8940.  
  8941. \section{MELPS-7700/65816}
  8942. \label{MELPS7700Spec}
  8943.  
  8944. As it seems, these two processor families took disjunct development
  8945. paths, starting from the 6502 via their 8 bit predecessors.  Shortly
  8946. listed, the following differences are present:
  8947. \begin{itemize}
  8948. \item{The 65816 does not have a B accumulator.}
  8949. \item{The 65816 does not have instructions to multiply or divide.}
  8950. \item{The 65816 misses the instructions \tty{SEB, CLB, BBC, BBS, CLM, SEM,
  8951.      PSH, PUL} and \tty{LDM}.  Instead, the instructions \tty{TSB, TRB, BIT, CLD,
  8952.      SED, XBA, XCE} and \tty{STZ} take their places in the opcode table.}
  8953. \end{itemize}
  8954. The following instructions have identical function, yet different
  8955. names:
  8956. \par
  8957. \begin{center}\begin{tabular}{|c|c||c|c|}
  8958. \hline
  8959.   65816  &  MELPS-7700 & 65816 &  MELPS-7700 \\
  8960. \hline
  8961. \hline
  8962.    \tty{REP}  &  \tty{CLP}  &  \tty{PHK}  &  \tty{PHG} \\
  8963.    \tty{TCS}  &  \tty{TAS}  &  \tty{TSC}  &  \tty{TSA} \\
  8964.    \tty{TCD}  &  \tty{TAD}  &  \tty{TDC}  &  \tty{TDA} \\
  8965.    \tty{PHB}  &  \tty{PHT}  &  \tty{PLB}  &  \tty{PLT} \\
  8966.    \tty{WAI}  &  \tty{WIT}  &             & \\
  8967. \hline
  8968. \end{tabular}\end{center}
  8969. \par
  8970. Especially tricky are the instructions \tty{PHB, PLB} and \tty{TSB}: these
  8971. instructions have a totally different encoding and meaning on both
  8972. processors!
  8973.  
  8974. Unfortunately, these processors address their memory in a way that is
  8975. IMHO even one level higher on the open-ended chart of perversity than
  8976. the Intel-like segmentation: They do banking!  Well, this seems to
  8977. be the price for the 6502 upward-compatibility; before one can use \asname{}
  8978. to write code for these processors, one has to inform \asname{} about the
  8979. contents of several registers (using the \tty{ASSUME} instruction):
  8980.  
  8981. The M flag rules whether the accumulators A and B should be used with
  8982. 8 bits (1) or 16 bits (0) width.  Analogously, the X flag decides the
  8983. width of the X and Y index registers.  \asname{} needs this information for
  8984. the decision about the argument's width when immediate addressing
  8985. (\verb!#<constant>!) occurs.
  8986.  
  8987. The memory is organized in 256 banks of 64 KBytes.  As all registers
  8988. in the CPU core have a maximum width of 16 bits, the upper 8 bits
  8989. have to be fetched from 2 special bank registers: DT delivers the
  8990. upper 8 bits for data accesses, and PG extends the 16-bit program
  8991. counter to 24 bits.  A 16 bits wide register DPR allows to move the
  8992. zero page known from the 6502 to an arbitrary location in the first
  8993. bank.  If \asname{} encounters an address (it is irrelevant if this address
  8994. is part of an absolute, indexed, or indirect expression), the
  8995. following addressing modes will be tested:
  8996. \begin{enumerate}
  8997. \item{Is the address in the range of DPR..DPR+\$ff?  If yes, use direct
  8998.      addressing with an 8-bit address.}
  8999. \item{Is the address contained in the page addressable via DT (resp.
  9000.      PG for branch instructions)? If yes, use absolute addressing
  9001.      with a 16-bit address.}
  9002. \item{If nothing else helps, use long addressing with a 24-bit
  9003.      address.}
  9004. \end{enumerate}
  9005. As one can see from this enumeration, the knowledge about the current
  9006. values of DT, PG and DPR is essential for a correct operation of \asname{};
  9007. if the specifications are incorrect, the program will probably do
  9008. wrong addressing at runtime.  This enumeration also implied that all
  9009. three address lengths are available; if this is not the case, the
  9010. decision chain will become shorter.
  9011. The automatic determination of the address length described above may
  9012. be overridden by the usage of prefixes.  If one prefixes the address
  9013. by a $<$, $>$, or $>>$ without a separating space, an address with 1, 2, or
  9014. 3 bytes of length will be used, regardless if this is the optimal
  9015. length.  If one uses an address length that is either not allowed for
  9016. the current instruction or too short for the address, an error
  9017. message is the result.
  9018. To simplify porting of 6502 programs, \asname{} uses the Motorola syntax for
  9019. hexadecimal constants instead of the Intel/IEEE syntax that is
  9020. the format preferred by Mitsubishi for their 740xxx series.  I still
  9021. think that this is the better format, and it looks as if the
  9022. designers of the 65816 were of the same opinion (as the \tty{RELAXED}
  9023. instruction allows the alternative use of Intel notation, this
  9024. decision should not hurt anything).  Another important detail for the
  9025. porting of programs is that it is valid to omit the accumulator A as
  9026. target for operations.  For example, it is possible to simply write
  9027. \verb!LDA #0! instead of \verb!LDA A,#0!.
  9028. A real goodie in the instruction set are the instructions \tty{MVN} resp.
  9029. \tty{MVP} to do block transfers.  However, their address specification
  9030. rules are a bit strange: bits 0--15 are stored in index registers,
  9031. bits 16--23 are part of the instruction.  When one uses \asname{}, one
  9032. simply specifies the full destination and source addresses.  \asname{} will
  9033. then automatically grab the correct bits.  This is a fine yet
  9034. important difference  Mitsubishi's assembler where you have to
  9035. extract the upper 8 bits on your own.  Things become really
  9036. convenient when a macro like the following is used:
  9037. \begin{verbatim}
  9038. mvpos   macro   src,dest,len
  9039.        if      MomCPU=$7700
  9040.         lda    #len
  9041.        elseif
  9042.         lda    #(len-1)
  9043.        endif
  9044.        ldx     #(src&$ffff)
  9045.        ldy     #(dest&$ffff)
  9046.        mvp     dest,src
  9047.        endm
  9048. \end{verbatim}
  9049. Caution, possible pitfall: if the accumulator contains the value n,
  9050. the Mitsubishi chip will transfer n bytes, but the 65816 will
  9051. transfer n+1 bytes!
  9052.  
  9053. The \tty{PSH} and \tty{PUL} instructions are also very handy because they
  9054. allow to save a user-defined set to be saved to the stack resp. to be
  9055. restored from the stack.  According to the Mitsubishi data book
  9056. \cite{Mit16}, the bit mask has to be specified as an immediate operand, so
  9057. the programmer either has to keep all bit$\leftrightarrow$register
  9058. assignments in mind or he has to define some appropriate symbols.  To make
  9059. things simpler, I decided to extend the syntax at this point: It is valid
  9060. to use a list as argument which may contain an arbitrary sequence of
  9061. register names or immediate expressions.  Therefore, the following
  9062. instructions
  9063. \begin{verbatim}
  9064.        psh     #$0f
  9065.        psh     a,b,#$0c
  9066.        psh     a,b,x,y
  9067.  
  9068. \end{verbatim}
  9069. are equivalent.  As immediate expressions are still valid, \asname{} stays
  9070. upward compatible to the Mitsubishi assemblers.
  9071.  
  9072. One thing I did not fully understand while studying the Mitsubishi
  9073. assembler is the treatment of the \tty{PER} instruction: this instruction
  9074. allows to push a 16-bit variable onto the stack whose address is
  9075. specified relative to the program counter.  Therefore, it is an
  9076. absolute addressing mode from the programmer's point of view.
  9077. Nevertheless, the Mitsubishi assembler requests immediate addressing,
  9078. and the instructions argument is placed into the code just as-is.
  9079. One has to calculate the address in his own, which is something
  9080. symbolic assemblers were designed for to avoid...as I wanted to stay
  9081. compatible, \asname{} contains a compromise:  If one chooses immediate
  9082. addressing (with a leading \# sign), \asname{} will behave like the original
  9083. from Mitsubishi.  But if the \# sign is omitted, as will calculate the
  9084. difference between the argument's value and the current program
  9085. counter and insert this difference instead.
  9086.  
  9087. A similar situation exists for the \tty{PEI} instruction that pushes the
  9088. contents of a 16-bit variable located in the zero page: Though the operand
  9089. represents an address, once again immediate addressing is required.  In
  9090. this case, \asname{} will simply allow both variants (i.e. with or without a \#
  9091. sign).
  9092.  
  9093. %%---------------------------------------------------------------------------
  9094.  
  9095. \section{M16}
  9096.  
  9097. The M16 family is a family of highly complex CISC processors with an
  9098. equally complicated instruction set.  One of the instruction set's
  9099. properties is the detail that in an instruction with two operands,
  9100. both operands may be of different sizes.  The method of appending the
  9101. operand size as an attribute of the instruction (known from Motorola
  9102. and adopted from Mitsubishi) therefore had to be extended: it is
  9103. valid to append attributes to the operands themselves.  For example,
  9104. the following instruction
  9105. \begin{verbatim}
  9106.        mov     r0.b,r6.w
  9107. \end{verbatim}
  9108. reads the lowest 8 bits of register 0, sign-extends them to 32 bits
  9109. and stores the result into register 6.  However, as one does not need
  9110. this feature in 9 out of 10 cases, it is still valid to append the
  9111. operand size to the instruction itself, e.g.
  9112. \begin{verbatim}
  9113.        mov.w   r0,r6
  9114. \end{verbatim}
  9115. Both variants may be mixed; in such a case, an operand size appended
  9116. to an operand overrules the ''default''.  An exception are instructions
  9117. with two operands.  For these instructions, the default for the
  9118. source operand is the destination operand's size.  For example, in
  9119. the following example
  9120. \begin{verbatim}
  9121.        mov.h   r0,r6.w
  9122. \end{verbatim}
  9123. register 0 is accessed with 32 bits, the size specification appended
  9124. to the instruction is not used at all.  If an instruction does not
  9125. contain any size specifications, word size (\tty{w}) will be used.
  9126. Remember: in contrast to the 68000 family, this means 32 bits instead
  9127. of 16 bits!
  9128.  
  9129. The chained addressing modes are also rather complex; the ability of
  9130. \asname{} to automatically assign address components to parts of the chain
  9131. keeps things at least halfway manageable.  The only way of influencing
  9132. \asname{} allows (the original assembler from Mitsubishi/Green Hills allows
  9133. a bit more in this respect) is the explicit setting of displacement
  9134. lengths by appending \tty{:4, :16} and \tty{:32}.
  9135.  
  9136. %%---------------------------------------------------------------------------
  9137.  
  9138. \section{CP-3F}
  9139.  
  9140. The CP-3F was developed in the early 1970, a time when development systems
  9141. were also much less powerful than today.  So when the assembly language for a
  9142. new processor was designed, it was also a design target that it should be easily
  9143. translatable into machine language.  So the CP-3F's original assembler
  9144. mnemonics group into few classes that can be treated the same by an assembler:
  9145. instructions with an immediate argument of 3, 4, or 8 bits, instructions with
  9146. a register operand, branches and instructions with no argument at all.  This is
  9147. simple to translate into machine code, the readability of the source code however
  9148. leaves to be desired by today's standards - comparable to Intel's assembly
  9149. language for the 8080.  I therefore decided to provide an alternate syntax which
  9150. more clearly expresses what an instruction does:
  9151.  
  9152. \begin{longtable}{|l|l|l|}
  9153. \hline
  9154. Original & Alternate & Function \\
  9155. \hline
  9156. \hline
  9157. \endhead
  9158. \input{../doc_COM/cp3finst.tex}
  9159. \\ \hline
  9160. \caption{Alternate Instruction Syntax for CP-3F}
  9161. \label{CP3FInst}
  9162. \end{longtable}
  9163.  
  9164. %%---------------------------------------------------------------------------
  9165.  
  9166. \section{4004/4040}
  9167.  
  9168. Thanks to John Weinrich, I now have the official Intel data sheets
  9169. describing these 'grandfathers' of all microprocessors, and the questions
  9170. about the syntax of register pairs (for 8-bit operations) have been weeded
  9171. out for the moment: It is \tty{RnRm} with \tty{n} resp. \tty{m} being even
  9172. integers in the range from 0 to E resp. 1 to F.  The equation {\tt m = n +
  9173. 1} must be fulfilled.
  9174.  
  9175. %%---------------------------------------------------------------------------
  9176.  
  9177. \section{MCS-48}
  9178.  
  9179. The maximum address space of these processors is 4 Kbytes, resp.  up to
  9180. 8 Kbytes on some Philips varaints.  This address space is not organized
  9181. in a linear way (how could this be on an Intel CPU...).  Instead, it is
  9182. split into 2 banks of 2 Kbytes.  The only way to change the program
  9183. counter from one bank to the other are the instructions \tty{CALL} and
  9184. \tty{JMP}, by setting the most significant bit of the address with the
  9185. instructions \tty{SEL MB0} to \tty{SEL MB3}.
  9186.  
  9187. The assembler may be informed about the bank currently being selected for
  9188. jumps and calls, via an {\tt \asname{}SUME} statement:
  9189. \begin{verbatim}
  9190.         \asname{}SUME MB:<0..3>
  9191. \end{verbatim}
  9192. If one tries to jump to an address in a different bank, a warnig is
  9193. issued.
  9194.  
  9195. If the special value {\tt NOTHING} is used (this is by the way the
  9196. default), an automatism uilt into \tty{JMP} and \tty{CALL} is activated.
  9197. It will insert a {\tt SEL MBx} instruction if the current program counter
  9198. and the target address are located in different banks.  Explicit usage of
  9199. \tty{SEL MBx} instructions is no longer necessary (though it remains possible),
  9200. and it might interfere with this mechanism, like in the following example:
  9201. \begin{verbatim}
  9202. 000:  SEL      MB1
  9203.       JMP      200h
  9204. \end{verbatim}
  9205. \asname{} assumes that the MB flag is 0 and therefore does not insert a \tty{SEL
  9206. MB0} instruction, with the result that the CPU jumps to address
  9207. A00h.
  9208.  
  9209. Furthermore, one should keep in mind that a jump instruction might
  9210. become longer (3 instead of 2 bytes).
  9211.  
  9212. %%---------------------------------------------------------------------------
  9213.  
  9214. \section{MCS-51}
  9215.  
  9216. The assembler is accompanied by the files \tty{STDDEF51.INC} resp.
  9217. \tty{80C50X.INC} that define all bits and SFRs of the processors 8051,
  9218. 8052, and 80515 resp. 80C501, 502, and 504.  Depending on the target
  9219. processor setting (made with the \tty{CPU} statement), the correct subset
  9220. will be included.  Therefore, the correct order for the instructions
  9221. at the beginning of a program is
  9222. \begin{verbatim}
  9223.        CPU     <processor type>
  9224.        INCLUDE stddef51.inc   .
  9225. \end{verbatim}
  9226. Otherwise, the MCS-51 pseudo instructions will lead to error
  9227. messages.
  9228.  
  9229. As the 8051 does not have instructions to to push the registers 0..7
  9230. onto the stack, one has to work with absolute addresses.  However,
  9231. these addresses depend on which register bank is currently active.
  9232. To make this situation a little bit better, the include files define
  9233. the macro \tty{USING} that accepts the symbols \tty{Bank0...Bank3} as arguments.
  9234. In response, the macro will assign the registers' correct absolute
  9235. addresses to the symbols \tty{AR0..AR7}.  This macro should be used after
  9236. every change of the register banks.  The macro itself does \bb{not}
  9237. generate any code to switch to the bank!
  9238.  
  9239. The macro also makes bookkeeping about which banks have been used.
  9240. The result is stored in the integer variable \tty{RegUsage}: bit 0
  9241. corresponds to bank 0, bit 1 corresponds to bank 1. and so on.  To
  9242. output its contents after the source has been assembled, use
  9243. something like the following piece of code:
  9244. \begin{verbatim}
  9245.        irp       BANK,Bank0,Bank1,Bank2,Bank3
  9246.         if        (RegUsage&(2^BANK))<>0
  9247.          message   "bank \{BANK} has been used"
  9248.         endif
  9249.        endm
  9250. \end{verbatim}
  9251. The multipass feature introduced with version 1.38 allowed to introduce
  9252. the additional instructions \tty{JMP} and \tty{CALL}.  If branches are
  9253. coded using these instructions, \asname{} will automatically use the variant that
  9254. is optimal for the given target address.  The options are \tty{SJMP,
  9255. AJMP}, or \tty{LJMP} for \tty{JMP} resp. \tty{ACALL} or \tty{LCALL} for
  9256. \tty{CALL}.  Of course it is still possible to use these variants
  9257. directly, in case one wants to force a certain coding.
  9258.  
  9259. %%---------------------------------------------------------------------------
  9260.  
  9261. \section{MCS-251}
  9262.  
  9263. When designing the 80C251, Intel really tried to make the move to
  9264. the new family as smooth as possible for programmers.  This
  9265. culminated in the fact that old applications can run on the new
  9266. processor without having to recompile them.  However, as soon as one
  9267. wants to use the new features, some details have to be regarded which
  9268. may turn into hidden pitfalls.
  9269.  
  9270. The most important thing is the absence of a distinct address space
  9271. for bits on the 80C251.  All SFRs can now be addressed bitwise,
  9272. regardless of their address.  Furthermore, the first 128 bytes of the
  9273. internal RAM are also bit addressable.  This has become possible
  9274. because bits are not any more handled by a separate address space
  9275. that overlaps other address spaces.  Instead, similar to other
  9276. processors, bits are addressed with a two-dimensional address that
  9277. consists of the memory location containing the bit and the bit's
  9278. location in the byte.  One result is that in an expression like
  9279. \tty{PSW.7}, \asname{} will do the separation of address and bit position itself.
  9280. Unlike to the 8051, it is not any more necessary to explicitly
  9281. generate 8 bit symbols.  This has the other result that the \tty{SFRB}
  9282. instruction does not exist any more.  If it is used in a program that
  9283. shall be ported, it may be replaced with a simple \tty{SFR} instruction.
  9284.  
  9285. Furthermore, Intel cleaned up the cornucopia of different address
  9286. spaces on the 8051: the internal RAM (\tty{DATA} resp. \tty{IDATA}), the
  9287. \tty{XDATA} space and the former \tty{CODE} space were unified to a single
  9288. \tty{CODE} space that is now 16 Mbytes large.  The internal RAM starts at
  9289. address 0, the internal ROM starts at address ff0000h, which is the
  9290. address code has to be relocated to.  In contrast, the SFRs were moved to
  9291. a separate address space (which \asname{} refers to as the \tty{IO} segment).
  9292. However, they have the same addresses in this new address space as they
  9293. used to have on the 8051.  The \tty{SFR} instructions knows of this
  9294. difference and automatically assigns symbols to either the \tty{DATA} or
  9295. \tty{IO} segment, depending on the target processor.  As there is no
  9296. \tty{BIT} segment any more, the \tty{BIT} instruction operates completely
  9297. different: Instead of a linear address ranging from 0..255, a bit symbol
  9298. now contains the byte's address in bit 0..7, and the bit position in bits
  9299. 24..26.  Unfortunately, creating arrays of flags with a symbolic address
  9300. is not that simple any more: On an 8051, one simply wrote:
  9301. \begin{verbatim}
  9302.        segment bitdata
  9303.  
  9304. bit1    db      ?
  9305. bit2    db      ?
  9306.  
  9307. or
  9308.  
  9309. defbit  macro   name
  9310. name    bit     cnt
  9311. cnt     set     cnt+1
  9312.        endm
  9313. \end{verbatim}
  9314. On a 251, only the second way still works, like this:
  9315.  \begin{verbatim}
  9316. adr     set     20h     ; start address of flags
  9317. bpos    set     0       ; in the internal RAM
  9318.  
  9319. defbit  macro   name
  9320. name    bit     adr.bpos
  9321. bpos    set     bpos+1
  9322.        if      bpos=8
  9323. bpos     set     0
  9324. adr      set     adr+1
  9325.        endif
  9326.        endm
  9327. \end{verbatim}
  9328. Another small detail: Intel now prefers \tty{CY} instead of \tty{C} as a
  9329. symbolic name for the carry, so you might have to rename an already
  9330. existing variable of the same name in your program.  However, \asname{} will
  9331. continue to understand also the old variant when using the instructions
  9332. \tty{CLR, CPL, SETB, MOV, ANL,} or \tty{ORL}.  The same is conceptually
  9333. true for the additional registers \tty{R8..R15, WR0..WR30, DR0..DR28, DR56,
  9334. DR60, DPX,} and \tty{SPX}.
  9335.  
  9336. Intel would like everyone to write absolute addresses in a syntax of
  9337. \tty{XX:YYYY}, where \tty{XX} is a 64K bank in the address space resp.
  9338. signifies addresses in the I/O space with an \tty{S}.  As one might guess,
  9339. I am not amused about this, which is why it is legal to alternitavely use
  9340. linear addresses in all places.  Only the \tty{S} for I/O addresses is
  9341. incircumventable, like in this case:
  9342. \begin{verbatim}
  9343. Carry   bit     s:0d0h.7
  9344. \end{verbatim}
  9345. Without the prefix, \asname{} would assume an address in the \tty{CODE} segment,
  9346. and only the first 128 bits in this space are bit-addressable...
  9347.  
  9348. Like for the 8051, the generic branch instructions \tty{CALL} and
  9349. \tty{JMP} exist that automatically choose the shortest machine code
  9350. depending on the address layout.  However, while \tty{JMP} also may use
  9351. the variant with a 24-bit address, \tty{CALL} will not do this for a good
  9352. reason: In contrast to \tty{ACALL} and \tty{LCALL}, \tty{ECALL} places an
  9353. additional byte onto the stack.  A \tty{CALL} instruction would result where
  9354. you would not know what it will do.  This problem does not exist for the
  9355. \tty{JMP} instructions.
  9356.  
  9357. There is one thing I did not understand: The 80251 is also able to
  9358. push immediate operands onto the stack, and it may push either single
  9359. bytes or complete words.  However, the same mnemonic (\tty{PUSH}) is
  9360. assigned to both variants - how on earth should an assembler know if
  9361. an instruction like
  9362. \begin{verbatim}
  9363.        push    #10
  9364. \end{verbatim}
  9365. shall push a byte or a word containing the value 10?  So the current
  9366. rule is that \tty{PUSH} always pushes a byte; if one wants to push a word,
  9367. simply use \tty{PUSHW} instead of \tty{PUSH}.
  9368.  
  9369. Another well-meant advise: If you use the extended instruction set,
  9370. be sure to operate the processor in source mode; otherwise, all
  9371. instructions will become one byte longer!  The old 8051 instructions
  9372. that will in turn become one byte longer are not a big matter:  \asname{}
  9373. will either replace them automatically with new, more general
  9374. instructions or they deal with obsolete addressing modes (indirect
  9375. addressing via 8 bit registers).
  9376.  
  9377. %%---------------------------------------------------------------------------
  9378.  
  9379. \section{8080/8085}
  9380. \label{8080Spec}
  9381.  
  9382. As mentioned before, the statement
  9383. \begin{verbatim}
  9384.       Z80SYNTAX <ON|OFF|EXCLUSIVE>
  9385. \end{verbatim}
  9386. makes it possible to write the vast majority of 8080/8085
  9387. instructions in 'Z80 style', i.e. with less mnemonics but with
  9388. operands that are easier to understand.  In non-exclusive mode,
  9389. the Z80 syntax is not allowed for the following instructions,
  9390. because they conflict with existing 8080 mnemonics:
  9391. \begin{itemize}
  9392. \item{\tty{CP} in 'Intel syntax' means 'Call on Positive', in
  9393.      Zilog syntax however it means 'Compare'.  If you use
  9394.      \tty{CP} with a numeric value, it is not possible for the
  9395.      assembler to recognize whether a jump to an absolute
  9396.      address or a compare with an immediate value is meant.
  9397.      The assembler will generate a jump in this case, since the
  9398.      Intel syntax has precedence in case of ambiguities. If
  9399.      one wants the comparison, one may explicitly write down the
  9400.      accumulator as destination operand, e.g. \tty{CP A,12h}
  9401.      instead of \tty{CP 12h}.}
  9402. \item{\tty{JP} in Intel syntax means 'Jump on Positive', in Zilog
  9403.      syntax however, this is the jump instruction in general.
  9404.      Conditional jumps in Zilog syntax (\tty{JP cond,addr}) are
  9405.      unambigious because of the two arguments.  With only one
  9406.      argument, the assembler will however always generate the
  9407.      conditional jump.  If you want an unconditional jump to
  9408.      an absolute address, you still have to use the Intel syntax
  9409.      ((\tty{JMP addr}).}
  9410. \end{itemize}
  9411. The 8085 supports the instructions \tty{RIM} and \tty{SIM} that are
  9412. not part of the Z80 instruction set.  They may be written in 'Z80 style'
  9413. as \tty{LD A,IM} resp. \tty{LD IM,A}.
  9414. \par
  9415. The 'generic jump' {\tt J} known from the Z80 target is also
  9416. available if Z80 syntax is activated.  However, since the 8080/8085
  9417. does not support relative jumps, {\tt J} is always translated to
  9418. {\tt JP}.
  9419.  
  9420. %%---------------------------------------------------------------------------
  9421.  
  9422. \section{8085UNDOC}
  9423. \label{8085Spec}
  9424.  
  9425. Similarly to the Z80 or 6502, Intel did not further specify the
  9426. undocumented 8085 instructions.  This however means that other assemblers
  9427. might use different mnemonics for the same function.  Therefore, I will
  9428. list the instructions in the following.  Once again, usage of these
  9429. instructions is at one's own risk - even the Z80 which is principally
  9430. upward compatible to the 8085 uses the opcodes for entirely different
  9431. functions...
  9432.  
  9433. \begin{tabbing}
  9434. Arguments         \= : \= \kill \\
  9435. Instruction       \> : \> \tty{DSUB [reg]} \\
  9436. Z80 Syntax        \> : \> \tty{SUB HL,reg} \\
  9437. Function          \> : \> HL $\leftarrow$ HL - reg \\
  9438. Flags             \> : \> CY, S, X5, AC, Z, V, P \\
  9439. Arguments         \> : \> \tty{reg} = B for BC (optional for non-Z80 syntax) \\
  9440. \end{tabbing}
  9441.  
  9442. \begin{tabbing}
  9443. Arguments         \= : \= \kill \\
  9444. Instruction       \> : \> \tty{ARHL} \\
  9445. Z80 Syntax        \> : \> \tty{SRA HL} \\
  9446. Function          \> : \> HL,CY $\leftarrow$ HL $>>$ 1 (arithmetisch) \\
  9447. Flags             \> : \> CY \\
  9448. Arguments         \> : \> none resp. fixed for Z80 syntax \\
  9449. \end{tabbing}
  9450.  
  9451. \begin{tabbing}
  9452. Arguments         \= : \= \kill \\
  9453. Instruction       \> : \> \tty{RDEL} \\
  9454. Z80 Syntax        \> : \> \tty{RLC DE} \\
  9455. Function          \> : \> CY,DE $\leftarrow$ DE $<<$ 1 \\
  9456. Flags             \> : \> CY, V \\
  9457. Arguments         \> : \> none resp. fixed for Z80 syntax \\
  9458. \end{tabbing}
  9459.  
  9460. \begin{tabbing}
  9461. Arguments         \= : \= \kill \\
  9462. Instruction       \> : \> \tty{LDHI d8} \\
  9463. Z80 Syntax        \> : \> \tty{ADD DE,HL,d8} \\
  9464. Function          \> : \> DE $\leftarrow$ HL + {\tt d8} \\
  9465. Flags             \> : \> none \\
  9466. Arguments         \> : \> {\tt d8} = 8-bit constant, registers fixed for Z80 syntax \\
  9467. \end{tabbing}
  9468.  
  9469. \begin{tabbing}
  9470. Arguments         \= : \= \kill \\
  9471. Instruction       \> : \> \tty{LDSI d8} \\
  9472. Z80 Syntax        \> : \> \tty{ADD DE,SP,d8} \\
  9473. Function          \> : \> DE $\leftarrow$ SP + {\tt d8} \\
  9474. Flags             \> : \> none \\
  9475. Arguments         \> : \> {\tt d8} = 8-bit constant, registers fixed for Z80 syntax \\
  9476. \end{tabbing}
  9477.  
  9478. \begin{tabbing}
  9479. Arguments         \= : \= \kill \\
  9480. Instruction       \> : \> \tty{RSTflag} \\
  9481. Z80 Syntax        \> : \> \tty{RST flag} \\
  9482. Function          \> : \> restart to 40h if {\tt flag}=1 \\
  9483. Flags             \> : \> none \\
  9484. Arguments         \> : \> {\tt flag} = V for overflow bit \\
  9485. \end{tabbing}
  9486.  
  9487. \begin{tabbing}
  9488. Arguments         \= : \= \kill \\
  9489. Instruction       \> : \> \tty{SHLX [reg]} \\
  9490. Z80 Syntax        \> : \> \tty{LD (reg),HL} \\
  9491. Function          \> : \> [reg] $\leftarrow$ HL \\
  9492. Flags             \> : \> none \\
  9493. Arguments         \> : \> \tty{reg} = D/DE for DE (optional for non-Z80 syntax) \\
  9494. \end{tabbing}
  9495.  
  9496. \begin{tabbing}
  9497. Arguments         \= : \= \kill \\
  9498. Instruction       \> : \> \tty{LHLX [reg]} \\
  9499. Z80 Syntax        \> : \> \tty{LD HL,(reg)} \\
  9500. Function          \> : \> HL $\leftarrow$ [reg] \\
  9501. Flags             \> : \> none \\
  9502. Arguments         \> : \> \tty{reg} = D/DE for DE (optional for non-Z80 syntax) \\
  9503. \end{tabbing}
  9504.  
  9505. \begin{tabbing}
  9506. Arguments         \= : \= \kill \\
  9507. Instruction       \> : \> \tty{JNX5 addr} \\
  9508. Z80 Syntax        \> : \> \tty{JP NX5, addr} \\
  9509. Function          \> : \> jump to {\tt addr} if X5=0 \\
  9510. Flags             \> : \> none \\
  9511. Arguments         \> : \> {\tt addr} = absolute 16-bit address \\
  9512. \end{tabbing}
  9513.  
  9514. \begin{tabbing}
  9515. Arguments         \= : \= \kill \\
  9516. Instruction       \> : \> \tty{JX5 addr} \\
  9517. Z80 Syntax        \> : \> \tty{JP X5,addr} \\
  9518. Function          \> : \> jump to {\tt addr} if X5=1 \\
  9519. Flags             \> : \> none \\
  9520. Arguments         \> : \> {\tt addr} = absolute 16-bit address \\
  9521. \end{tabbing}
  9522.  
  9523. X5 refers to the otherwise unused bit 5 in the processor status word (PSW).
  9524.  
  9525. %%---------------------------------------------------------------------------
  9526.  
  9527. \section{8086..V35}
  9528.  
  9529. Actually, I had sworn myself to keep the segment disease of Intel's
  9530. 8086 out of the assembler.  However, as there was a request and as
  9531. students are more flexible than the developers of this processor
  9532. obviously were, there is now a rudimentary support of these
  9533. processors in \asname{}.  When saying, 'rudimentary', it does not mean that
  9534. the instruction set is not fully covered.  It means that the whole
  9535. pseudo instruction stuff that is available when using MASM, TASM, or
  9536. something equivalent does not exist.  To put it in clear words, \asname{}
  9537. was not primarily designed to write assembler programs for PC's
  9538. (heaven forbid, this really would have meant reinventing the wheel!);
  9539. instead, the development of programs for single-board computers was
  9540. the main goal (which may also be equipped with an 8086 CPU).
  9541.  
  9542. For die-hards who still want to write DOS programs with \asname{}, here is a
  9543. small list of things to keep in mind:
  9544. \begin{itemize}
  9545. \item{Only \tty{COM} files may be created.}
  9546. \item{Only use the \tty{CODE} segment, and place also all variables in
  9547.      this segment.}
  9548. \item{DOS initializes all segment registers to the code segment.
  9549.      An \tty{ASSUME DS:DATA, SS:DATA} right at the program's beginning
  9550.      is therefore necessary.}
  9551. \item{DOS loads the code to a start address of 100h.  An \tty{ORG} to this
  9552.      address is absolutely necessary.}
  9553. \item{The conversion to a binary file is done with P2BIN (see later in
  9554.      this document), with an address filter of \tty{\$-\$}.}
  9555. \end{itemize}
  9556. For these processors, \asname{} only supports a small programming model, i.e.
  9557. there is \bb{one} code segment with a maximum of 64 Kbytes and a data
  9558. segment of equal size for data (which cannot be set to initial values for
  9559. \tty{COM} files).  The \tty{SEGMENT} instruction allows to switch between
  9560. these two segments.  From this facts results that branches are always
  9561. intrasegment branches if they refer to targets in this single code
  9562. segment.  In case that far jumps should be necessary, they are possible
  9563. via \tty{CALLF} or \tty{JMPF} with a memory address or a
  9564. \tty{Segment:Offset} value as argument.
  9565.  
  9566. Another big problem of these processors is their assembler syntax,
  9567. which is sometimes ambiguous and whose exact meaning can then only be
  9568. deduced by looking at the current context.  In the following example,
  9569. either absolute or immediate addressing may be meant, depending on
  9570. the symbol's type:
  9571. \begin{verbatim}
  9572.        mov     ax,value
  9573. \end{verbatim}
  9574. When using \asname{}, an expression without brackets always is interpreted
  9575. as immediate addressing.  For example, when either a variable's
  9576. address or its contents shall be loaded, the differences listed in table
  9577. \ref{TabMASM} are present between MASM and \asname{}:
  9578. \begin{table*}
  9579. \begin{center}\begin{tabular}{|l|l|l|}
  9580. \hline
  9581. assembler  & address             & contents \\
  9582. \hline
  9583. \hline
  9584. MASM       &  \tty{mov ax,offset vari} &  \tty{mov ax,vari} \\
  9585.           &  \tty{lea ax,vari}        &  \tty{mov ax,[vari]} \\
  9586.           &  \tty{lea ax,[vari]}      & \\
  9587.           &                           & \\
  9588. \asname{}         &  \tty{mov ax,vari}        &  \tty{mov ax,[vari]} \\
  9589.           &  \tty{lea ax,[vari]}      & \\
  9590. \hline
  9591. \end{tabular}\end{center}
  9592. \caption{Differences \asname{}$\leftrightarrow$MASM Concerning Addressing
  9593.         Syntax\label{TabMASM}}
  9594. \end{table*}
  9595. \par
  9596. When addressing via a symbol, the assembler checks whether they are
  9597. assigned to the data segment and tries to automatically insert an
  9598. appropriate segment prefix.  This happens for example when symbols
  9599. from the code segment are accessed without specifying a \tty{CS} segment
  9600. prefix.  However, this mechanism can only work if the \tty{ASSUME}
  9601. instruction (see there) has previously been applied correctly.
  9602.  
  9603. The Intel syntax also requires to store whether bytes or words were
  9604. stored at a symbol's address.  \asname{} will do this only when the \tty{DB} resp.
  9605. \tty{DW} instruction is in the same source line as the label.  For any
  9606. other case, the operand size has to be specified explicitly with the
  9607. \tty{BYTE PTR, WORD PTR,...} operators.  As long as a register is the other
  9608. operator, this may be omitted, as the operand size is then clearly
  9609. given by the register's name.
  9610.  
  9611. In an 8086-based system, the coprocessor is usually synchronized via
  9612. via the processor's TEST input line which is connected to toe
  9613. coprocessor's BUSY output line.  \asname{} supports this type of handshaking
  9614. by automatically inserting a \tty{WAIT} instruction prior to every 8087
  9615. instruction.  If this is undesired for any reason, an \tty{N} has to be
  9616. inserted after the \tty{F} in the mnemonic; for example,
  9617. \begin{verbatim}
  9618.        FINIT
  9619.        FSTSW   [vari]
  9620. \end{verbatim}
  9621. becomes
  9622. \begin{verbatim}
  9623.        FNINIT
  9624.        FNSTSW  [vari]
  9625. \end{verbatim}
  9626. This variant is valid for \bb{all} coprocessor instructions.
  9627.  
  9628. %%---------------------------------------------------------------------------
  9629.  
  9630. \section{8X30x}
  9631. \label{8X30xSpec}
  9632.  
  9633. The processors of this family have been optimized for an easy manipulation
  9634. of bit groups at peripheral addresses.  The instructions \tty{LIV} and
  9635. \tty{RIV} were introduced to deal with such objects in a symbolic fashion.
  9636. They work similar to \tty{EQU}, however they need three parameters:
  9637. \begin{enumerate}
  9638. \item{the address of the peripheral memory cell that contains the bit
  9639.     group (0..255);}
  9640. \item{the number of the group's first bit (0..7);}
  9641. \item{the length of the group, expressed in bits (1..8).}
  9642. \end{enumerate}
  9643. \bb{CAUTION!} The 8X30x does not support bit groups that span over more
  9644. than one memory address.  Therefore, the valid value range for the
  9645. length can be stricter limited, depending on the start position.  \asname{}
  9646. does \bb{not} perform any checks at this point, you simply get strange
  9647. results at runtime!
  9648.  
  9649. Regarding the machine code, length and position are expressed vis a 3
  9650. bit field in the instruction word and a proper register number (\tty{LIVx}
  9651. resp. \tty{RIVx}).  If one uses a symbolic object, \asname{} will automatically
  9652. assign correct values to this field, but it is also allowed to
  9653. specify the length explicitly as a third operand if one does not work
  9654. with symbolic objects.  If \asname{} finds such a length specification in
  9655. spite of a symbolic operand, it will compare both lengths and issue
  9656. an error if they do not match (the same will happen for the MOVE
  9657. instruction if two symbolic operands with different lengths are used
  9658. - the instruction simply only has a single length field...).
  9659.  
  9660. Apart from the real machine instructions, \asname{} defines similarly to its
  9661. ''idol'' MCCAP some pseudo instructions that are implemented as builtin
  9662. macros:
  9663. \begin{itemize}
  9664. \item{\tty{NOP} is a shortform for \tty{MOVE AUX,AUX}}
  9665. \item{\tty{HALT} is a shortform for {\tt JMP \verb!*!}}
  9666. \item{\tty{XML ii} is a shortform for \tty{XMIT ii,R12} (only 8X305)}
  9667. \item{\tty{XMR ii} is a shortform for \tty{XMIT ii,R13} (only 8X305)}
  9668. \item{\tty{SEL $<$busobj$>$} is a shortform for \tty{XMIT $<$adr$>$,IVL/IVR},
  9669.   i.e. it performs the necessary preselection to access $<$busobj$>$.}
  9670. \end{itemize}
  9671. The \tty{CALL} and \tty{RTN} instructions MCCAP also implements are
  9672. currently missing due to sufficient documentation.  The same is true for a
  9673. set of pseudo instructions to store constants to memory.  Time may change
  9674. this...
  9675.  
  9676. %%---------------------------------------------------------------------------
  9677.  
  9678. \section{XA}
  9679.  
  9680. Similar to its predecessor MCS/51, but in contrast to its
  9681. 'competitor' MCS/251, the Philips XA has a separate address space for
  9682. bits, i.e. all bits that are accessible via bit instructions have a
  9683. certain, one-dimensional address which is stored as-is in the machine
  9684. code.  However, I could not take the obvious opportunity to offer
  9685. this third address space (code and data are the other two) as a
  9686. separate segment.  The reason is that - in contrast to the MCS/51 -
  9687. some bit addresses are ambiguous: bits with an address from 256 to 511
  9688. refer to the bits of memory cells 20h..3fh in the current data
  9689. segment.  This means that these addresses may correspond to different
  9690. physical bits, depending on the current state.  Defining bits with
  9691. the help of \tty{DC} instructions - something that would be possible with a
  9692. separate segment - would not make too much sense.  However, the \tty{BIT}
  9693. instruction still exists to define individual bits (regardless if
  9694. they are located in a register, the RAM or SFR space) that can then
  9695. be referenced symbolically.  If the bit is located in RAM, the
  9696. address of the 64K-bank is also stored.  This way, \asname{} can check
  9697. whether the DS register has previously be assigned a correct value
  9698. with an \tty{ASSUME} instruction.
  9699.  
  9700. In contrast, nothing can stop \asname{}'s efforts to align potential branch
  9701. targets to even addresses.  Like other XA assemblers, \asname{} does this by
  9702. inserting \tty{NOP}s right before the instruction in question.
  9703.  
  9704. %%---------------------------------------------------------------------------
  9705.  
  9706. \section{AVR}
  9707.  
  9708. In contrast to the AVR assembler, \asname{} by default uses the Intel format
  9709. to write hexadecimal contants instead of the C syntax.  All right, I
  9710. did not look into the (free) AVR assembler before, but when I started
  9711. with the AVR part, there was hardly mor einformation about the AVR
  9712. than a preliminary manual describing processor types that were never
  9713. sold...this problem can be solved with a simple RELAXED ON.
  9714.  
  9715. Optionally, \asname{} can generate so-called "object files" for the AVRs (it
  9716. also works for other CPUs, but it does not make any sense for them...).
  9717. These are files containing code and source line info what e.g. allows
  9718. a step-by-step execution on source level with the WAVRSIM simulator
  9719. delivered by Atmel.  Unfortunately, the simulator seems to have
  9720. trouble with source file names longer than approx. 20 characters:
  9721. Names are truncated and/or extended by strange special characters
  9722. when the maximum length is exceeded.  \asname{} therefore stores file name
  9723. specifications in object files without a path specification.
  9724. Therefore, problems may arise when files like includes are not in the
  9725. current directory.
  9726.  
  9727. A small specialty are machine instructions that have already been defined
  9728. by Atmel as part of the architecture, but up to now haven't been
  9729. implemented in any of the family's members.  The instructions in question
  9730. are {\tt MUL, JMP,} and {\tt CALL}.  Considering the latter ones, one may
  9731. ask himself how to reach the 4 Kwords large address space of the AT90S8515
  9732. when the 'next best' instructions {\tt RJMP} and {\tt RCALL} can only
  9733. branch up to 2 Kwords forward or backward.  The trick is named 'discarding
  9734. the upper address bits' and described in detail with the {\tt WRAPMODE}
  9735. statement.
  9736.  
  9737. All AVR targets support the optional CPU argument {\tt CODESEGSIZE}.
  9738. Like in this example,
  9739. \begin{verbatim}
  9740.   cpu atmega8:codesegsize=0
  9741. \end{verbatim}
  9742. it may be used to instruct the assembler to treat the code segment (i.e.
  9743. the internal flash ROM) as being organized in bytes instead of 16 bit words.
  9744. This is the view when the {\tt LPM} instruction is used, and which some other
  9745. (non Atmel) assemblers use in general.  It has the advantage that addresses
  9746. in the {\tt CODE} segment need not be multiplied by two if used for data
  9747. accesses.  On the other hand, care has to be taken that instructions do
  9748. not start on an odd address - this would be the equivalent of an instruction
  9749. occupying fractions of flash words.  The {\tt PADDING} option is therefore
  9750. enabled by default, while it remains possible to define arrays of bytes via
  9751. multiple uses of {\tt DB} or {\tt DATA} without the risk of padding bytes
  9752. inserted in between.  Target addresses for relative and absolute branches
  9753. automatically get divided by two in this ''byte mode''.  The default is the
  9754. organizazion in 16 bit word as used by the original Atmel assembler.  This
  9755. may explicitly be selected by using the argument \verb!codesegsize=1!.
  9756.  
  9757. %%---------------------------------------------------------------------------
  9758.  
  9759. \section{Z80, Z380}
  9760.  
  9761. The Z80 supports two types of jump instructions: relative ({\tt JR}) supports
  9762. jump distances from -128 to +127 bytes, while absolute jumps  ({\tt JP})
  9763. allow to reach the complete address space. \asname{} additionally supports
  9764. a pseudo instruction {\tt J} which automatically selects the shortest
  9765. possible variant, depending on the target address and the condition (relative
  9766. jumps do not support all conditions).  This also applies to all targets
  9767. 'derived' from Z80, like Z80UNDOC, Z180, RABBIT2000, and LR35902.
  9768.  
  9769. {\tt J} is also offered for the Z380, but since the Z380 supports larger
  9770. jump distances, absolute jumps will only be used if the largest possible
  9771. jump distance (+/- 8 MByte) no longer suffices.
  9772.  
  9773. This instruction should be used with thought and care, since {\tt JR} and
  9774. {\tt JP} are not entirely equivalent in function: code that exclusively
  9775. uses relative jumps is position-independent, while absolute jumps
  9776. require relocation.
  9777.  
  9778. %%---------------------------------------------------------------------------
  9779.  
  9780. \section{Z80UNDOC}
  9781.  
  9782. As one might guess, Zilog did not make any syntax definitions for the
  9783. undocumented instructions; furthermore, not everyone might know the
  9784. full set.  It might therefore make sense to list all instructions at
  9785. this place:
  9786.  
  9787. Similar to the Z380 and eZ80, it is possible to access the byte halves
  9788. of IX and IY separately.  In detail, these are the instructions that allow
  9789. this:
  9790. \begin{verbatim}
  9791. INC Rx              LD R,Rx             LD  Rx,n
  9792. DEC Rx              LD Rx,R             LD  Rx,Ry
  9793. ADD/ADC/SUB/SBC/AND/XOR/OR/CP A,Rx
  9794. \end{verbatim}
  9795. \tty{Rx} and \tty{Ry} are synonyms for \tty{IXL, IXU, IYL} or \tty{IYU}.
  9796. Keep however in mind that in the case of \tty{LD  Rx,Ry}, both registers
  9797. must be part of the same index register.
  9798.  
  9799. The coding of shift instructions leaves an undefined bit combination which
  9800. is now accessible as the tty{SL1}, \tty{SLI}, \tty{SLIA}, or \tty{SLS}
  9801. instruction.  It works like \tty{SLA} with the difference of entering a 1
  9802. into bit position 0.  \bb{CAUTION!} Some sources also name this operation
  9803. \tty{SLL}.  It decided to not offer this, since it is misleading: \tty{SLL}
  9804. translates into "shift left logically", and the operation performed by this
  9805. instruction is no logical left shift.  If one should define \tty{SLL} at
  9806. all, then as an alias for \tty{SLA}.  If you have existing code that uses
  9807. \tty{SLL} in the meaning of \tty{SL1/SLI}, define it via a macro.
  9808.  
  9809. Like all other (docummented) shift instructions, this also works in
  9810. another undocumented variant:
  9811. \begin{verbatim}
  9812.        SLIA    R,(XY+d)
  9813.        SLIA    (XY+d),R
  9814. \end{verbatim}
  9815. In this case, \tty{R} is an arbitrary 8-bit register (excluding index
  9816. register halves...), and \tty{(XY+d)} is a normal indexed address.  This
  9817. operation has the additional effect of copying the result into the
  9818. register.  This also works for the \tty{RES} and \tty{SET} instructions:
  9819. \begin{verbatim}
  9820.        SET/RES R,n,(XY+d)
  9821.        SET/RES n,(XY+d),R
  9822. \end{verbatim}
  9823. Furthermore, two hidden I/O instructions exist:
  9824. \begin{verbatim}
  9825.        IN      (C) resp. TSTI
  9826.        OUT     (C),0
  9827. \end{verbatim}
  9828. Their operation should be clear.  \bb{CAUTION!}  Noone can
  9829. guarantee that all mask revisions of the Z80 execute these
  9830. instructions, and the Z80's successors will react with traps if they
  9831. find one of these instructions.  Use them on your own risk...
  9832.  
  9833. %%---------------------------------------------------------------------------
  9834.  
  9835. \section{GB\_Z80 resp. LR35902}
  9836.  
  9837. The LR35902 SoC used in the original Gameboy  was developed by Sharp,
  9838. and the CPU core is (probably) the same as in the SM83
  9839. microcontrollers.  Regarding its instruction set, it is somewhere
  9840. ''half way'' between 8080 and Z80, however with its own omissions and
  9841. extensions.  Sharp of course defined an assembler syntax for the new
  9842. instructions.  However, variations have established itself in the
  9843. ''Gameboy scene''.  I tried to regard those as well (as far as I am
  9844. aware of them):
  9845.  
  9846. \begin{center}\begin{tabular}{|l|l|l|}
  9847. \hline
  9848. Sharp & Alternate & Function \\
  9849. \hline
  9850. \hline
  9851. LD A,(HLD)    & LD A,(HL-)  & A $\longleftarrow$ (HL), \\
  9852.              & LDD A,(HL)  & HL $\longleftarrow$ HL-1 \\
  9853. \hline
  9854. LD A,(HLI)    & LD A,(HL+)  & A $\longleftarrow$ (HL), \\
  9855.              & LDI A,(HL)  & HL $\longleftarrow$ HL+1 \\
  9856. \hline
  9857. LD (HLD),A    & LD (HL-),A  & (HL) $\longleftarrow$ A, \\
  9858.              & LDD (HL),A  & HL $\longleftarrow$ HL-1 \\
  9859. \hline
  9860. LD (HLI),A    & LD (HL+),A  & (HL) $\longleftarrow$ A, \\
  9861.              & LDI (HL),A  & HL $\longleftarrow$ HL+1 \\
  9862. \hline
  9863. LD A,(C)      & LD A,(FF00+C) & A $\longleftarrow$ (0ff00h+C) \\
  9864.              & LDH A,(C)     & \\
  9865. \hline
  9866. LD (C),A      & LD (FF00+C),A & (0ff00h+C) $\longleftarrow$ A \\
  9867.              & LDH (C),A     & \\
  9868. \hline
  9869. LD (FF00+n),A & LDH (n),A     & (0ff00h+n) $\longleftarrow$ A \\
  9870. \hline
  9871. LD A,(FF00+n) & LDH A,(n)     & A $\longleftarrow$ (0ff00h+n) \\
  9872. \hline
  9873. LDHL SP,d     & LD HL,SP+d    & HL $\longleftarrow$ SP + d \\
  9874. \hline
  9875. LDX A,(nn)    & LD A,(nn)     & A $\longleftarrow$ (nn) $^{1}$ \\
  9876. \hline
  9877. LDX (nn),A    & LD (nn),A     & (nn) $\longleftarrow$ A $^{1}$ \\
  9878. \hline
  9879. \multicolumn{3}{|l|}{$^{1}$ enforces 16 bit addressing } \\
  9880. \hline
  9881. \end{tabular}\end{center}
  9882.  
  9883. %%---------------------------------------------------------------------------
  9884.  
  9885. \section{Z380}
  9886.  
  9887. As this processor was designed as a grandchild of the still most popular
  9888. 8-bit microprocessor, it was a sine-qua-non design target to execute
  9889. existing Z80 programs without modification (of course, they execute a bit
  9890. faster, roughly by a factor of 10...).  Therefore, all extended features
  9891. can be enabled after a reset by setting two bits which are named XM
  9892. (eXtended Mode, i.e. a 32-bit instead of a 16-bit address space)
  9893. respectively LW (long word mode, i.e. 32-bit instead of 16-bit operands).
  9894. One has to inform \asname{} about their current setting with the instructions
  9895. \tty{EXTMODE} resp. \tty{LWORDMODE}, to enable \asname{} to check addresses and
  9896. constants against the correct upper limits.  The toggle between 32- and
  9897. 16-bit instruction of course only influences instructions that are
  9898. available in a 32-bit variant.  Unfortunately, the Z380 currently offers
  9899. such variants only for load and store instructions; arithmetic can only be
  9900. done in 16 bits.  Zilog really should do something about this, otherwise
  9901. the most positive description for the Z380 would be ''16-bit processor
  9902. with 32-bit extensions''...
  9903.  
  9904. The whole thing becomes complicated by the ability to override the operand
  9905. size set by LW with the instruction prefixes \tty{DDIR W} resp.
  9906. \tty{DDIR LW}.  \asname{} will note the occurrence of such instructions and will
  9907. toggle setting for the instruction following directly.  By the way, one
  9908. should never explicitly use other \tty{DDIR} variants than \tty{W} resp.
  9909. \tty{LW}, as \asname{} will introduce them automatically when an operand is
  9910. discovered that is too long.  Explicit usage might puzzle \asname{}.  The
  9911. automatism is so powerful that in a case like this:
  9912. \begin{verbatim}
  9913.        DDIR    LW
  9914.        LD      BC,12345678h   ,
  9915. \end{verbatim}
  9916. the necessary \tty{IW} prefix will automatically be merged into the previous
  9917. instruction, resulting in
  9918. \begin{verbatim}
  9919.        DDIR    LW,IW
  9920.        LD      BC,12345668h   .
  9921. \end{verbatim}
  9922. The machine code that was first created for \tty{DDIR LW} is retracted and
  9923. replaced, which is signified with an \tty{R} in the listing.
  9924.  
  9925. %%---------------------------------------------------------------------------
  9926.  
  9927. \section{Z8, Super8, and eZ8}
  9928. \label{Z8Spec}
  9929.  
  9930. The CPU core contained in the Z8 microcontrollers does not
  9931. contain any specific registers.  Instead, a block of 16
  9932. consecutive cells of the internal address space (contains RAM and
  9933. I/O registers) may be used as 'work registers' and be addressed
  9934. with 4-bit addresses.  The RP registers define which memory block
  9935. is used as work registers: on a classic Z8, bits 4 to 7 of RP
  9936. define the 'offset' that is added to a 4-bit work register
  9937. address to get a complete 8-bit address.  The Super8 core
  9938. features two register pointers (RP0 and RP1), which allow mapping
  9939. the lower and upper half of work registers to separate places.
  9940.  
  9941. Usually, one refers to work registers as R0..R15 in assembly
  9942. statements.  It is however also posssible to regard work registers as
  9943. an efficient way to address a block of memory addresses in internal
  9944. RAM.
  9945.  
  9946. The \tty{ASSUME} statement is used to inform \asname{} about the current
  9947. value of RP. \asname{} is then capable to automatically decide whether an
  9948. address in internal RAM may be reached with a 4-bit or 8-bit address.
  9949. This may be used to assign symbolic names to work registers:
  9950. \begin{verbatim}
  9951. op1     equ     040h
  9952. op2     equ     041h
  9953.  
  9954.        srp     #040h
  9955.        assume  rp:040h
  9956.  
  9957.        ld      op1,op2         ; equal to ld r0,r1
  9958. \end{verbatim}
  9959. Note that though the Super8 does not have an RP register (only
  9960. RP0 and RP1), RP as argument to \tty{ASSUME} is still allowed -
  9961. it will set the assumed values of RP0 and RP1 to $value$ resp.
  9962. $value+8$, as the \tty{SRP} machine instruction does on the Super
  9963. 8 core.
  9964.  
  9965. Opposed to the original Zilog assembler, it is not necessary to
  9966. explicitly specify 'work register addressing' with a prefixed
  9967. exclamation mark.  \asname{} however also understands this syntax - a
  9968. prefixed exclamation mark enforces 4-bit addressing, even when the
  9969. address does not lie within the 16-address block defined by RP (\asname{} will
  9970. issue a warning in that case).  Vice versa, a prefixed $>$
  9971. character enforces 8-bit addressing even when the address is within
  9972. the current 16-address block.
  9973.  
  9974. The eZ8 takes this 'game' to the next level: the internal address
  9975. space now has 12 instead of 8 bits.  To assure compatibility with the
  9976. old Z8 core, Zilog placed the additional 4 bits in the {\em lower}
  9977. four bits of RP.  For instance, an RP value of 12h defines an address
  9978. window from 210h to 21fh.
  9979.  
  9980. At the same time, the lower four bits of RP define a window of 256
  9981. addresses that can be addressed with 8-bit addresses.  The mechanism
  9982. to automatically select between 8- and 12-bit addresses is analogous.
  9983. 'Long' 12-bit addresses may be enforced by prefixing two $>$
  9984. characters.
  9985.  
  9986. %%---------------------------------------------------------------------------
  9987.  
  9988. \section{Z8000}
  9989. \label{Z8000Spec}
  9990.  
  9991. A Z8001/8003 may be operated in one of two modes:
  9992.  
  9993. \begin{itemize}
  9994. \item{{\em Non-Segmented}: The memory address space is limited to 64 KBytes,
  9995.      and all addresses are 'simple' linear 16 bit addresses.  Address
  9996.      registers are single 16 bit registers (Rn), and absolute addresses
  9997.      within instructions are one byte long.}
  9998. \item{{\em Segmented}: Memory is structured into up to 128 segments of up
  9999.      to 64 KBytes size.  Addresses consist of a 7 bit segment number and a
  10000.      16 bit offset. Address registers are register pairs (RRn).  Absolute
  10001.      addresses in instructions occupy two 16 bit words, unless the offset
  10002.      is smaller than 256.}
  10003. \end{itemize}
  10004.  
  10005. The operation mode (segmented or non-segmented) therefore has an influence
  10006. on the generated code and is selected implicitly via the selected processor
  10007. type.  For instance, if the target is a Z8001 in non-segmented mode, use
  10008. Z8002 as target.
  10009.  
  10010. However, similar to the 8086, there is no 'real' support for a segmented
  10011. memory model in \asname{}. In segmented mode, the segment number is simply interpreted
  10012. as the upper seven bits of a virtually linear address space.  Though this is
  10013. not what Zilog intended, it is the way the segment number was used on the
  10014. Z8001 if the system had no MMU.
  10015.  
  10016. \asname{} in general implements the Z8000 machine instruction syntax as it is specified
  10017. by Zilog in its manuals.  However, there are assemblers that support extensions
  10018. or variations of the syntax.  \asname{} implements a few of them as well:
  10019.  
  10020. \subsection{Conditions}
  10021.  
  10022. In addition to the conditions defined by Zilog, the following alternative names
  10023. are defined:
  10024.  
  10025. \begin{center}\begin{tabular}{|l|l|l|}
  10026. \hline
  10027. Alternate & Zilog & Meaning \\
  10028. \hline
  10029. \hline
  10030. ZR         & Z     & Z = 1 \\
  10031. CY         & C     & C = 1 \\
  10032. LLE        & ULE   & (C OR Z) = 1 \\
  10033. LGE        & UGE   & C = 0 \\
  10034. LGT        & UGT   & ((C = 0) AND (Z = 0)) = 1 \\
  10035. LLT        & ULT   & C = 1 \\
  10036. \hline
  10037. \end{tabular}\end{center}
  10038.  
  10039. \subsection{Flags}
  10040.  
  10041. \tty{SETFLG}, \tty{COMFLG} und \tty{RESFLG} accept the following alternate names
  10042. as arguments:
  10043.  
  10044. \begin{center}\begin{tabular}{|l|l|l|}
  10045. \hline
  10046. Alternate & Zilog & Meaning \\
  10047. \hline
  10048. \hline
  10049. ZR         & Z     & Zero Flag \\
  10050. CY         & C     & Carry Flag \\
  10051. \hline
  10052. \end{tabular}\end{center}
  10053.  
  10054. \subsection{Indirect Addressing}
  10055.  
  10056. It is valid to write \verb!Rn^! instead of \verb!@Rn!, if the option
  10057. \tty{AMDSyntax=1} was given to the \tty{CPU} statement.  If an I/O address
  10058. is addressed indirectly, this option even allows to write just \verb!Rn!.
  10059.  
  10060. \subsection{Direct versus Immediate Addressing}
  10061.  
  10062. The Zilog syntax mandates that immediate addressing has to be done by prefixing
  10063. the argument with a hash character.  However, if the \tty{AMDSyntax=1} option
  10064. was given to the \tty{CPU} statement, the type of argument (label or constant)
  10065. decides whether immediate or direct addressing is to be used.  Immediate addressing
  10066. may be forced by prefixing the argument with a circumflex, i.e. to load the address
  10067. of a label into a register.
  10068.  
  10069. %%---------------------------------------------------------------------------
  10070.  
  10071. \section{TLCS-900(L)}
  10072. \label{TLCS900Spec}
  10073.  
  10074. These processors may run in two operating modes: on the one hand, in
  10075. minimum mode, which offers almost complete source code compatibility
  10076. to the Z80 and TLCS-90, and on the other hand in maximum mode, which
  10077. is necessary to make full use of the processor's capabilities.  The
  10078. main differences between these two modes are:
  10079. \begin{itemize}
  10080. \item{width of the registers WA, BC, DE, and HL: 16 or 32 bits;}
  10081. \item{number of register banks: 8 or 4;}
  10082. \item{code address space: 64 Kbytes or 16 Mbytes;}
  10083. \item{length of return addresses: 16 or 32 bits.}
  10084. \end{itemize}
  10085. To allow \asname{} to check against the correct limits, one has to inform him
  10086. about the current execution mode via the \tty{MAXMODE} instruction (see
  10087. there).  The default is the minimum mode.
  10088.  
  10089. From this follows that, depending on the operating mode, the 16-bit
  10090. resp. 32-bit versions of the bank registers have to be used for
  10091. addressing, i.e. WA, BC, DE and HL for the minimum mode resp. XWA,
  10092. XBC, XDE and XHL for the maximum mode.  The registers XIX..XIZ and
  10093. XSP are \bb{always} 32 bits wide and therefore always have to to be used
  10094. in this form for addressing; in this detail, existing Z80 code
  10095. definitely has to be adapted (not including that there is no I/O
  10096. space and all I/O registers are memory-mapped...).
  10097.  
  10098. Absolute addresses and displacements may be coded in different
  10099. lengths.  Without an explicit specification, \asname{} will always use
  10100. the shortest possible coding.  This includes eliminating a zero
  10101. displacement, i.e. \verb!(XIX+0)! becomes \verb!(XIX)!.  If a certain
  10102. length is needed, it may be forced by appending a suffix (:8, :16,
  10103. :24) to the displacmenet resp. the address.
  10104.  
  10105. The syntax chosen by Toshiba is a bit unfortunate in the respect of
  10106. choosing an single quote (') to reference the previous register bank.  The
  10107. processor independent parts of \asname{} already use this character to mark
  10108. character constants.  In an instruction like
  10109. \begin{verbatim}
  10110.        ld      wa',wa   ,
  10111. \end{verbatim}
  10112. \asname{} will not recognize the comma for parameter separation.  This
  10113. problem can be circumvented by usage of an inverse single quote (`), for
  10114. example
  10115. \begin{verbatim}
  10116.        ld      wa`,wa
  10117. \end{verbatim}
  10118. Toshiba delivers an own assembler for the TLCS-900 series (TAS900),
  10119. which is different from \asname{} in the following points:
  10120.  
  10121. \subsubsection{Symbol Conventions}
  10122.  
  10123. \begin{itemize}
  10124. \item{TAS900 differentiates symbol names only on the first 32
  10125.      characters.  In contrast, \asname{} always stores symbol names with the
  10126.      full length (up to 255 characters) and uses them all for
  10127.      differentiation.}
  10128. \item{TAS900 allows to write integer constants either in Intel or C
  10129.      notation (with a 0 prefix for octal or a 0x prefix for hexadecimal
  10130.      constants).  By default, \asname{} only supports the Intel notation.
  10131.      With the help of the \tty{RELAXED} instruction, one also gets the C
  10132.      notation (among other).}
  10133. \item{\asname{} does not distinguish between upper and lower case.  In
  10134.      contrast, TAS900 differentiates between upper- and lowercase
  10135.      letters in symbol names.  One needs to engage the \tty{-u} command
  10136.      line option to force \asname{} to do this.}
  10137. \end{itemize}
  10138.  
  10139. \subsubsection{Syntax}
  10140.  
  10141. For many instructions, the syntax checking of \asname{} is less strict than
  10142. the checking of TAS900.  In some (rare) cases, the syntax is slightly
  10143. different.  These extensions and changes are on the one hand for the
  10144. sake of a better portability of existing Z80 codes, on the other hand
  10145. they provide a simplification and better orthogonality of the
  10146. assembly syntax:
  10147. \begin{itemize}
  10148. \item{In the case of \tty{LDA, JP}, and \tty{CALL}, TAS requires that address
  10149.      expressions like \tty{XIX+5} must not be placed in parentheses, as it
  10150.      is usually the case.  For the sake of better orthogonality, \asname{}
  10151.      requires parentheses for \tty{LDA}.  They are optional if \tty{JP} resp.
  10152.      \tty{CALL} are used with a simple, absolute address.}
  10153. \item{In the case of \tty{JP, CALL, JR}, and \tty{SCC}, \asname{} leaves the choice to the
  10154.      programmer whether to explicitly write out the default condition
  10155.      \tty{T} (= true) as first parameter or not.  TAS900 in contrast only
  10156.      allows to use the default condition implicitly (e.g. \tty{jp (xix+5)}
  10157.      instead of \tty{jp t,(xix+5))}.}
  10158. \item{For the \tty{EX} instruction, \asname{} allows operand combinations which are
  10159.      not listed in \cite{Tosh900} but can be reduced to a standard
  10160.      combination by swapping the operands.  Combinations like \tty{EX f`,f}
  10161.      or \tty{EX wa,(xhl)} become possible.  In contrast, TAS900 limits to
  10162.      the 'pure' combinations.}
  10163. \item{\asname{} allows to omit an increment resp. decrement of 1 when using the
  10164.      instructions \tty{INC} and \tty{DEC}.  TAS900 instead forces the programmer to
  10165.      explicit usage of '1'.}
  10166. \item{The similar is true for the shift instructions: If the operand is
  10167.      a register, TAS900 requires that even a shift count of 1 has to
  10168.      be written explicitly; however, when the operand is in memory,
  10169.      the hardware limits the shift count to 1 which must not be written
  10170.      in this case.  With \asname{}, a shift count of 1 is always optional and
  10171.      valid for all types of operands.}
  10172. \end{itemize}
  10173.  
  10174. \subsubsection{Macro Processor}
  10175.  
  10176. The macro processor of TAS900 is an external program that operates
  10177. like a preprocessor.  It consists of two components: The first one is
  10178. a C-like preprocessor, and the second one is a special macro language
  10179. (MPL) that reminds of high level languages.  The macro processor of
  10180. \asname{} instead is oriented towards ''classic'' macro assemblers like MASM
  10181. or M80 (both programs from Microsoft).  It is a fixed component of
  10182. \asname{}.
  10183.  
  10184. \subsubsection{Output Format}
  10185.  
  10186. TAS900 generates relocatable code that allows to link separately
  10187. compiled programs to a single application.  \asname{} instead generates
  10188. absolute machine code that is not linkable.  There are currently no
  10189. plans to extend \asname{} in this respect.
  10190.  
  10191. \subsubsection{Pseudo Instructions}
  10192.  
  10193. Due to the missing linker, \asname{} lacks a couple of pseudo instructions
  10194. needed for relocatable code TAS900 implements.  The following
  10195. instructions are available with equal meaning:
  10196. \begin{quote}\tt
  10197.   EQU, DB, DW, ORG, ALIGN, END, TITLE, SAVE, RESTORE
  10198. \rm\end{quote}
  10199. The latter two have an extended functionality for \asname{}.  Some TAS900
  10200. pseudo instructions can be replaced with equivalent \asname{} instructions (see
  10201. table \ref{TabTAS900}).
  10202. \par
  10203. \begin{table*}[htbp]
  10204. \begin{center}\begin{tabular}{|l|l|l|}
  10205. \hline
  10206. TAS900           & \asname{}                  &     meaning/function \\
  10207. \hline
  10208. \hline
  10209. \tty{DL} $<$Data$>$    & \tty{DD} $<$Data$>$           & define longword constants \\
  10210. \hline
  10211. \tty{DSB} $<$number$>$ & \tty{DB} $<$number$>$ \tty{DUP} (?) & reserve bytes of memory \\
  10212. \hline
  10213. \tty{DSW} $<$number$>$ & \tty{DW} $<$number$>$ \tty{DUP} (?) & reserve words of memory \\
  10214. \hline
  10215. \tty{DSD} $<$number$>$ & \tty{DD} $<$number$>$ \tty{DUP} (?) & reserve longwords of memory \\
  10216. \hline
  10217. \tty{\$MIN[IMUM]}      & \tty{MAXMODE OFF}             & following code runs \\
  10218.                       &                               & in minimum mode \\
  10219. \hline
  10220. \tty{\$MAX[IMUM]}      & \tty{MAXMODE ON}              & following code runs \\
  10221.                       &                               & in maximum mode \\
  10222. \hline
  10223. \tty{\$SYS[TEM]}       & \tty{SUPMODE ON}              & following code runs \\
  10224.                       &                               & in system mode \\
  10225. \hline
  10226. \tty{\$NOR[MAL]}       & \tty{SUPMODE OFF}             & following code runs \\
  10227.                       &                               & in user mode \\
  10228. \hline
  10229. \tty{\$NOLIST}         & \tty{LISTING OFF}             & turn off assembly listing \\
  10230. \hline
  10231. \tty{\$LIST}           & \tty{LISTING ON}              & turn on assembly listing \\
  10232. \hline
  10233. \tty{\$EJECT}          & \tty{NEWPAGE}                 & start new page in listing \\
  10234. \hline
  10235. \end{tabular}\end{center}
  10236. \caption{equivalent instructions TAS900$\leftrightarrow$\asname{}\label{TabTAS900}}
  10237. \end{table*}
  10238. Toshiba manufactures two versions of the processor core, with the L
  10239. version being an ''economy version''.  \asname{} will make the following
  10240. differences between TLCS-900 and TLCS-900L:
  10241. \begin{itemize}
  10242. \item{The instructions \tty{MAX} and \tty{NORMAL} are not allowed for the L version;
  10243.      the \tty{MIN} instruction is disabled for the full version.}
  10244. \item{The L version does not know the normal stack pointer XNSP/NSP, but
  10245.      instead has the interrupt nesting register INTNEST.}
  10246. \end{itemize}
  10247. The instructions \tty{SUPMODE} and \tty{MAXMODE} are not influenced, just as
  10248. their initial setting \tty{OFF}.  The programmer has to take care of the
  10249. fact that the L version starts in maximum mode and does not have a
  10250. normal mode.  However, \asname{} shows a bit of mercy against the L variant
  10251. by suppressing warnings for privileged instructions.
  10252.  
  10253. %%---------------------------------------------------------------------------
  10254.  
  10255. \section{TLCS-90}
  10256.  
  10257. Maybe some people might ask themselves if I mixed up the order a
  10258. little bit, as Toshiba first released the TLCS-90 as an extended Z80
  10259. and afterwards the 16-bit version TLCS-900.  Well, I discovered the
  10260. '90 via the '900 (thank you Oliver!).  The two families are quite
  10261. similar, not only regarding their syntax but also in their
  10262. architecture.  The hints for the '90 are therefore a subset of of the
  10263. chapter for the '900: As the '90 only allows shifts, increments, and
  10264. decrements by one, the count need not and must not be written as the
  10265. first argument.  Once again, Toshiba wants to omit parentheses for
  10266. memory operands of \tty{LDA, JP, and CALL}, and once again \asname{} requires them
  10267. for the sake of orthogonality (the exact reason is of course that
  10268. this way, I saved an extra in the address parser, but one does not
  10269. say such a thing aloud).
  10270.  
  10271. Principally, the TLCS-90 series already has an address space of 1
  10272. Mbyte which is however only accessible as data space via the index
  10273. registers.  \asname{} therefore does not regard the bank registers and
  10274. limits the address space to 64 Kbytes.  This should not limit too
  10275. much as this area above is anyway only reachable via indirect
  10276. addressing.
  10277.  
  10278. %%---------------------------------------------------------------------------
  10279.  
  10280. \section{TLCS-870}
  10281.  
  10282. Once again Toshiba...a company quite productive at the moment!
  10283. Especially this branch of the family (all Toshiba microcontrollers
  10284. are quite similar in their binary coding and programming model) seems
  10285. to be targeted towards the 8051 market: the method of separating the
  10286. bit position from the address expression with a dot had its root in
  10287. the 8051.  However, it creates now exactly the sort of problems I
  10288. anticipated when working on the 8051 part: On the one hand, the dot
  10289. is a legal part of symbol names, but on the other hand, it is part of
  10290. the address syntax.  This means that \asname{} has to separate address and
  10291. bit position and must process them independently.  Currently, I
  10292. solved this conflict by seeking the dot starting at the \bb{end} of the
  10293. expression.  This way, the last dot is regarded as the separator, and
  10294. further dots stay parts of the address.   I continue to urge everyone
  10295. to omit dots in symbol names, they will lead to ambiguities:
  10296. \begin{verbatim}
  10297.        LD      CF,A.7  ; accumulator bit 7 to carry
  10298.        LD      C,A.7   ; constant 'A.7' to accumulator
  10299. \end{verbatim}
  10300.  
  10301. %%---------------------------------------------------------------------------
  10302.  
  10303. \section{TLCS-47}
  10304.  
  10305. This family of 4-bit microcontrollers should mark the low end of what
  10306. is supportable by \asname{}.  Apart from the \tty{ASSUME} instruction for the data
  10307. bank register (see there), there is only one thing that is worth
  10308. mentioning: In the data and I/O segment, nibbles are reserved instead
  10309. of byte (it's a 4-bitter...).  The situation is similar to the bit
  10310. data segment of the 8051, where a \tty{DB} reserves a single bit, with the
  10311. difference that we are dealing with nibbles.
  10312.  
  10313. Toshiba defined an ''extended instruction set'' for this processor
  10314. family to facilitate the work with their limited instruction set.  In
  10315. the case of \asname{}, it is defined in the include file \tty{STDDEF47.INC}.
  10316. However, some instructions that could not be realized as macros are
  10317. ''builtins'' and are therefore also available without the include file:
  10318. \begin{itemize}
  10319. \item{the \tty{B} instruction that automatically chooses the optimal version
  10320.      of the jump instruction (\tty{BSS; BS}, or \tty{BSL});}
  10321. \item{\tty{LD} in the variant of \tty{HL} with an immediate operand;}
  10322. \item{\tty{ROLC} and \tty{RORC} with a shift amplitude higher than one.}
  10323. \end{itemize}
  10324.  
  10325. %%---------------------------------------------------------------------------
  10326.  
  10327. \section{TLCS-9000}
  10328.  
  10329. This was the first time that I implemented a processor for \asname{} which
  10330. was not yet available at that point of time.  And unfortunately,
  10331. I received back then information that Toshiba had decided no to
  10332. maket this processor at all.  This of course had the result that
  10333. the TLCS-9000 part of the assembler
  10334. \begin{enumerate}
  10335. \item{was a ''paper design'', i.e. there was so far no chance to test
  10336.      it on real hardware and}
  10337. \item{the documentation for the '9000 I could get hold of \cite{Tosh9000}
  10338.      was preliminary and was unclear in a couple of detail
  10339.      issues.}
  10340. \end{enumerate}
  10341. So i effect, this target went into 'dormant mode'...
  10342.  
  10343. ...cut, 20 years have passed: all of a sudden, people are
  10344. contacting me and tell me that Toshiba actually did sell
  10345. TLCS-9000 chips to customers, and they ask for documentation to
  10346. do reverse engineering.  Maybe this will shed some light on the
  10347. remaining unclarities.  Nevertheless, errors in this code generator
  10348. are quite possible (and will of course be fixed!).  At least the
  10349. few examples listed in \cite{Tosh9000} are assembled correctly.
  10350.  
  10351. Displacements included in machine instructions may only have a
  10352. certain maximum length (e.g. 9 or 13 bits).  In case the
  10353. displacement is longer, a prefix containing the 'upper bits' must
  10354. be prepended to the instruction.  \asname{} will automatically insert
  10355. such prefixes when necessary, however it is also possible to
  10356. force usage of a prefix by adding a leading \verb!'>'!.  An
  10357. example for this:
  10358.  
  10359. \begin{verbatim}
  10360.  ld:g.b  (0h),0       ; no prefix
  10361.  ld:g.b  (400000h),0  ; prefix added automatically
  10362.  ld:g.b  (>0h),0      ; forced prefix
  10363. \end{verbatim}
  10364.  
  10365. %%---------------------------------------------------------------------------
  10366.  
  10367. \section{TC9331}
  10368.  
  10369. Toshiba supplied a (DOS-based) assembler for this processor which
  10370. was named ASM31T.  This assembler supports a number of syntax
  10371. elements which could not be mapped on the capabilities of \asname{}
  10372. without risking incompatibilities for existing source files for
  10373. other targets.  The following issues might require changes on
  10374. programs written for ASM31T:
  10375.  
  10376. \begin{itemize}
  10377. \item{ASM31T supports C-like comments (\verb!/* ... */!) which
  10378.      may also span multiple lines.  Such comments are not
  10379.      supported by \asname{} and have to be replaced by comments
  10380.      beginning with a semicolon.}
  10381. \item{Similar to ASM31T, \asname{} supports comments with round parentheses
  10382.      (\verb!( ... )!), however only within a single command
  10383.      argument.  Should such a comment contain a comma, this
  10384.      comma will be treated like an argument separator and the
  10385.      comment will not be skipped when parsing the arguments.}
  10386. \item{ASM31T allows symbol and label names containing a dash.
  10387.      \asname{} does not allow this, because the dash is regarded to be
  10388.      the subtraction operator.  It would be unclear whether an
  10389.      expression like \verb!end-start! represents a single symbol
  10390.      or the difference of two symbols.}
  10391. \item{ASM31T requires an \tty{END} statement as the last
  10392.      statement of the program; this is optional for \asname{}.}
  10393. \end{itemize}
  10394.  
  10395. Furthermore, \asname{} currently lacks the capabilities to detect
  10396. conflicting uses of functional units in a machine instructions.
  10397. Toshiba's documentation is a bit difficult to understand in this
  10398. respect...
  10399.  
  10400. %%---------------------------------------------------------------------------
  10401.  
  10402. \section{29xxx}
  10403.  
  10404. As it was already described in the discussion of the \tty{ASSUME}
  10405. instruction, \asname{} can use the information about the current setting of
  10406. the RBP register to detect accesses to privileged registers in user
  10407. mode.  This ability is of course limited to direct accesses (i.e.
  10408. without using the registers IPA...IPC), and there is one more
  10409. pitfall: as local registers (registers with a number $>$127) are
  10410. addressed relative to the stack pointer, but the bits in RBP always
  10411. refer to absolute numbers, the check is NOT done for local registers.
  10412. An extension would require \asname{} to know always the absolute value of
  10413. SP, which would at least fail for recursive subroutines...
  10414.  
  10415. %%---------------------------------------------------------------------------
  10416.  
  10417. \section{80C16x}
  10418.  
  10419. As it was already explained in the discussion of the \tty{ASSUME}
  10420. instruction, \asname{} tries to hide the fact that the processor has more
  10421. physical than logical RAM as far as possible.  Please keep in mind
  10422. that the DPP registers are valid only for data accesses and only
  10423. have an influence on absolute addressing, neither on indirect nor on indexed
  10424. addresses.  \asname{} cannot know which value the computed address may take
  10425. at runtime...
  10426. The paging unit unfortunately does not operate for code accesses so
  10427. one has to work with explicit long or short \tty{CALL}s, \tty{JMP}s, or
  10428. \tty{RET}s.  At least for the ''universal'' instructions \tty{CALL} and
  10429. \tty{JMP}, \asname{} will automatically use the shortest variant, but at least for the RET one
  10430. should know where the call came from.  \tty{JMPS} and \tty{CALLS} principally
  10431. require to write segment and address separately, but \asname{} is written in
  10432. a way that it can split an address on its own, e.g. one can write
  10433. \begin{verbatim}
  10434.        jmps    12345h
  10435. \end{verbatim}
  10436. instead of
  10437. \begin{verbatim}
  10438.        jmps    1,2345h
  10439. \end{verbatim}
  10440. Unfortunately, not all details of the chip's internal instruction
  10441. pipeline are hidden: if CP (register bank address), SP (stack), or
  10442. one of the paging registers are modified, their value is not
  10443. available for the instruction immediately following.  \asname{} tries to
  10444. detect such situations and will issue a warning in such cases.  Once
  10445. again, this mechanism only works for direct accesses.
  10446.  
  10447. Bits defined with the \tty{BIT} instruction are internally stored as a
  10448. 12-bit word, containing the address in bits 4..11 and the bit
  10449. position in the four LSBs.  This order allows to refer the next resp.
  10450. previous bit by incrementing or decrementing the address.  This will
  10451. however not work for explicit bit specifications when a word boundary
  10452. is crossed.  For example, the following expression will result in a
  10453. range check error:
  10454. \begin{verbatim}
  10455.        bclr    r5.15+1
  10456. \end{verbatim}
  10457. We need a \tty{BIT} in this situation:
  10458. \begin{verbatim}
  10459. msb     bit     r5.15
  10460.        .
  10461.        .
  10462.        bclr    msb+1
  10463. \end{verbatim}
  10464. The SFR area was doubled for the 80C167/165/163: bit 12 flags that a bit
  10465. lies in the second part.  Siemens unfortunately did not foresee that
  10466. 256 SFRs (128 of them bit addressable) would not suffice for
  10467. successors of the 80C166.  As a result, it would be impossible to
  10468. reach the second SFR area from F000H..F1DFH with short addresses or
  10469. bit instructions if the developers had not included a toggle
  10470. instruction:
  10471. \begin{verbatim}
  10472.        EXTR    #n
  10473. \end{verbatim}
  10474. This instruction has the effect that for the next \tty{n} instructions
  10475. ($0<n<5$), it is possible to address the alternate SFR space instead of
  10476. the normal one.  \asname{} does not only generate the appropriate machine
  10477. code when it encounters this instruction.  It also sets an internal
  10478. flag that will only allow accesses to the alternate SFR space for
  10479. the next \tty{n} instructions.  Of course, they may not contain jumps...
  10480. Of course, it is always possible to define bits from either area at
  10481. any place, and it is always possible to reach all registers with
  10482. absolute addresses.  In contrast, short and bit addressing only works
  10483. for one area at a time, attempts contradicting to this will result in
  10484. an error message.
  10485.  
  10486. The situation is similar for prefix instructions and absolute resp.
  10487. indirect addressing: as the prefix argument and the address
  10488. expression cannot always be evaluated at assembly time, chances for
  10489. checking are limited and \asname{} will limit itself to warnings...in
  10490. detail, the situation is as follows:
  10491. \begin{itemize}
  10492. \item{fixed specification of a 64K bank with \tty{EXTS} or \tty{EXTSR}: the address
  10493.      expression directly contains the lower 16 bits of the target
  10494.      address.  If the prefix and the following instruction have a
  10495.      constant operand, \asname{} will check if the the prefix argument and bits
  10496.      16..23 of the target address are equal.}
  10497. \item{fixed specification of a 16K page with \tty{EXTP} or \tty{EXTPR}: the address
  10498.      expression directly contains the lower 14 bits of the target
  10499.      address.  Bits 14 and 15 are fixed to 0, as the processor ignores
  10500.      them in this mode.  If the prefix and the following instruction
  10501.      have a constant operand, \asname{} will check if the the prefix argument
  10502.      and bits 14..23 of the target address are equal.}
  10503. \end{itemize}
  10504. An example to clarify things a bit (the DPP registers have their
  10505. reset values):
  10506. \begin{verbatim}
  10507.        extp    #7,#1      ; range from 112K..128K
  10508.        mov     r0,1cdefh  ; results in address 0defh in code
  10509.        mov     r0,1cdefh  ; -->warning
  10510.        exts    #1,#1      ; range from 64K..128K
  10511.        mov     r0,1cdefh  ; results in address 0cdefh in code
  10512.        mov     r0,1cdefh  ; -->warning
  10513. \end{verbatim}
  10514.  
  10515. %%---------------------------------------------------------------------------
  10516.  
  10517. \section{PIC16C5x/16C8x}
  10518.  
  10519. Similar to the MCS-48 family, the PICs split their program memory
  10520. into several banks because the opcode does not offer enough space for
  10521. a complete address.  \asname{} uses the same automatism for the instructions
  10522. \tty{CALL} and \tty{GOTO}, i.e. the PA bits in the status word are set according
  10523. to the start and target address.  However, this procedure is far more
  10524. problematic compared to the 48's:
  10525. \begin{enumerate}
  10526. \item{The instructions are not any more one word long (up to three
  10527.      words).  Therefore, it is not guaranteed that they can be
  10528.      skipped with a conditional branch.}
  10529. \item{It is possible that the program counter crosses a page boundary
  10530.      while the program sequence is executed.  The setting of PA bits
  10531.      \asname{} assumes may be different from reality.}
  10532. \end{enumerate}
  10533. The instructions that operate on register W and another register
  10534. normally require a second parameter that specifies whether the result
  10535. shall be stored in W or the register.  Under \asname{}, it is valid to omit
  10536. the second parameter.  The assumed target then depends upon the
  10537. operation's type: For unary operations, the result is by default
  10538. stored back into the register.  These instructions are:
  10539. \begin{quote}{\tt
  10540.    COMF, DECF, DECFSZ, INCF, INCFSZ, RLF, RRF, and SWAPF
  10541. }\end{quote}
  10542. The other operations by default regard W as an accumulator:
  10543. \begin{quote}{\tt
  10544.    ADDWF, ANDWF, IORWF, MOVF, SUBWF, and XORWF
  10545. }\end{quote}
  10546. The syntax defined by Microchip to write literals is quite obscure
  10547. and reminds of the syntax used on IBM 360/370 systems (greetings from
  10548. the stone-age...).  To avoid introducing another branch into the
  10549. parser, with \asname{} one has to write constants in the Motorola syntax
  10550. (optionally Intel or C in \tty{RELAXED} mode).
  10551.  
  10552. %%---------------------------------------------------------------------------
  10553.  
  10554. \section{PIC 17C4x}
  10555.  
  10556. With two exceptions, the same hints are valid as for its two smaller
  10557. brothers: the corresponding include file only contains register
  10558. definitions, and the problems concerning jump instructions are much
  10559. smaller.  The only exception is the \tty{LCALL} instruction, which allows a
  10560. jump with a 16-bit address.  It is translated with the following
  10561. ''macro'':
  10562. \begin{verbatim}
  10563.        MOVLW   <addr15..8>
  10564.        MOWF    3
  10565.        LCALL   <addr0..7>
  10566. \end{verbatim}
  10567.  
  10568. %%---------------------------------------------------------------------------
  10569.  
  10570. \section{SX20/28}
  10571.  
  10572. The limited length of the instruction word does not permit specifying
  10573. a complete program memory address (11 bits) or data memory address (8
  10574. bits).  The CPU core augments the truncated address from the
  10575. instruction word with the PA bits from the STATUS registers,
  10576. respectively with the upper bits of the FSR register.  It is possible
  10577. to inform the assembler via \tty{ASSUME} instructions about the
  10578. contents of these two registers.  In case that addresses are used
  10579. that are inaccessible with th current values, a warning is issued.
  10580.  
  10581. %%---------------------------------------------------------------------------
  10582.  
  10583. \section{ST6}
  10584.  
  10585. These processors have the ability to map their code ROM pagewise into the
  10586. data area.  I am not keen on repeating the whole discussion of the
  10587. \tty{ASSUME} instruction at this place, so I refer to the corresponding
  10588. section (\ref{ST6Assume}) for an explanation how to read constants out of
  10589. the code ROM without too much headache.
  10590.  
  10591. Some builtin ''macros'' show up when one analyzes the instruction set a
  10592. bit more in detail.  The instructions I found are listed in table
  10593. \ref{TabHid62} (there are probably even more...):
  10594. \par
  10595. \begin{table*}[htbp]
  10596. \begin{center}\begin{tabular}{|l|l|}
  10597. \hline
  10598. instruction & in reality \\
  10599. \hline
  10600. \hline
  10601. \tty{CLR A}      & \tty{SUB A,A} \\
  10602. \tty{SLA A}      & \tty{ADD A,A} \\
  10603. \tty{CLR addr}   & \tty{LDI addr,0} \\
  10604. \tty{NOP}        & \tty{JRZ PC+1} \\
  10605. \hline
  10606. \end{tabular}\end{center}
  10607. \caption{Hidden Macros in the ST62's Instruction Set\label{TabHid62}}
  10608. \end{table*}
  10609. Especially the last case is a bit astonishing...unfortunately, some
  10610. instructions are really missing.  For example, there is an \tty{AND}
  10611. instruction but no \tty{OR}...not to speak of an \tty{XOR}.  For this reason, the
  10612. include file \tty{STDDEF62.INC} contains also some helping macros
  10613. (additionally to register definitions).
  10614.  
  10615. The original assembler AST6 delivered by SGS-Thomson partially uses
  10616. different pseudo instructions than \asname{}.  Apart from the fact that \asname{}
  10617. does not mark pseudo instructions with a leading dot, the following
  10618. instructions are identical:
  10619. \begin{verbatim}
  10620.  ASCII, ASCIZ, BLOCK, BYTE, END, ENDM, EQU, ERROR, MACRO,
  10621.  ORG, TITLE, WARNING
  10622. \end{verbatim}
  10623. Table \ref{TabAST6} shows the instructions which have \asname{} counterparts
  10624. with similar function.
  10625. \par
  10626. \begin{table*}[htbp]
  10627. \begin{center}\begin{tabular}{|l|l|l|}
  10628. \hline
  10629. AST6            & \asname{}                     & meaning/function \\
  10630. \hline
  10631. \hline
  10632. \tty{.DISPLAY}  & \tty{MESSAGE}          & output message \\
  10633. \hline
  10634. \tty{.EJECT}    & \tty{NEWPAGE}          & new page in assembly listing \\
  10635. \hline
  10636. \tty{.ELSE}     & \tty{ELSEIF}           & conditional assembly \\
  10637. \hline
  10638. \tty{.ENDC}     & \tty{ENDIF}            & conditional assembly \\
  10639. \hline
  10640. \tty{.IFC}      & \tty{IF...}            & conditional assembly \\
  10641. \hline
  10642. \tty{.INPUT}    & \tty{INCLUDE}          & insert include file \\
  10643. \hline
  10644. \tty{.LIST}     & \tty{LISTING, MACEXP\_DFT}  & settings for listing \\
  10645. \hline
  10646. \tty{.PL}       & \tty{PAGE}             & page length of listing \\
  10647. \hline
  10648. \tty{.ROMSIZE}  & \tty{CPU}              & set target processor \\
  10649. \hline
  10650. \tty{.VERS}     & \tty{VERSION} (symbol) & query version \\
  10651. \hline
  10652. \tty{.SET}      & \tty{EVAL}             & redefine variables \\
  10653. \hline
  10654. \end{tabular}\end{center}
  10655. \caption{Equivalent Instructions AST6$\leftrightarrow$\asname{}\label{TabAST6}}
  10656. \end{table*}
  10657.  
  10658. %%---------------------------------------------------------------------------
  10659.  
  10660. \section{ST7}
  10661.  
  10662. In \cite{ST7Man}, the \tty{.w} postfix to signify 16-bit addresses is only
  10663. defined for memory indirect operands.  It is used to mark that a
  10664. 16-bit address is stored at a zero page address.  \asname{} additionally
  10665. allows this postfix for absolute addresses or displacements of
  10666. indirect address expressions to force 16-bit displacements in spite
  10667. of an 8-bit value (0..255).
  10668.  
  10669. %%---------------------------------------------------------------------------
  10670.  
  10671. \section{ST9}
  10672.  
  10673. The ST9's bit addressing capabilities are quite limited: except for
  10674. the \tty{BTSET} instruction, only bits within the current set of working
  10675. registers are accessible.  A bit address is therefore of the
  10676. following style:
  10677. \begin{verbatim}
  10678.        rn.[!]b   ,
  10679. \end{verbatim}
  10680. whereby \tty{!} means an optional complement of a source operand.  If a bit
  10681. is defined symbolically, the bit's register number is stored in bits
  10682. 7..4, the bit's position is stored in bits 3..1 and the optional
  10683. complement is kept in bit 0.  \asname{} distinguishes explicit and symbolic
  10684. bit addresses by the missing dot.  A bit's symbolic name therefore
  10685. must not contain a dot, thought it would be legal in respect to the
  10686. general symbol name conventions.  It is also valid to invert a
  10687. symbolically referred bit:
  10688. \begin{verbatim}
  10689. bit2    bit     r5.3
  10690.        .
  10691.        .
  10692.        bld     r0.0,!bit2
  10693. \end{verbatim}
  10694. This opportunity also allows to undo an inversion that was done at
  10695. definition of the symbol.
  10696.  
  10697. The include file \tty{REGST9.INC} defines the symbolic names of all on-chip
  10698. registers and their associated bits. Keep however in mind that the
  10699. bit definitions only work after previously setting the working
  10700. register bank to the address of these peripheral registers!
  10701.  
  10702. In contrast to the definition file delivered with the AST9 assembler
  10703. from SGS-Thomson, the names of peripheral register names are only
  10704. defined as general registers (\tty{R...}), not also as working registers
  10705. (\tty{r...}).  The reason for this is that \asname{} does not support register
  10706. aliases; a tribute to assembly speed.
  10707.  
  10708. %%---------------------------------------------------------------------------
  10709.  
  10710. \section{6804}
  10711.  
  10712. To be honest: I only implemented this processor in \asname{} to quarrel
  10713. about SGS-Thomson's peculiar behaviour.  When I first read the 6804's
  10714. data book, the ''incomplete'' instruction set and the built-in macros
  10715. immediately reminded me of the ST62 series manufactured by the same
  10716. company.  A more thorough comparison of the opcodes gave surprising
  10717. insights: A 6804 opcode can be generated by taking the equivalent
  10718. ST62 opcode and mirroring all the bits!  So Thomson obviously did a
  10719. bit of processor core recycling...which would be all right if they
  10720. would not try to hide this:  different peripherals, motorola instead
  10721. of Zilog-style syntax, and the awful detail of \bb{not} mirroring operand
  10722. fields in the opcode (e.g. bit fields containing displacements).  The
  10723. last item is also the reason that finally convinced me to support the
  10724. 6804 in \asname{}.  I personally can only guess which department at Thomson
  10725. did the copy...
  10726.  
  10727. In contrast to its ST62 counterpart, the include file for the 6804
  10728. does not contain instruction macros that help a bit to deal with the
  10729. limited machine instruction set.  This is left as an exercise to the
  10730. reader!
  10731.  
  10732. %%---------------------------------------------------------------------------
  10733.  
  10734. \section{TMS3201x}
  10735.  
  10736. It seems that every semiconductor's ambition is to invent an own
  10737. notation for hexadecimal numbers.  Texas Instrument took an
  10738. especially eccentric approach for these processors: a $>$ sign as
  10739. prefix!  The support of such a format in \asname{} would have lead to
  10740. extreme conflicts with \asname{}'s compare and shift operators.  I therefore
  10741. decided to use the Intel notation, which is what TI also uses for the
  10742. 340x0 series and the 3201x's successors...
  10743.  
  10744. The instruction word of these processors unfortunately does not have
  10745. enough bits to store all 8 bits for direct addressing.  This is why
  10746. the data address space is split into two banks of 128 words.  \asname{}
  10747. principally regards the data address space as a linear segment of 256
  10748. words and automatically clears bit 7 on direct accesses (an exception
  10749. is the \tty{SST} instruction that can only write to the upper bank).  The
  10750. programmer has to take care that the bank flag always has the correct
  10751. value!
  10752.  
  10753. Another hint that is well hidden in the data book: The \tty{SUBC}
  10754. instruction internally needs more than one clock for completion, but
  10755. the control unit already continues to execute the next instruction.
  10756. An instruction following \tty{SUBC} therefore may not access the
  10757. accumulator.  \asname{} does not check for such conditions!
  10758.  
  10759. %%---------------------------------------------------------------------------
  10760.  
  10761. \section{TMS320C2x}
  10762.  
  10763. As I did not write this code generator myself (that does not lower
  10764. its quality by any standard), I can only roughly line out why there
  10765. are some instructions that force a prefixed label to be untyped, i.e.
  10766. not assigned to any specific address space: The 2x series of TMS
  10767. signal processors has a code and a data segment which are both 64
  10768. Kbytes large.  Depending on external circuitry, code and data space may
  10769. overlap, e.g. to allow storage of constants in the code area and
  10770. access them as data.  Data storage in the code segment may be
  10771. necessary because older versions of \asname{} assume that the data segment
  10772. only consists of RAM that cannot have a defined power-on state in a
  10773. single board system.  They therefore reject storage of contents in
  10774. other segments than \tty{CODE}.  Without the feature of making symbols
  10775. untyped, \asname{} would punish every access to a constant in code space
  10776. with a warning (''symbol out of wrong segment'').  To say it in detail,
  10777. the following instructions make labels untyped:
  10778. \begin{quote}\tt
  10779.  BSS, STRING, RSTRING, BYTE, WORD , LONG\\
  10780.  FLOAT, DOUBLE, EFLOAT, BFLOAT and TFLOAT
  10781. \rm\end{quote}
  10782. If one needs a typed label in front of one of these instructions, one
  10783. can work around this by placing the label in a separate line just
  10784. before the pseudo instruction itself.  On the other hand, it is
  10785. possible to place an untyped label in front of another pseudo
  10786. instruction by defining the label with \tty{EQU}, e.g.
  10787. \begin{verbatim}
  10788. <name>  EQU     $        .
  10789. \end{verbatim}
  10790.  
  10791. %%---------------------------------------------------------------------------
  10792.  
  10793. \section{TMS320C3x/C4x}
  10794.  
  10795. The syntax detail that created the biggest amount of headache for me
  10796. while implementing this processor family is the splitting of parallel
  10797. instructions into two separate source code lines.  Fortunately, both
  10798. instructions of such a construct are also valid single instructions.
  10799. \asname{} therefore first generates the code for the first instruction and
  10800. replaces it by the parallel machine code when a parallel construct is
  10801. encountered in the second line.  This operation can be noticed in the
  10802. assembly listing by the machine code address that does not advance
  10803. and the double dot replaced with a \tty{R}.
  10804.  
  10805. Compared to the TI assembler, \asname{} is not as flexible regarding the
  10806. position of the double lines that signify a parallel operation
  10807. (\tty{||}): One either has to place them like a label (starting in the
  10808. first column) or to prepend them to the second mnemonic.  The line
  10809. parser of \asname{} will run into trouble if you do something else...
  10810.  
  10811. %%---------------------------------------------------------------------------
  10812.  
  10813. \section{TMS9900}
  10814.  
  10815. Similar to most older TI microprocessor families, TI used an own
  10816. format for hexadecimal and binary constants.  \asname{} instead favours the
  10817. Intel syntax which is also common for newer processor designs from
  10818. TI.
  10819.  
  10820. The TI syntax for registers allows to use a simple integer number
  10821. between 0 and 15 instead of a real name (\tty{Rx} or \tty{WRx}).
  10822. This has two consequences:
  10823. \begin{itemize}
  10824. \item{\tty{R0...R15} resp. \tty{WR0..WR15} are simple predefined integer
  10825.      symbols with values from 0 to 15, and the definition of register
  10826.      aliases is a simple matter of \tty{EQU}.}
  10827. \item{In contrast to several other processors, I cannot offer the
  10828.      additional \asname{} feature that allows to omit the character sigifying
  10829.      absolute addressing (a \@ sign in this case).  As a missing
  10830.      character would mean register numbers (from 0 to 15) in this case,
  10831.      it was not possible to offer the optional omission.}
  10832. \end{itemize}
  10833. Furthermore, TI sometimes uses \tty{Rx} to name registers and \tty{WRx}
  10834. at other places...currently both variants are recognized by \asname{}.
  10835.  
  10836. %%---------------------------------------------------------------------------
  10837.  
  10838. \section{TMS70Cxx}
  10839.  
  10840. This processor family belongs to the older families developed by TI
  10841. and therefore TI's assemblers use their proprietary syntax for
  10842. hexadecimal resp. binary constants (a prefixed $<$ resp. \tty{?} character).
  10843. As this format could not be realized for \asname{}, the Intel syntax is used
  10844. by default.  This is the format TI to which also switched over when
  10845. introducing the successors, of this family, the 370 series of
  10846. microcontrollers.  Upon a closer inspection of both's machine
  10847. instruction set, one discovers that about 80\% of all instruction are
  10848. binary upward compatible, and that also the assembly syntax is almost
  10849. identical - but unfortunately only almost.  TI also took the chance to
  10850. make the syntax more orthogonal and simple.  I tried to introduce
  10851. the majority of these changes also into the 7000's instruction set:
  10852. \begin{itemize}
  10853. \item{It is valid to use the more common \tty{\#} sign for immediate addressing
  10854.      instead of the percent sign.}
  10855. \item{If a port address (\tty{P...}) is used as source or destination in a
  10856.      \tty{AND, BTJO, BTJZ, MOV, OR}, or \tty{XOR} instruction, it is not necessary
  10857.      to use the mnemonic variant with an appended \tty{P} - the general
  10858.      form is sufficient.}
  10859. \item{The prefixed \tty{@} sign for absolute or B-relative addressing may be
  10860.      omitted.}
  10861. \item{Instead of \tty{CMPA, CMP} with \tty{A} as target may be written.}
  10862. \item{Instead of \tty{LDA} resp. \tty{STA}, one can simply use the
  10863.      \tty{MOV} instruction with \tty{A} as source resp. destination.}
  10864. \item{One can write \tty{MOVW} instead of \tty{MOVD}.}
  10865. \item{It is valid to abbreviate \tty{RETS} resp. \tty{RETI} as \tty{RTS}
  10866.      resp. \tty{RTI}.}
  10867. \item{\tty{TSTA} resp. \tty{TSTB} may be written as \tty{TST A} resp.
  10868.      \tty{TST B}.}
  10869. \item{\tty{XCHB B} is an alias for \tty{TSTB}.}
  10870. \end{itemize}
  10871. An important note: these variants are only allowed for the TMS70Cxx -
  10872. the corresponding 7000 variants are not allowed for the 370 series!
  10873.  
  10874. %%---------------------------------------------------------------------------
  10875.  
  10876. \section{TMS370xxx}
  10877.  
  10878. Though these processors do not have specialized instructions for bit
  10879. manipulation, the assembler creates (with the help of the \tty{DBIT}
  10880. instruction - see there) the illusion as if single bits were
  10881. addressable.  To achieve this, the \tty{DBIT} instructions stores an
  10882. address along with a bit position into an integer symbol which may
  10883. then be used as an argument to the pseudo instructions \tty{SBIT0, SBIT1,
  10884. CMPBIT, JBIT0}, and \tty{JBIT1}.  These are translated into the instructions
  10885. \tty{OR, AND, XOR, BTJZ}, and \tty{BTJO} with an appropriate bit mask.
  10886.  
  10887. There is nothing magic about these bit symbols, they are simple
  10888. integer values that contain the address in their lower and the bit
  10889. position in their upper half.  One could construct bit symbols
  10890. without the \tty{DBIT} instruction, like this:
  10891. \begin{verbatim}
  10892. defbit  macro   name,bit,addr
  10893. name    equ     addr+(bit<<16)
  10894.        endm
  10895. \end{verbatim}
  10896. but this technique would not lead to the \tty{EQU}-style syntax defined by
  10897. TI (the symbol to be defined replaces the label field in a line).
  10898. \bb{CAUTION!} Though \tty{DBIT} allows an arbitrary address, the pseudo
  10899. instructions can only operate with addresses either in the range from
  10900. 0..255 or 1000h..10ffh.  The processor does not have an absolute
  10901. addressing mode for other memory ranges...
  10902.  
  10903. %%---------------------------------------------------------------------------
  10904.  
  10905. \section{MSP430(X)}
  10906. \label{MSPSpec}
  10907.  
  10908. The MSP was designed to be a RISC processor with a minimal power
  10909. consumption.  The set of machine instructions was therefore reduced
  10910. to the absolute minimum (RISC processors do not have a microcode ROM
  10911. so every additional instruction has to be implemented with additional
  10912. silicon that increases power consumption).  A number of instructions
  10913. that are hardwired for other processors are therefore emulated with
  10914. other instructions.  Older versions of \asname{} implemented these
  10915. instructions via macros in the file \tty{REGMSP.INC}.  If one did
  10916. not include this file, you got error messages for more than
  10917. half of the instructions defined by TI.  This has been changed in
  10918. recent versions: as part of adding the 430X instruction set,
  10919. implementation of these instructions was moved into the assmebler's
  10920. core.  \tty{REGMSP.INC} now only contains addresses of I/O
  10921. registers.  If you need the old macros for some reason, they have
  10922. been moved to the file \tty{EMULMSP.INC}.
  10923.  
  10924. Instruction emulation also covers some special cases not handled
  10925. by the original TI assembler.  For instance,
  10926. \begin{verbatim}
  10927.    rlc  @r6+
  10928. \end{verbatim}
  10929. is automatically assembled as
  10930. \begin{verbatim}
  10931.    addc @r6+,-2(r6)
  10932. \end{verbatim}
  10933.  
  10934. %%---------------------------------------------------------------------------
  10935.  
  10936. \section{TMS1000}
  10937.  
  10938. At last, world's first microcontroller finally also supported in
  10939. \asname{} - it took long to fill this gap, but now it is done.  This
  10940. target has some pitfalls that will be discussed shortly in this
  10941. section.
  10942.  
  10943. First, the instruction set of these controllers is partially
  10944. defined via the ROM mask, i.e. the function of some opcodes may
  10945. be freely defined to some degree.  \asname{} only knows the instructions
  10946. and codings that are described as default codings in
  10947. \cite{TMS1000PGMRef}.  If you have a special application with an
  10948. instruction set deviating from this, you may define and modify
  10949. instructions via macros and the \tty{DB} instruction.
  10950.  
  10951. Furthermore, keep in mind that branches and subroutine calls only
  10952. contain the lower 6 bits of the target address.  The upper 4
  10953. resp. 5 bits are fetched from page and chapter registers tha
  10954. thave to be set beforehand.  \asname{} cannot check whether these
  10955. registers have been set correctly by the programmer! At least for
  10956. the cas of staying in the same chapter, there are the assmebler
  10957. pseudo instructions \tty{CALLL} resp. \tty{BL} that combine an
  10958. \tty{LDP} and \tty{CALL/BR} instruction.  Regarding the limited
  10959. amount of program memory, this is a convenient yet inefficient
  10960. variant.
  10961.  
  10962. %%---------------------------------------------------------------------------
  10963.  
  10964. \section{COP8}
  10965. \label{COP8Spec}
  10966.  
  10967. National unfortunately also decided to use the syntax well known from
  10968. IBM mainframes (and much hated by me..) to write non-decimal integer
  10969. constants.  Just like with other processors, this does not work with
  10970. \asname{}'s parser.  ASMCOP however fortunately also seems to allow the C
  10971. syntax, which is why this became the default for the COP series and
  10972. the SC/MP...
  10973.  
  10974. %%---------------------------------------------------------------------------
  10975.  
  10976. \section{SC/MP}
  10977.  
  10978. If indirect addressing with displacement is used on the SC/MP, and
  10979. if the base or pointer register is not P0/PC, a displacement of -128
  10980. (80 hex) has a special meaning: the contents of the E register are
  10981. used as displacement instead of this value.  If using the 'classic NS
  10982. assembler', the programmer has to know about this, and even explicitly
  10983. use it:
  10984. \begin{verbatim}
  10985. ereg   equ -128
  10986.       ld  ereg(p1)
  10987. \end{verbatim}
  10988. This however bears the risk that -128 may accidentally be the result of
  10989. a computed displacement, and you might have a hard time finding out
  10990. why the program does not do what was indented. I therefore decided to
  10991. make this special value more explicit:
  10992.  
  10993. If a displacement of -128 is used, a warning is issued.  One may
  10994. simply ignore this warning.  If you want to get rid of it, use
  10995. the built-in literal \verb!E!, which explicitly references the
  10996. register of same name:
  10997. \begin{verbatim}
  10998.       ld e(p1)
  10999. \end{verbatim}
  11000. Since the SC/MP target supports register symbols, it is also possible
  11001. to define the 'own symbol' in a proper way:
  11002. \begin{verbatim}
  11003. ereg   reg e
  11004.       ld  ereg(p1)
  11005. \end{verbatim}
  11006. This should reduce the amount of necessary changes in existing code
  11007. to a minimum.
  11008.  
  11009. %%---------------------------------------------------------------------------
  11010.  
  11011. \section{SC144xxx}
  11012. \label{SC144xxspec}
  11013.  
  11014. Originally, National offered a relatively simple assembler for this series
  11015. of DECT controllers.  An much more powerful assembler has been announced
  11016. by IAR, but it is not available up to now.  However, since the development
  11017. tools made by IAR are as much target-independent as possible, one can
  11018. roughly estimate the pseudo instructions it will support by looking at
  11019. other available target platforms.  With this in mind, the (few)
  11020. SC144xx-specific instructions {\tt DC, DC8, DW16, DS, DS8, DS16, DW} were
  11021. designed.  Of course, I didn't want to reinvent the wheel for pseudo
  11022. instructions whose functionality is already part of the \asname{} core.
  11023. Therefore, here is a little table with equivalences.  The statements
  11024. \tty{ALIGN, END, ENDM, EXITM, MACRO, ORG, RADIX, SET,} and \tty{REPT} both
  11025. exist for the IAR assembler and \asname{} and have same functionality.  Changes
  11026. are needed for the following instructions:
  11027.  
  11028. \begin{table*}[htb]
  11029. \begin{center}\begin{tabular}{|l|l|l|}
  11030. \hline
  11031. IAR & \asname{} & Funktion\\
  11032. \hline
  11033. \hline
  11034. \tty{\#include} & \tty{include} & include file \\
  11035. \tty{\#define} & \tty{SET, EQU} & define symbol \\
  11036. \tty{\#elif, ELIF, ELSEIF} & \tty{ELSEIF} & start another \\
  11037.                           &              & IF branch \\
  11038. \tty{\#else, ELSE} & \tty{ELSE} & last branch of an IF \\
  11039.                   &            & construct \\
  11040. \tty{\#endif, ENDIF} & \tty{ENDIF} & ends an IF construct \\
  11041. \tty{\#error} & \tty{ERROR, FATAL} & create error message \\
  11042. \tty{\#if, IF} & \tty{IF} & start an IF construct \\
  11043. \tty{\#ifdef} & \tty{IFDEF} & symbol defined ? \\
  11044. \tty{\#ifndef} & \tty{IFNDEF} & symbol not defined ? \\
  11045. \tty{\#message} & \tty{MESSAGE} & output message \\
  11046. \tty{=, DEFINE, EQU} & \tty{=, EQU} & fixed value assignment \\
  11047. \tty{EVEN} & \tty{ALIGN 2} & force PC to be equal \\
  11048. \tty{COL, PAGSIZ} & \tty{PAGE} & set page size for listing \\
  11049. \tty{ENDR} & \tty{ENDM} & end REPT construct \\
  11050. \tty{LSTCND, LSTOUT} & \tty{LISTING} & control amount of listing \\
  11051. \tty{LSTEXP, LSTREP} & \tty{MACEXP} & list expanded macros? \\
  11052. \tty{LSTXRF} & \verb!<command line>! & generate cross reference \\
  11053. \tty{PAGE} & \tty{NEWPAGE} & new page in listing \\
  11054. \tty{REPTC} & \tty{IRPC} & repetition with character \\
  11055.            &            & replacement \\
  11056. \hline
  11057. \end{tabular}\end{center}
  11058. \end{table*}
  11059.  
  11060. There is no direct equivalent for {\tt CASEON}, {\tt CASEOFF,}
  11061. \tty{LOCAL}, \tty{LSTPAG}, \tty{\#undef,} and {\tt REPTI}.
  11062.  
  11063. A 100\% equivalent is of course impossible as long as there is no C-like
  11064. preprocessor in \asname{}.  C-like comments unfortunately are also impossible
  11065. at the moment.  Caution: When modifying IAR codes for \asname{}, do not forget to
  11066. move converted preprocessor statements out of column 1 as \asname{} reserves this
  11067. column exclusively for labels!
  11068.  
  11069. %%---------------------------------------------------------------------------
  11070.  
  11071. \section{NS32xxx}
  11072.  
  11073. As one might expect from a CISC processor, the NS32xxx series provides
  11074. sophisticated and complex addressing modes.  National defied the assembly syntax
  11075. for each of them in its manuals, and this is also the syntax \asname{} implements.
  11076. However, as for every architecture that was supported by third-party tools,
  11077. there are deviations and extensions, and I added a few of them to \asname{}:
  11078.  
  11079. The syntax to use PC-relative addressing, as defined by National, is:
  11080. \begin{verbatim}
  11081. movb r0,*+disp
  11082. \end{verbatim}
  11083. This of course quite clearly expresses what is happening at runtime, one however
  11084. has to compute the distance himself if a certain memory location is to be
  11085. addressed:
  11086. \begin{verbatim}
  11087. movb r0,*+(addr-*)
  11088. \end{verbatim}
  11089. The first simplification is that under certain conditions, it is sufficient to
  11090. just write:
  11091. \begin{verbatim}
  11092. movb r0,addr
  11093. \end{verbatim}
  11094. since absolute addressierung is marked by a \@ prefix.  This is allowed under
  11095. the following conditions:
  11096. \begin{itemize}
  11097. \item{Immediate addressierung is not allowed, e.g. because the operand is
  11098.      the destination and there is no risk os ambiguities.}
  11099. \item{An index extension is used (appended in square brackets), which must not
  11100.      be combined with immediate addressing.}
  11101. \end{itemize}
  11102. As an alterntative, \asname{} also supports the following way to use PC-relative addressing:
  11103. \begin{verbatim}
  11104. movb r0,addr(pc)
  11105. \end{verbatim}
  11106. Analog to the 68000, the distance is computed automatically.
  11107.  
  11108. The external mode, whis written this way in National syntax:
  11109. \begin{verbatim}
  11110. movb r0,ext(disp1)+disp2
  11111. \end{verbatim}
  11112. there is another supported syntax variant:
  11113. \begin{verbatim}
  11114. movb r0,disp2(disp1(ext))
  11115. \end{verbatim}
  11116. which used to be common in UNIX environments.
  11117.  
  11118. %%---------------------------------------------------------------------------
  11119.  
  11120. \section{uPD78(C)1x}
  11121. \label{78C1xSpec}
  11122.  
  11123. For relative, unconditional instructions, there is the \tty{JR} instruction
  11124. branch distance -32...+31, one byte), and the \tty{JRE} instruction (branch
  11125. distance -256...+255, two bytes).  \asname{} furthermore knows the \tty{J} pseudo
  11126. instruction, which automatically selects the shortest possible variant.
  11127.  
  11128. Architecture and instructon set of these processors are coarsely
  11129. related to the Intel 8080/8085 - thi is also true for the
  11130. mnemonics.  The adressing mode (direct, indirect, immediate) is
  11131. packed into the mnemonic, and 16 bit registers (BC, DE, HL) are
  11132. written with just one letter.  However, since NEC itself also
  11133. uses at some places written-out register names and parentheses to
  11134. signify indirect addressing, I decided to support some
  11135. alternative notations next to the 'official' ones.   Some non-NEC
  11136. tools like disassemblers seem to use these notations either:
  11137.  
  11138. \begin{itemize}
  11139. \item{It is allowed to use \tty{BC}, \tty{(B)}, or \tty{(BC)}
  11140.      instead of \tty{B}.}
  11141. \item{It is allowed to use \tty{DE}, \tty{(D)}, or \tty{(DE)}
  11142.      instead of \tty{D}.}
  11143. \item{It is allowed to use \tty{HL}, \tty{(H)}, or \tty{(HL)}
  11144.      instead of \tty{H}.}
  11145. \item{It is allowed to use \tty{DE+}, \tty{(D+)}, \tty{(DE+)},
  11146.      or \tty{(DE)+} instead of \tty{D+}.}
  11147. \item{It is allowed to use \tty{HL+}, \tty{(H+)}, \tty{(HL+)},
  11148.      or \tty{(HL)+} instead of \tty{H+}.}
  11149. \item{It is allowed to use \tty{DE-}, \tty{(D-)}, \tty{(DE-)},
  11150.      or \tty{(DE)-} instead of \tty{D-}.}
  11151. \item{It is allowed to use \tty{HL-}, \tty{(H-)}, \tty{(HL-)},
  11152.      or \tty{(HL)-} instead of \tty{H-}.}
  11153. \item{It is allowed to use \tty{DE++}, \tty{(D++)}, \tty{(DE++)},
  11154.      or \tty{(DE)++} instead of \tty{D++}.}
  11155. \item{It is allowed to use \tty{HL++}, \tty{(H++)}, \tty{(HL++)},
  11156.      or \tty{(HL)++} instead of \tty{H++}.}
  11157. \item{It is allowed to use \tty{DE--}, \tty{(D--)}, \tty{(DE--)},
  11158.      or \tty{(DE)--} instead of \tty{D--}.}
  11159. \item{It is allowed to use \tty{HL--}, \tty{(H--)}, \tty{(HL--)},
  11160.      or \tty{(HL)--} instead of \tty{H--}.}
  11161. \item{It is allowed to use \tty{HL+A}, \tty{A+H}, \tty{A+HL},
  11162.      \tty{(H+A)}, \tty{(HL+A)}, \tty{(A+H)}, or \tty{(A+HL)}
  11163.      instead of \tty{H+A}.}
  11164. \item{It is allowed to use \tty{HL+B}, \tty{B+H}, \tty{B+HL},
  11165.      \tty{(H+B)}, \tty{(HL+B)}, \tty{(B+H)}, or \tty{(B+HL)}
  11166.      instead of \tty{H+B}.}
  11167. \item{It is allowed to use \tty{HL+EA}, \tty{EA+H}, \tty{EA+HL},
  11168.      \tty{(H+EA)}, \tty{(HL+EA)}, \tty{(EA+H)}, or \tty{(EA+HL)}
  11169.      instead of \tty{H+EA}.}
  11170. \end{itemize}
  11171.  
  11172. Since architecture and instruction set are so ''8080-like'', it was
  11173. straightforward to support the {\tt Z80SYNTAX} statement, which
  11174. allows to write many machine instructions in a more intuitive and
  11175. better-known way.  However, since both the uCON87 family's architecture
  11176. and instruction set differ from the 8080 in a couple of details, it
  11177. is not possible to provide a complete one-to-one mapping.  Not all
  11178. original instructions have a ''Z80 equivalent'', and some instructions
  11179. known from 8080 and Z80 do not exist on the uCOM87.  It therefore
  11180. does not make sense to support {\tt Z80SYNTAX EXCLUSIVE}.
  11181.  
  11182. The following table lists all instructions defined in {\tt Z80SYNTAX}
  11183. mode and their equivalents in original syntax:
  11184.  
  11185. \begin{longtable}{|l|l|l|l|}
  11186. \hline
  11187. {\tt Z80SYNTAX} & Original & Operation  & CPUs \\
  11188. \hline
  11189. \hline
  11190. \endhead
  11191. \input{../doc_COM/78z80inst.tex}
  11192. \\ \hline
  11193. \multicolumn{4}{|l|}{CPU Group 1: 78C05, 78C06} \\
  11194. \multicolumn{4}{|l|}{CPU Group 2: 7800, 7801, 7802} \\
  11195. \multicolumn{4}{|l|}{CPU Group 3: 7807, 7808, 7809, 7810} \\
  11196. \multicolumn{4}{|l|}{CPU Group 4: 7810, 78C1x} \\
  11197. \hline
  11198. \caption{Instruction Variants in {\tt Z80SYNTAX} Mode}
  11199. \end{longtable}
  11200.  
  11201. %%---------------------------------------------------------------------------
  11202.  
  11203. \section{75K0}
  11204. \label{75K0Spec}
  11205.  
  11206. Similar to other processors, the assembly language of the 75 series
  11207. also knows pseudo bit operands, i.e. it is possible to assign a
  11208. combination of address and bit number to a symbol that can then be
  11209. used as an argument for bit oriented instructions just like explicit
  11210. expressions.  The following three instructions for example generate
  11211. the same code:
  11212. \begin{verbatim}
  11213. ADM     sfr     0fd8h
  11214. SOC     bit     ADM.3
  11215.  
  11216.        skt     0fd8h.3
  11217.        skt     ADM.3
  11218.        skt     SOC
  11219. \end{verbatim}
  11220. \asname{} distinguishes direct and symbolic bit accesses by the missing dot
  11221. in symbolic names; it is therefore forbidden to use dots in symbol
  11222. names to avoid misunderstandings in the parser.
  11223.  
  11224. The storage format of bit symbols mostly accepts the binary coding in
  11225. the machine instructions themselves:  16 bits are used, and there is
  11226. a ''long'' and a ''short'' format.  The short format can store the
  11227. following variants:
  11228. \begin{itemize}
  11229. \item{direct accesses to the address range from 0FBxH to 0FFxH}
  11230. \item{indirect accesses in the style of \tty{Addr.@L} (0FC0H $\leq$ \tty{Addr} $\leq$0FFFH)}
  11231. \item{indirect accesses in the style of \tty{@H+d4.bit}}
  11232. \end{itemize}
  11233. The upper byte is set to 0, the lower byte contains the bit
  11234. expression coded according to \cite{NEC75}.  The long format in contrast
  11235. only knows direct addressing, but it can cover the whole address space
  11236. (given a correct setting of MBS and MBE).  A long expression stores
  11237. bits 0..7 of the address in the lower byte, the bit position in bits
  11238. 8 and 9, and a constant value of 01 in bits 10 and 11.  The highest
  11239. bits allow to distinguish easily between long and short addresses via
  11240. a check if the upper byte is 0.  Bits 12..15 contain bits 8..11 of
  11241. the address; they are not needed to generate the code, but they have
  11242. to be stored somewhere as the check for correct banking can only
  11243. take place when the symbol is actually used.
  11244.  
  11245. %%---------------------------------------------------------------------------
  11246.  
  11247. \section{78K0}
  11248. \label{78K0Spec}
  11249.  
  11250. NEC uses different ways to mark absolute addressing in its data
  11251. books:
  11252. \begin{itemize}
  11253. \item{absolute short: no prefix}
  11254. \item{absolute long: prefix of \tty{!}}
  11255. \item{PC relative: prefix of \tty{\$}}
  11256. \end{itemize}
  11257. Under \asname{}, these prefixes are only necessary if one wants to force a
  11258. certain addressing mode and the instruction allows different
  11259. variants.  Without a prefix, \asname{} will automatically select the shortest
  11260. variant.  It should therefore rarely be necessary to use a prefix in
  11261. practice.
  11262.  
  11263. %%---------------------------------------------------------------------------
  11264.  
  11265. \section{78K2/78K3/78K4}
  11266. \label{78K234Spec}
  11267.  
  11268. Analogous to the 78K0, NEC here also uses dollar signs and exclamation
  11269. marks to specify different lengths of address expressions.  The selection
  11270. between long and short addresses is done automatically (both in RAM and
  11271. SFR areas), only relative addressing has to be selected explicitly, if an
  11272. instruction supports both variants (like {\tt BR}).
  11273.  
  11274. An additional remark (which is also true for the 78K0): Those who want to
  11275. use Motorola syntax via {\tt RELAXED}, might have to put hexadecimal
  11276. constants in parentheses, since the leading dollar sign might be
  11277. misunderstood as relative addressing...
  11278.  
  11279. %%---------------------------------------------------------------------------
  11280.  
  11281. \section{uPD772x}
  11282.  
  11283. Both the 7720 and 7725 are provided by the same code generator and are
  11284. extremely similar in their instruction set.  One should however not
  11285. beleive that they are binary compatible: To get space for the longer
  11286. address fields and additional instructions, the bit positions of some
  11287. fields in the instruction word have changed, and the instruction length
  11288. has changed from 23 to 24 bits.  The code format therefore uses different
  11289. header ids for both CPUs.
  11290.  
  11291. They both have in common that in addition to the code and data segment,
  11292. there is also a ROM for storage of constants.  In the case of \asname{}, it is
  11293. mapped onto the \tty{ROMDATA} segment!
  11294.  
  11295. %%---------------------------------------------------------------------------
  11296.  
  11297. \section{uCOM-43}
  11298.  
  11299. The uCOM-43 instruction set contains an instruction {\tt CZP} that performs a
  11300. single byte subroutine call to the addresses 0, 4, 8, 12...60.  However, the
  11301. available documentation is unclear about the instruction's argument in source
  11302. code: should it be the target address (i.e., a multiple of four) or th vector
  11303. contained in the opcode (i.e., a number from 0 to 15).  To decide, the assembler
  11304. performs some guessing:
  11305. \begin{itemize}
  11306. \item{If the argument is larger than 15, it must be an address, otherwise:}
  11307. \item{If the argument is not a multiple of four, it must be a vector, otherwise:}
  11308. \item{If the argument is zero, no distinction is possible, otherwise:}
  11309. \item{If the argument is a symbol from CODE space (e.g. a label), it must
  11310.      be an address, otherwise:}
  11311. \item{The argument is a vector.}
  11312. \end{itemize}
  11313. The final two rules only apply to the values 4, 8, and 12, and since the
  11314. decision is not intuitively clear, the decision for a vector is accompanied
  11315. with a warning.  In case an address was meant, define the argument as symbol
  11316. from CODe space:
  11317. \begin{verbatim}
  11318. dest   label  4
  11319.       .
  11320.       .
  11321.       .
  11322.       czp dest
  11323. \end{verbatim}
  11324. In case a vector was meant, and the warning bothers you, it may be suppressed
  11325. this way:
  11326. \begin{verbatim}
  11327. vector equ    4
  11328.       .
  11329.       .
  11330.       .
  11331.       expect 480
  11332.       czp    vector
  11333.       endexpect
  11334. \end{verbatim}
  11335. I admit that this situation is not 100% satisfactory.  If anyone has information
  11336. about the behaviour of the original NEC assembler, I'd be grateful for contacting
  11337. me.
  11338.  
  11339. %%---------------------------------------------------------------------------
  11340.  
  11341. \section{F2MC16L}
  11342.  
  11343. Along with the discussion of the {\tt ASSUME} statement, it has already
  11344. been mentioned that it is important to inform \asname{} about the correct current
  11345. values of all bank registers - if your program uses more than 64K RAM or
  11346. 64K ROM.  With these assumptions in mind, \asname{} checks every direct memory
  11347. access for attempts to access a memory location that is currently not in
  11348. reach.  Of course, standard situations only require knowledge of DTB and
  11349. DPR for this purpose, since ADB resp. SSB/USB are only used for indirect
  11350. accesses via RW2/RW6 resp. RW3/RW7 and this mechanism anyway doesn't work
  11351. for indirect accesses.  However, similar to the 8086, it is possible to
  11352. place a prefix in front of an instruction to replace DTB by a different
  11353. register.  \asname{} therefore keeps track of used segment prefixes and
  11354. toggles appropriately for the next {\em machine instruction}.  A pseudo
  11355. instruction placed between the prefix and the machine instruction does
  11356. {\em not} reset the toggle.  This is also true for pseudo instructions
  11357. that store data or modify the program counter.  Which doesn't make much
  11358. sense anyway...
  11359.  
  11360. %%---------------------------------------------------------------------------
  11361.  
  11362. \section{MN161x}
  11363.  
  11364. This target is special because there are two different code generators one may
  11365. choose from.  The first one was kindly provided by Haruo Asano and that may be
  11366. reached via the CPU names \tty{MN1610} resp.\tty{MN1613}.  The other one was
  11367. written by me and is activated via the CPU names \tty{MN1610ALT} resp.
  11368. \tty{MN1613ALT}.  If you want to use the MN1613's extended address space of
  11369. 256 KWords, or if you want to experiment with the MN1613's floating point
  11370. formant, you have to use the \tty{ALT} target.
  11371.  
  11372. %%---------------------------------------------------------------------------
  11373.  
  11374. \section{CDP180x}
  11375.  
  11376. This family of processors supports both long and short branches: a short
  11377. branch is only possible within the same 256 byte memory page, and a long branch
  11378. is possible to any target in the 64K address space.  The assembly syntax provides
  11379. different mnemonics for both variants (the long variant with a leading 'L'), but
  11380. there is no variant that would let the assembler decide itself between long
  11381. or short.  \asname{} supports such 'pseudo instructions' as an extension:
  11382. \begin{itemize}
  11383. \item{\tty{JMP} becomes \tty{BR} oder \tty{LBR}.}
  11384. \item{\tty{JZ} becomes \tty{BZ} oder \tty{LBZ}.}
  11385. \item{\tty{JNZ} becomes \tty{BNZ} oder \tty{LBNZ}.}
  11386. \item{\tty{JDF} becomes \tty{BDF} oder \tty{LBDF}.}
  11387. \item{\tty{JPZ} becomes \tty{BPZ} oder \tty{LBPZ}.}
  11388. \item{\tty{JGE} becomes \tty{BGE} oder \tty{LBGE}.}
  11389. \item{\tty{JNF} becomes \tty{BNF} oder \tty{LBNF}.}
  11390. \item{\tty{JM} becomes \tty{BM} oder \tty{LBM}.}
  11391. \item{\tty{JL} becomes \tty{BL} oder \tty{LBL}.}
  11392. \item{\tty{JQ} becomes \tty{BQ} oder \tty{LBQ}.}
  11393. \item{\tty{JNQ} becomes \tty{BNQ} oder \tty{LBNQ}.}
  11394. \end{itemize}
  11395.  
  11396.  
  11397. %%---------------------------------------------------------------------------
  11398.  
  11399. \section{KENBAK}
  11400.  
  11401. The KENBAK-1 was developed in 1970, at a time when the first microprocessor
  11402. was still three years away.  One may assume that for the few hobbyists that
  11403. could afford the kit back then, this was their first and only computer.  As
  11404. a consequence, they had nothing they could run an assembler on, the KENBAK-1
  11405. itself with its 256 bytes of memory was way too small for such a task.  The
  11406. preferred method was to use pre-printed tables, which had fields to fill in
  11407. instructions and machine codes.  Once this ''programming job'' was done, one
  11408. would enter the machine code manually via the computer's switch row.
  11409.  
  11410. The effect of this is that though the KENBAK's assembly language is described
  11411. in the manual, there is no real formal definition of it.  When Grant Stockly
  11412. released new KENBAK kits a few years ago, he did a first implementation of the
  11413. KENBAK on my assembler.  Unfortunately, this never went upstream.  I tried
  11414. to take up his ideas in my implementation, but on the other hand I also tried to
  11415. offer a syntax that should be familiar to programmers of 6502, Z80 or similar
  11416. processors.  The following table lists the syntax differences:
  11417.  
  11418. \hfuzz=60pt
  11419. \begin{center}\begin{longtable}{|l|l|l|}
  11420. \hline
  11421. Stockly & Alternativ & Bemerkung \\
  11422. \hline
  11423. \hline
  11424. \endhead
  11425. \multicolumn{3}{|l|}{\bf Arithmetic/Logic (ADD/SUB/LOAD/STORE/AND/OR/LNEG)} \\
  11426. \hline
  11427. {\it instr} {\tt Constant}, {\it Reg}, {\it Wert}, & {\it instr} {\it Reg}, {\it \#Wert} & immediate \\
  11428. {\it instr} {\tt Memory}, {\it Reg}, {\it Addr}, & {\it instr} {\it Reg}, {\it Addr} & direct \\
  11429. {\it instr} {\tt Indirect}, {\it Reg}, {\it Addr}, & {\it instr} {\it Reg}, {\it (Addr)} & direct \\
  11430. {\it instr} {\tt Indexed}, {\it Reg}, {\it Addr}, & {\it instr} {\it Reg}, {\it Addr},X & indexed \\
  11431. {\it instr} {\tt Indirect-Indexed}, {\it Reg}, {\it Addr}, & {\it instr} {\it Reg}, {\it (Addr)},X & indirect-indexed \\
  11432. \hline
  11433. \multicolumn{3}{|l|}{\bf Jumps} \\
  11434. \hline
  11435. {\tt JPD} {\it Reg}, {\it Cond}, {\it Addr} & {\tt JP} {\it Reg}, {\it Cond}, {\it Addr} & conditional-direct \\
  11436. {\tt JPI} {\it Reg}, {\it Cond}, {\it Addr} & {\tt JP} {\it Reg}, {\it Cond}, {\it (Addr)} & conditional-indirect \\
  11437. {\tt JMD} {\it Reg}, {\it Cond}, {\it Addr} & {\tt JM} {\it Reg}, {\it Cond}, {\it Addr} & conditional-direct \\
  11438. {\tt JMI} {\it Reg}, {\it Cond}, {\it Addr} & {\tt JM} {\it Reg}, {\it Cond}, {\it (Addr)} & conditional-indirect \\
  11439. {\tt JPD} {\tt Unconditional}, {\it Cond}, {\it Addr} & {\tt JP} {\it Addr} & unconditional-direct \\
  11440. {\tt JPI} {\tt Unconditional}, {\it Cond}, {\it Addr} & {\tt JP} {\it (Addr)} & unconditional-indirect \\
  11441. {\tt JMD} {\tt Unconditional}, {\it Cond}, {\it Addr} & {\tt JM} {\it Addr} & unconditional-direct \\
  11442. {\tt JMI} {\tt Unconditional}, {\it Cond}, {\it Addr} & {\tt JM} {\it (Addr)} & unconditional-indirect \\
  11443. \hline
  11444. \multicolumn{3}{|l|}{\bf Jump Conditions} \\
  11445. \hline
  11446. {\tt Non-zero} & {\tt NZ} & $\neq 0$ \\
  11447. {\tt Zero} & {\tt Z} & $= 0$ \\
  11448. {\tt Negative} & {\tt N} & $< 0$ \\
  11449. {\tt Positive} & {\tt P} & $\geq 0$ \\
  11450. {\tt Positve-Non-zero} & {\tt PNZ} & $ > 0$ \\
  11451. \hline
  11452. \multicolumn{3}{|l|}{\bf Skips} \\
  11453. \hline
  11454. {\tt SKP 0}, {\it bit}, {\it Addr} & {\tt SKP0} {\it bit}, {\it Addr} {\it [,Dest]} & \\
  11455. {\tt SKP 1}, {\it bit}, {\it Addr} & {\tt SKP1} {\it bit}, {\it Addr} {\it [,Dest]} & \\
  11456. \hline
  11457. \multicolumn{3}{|l|}{\bf Bit Manipulation} \\
  11458. \hline
  11459. {\tt SET 0}, {\it bit}, {\it Addr} & {\tt SET0} {\it bit}, {\it Addr} & \\
  11460. {\tt SET 1}, {\it bit}, {\it Addr} & {\tt SET1} {\it bit}, {\it Addr} & \\
  11461. \hline
  11462. \multicolumn{3}{|l|}{\bf Shifts/Rotates} \\
  11463. \hline
  11464. {\tt SHIFT LEFT}, {\it cnt}, {\it Reg} & {\tt SFTL} {\it [cnt,]} {\it Reg} & \\
  11465. {\tt SHIFT RIGHT}, {\it cnt}, {\it Reg} & {\tt SFTR} {\it [cnt,]} {\it Reg} & arithm. Shift \\
  11466. {\tt ROTATE LEFT}, {\it cnt}, {\it Reg} & {\tt ROTL} {\it [cnt,]} {\it Reg} & \\
  11467. {\tt ROTATE RIGHT}, {\it cnt}, {\it Reg} & {\tt ROTR} {\it [cnt,]} {\it Reg} & \\
  11468. \hline
  11469. \caption{KENBAK-Befehlssyntax \label{TabKENBAKSyntax}}
  11470. \end{longtable}\end{center}
  11471. \hfuzz=0pt
  11472.  
  11473. There is no pseudo instruction to switch between these syntax variants.  They may
  11474. both be used anytime and in an arbitrary mix.
  11475.  
  11476. The target address {\it [Dest]} that may optionally be added to skip instructions
  11477. will not become part of the machine code.  The assembler only checks whether the
  11478. processor wil actually skip to the given address.  This allows for instance to check
  11479. whether one actually tries to skip a one-byte instruction.  If the shift count
  11480. argument {\it [cnt]} is omitted, a one-bit shift/rotate is coded.
  11481.  
  11482. %%---------------------------------------------------------------------------
  11483.  
  11484. \section{HP Nanoprocessor}
  11485.  
  11486. The HP Nanoprocessor does not provide any instructions to read data from the ROM
  11487. address space.  The respective instructions {\tt LDR} and {\tt STR} rather
  11488. represent what is called ''immediate addressing'' on other processors.  For this
  11489. reson, there are pseudo instructions that would allow placing data constants
  11490. im ROM memory or to reserve space in it.
  11491.  
  11492. %%---------------------------------------------------------------------------
  11493.  
  11494. \section{IM61x0}
  11495.  
  11496. This microprocessor is effectively a single chip implementation of the PDP8/E,
  11497. which is why Digital Equipment's PAL-II is usually the ''reference assembler''
  11498. for source code samples.  The \asname{} implementation deviates from the PAL-III syntax
  11499. in a couple of areas, among other reasons also because several things only
  11500. could have been provided with huge efforts.  Here are some hints about how to
  11501. adapt existing code:
  11502.  
  11503. \begin{itemize}
  11504. \item{PAL-III marks labels by an appended comma.  \asname{} instead uses an appended
  11505.      double colon, or no special character at all if the label begins in the
  11506.      first column of a line.}
  11507. \item{Placing constants in memory is done with PAL-III simply by writing the
  11508.      numeric constant instead of a mnemonic.  \asname{} uses the \tty{DC} instruction
  11509.      to place data, which will also accept more than one word as argument.
  11510.      However, the \tty{LTORG} mechanism may be used in some cases to get
  11511.      around explicitly placing constants in memory at all.}
  11512. \item{The program counter is set by \tty{ORG address} instead of {*address}.}
  11513. \end{itemize}
  11514.  
  11515. %%===========================================================================
  11516.  
  11517. \cleardoublepage
  11518. \chapter{File Formats}
  11519.  
  11520. In this chapter, the formats of files \asname{} generates shall be explained
  11521. whose formats are not self-explanatory.
  11522.  
  11523. %%---------------------------------------------------------------------------
  11524.  
  11525. \section{Code Files}
  11526. \label{SectCodeFormat}
  11527.  
  11528. The format for code files generated by the assembler must be able to
  11529. separate code parts that were generated for different target
  11530. processors; therefore, it is a bit different from most other formats.
  11531. Though the assembler package contains tools to deal with code files,
  11532. I think is a question of good style to describe the format in short:
  11533.  
  11534. If a code file contains multibyte values, they are stored in little
  11535. endian order.  This rule is already valid for the 16-bit magic word
  11536. \$1489, i.e. every code file starts with the byte sequence \$89/\$14.
  11537. This magic word is followed by an arbitrary number of ''records''.  A
  11538. record may either contain a continuous piece of the code or certain
  11539. additional information.  Even without switching to different
  11540. processor types, a file may contain several code-containing records,
  11541. in case that code or constant data areas are interrupted by reserved
  11542. memory areas that should not be initialized.  This way, the assembler
  11543. tries to keep the file as short as possible.
  11544. Common to all records is a header byte which defines the record's type
  11545. and its contents.  Written in a PASCALish way, the record structure
  11546. can be described in the following way:
  11547. \begin{verbatim}
  11548. FileRecord = RECORD CASE Header:Byte OF
  11549.              $00:(Creator:ARRAY[] OF Char);
  11550.              $01..
  11551.              $7f:(StartAdr : LongInt;
  11552.                   Length   : Word;
  11553.                   Data     : ARRAY[0..Length-1] OF Byte);
  11554.              $80:(EntryPoint:LongInt);
  11555.              $81:(Header   : Byte;
  11556.                   Segment  : Byte;
  11557.                   Gran     : Byte;
  11558.                   StartAdr : LongInt;
  11559.                   Length   : Word;
  11560.                   Data     : ARRAY[0..Length-1] OF Byte);
  11561.             END
  11562. \end{verbatim}
  11563. This description does not express fully that the length of data
  11564. fields is variable and depends on the value of the \tty{Length} entries.
  11565.  
  11566. A record with a header byte of \$81 is a record that may contain code
  11567. or data from arbitrary segments.  The first byte (\tty{Header}) describes
  11568. the processor family the following code resp. data was generated for (see
  11569. table \ref{TabHeader}).
  11570. \newcounter{headidcounter}
  11571. \setcounter{headidcounter}{1}
  11572. \newcommand{\headid}[2]{#1 & #2
  11573.  \ifnum\value{headidcounter}>1 \\ \fi
  11574.  \ifnum\value{headidcounter}<2 & \fi
  11575.  \stepcounter{headidcounter}
  11576.  \ifnum\value{headidcounter}>2
  11577.   \setcounter{headidcounter}{1}
  11578.  \fi
  11579. }
  11580. \begin{center}\begin{longtable}{|c|l||c|l|}
  11581. \hline
  11582. Header  & Family & Header  & Family \\
  11583. \hline
  11584. \hline
  11585. \endhead
  11586. \input{../doc_COM/tabids.tex}
  11587. \\ \hline
  11588. \caption{Header Bytes for the Different Processor Families}
  11589. \label{TabHeader}
  11590. \end{longtable}\end{center}
  11591. The \tty{Segment} field signifies the address space the following code
  11592. belongs to.  The assignment defined in table \ref{TabSegments} applies.
  11593. \begin{table*}[htbp]
  11594. \begin{center}\begin{tabular}{|c|l||c|l|}
  11595. \hline
  11596. number  & segment               & number  & segment \\
  11597. \hline
  11598. \hline
  11599. \$00    & $<$undefined$>$       & \$01    & \tty{CODE} \\
  11600. \$02    & \tty{DATA}            & \$03    & \tty{IDATA} \\
  11601. \$04    & \tty{XDATA}           & \$05    & \tty{YDATA} \\
  11602. \$06    & \tty{BDATA}           & \$07    & \tty{IO} \\
  11603. \$08    & \tty{REG}             & \$09    & \tty{ROMDATA} \\
  11604. \hline
  11605. \end{tabular}\end{center}
  11606. \caption{Codings of the {\tt Segment} Field\label{TabSegments}
  11607.         \label{TabSegmentNums}}
  11608. \end{table*}
  11609. The \tty{Gran} field describes the code's ''granularity'', i.e. the size of
  11610. the smallest addressable unit in the following set of data.  This
  11611. value is a function of processor type and segment and is an important
  11612. parameter for the interpretation of the following two fields that
  11613. describe the block's start address and its length: While the start
  11614. address refers to the granularity, the \tty{Length} value is always
  11615. expressed in bytes!  For example, if the start address is \$300 and
  11616. the length is 12, the resulting end address would be \$30b for a
  11617. granularity of 1, however \$303 for a granularity of 4!  Granularities
  11618. that differ from 1 are rare and mostly appear in DSP CPU's that are
  11619. not designed for byte processing.  For example, a DSP56K's address
  11620. space is organized in 64 Kwords of 16 bits.  The resulting storage
  11621. capacity is 128 Kbytes, however it is organized as $2^{16}$ words that
  11622. are addressed with addresses 0,1,2,...65535!
  11623.  
  11624. The start address is always 32 bits in size, independent of the
  11625. processor family.  In contrast, the length specification has only 16
  11626. bits, i.e. a record may have a maximum length of 4+4+2+(64K-1) =
  11627. 65545 bytes.
  11628.  
  11629. Data records with a Header ranging from \$01 to \$7f present a shortcut
  11630. and preserve backward compatibility to earlier definitions of the
  11631. file format: in their case, the Header directly defines the processor
  11632. type, the target segment is fixed to \tty{CODE} and the granularity is
  11633. implicitly given by the processor type, rounded up to the next power
  11634. of two.  \asname{} prefers to use these records whenever data or code should
  11635. go into the \tty{CODE} segment.
  11636.  
  11637. A record with a Header of \$80 defines an entry point, i.e. the
  11638. address where execution of the program should start.  Such a record
  11639. is the result of an \tty{END} statement with a corresponding address as
  11640. argument.
  11641.  
  11642. The last record in a file bears the Header \$00 and has only a string
  11643. as data field.  This string does not have an explicit length
  11644. specification; its end is equal to the file's end.  The string
  11645. contains only the name of the program that created the file and has
  11646. no further meaning.
  11647.  
  11648. %%---------------------------------------------------------------------------
  11649.  
  11650. \section{Debug Files}
  11651. \label{SectDebugFormat}
  11652.  
  11653. Debug files may optionally be generated by \asname{}.  They deliver important
  11654. information for tools used after assembly, like disassemblers or
  11655. debuggers.  \asname{} can generate debug files in one of three formats: On the
  11656. one hand, the object format used by the AVR tools from Atmel respectively
  11657. a NoICE-compatible command file, and on the other hand an own format.  The
  11658. first two are described in detail in \cite{AVRObj} resp. the NoICE
  11659. documentations, which is why the following description limits itself to
  11660. the \asname{}-specific MAP format:
  11661.  
  11662. The information in a MAP file is split into three groups:
  11663. \begin{itemize}
  11664. \item{symbol table}
  11665. \item{memory usage per section}
  11666. \item{machine addresses of source lines}
  11667. \end{itemize}
  11668. The second item is listed first in the file.  A single entry in this
  11669. list consists of two numbers that are separated by a \tty{:} character:
  11670. \begin{verbatim}
  11671. <line number>:<address>
  11672. \end{verbatim}
  11673. Such an entry states that the machine code generated for the source
  11674. statement in a certain line is stored at the mentioned address
  11675. (written in hexadecimal notation).  With such an information, a
  11676. debugger can display the corresponding source lines while stepping
  11677. through a program.  As a program may consist of several include
  11678. files, and due to the fact that a lot of processors have more than
  11679. one address space (though admittedly only one of them is used to
  11680. store executable code), the entries described above have to be
  11681. sorted.  \asname{} does this sorting in two levels: The primary sorting
  11682. criteria is the target segment, and the entries in one of these
  11683. sections are sorted according to files.  The sections resp.
  11684. subsections are separated by special lines in the style of
  11685. \begin{verbatim}
  11686. Segment <segment name>
  11687. \end{verbatim}
  11688. resp.
  11689. \begin{verbatim}
  11690. File <file name>   .
  11691. \end{verbatim}
  11692. The source line info is followed by the symbol table.  Similar to the
  11693. source line info, the symbol table is primarily sorted by the
  11694. segments individual symbols are assigned to.  In contrast to the
  11695. source line info, an additional section \tty{NOTHING} exists which contains
  11696. the symbols that are not assigned to any specific segment (e.g.
  11697. symbols that have been defined with a simple \tty{EQU} statement).  A
  11698. section in the symbol table is started with a line of the following
  11699. type:
  11700. \begin{verbatim}
  11701. Symbols in Segment <segment name>
  11702. \end{verbatim}
  11703. The symbols in a section are sorted according to the alphabetical
  11704. order of their names, and one symbol entry consists of exactly one
  11705. line.  Such a line consists of six fields witch are separated by at
  11706. least a single space:
  11707.  
  11708. The first field is the symbol's name, possibly extended by a section
  11709. number enclosed in brackets.  Such a section number limits the
  11710. range of validity for a symbol.  The second field designates the
  11711. symbol's type: \tty{Int} stands for integer values, \tty{Float} for floating
  11712. point numbers, and \tty{String} for character arrays.  The third field
  11713. finally contains the symbol's value.  If the symbol contains a
  11714. string, it is necessary to use a special encoding for control
  11715. characters and spaces.  Without such a coding, spaces in a string
  11716. could be misinterpreted as delimiters to the next field.  \asname{} uses the
  11717. same syntax that is also valid for assembly source files: Instead of
  11718. the character, its ASCII value with a leading backslash (\verb!\!) is
  11719. inserted.  For example, the string
  11720. \begin{verbatim}
  11721. This is a test
  11722. \end{verbatim}
  11723. becomes
  11724. \begin{verbatim}
  11725. This\032is\032\a\032test   .
  11726. \end{verbatim}
  11727. The numerical value always has three digits and has to be interpreted
  11728. as a decimal value.  Naturally, the backslash itself also has to be
  11729. coded this way.
  11730.  
  11731. The fourth field specifies - if available - the size of the data
  11732. structure placed at the address given by the symbol.   A debugger may
  11733. use this information to automatically display variables in their
  11734. correct length when they are referred symbolically.  In case \asname{} does
  11735. not have any information about the symbol size, this field simply
  11736. contains the value -1.
  11737.  
  11738. The fifth field states via the values 0 or 1 if the symbol has been
  11739. used during assembly.  A program that reads the symbol table can use
  11740. this field to skip unused symbols as they are probably unused during
  11741. the following debugging/disassembly session.
  11742.  
  11743. Finally, the sixth field states via the values 0 or 1 if the symbol
  11744. is a constant (0) or variable(1).  Constant symbols are set once, e.g.
  11745. via the \tty{EQU} statement or a label, while variables are allowed
  11746. to change their value during the course of assembly.  The MAP file
  11747. lists the final value.
  11748.  
  11749. The third section in a debug file describes the program's sections in
  11750. detail.  The need for such a detailed description arises from the
  11751. sections' ability to limit the validity range of symbols.  A symbolic
  11752. debugger for example cannot use certain symbols for a reverse
  11753. translation, depending on the current PC value.  It may also have to
  11754. regard priorities for symbol usage when a value is represented by
  11755. more than one symbol.  The definition of a section starts with a line
  11756. of the following form:
  11757. \begin{verbatim}
  11758. Info for Section nn ssss pp
  11759. \end{verbatim}
  11760. \tty{nn} specifies the section's number (the number that is also used in
  11761. the symbol table as a postfix for symbol names), \tty{ssss} gives its name
  11762. and \tty{pp} the number of its parent section.  The last information is
  11763. needed by a retranslator to step upward through a tree of sections
  11764. until a fitting symbol is found.  This first line is followed by a
  11765. number of further lines that describe the code areas used by this
  11766. section.  Every single entry (exactly one entry per line) either
  11767. describes a single address or an address range given by a lower and
  11768. an upper bound (separation of lower and upper bound by a minus sign).
  11769. These bounds are ''inclusive'', i.e. the bounds themselves also belong
  11770. to the area.  Is is important to note that an area belonging to a
  11771. section is not additionally listed for the section's parent sections
  11772. (an exception is of course a deliberate multiple allocation of address
  11773. areas, but you would not do this, would you?).  On the one hand, this
  11774. allows an optimized storage of memory areas during assembly. On the
  11775. other hand, this should not be an obstacle for symbol backtranslation
  11776. as the single entry already gives an unambiguous entry point for the
  11777. symbol search path.  The description of a section is ended by an
  11778. empty line or the end of the debug file.
  11779.  
  11780. Program parts that lie out of any section are not listed separately.
  11781. This implicit ''root section'' carries the number -1 and is also used
  11782. as parent section for sections that do not have a real parent
  11783. section.
  11784.  
  11785. It is possible that the file contains empty lines or comments (semi
  11786. colon at line start).  A program reading the file has to ignore such
  11787. lines.
  11788.  
  11789. %%===========================================================================
  11790.  
  11791. \cleardoublepage
  11792. \chapter{Utility Programs}
  11793. \label{ChapTools}
  11794.  
  11795. To simplify the work with the assembler's code format a bit, I added
  11796. some tools to aid processing of code files.  These programs are
  11797. released under the same license terms as stated in section
  11798. \ref{SectLicense}!
  11799.  
  11800. Common to all programs are the possible return codes they may deliver
  11801. upon completion (see table \ref{TabToolReturns}).
  11802. \par
  11803. \begin{table*}[h]
  11804. \begin{center}\begin{tabular}{|c|l|}
  11805. \hline
  11806. return code   & error condition \\
  11807. \hline
  11808. \hline
  11809. 0             & no errors \\
  11810. 1             & error in command line parameters \\
  11811. 2             & I/O error \\
  11812. 3             & file format error \\
  11813. \hline
  11814. \end{tabular}\end{center}
  11815. \caption{Return Codes of the Utility Programs\label{TabToolReturns}}
  11816. \end{table*}
  11817. Just like \asname{}, all programs take their input from STDIN and write
  11818. messages to STDOUT (resp. error messages to STDERR).  Therefore,
  11819. input and output redirections should not be a problem.
  11820.  
  11821. In case that numeric or address specifications have to be given in
  11822. the command line, they may also be written in hexadecimal
  11823. notation,  either ba allending a \verb!h! or prepending a dollar
  11824. character or a \tty{0x} like in C.
  11825. (e.g. \verb!10h!, \verb!$10!, or \verb!0x10! instead of 16).
  11826.  
  11827. Unix shells however \marginpar{{\em UNIX}} assign a special meaning to the
  11828. dollar sign, which makes it necessary to escape a dollar sign with a
  11829. backslash.  The \tty{0x} variant is definitely more comfortable in this case.
  11830.  
  11831. Otherwise, calling conventions and variations are equivalent to those
  11832. of \asname{} (except for PLIST and AS2MSG); i.e. it is possible to store
  11833. frequently used parameters in an environment variable (whose name is
  11834. constructed by appending CMD to the program's name, i.e. \tty{BINDCMD} for
  11835. BIND), to negate options, and to use all upper- resp. lower-case
  11836. writing (for details on this, see section \ref{SectCallConvention}).
  11837.  
  11838. Address specifications always relate to the granularity of the
  11839. processor currently in question; for example, on a PIC, an address
  11840. difference of 1 means a word and not a byte.
  11841.  
  11842. %%---------------------------------------------------------------------------
  11843.  
  11844. \section{PLIST}
  11845.  
  11846. PLIST is the simplest one of the five programs supplied: its purpose
  11847. is simply to list all records that are stored in a code file.  As the
  11848. program does not do very much, calling is quite simple:
  11849. \begin{verbatim}
  11850.    PLIST <file name>
  11851. \end{verbatim}
  11852. The file name will automatically be extended with the extension \tty{P} if
  11853. it doesn't already have one.
  11854.  
  11855. \bb{CAUTION!} At this place, no wildcards are allowed!  If there is a
  11856. necessity to list several files with one command, use the following
  11857. ''mini batch'':
  11858. \begin{verbatim}
  11859.     for %n in (*.p) do plist %n
  11860. \end{verbatim}
  11861. PLIST prints the code file's contents in a table style, whereby
  11862. exactly one line will be printed per record.  The individual rows
  11863. have the following meanings:
  11864. \begin{itemize}
  11865. \item{code type: the processor family the code has been generated for.}
  11866. \item{start address: absolute memory address that expresses the load
  11867.      destination for the code.}
  11868. \item{length: length of this code chunk in bytes.}
  11869. \item{end address: last address of this code chunk.  This address
  11870.      is calculated as start address+length-1.}
  11871. \end{itemize}
  11872. All outputs are in hexadecimal notation.
  11873.  
  11874. Finally, PLIST will print a copyright remark (if there is one in the
  11875. file), together with a summaric code length.
  11876.  
  11877. Simply said, PLIST is a sort of DIR for code files.  One can use it
  11878. to examine a file's contents before one continues to process it.
  11879.  
  11880. %%---------------------------------------------------------------------------
  11881.  
  11882. \section{BIND}
  11883.  
  11884. BIND is a program that allows to concatenate the records of several
  11885. code files into a single file.  A filter function is available that
  11886. can be used to copy only records of certain types.  Used in this way,
  11887. BIND can also be used to split a code file into several files.
  11888.  
  11889. The general syntax of BIND is
  11890. \begin{verbatim}
  11891.   BIND <source file(s)> <target file> [options]
  11892. \end{verbatim}
  11893. Just like \asname{}, BIND regards all command line arguments that do not
  11894. start with a \tty{+, -} or \tty{/} as file specifications, of which the last one
  11895. must designate the destination file.  All other file specifications
  11896. name sources, which may again contain wildcards.
  11897.  
  11898. Currently, BIND defines only one command line option:
  11899. \begin{itemize}
  11900. \item{\tty{f $<$Header[,Header]$>$}: sets a list of record headers that should
  11901.      be copied.  Records with other header IDs will
  11902.      not be copied.  Without such an option, all
  11903.      records will be copied.  The headers given in
  11904.      the list correspond to the \tty{HeaderID} field of the
  11905.      record structure described in section \ref{SectCodeFormat}.
  11906.      Individual headers in this list are separated
  11907.      with commas.}
  11908. \end{itemize}
  11909. For example, to filter all MCS-51 code out of a code file, use BIND
  11910. in the following way:
  11911. \begin{verbatim}
  11912.   BIND <source name> <target name> -f $31
  11913. \end{verbatim}
  11914. If a file name misses an extension, the extension \tty{P} will be added
  11915. automatically.
  11916.  
  11917. %%---------------------------------------------------------------------------
  11918.  
  11919. \section{P2HEX}
  11920.  
  11921. P2HEX is an extension of BIND.  It has all command line options of BIND and
  11922. uses the same conventions for file names.  In contrary to BIND, the
  11923. target file is written as a Hex file, i.e. as a sequence of lines
  11924. which represent the code as ASCII hex numbers.
  11925.  
  11926. P2HEX knows nine different target formats, which can be selected via the
  11927. command line parameter \tty{F}:
  11928. \begin{itemize}
  11929. \item{Motorola S-Records (\tty{-F Moto)})}
  11930. \item{MOS Hex \tty{(-F MOS)}}
  11931. \item{Intel Hex (Intellec-8, \tty{-F Intel})}
  11932. \item{16-Bit Intel Hex (MCS-86, \tty{-F Intel16})}
  11933. \item{32-Bit Intel Hex (\tty{-F Intel32)})}
  11934. \item{Tektronix Hex (\tty{-F Tek})}
  11935. \item{Texas Instruments DSK (\tty{-F DSK})}
  11936. \item{Atmel AVR Generic (\tty{-F Atmel}, see \cite{AVRObj})}
  11937. \item{Lattice Mico8 prom\_init (\tty{-F Mico8})}
  11938. \item{C arrays, for inclusion into C(++) source files (\tty{-F C})}
  11939. \end{itemize}
  11940. If no target format is explicitly specified, P2HEX will automatically
  11941. choose one depending in the processor type:  S-Records for Motorola
  11942. CPUs, Hitachi, and TLCS-900, MOS for 65xx/MELPS, DSK for the 16 bit
  11943. signal processors from Texas, Atmel Generic for the AVRs, and Intel Hex
  11944. for the rest.  Depending on the start addresses width, the S-Record
  11945. format will use Records of type 1, 2, or 3, however, records in one
  11946. group will always be of the same type.  This automatism can be partially
  11947. suppressed via the command line option
  11948. \begin{verbatim}
  11949.  -M <1|2|3>
  11950. \end{verbatim}
  11951. A value of 2 resp. 3 assures that that S records with a minimum type of 2
  11952. resp. 3 will be used, while a value of 1 corresponds to the full
  11953. automatism.
  11954.  
  11955. Normally, the AVR format always uses an address length of 3 bytes.  Some
  11956. programs however do not like that...which is why there is a switch
  11957. \begin{verbatim}
  11958.  -avrlen <2|3>
  11959. \end{verbatim}
  11960. that allows to reduce the address length to two bytes in case of
  11961. emergency.
  11962.  
  11963. The Mico8 format is different from all the other formats in
  11964. having no address fields - it is plain list of all instruction
  11965. words in program memory.  When using it, be sure that the used
  11966. address range (as displeyed e.g. by PLIS) starts at zero and is
  11967. continuous.
  11968.  
  11969. The Intel, MOS and Tektronix formats are limited to 16 bit addresses, the
  11970. 16-bit Intel format reaches 4 bits further.  Addresses that are to long
  11971. for a given format will be reported by P2HEX with a warning; afterwards,
  11972. they will be truncated (!).
  11973.  
  11974. For the PIC microcontrollers, the switch
  11975. \begin{verbatim}
  11976. -m <0..3>
  11977. \end{verbatim}
  11978. allows to generate the three different variants of the Intel Hex
  11979. format.  Format 0 is INHX8M which contains all bytes in a
  11980. Lo-Hi-Order.  Addresses become double as large because the PICs have
  11981. a word-oriented address space that increments addresses only by one
  11982. per word.  This format is also the default.  With Format 1 (INHX16M),
  11983. bytes are stored in their natural order.  This is the format
  11984. Microchip uses for its own programming devices.  Format 2 (INHX8L)
  11985. resp. 3 (INHX8H) split words into their lower resp. upper bytes.
  11986. With these formats, P2HEX has to be called twice to get the complete
  11987. information, like in the following example:
  11988. \begin{verbatim}
  11989.  p2hex test -m 2
  11990.  rename test.hex test.obl
  11991.  p2hex test -m 3
  11992.  rename test.hex test.obh
  11993. \end{verbatim}
  11994. For the Motorola format, P2HEX additionally uses the S5 record type
  11995. mentioned in \cite{CPM68K}.  This record contains the number of data
  11996. records (S1/S2/S3) to follow.  As some programs might not know how to
  11997. deal with this record, one can suppress it with the option
  11998. \begin{verbatim}
  11999. +5  .
  12000. \end{verbatim}
  12001. The C format is different in the sense that it always has to be
  12002. selected explicitly.  The output file is basically a complete piece of
  12003. C or C++ code that contains the data as a list of C arrays.  Additionally to
  12004. the data itself, a list of descriptors is written that describes the
  12005. start, length, and end address of each data block.  The contents of these
  12006. descriptors may be configured via the option
  12007. \begin{verbatim}
  12008. -cformat <format>
  12009. \end{verbatim}
  12010. Each letter in \verb!format! defines an element of the descriptor:
  12011. \begin{itemize}
  12012. \item{A \verb!d! or \verb!D! defines a pointer to the data itself.
  12013.      Usage of a lower or upper case letter defines whether lowercase
  12014.      or uppercase letters are used for hexadecimal constants.}
  12015. \item{An \verb!s! or \verb!S! defines the start address of the data,
  12016.      either as {\em unsigned} or {\em unsigned long}.}
  12017. \item{An \verb!l! or \verb!L! defines the length of the data,
  12018.      either as {\em unsigned} or {\em unsigned long}.}
  12019. \item{An \verb!e! or \verb!E! defines the end address of the data,
  12020.      specifically the last address used by the data, either as
  12021.      {\em unsigned} or {\em unsigned long}.}
  12022. \end{itemize}
  12023. \par
  12024. In case a source file contains code record for different processors,
  12025. the different hex formats will also show up in the target file - it
  12026. is therefore strongly advisable to use the filter function.
  12027.  
  12028. Apart form this filter function, P2HEX also supports an address
  12029. filter, which is useful to split the code into several parts (e.g.
  12030. for a set of EPROMs):
  12031. \begin{verbatim}
  12032. -r <start address>-<end address>
  12033. \end{verbatim}
  12034. The start address is the first address in the window, and the end
  12035. address is the last address in the window, \bb{not} the first address
  12036. that is out of the window.  For example, to split an 8051 program
  12037. into 4 2764 EPROMs, use the following commands:
  12038. \begin{verbatim}
  12039. p2hex <source file> eprom1 -f $31 -r $0000-$1fff
  12040. p2hex <source file> eprom2 -f $31 -r $2000-$3fff
  12041. p2hex <source file> eprom3 -f $31 -r $4000-$5fff
  12042. p2hex <source file> eprom4 -f $31 -r $6000-$7fff
  12043. \end{verbatim}
  12044. It is allowed to specifiy a single dollar character or '0x' as start
  12045. or stop address.  This means that the lowest resp. highest address found
  12046. in the source file shall be taken as start resp. stop address.  The
  12047. default range is '0x-0x', i.e. all data from the source file is
  12048. transferred.
  12049.  
  12050. \bb{CAUTION!} This type of splitting does not change the absolute
  12051. addresses that will be written into the files!  If the addresses in
  12052. the individual hex files should rather start at 0, one can force this
  12053. with the additional switch
  12054. \begin{verbatim}
  12055. -a     .
  12056. \end{verbatim}
  12057. On the other hand, to move the addresses to a different location, one may
  12058. use the switch
  12059. \begin{verbatim}
  12060. -R <value> .
  12061. \end{verbatim}
  12062. The value given is an {\em offset}, i.e. it is added to the addresses
  12063. given in the code file.
  12064. \par
  12065. By using an offset, it is possible to move a file's contents to an
  12066. arbitrary position.  This offset is simply appended to a file's name,
  12067. surrounded with parentheses.  For example, if the code in a file
  12068. starts at address 0 and you want to move it to address 1000 hex in the
  12069. hex file, append \tty{(\$1000)} to the file's name (without spaces!).
  12070. \par
  12071. In case the source file(s) not only contain data for the code segment,
  12072. the switch
  12073. \begin{verbatim}
  12074. -segment <name>
  12075. \end{verbatim}
  12076. allows to select the segment data is extracted from and converted to
  12077. HEX format.  The segment names are the same as for the \tty{SEGMENT}
  12078. pseudo instruction (\ref{SEGMENT}).  The TI DSK is a special case
  12079. since it has the ability to distinguish between data and code in one
  12080. file.  If TI DSK is the output format, P2HEX will automatically
  12081. extract data from both segments if no segment was specified explicitly.
  12082. \par
  12083. Similar to the \verb!-r! option, the argument
  12084. \begin{verbatim}
  12085. -d <start>-<end>
  12086. \end{verbatim}
  12087. allows to designate the address range that should be written as data
  12088. instead of code.
  12089. \par
  12090. The option
  12091. \begin{verbatim}
  12092. -e <address>
  12093. \end{verbatim}
  12094. is valid for the DSK, Intel, and Motorola formats.  Its purpose is to
  12095. set the entry address that will be inserted into the hex file.  If
  12096. such a command line parameter is missing, P2HEX will search a
  12097. corresponding entry in the code file.  If even this fails, no entry
  12098. address will be written to the hex file (DSK/Intel) or the field
  12099. reserved for the entry address will be set to 0 (Motorola).
  12100. Unfortunately, one finds different statements about the last line of
  12101. an Intel-Hex file in literature.  Therefore, P2HEX knows three
  12102. different variants that may be selected via the command-line
  12103. parameter \tty{i} and an additional number:
  12104. \begin{verbatim}
  12105. 0  :00000001FF
  12106. 1  :00000001
  12107. 2  :0000000000
  12108. \end{verbatim}
  12109. By default, variant 0 is used which seems to be the most common one.
  12110. If the target file name does not have an extension, an extension of
  12111. \tty{HEX} is supposed.
  12112. By default, P2HEX will print a maximum of 16 data bytes per line,
  12113. just as most other tools that output Hex files.  If you want to
  12114. change this, you may use the switch
  12115. \begin{verbatim}
  12116. -l <count>   .
  12117. \end{verbatim}
  12118. The allowed range of values goes from 2 to 254 data bytes; odd values
  12119. will implicitly be rounded down to an even count.
  12120. In most cases, the temporary code files generated by \asname{} are not of
  12121. any further need after P2HEX has been run.  The command line option
  12122. \begin{verbatim}
  12123. -k
  12124. \end{verbatim}
  12125. allows to instruct P2HEX to erase them automatically after
  12126. conversion.
  12127. In contrast to BIND, P2HEX will not produce an empty target file if
  12128. only one file name (i.e. the target name) has been given.  Instead,
  12129. P2HEX will use the corresponding code file.  Therefore, a minimal
  12130. call in the style of
  12131. \begin{verbatim}
  12132. P2HEX <name>
  12133. \end{verbatim}
  12134. is possible, to generate \tty{$<$name$>$.hex} out of \tty{$<$name$>$.p}.
  12135.  
  12136. %%---------------------------------------------------------------------------
  12137.  
  12138. \section{P2BIN}
  12139.  
  12140. P2BIN works similar to P2HEX and offers the same options (except for
  12141. the a and i options that do not make sense for binary files),
  12142. however, the result is stored as a simple binary file instead of a
  12143. hex file.  Such a file is for example suitable for programming an
  12144. EPROM.
  12145.  
  12146. P2BIN knows three additional options to influence the resulting binary
  12147. file:
  12148. \begin{itemize}
  12149. \item{\tty{l $<$8 bit number$>$}: sets the value that should be used to fill
  12150.      unused memory areas.  By default, the value
  12151.      \$ff is used.  This value assures that every
  12152.      half-way intelligent EPROM burner will skip
  12153.      these areas.  This option allows to set different values,
  12154.      for example if you want to
  12155.      generate an image for the EPROM versions of
  12156.      MCS-48 microcontrollers (empty cells of their
  12157.      EPROM array contain zeroes, so \$00 would be
  12158.      the correct value in this case).}
  12159. \item{\tty{s}:  commands the program to calculate a checksum
  12160.      of the binary file.  This sum is printed as
  12161.      a 32-bit value, and the two's complement of
  12162.      the least significant bit will be stored in
  12163.      the file's last byte.  This way, the modulus-
  12164.      256-sum of the file will become zero.}
  12165. \item{\tty{m}:  is designed for the case that a CPU with a
  12166.      16- or 32-bit data bus is used and the file
  12167.      has to be split for several EPROMs.  The
  12168.      argument may have the following values:
  12169.      \begin{itemize}
  12170.      \item{\tty{ALL}: copy everything}
  12171.      \item{\tty{ODD}: copy all bytes with an odd address}
  12172.      \item{\tty{EVEN}: copy all bytes with an even address}
  12173.      \item{\tty{BYTE0..BYTE3}: copy only bytes with an address of
  12174.            4n+0 .. 4n+3}
  12175.      \item{\tty{WORD0, WORD1}: copy only the lower resp. upper 16-
  12176.            bit word of a 32-bit word}
  12177.      \end{itemize}}
  12178. \end{itemize}
  12179. To avoid confusions: If you use this option, the resulting binary file
  12180. will become smaller because only a part of the source will be copied.
  12181. Therefore, the resulting file will be smaller by a factor of 2 or 4
  12182. compared to \tty{ALL}.  This is just natural...
  12183.  
  12184. In case the code file does not contain an entry address, one may set
  12185. it via the \tty{-e} command line option just like with P2HEX.  Upon
  12186. request, P2BIN prepends the resulting image with this address.  The
  12187. command line option
  12188. \begin{verbatim}
  12189. -S
  12190. \end{verbatim}
  12191. activates this function.  It expects a numeric specification ranging
  12192. from 1 to 4 as parameter which specifies the length of the address
  12193. field in bytes.  This number may optionally be prepended wit a \tty{L} or
  12194. \tty{B} letter to set the endian order of the address.  For example, the
  12195. specification \tty{B4} generates a 4 byte address in big endian order,
  12196. while a specification of \tty{L2} or simply \tty{2} creates a 2 byte address
  12197. in little endian order.
  12198.  
  12199. %%---------------------------------------------------------------------------
  12200.  
  12201. \section{AS2MSG}
  12202.  
  12203. AS2MSG is not a tool in the real sense, it is a filter that was
  12204. designed to simplify the work with the assembler for (fortunate)
  12205. users of Borland Pascal 7.0.  The DOS IDEs feature a 'tools' menu
  12206. that can be extended with own programs like \asname{}.  The filter allows to
  12207. directly display the error messages paired with a line
  12208. specification delivered by \asname{} in the editor window.  A new entry has
  12209. to be added to the tools menu to achieve this (Options/Tools/New).
  12210. Enter the following values:
  12211. \begin{verbatim}
  12212. - Title: ~m~acro assembler
  12213. - Program path: AS
  12214. - Command line:
  12215.      -E !1 $EDNAME $CAP MSG(AS2MSG) $NOSWAP $SAVE ALL
  12216. - assign a hotkey if wanted (e.g. Shift-F7)
  12217. \end{verbatim}
  12218. The -E option assures that Turbo Pascal will not become puzzled by
  12219. STDIN and STDERR.
  12220.  
  12221. I assume that \asname{} and AS2MSG are located in a directory listed in the
  12222. \tty{PATH} variable.  After pressing the appropriate hotkey (or selecting
  12223. \asname{} from the tools menu), as will be called with the name of the file
  12224. loaded in the active editor window as parameter.  The error messages
  12225. generated during assembly are redirected to a special window that
  12226. allows to browse through the errors.  \tty{Ctrl-Enter} jumps to an
  12227. erroneous line.  The window additionally contains the statistics \asname{}
  12228. prints at the end of an assembly.  These lines obtain the dummy line
  12229. number 1.
  12230.  
  12231. \tty{TURBO.EXE} (Real Mode) and \tty{BP.EXE} (Protected Mode) may be used for
  12232. this way of working with \asname{}.  I recommend however BP, as this version
  12233. does not have to 'swap' half of the DOS memory before before \asname{} is
  12234. called.
  12235.  
  12236. %%===========================================================================
  12237. \appendix
  12238.  
  12239. \cleardoublepage
  12240. \chapter{Error Messages of \asname{}}
  12241. \label{ChapErrMess}
  12242.  
  12243. Here is a list of all error messages emitted by \asname{}. Each error message is
  12244. described by:
  12245. \begin{itemize}
  12246. \item{the internal error number (it is displayed only if \asname{} is started with the
  12247.      \tty{-n} option)}
  12248. \item{the text of the error message}
  12249. \item{error type:
  12250.      \begin{itemize}
  12251.      \item{Warning: informs the user that a possible error was
  12252.            found, or that some inefficient binary code
  12253.            could be generated. The assembly process is not
  12254.            stopped.}
  12255.      \item{Error: an error was detected. The assembly process
  12256.            continues, but no binary code is emitted.}
  12257.      \item{Fatal: unrecoverable error. The assembly process is
  12258.            terminated.}
  12259.      \end{itemize}}
  12260. \item{reason of the error: the situation originating the error.}
  12261. \item{argument:  a further explanation of the error message.}
  12262. \end{itemize}
  12263.  
  12264. \par
  12265.  
  12266. \newcommand{\errentry}[5]
  12267.           {\item[#1]{#2
  12268.                      \begin{description}
  12269.                      \item[Type:]{\ \\#3}
  12270.                      \item[Reason:]{\ \\#4}
  12271.                      \item[Argument:]{\ \\#5}
  12272.                      \end{description}}
  12273.           }
  12274.  
  12275. \begin{description}
  12276. \errentry{   5}{useless displacement}
  12277.               {warning}
  12278.               {680x0, 6809 and COP8 CPUs: an address displacement of 0 was
  12279.                given.  An address expression without displacement is
  12280.                generated, and a convenient number of NOPs are emitted
  12281.                to avoid phasing errors.}
  12282.               {none}
  12283. \errentry{  10}{short addressing possible}
  12284.               {warning}
  12285.               {680x0-, 6502 and 68xx CPUs: a given memory location can be
  12286.                reached using short addressing. A short addressing
  12287.                instruction is emitted, together with the required
  12288.                number of NOPs to avoid phasing errors.}
  12289.               {none}
  12290. \errentry{  20}{short jump possible}
  12291.               {warning}
  12292.               {680x0- and 8086 CPUs can execute jumps using a short or long
  12293.                displacement. If a shorter jump was not explicitly
  12294.                requested, in the
  12295.                first pass room for the long jump is reserved. Then the code
  12296.                for the shorter jump is emitted, and the remaining space is
  12297.                filled with NOPs to avoid phasing errors.}
  12298.               {none}
  12299. \errentry{  25}{relative jump possible}
  12300.               {warning}
  12301.               {Z80 jumps may be either relative or absolute.  An absolute
  12302.                jump was requested in this case, however a (shorter) relative
  12303.                jump would be possible as well.}
  12304.               {the jump instruction's argument}
  12305. \errentry{  30}{no sharefile created, SHARED ignored}
  12306.               {warning}
  12307.               {A \tty{SHARED} directive was found, but on the command line no
  12308.                options were specified, to generate a shared file.}
  12309.               {none}
  12310. \errentry{  40}{FPU possibly cannot read this value ($>$=1E1000)}
  12311.               {warning}
  12312.               {The BCD-floating point format used by the 680x0-FPU
  12313.                allows such a large exponent, but according to the latest
  12314.                databooks, this cannot be fully interpreted. The
  12315.                corresponding word is assembled, but the associated
  12316.                function is not expected to produce the correct result.}
  12317.               {none}
  12318. \errentry{  50}{privileged instruction}
  12319.               {warning}
  12320.               {A Supervisor-mode directive was used, that was not preceded
  12321.                by an explicit \tty{SUPMODE ON} directive}
  12322.               {none}
  12323. \errentry{  60}{distance of 0 not allowed for short jump (NOP created instead)}
  12324.               {warning}
  12325.               {A short jump with a jump distance equal to 0 is not allowed
  12326.                by 680x0 resp. COP8 processors, since the associated code word is
  12327.                used to identify long jump instruction. Instead of a
  12328.                jump instruction, \asname{} emits a NOP}
  12329.               {none}
  12330. \errentry{  70}{symbol out of wrong segment}
  12331.               {warning}
  12332.               {The symbol used as an operand comes from an address space
  12333.                that cannot be addressed together with the given instruction}
  12334.               {none}
  12335. \errentry{  75}{segment not accessible}
  12336.               {warning}
  12337.               {The symbol used as an operand belongs to an address space
  12338.                that cannot be accessed with any of the segment registers of
  12339.                the 8086}
  12340.               {The name of the inaccessible segment}
  12341. \errentry{  80}{change of symbol values forces additional pass}
  12342.               {warning}
  12343.               {A symbol changed value, with respect to previous pass. This
  12344.                warning is emitted only if the \tty{-r} option is used.}
  12345.               {name of the symbol that changed value.}
  12346. \errentry{  90}{overlapping memory usage}
  12347.               {warning}
  12348.               {The analysis of the usage list shows that part of the
  12349.                program memory was used more than once. The reason can be an
  12350.                excessive usage of \tty{ORG} directives.}
  12351.               {none}
  12352. \errentry{  95}{overlapping register usage}
  12353.               {warning}
  12354.               {The instruction uses whole registers or parts thereof in
  12355.                a non-allowed way.}
  12356.               {The offending argument}
  12357. \errentry{ 100}{none of the CASE conditions was true}
  12358.               {warning}
  12359.               {A \tty{SWITCH...CASE} directive without \tty{ELSECASE} clause was
  12360.                executed, and none of the \tty{CASE} conditions was found
  12361.                to be true.}
  12362.               {none}
  12363. \errentry{ 110}{page might not be addressable}
  12364.               {warning}
  12365.               {The symbol used as an operand was not found in the memory
  12366.                page defined by an \tty{ASSUME} directive (ST6, 78(C)10).}
  12367.               {none}
  12368. \errentry{ 120}{register number must be even}
  12369.               {warning}
  12370.               {The CPU allows to concatenate only register pairs, whose
  12371.                start address is even (RR0, RR2, ..., only for Z8).}
  12372.               {none}
  12373. \errentry{ 130}{obsolete instruction, usage discouraged}
  12374.               {warning}
  12375.               {The instruction used, although supported, was superseded by
  12376.                a new instruction. Future versions of the CPU could no more
  12377.                implement the old instruction.}
  12378.               {none}
  12379. \errentry{ 140}{unpredictable execution of this instruction}
  12380.               {warning}
  12381.               {The addressing mode used for this instruction is allowed,
  12382.                however a register is used in such a way that its contents
  12383.                cannot be predicted after the execution of the
  12384.                instruction.}
  12385.               {none}
  12386. \errentry{ 150}{localization operator senseless out of a section}
  12387.               {warning}
  12388.               {An aheaded \@ must be used, so that it is
  12389.                explicitly referred to the local symbols used in the
  12390.                section. When the operator is used out of a section, there
  12391.                are no local symbols, because this operator is useless in
  12392.                this context.}
  12393.               {none}
  12394. \errentry{ 160}{senseless instruction}
  12395.               {warning}
  12396.               {The instruction used has no meaning, or it can be
  12397.                substituted by an other instruction, shorter and more
  12398.                rapidly executed.}
  12399.               {none}
  12400. \errentry{ 170}{unknown symbol value forces additional pass}
  12401.               {warning}
  12402.               {\asname{} expects a forward definition of a symbol, i.e. a symbol
  12403.                was used before it was defined. A further pass must be
  12404.                executed. This warning is emitted only if the \tty{-r} option was
  12405.                used.}
  12406.               {none}
  12407. \errentry{ 180}{address is not properly aligned}
  12408.               {warning}
  12409.               {An address was used that is not an exact multiple of the
  12410.                operand size. Although the CPU databook forbids this, the
  12411.                address could be stored in the instruction word, so \asname{}
  12412.                simply emits a warning.}
  12413.               {none.}
  12414. \errentry{ 190}{I/O-address must not be used here}
  12415.               {warning}
  12416.               {The addressing mode or the address used are correct, but the
  12417.                address refers to the peripheral registers, and it
  12418.                cannot be used in this circumstance.}
  12419.               {none.}
  12420. \errentry{ 200}{possible pipelining effects}
  12421.               {warning}
  12422.               {A register is used in a series of instructions, so that a
  12423.                sequence of instructions probably does not generate the
  12424.                desired result. This usually happens when a register is
  12425.                used before its new content was effectively loaded in it.}
  12426.               {the register probably causing the problem.}
  12427. \errentry{ 210}{multiple use of address register in one instruction}
  12428.               {warning}
  12429.               {A register used for the addressing is used once more in the
  12430.                same instruction, in a way that results in a modification
  12431.                of the register value. The resulting address does not have a
  12432.                well defined value.}
  12433.               {the register used more than once.}
  12434. \errentry{ 220}{memory location is not bit addressable}
  12435.               {warning}
  12436.               {Via a \tty{SFRB} statement, it was tried to declare a memory cell
  12437.                as bit addressable which is not bit addressable due to the
  12438.                8051's architectural limits.}
  12439.               {none}
  12440. \errentry{ 230}{stack is not empty}
  12441.               {warning}
  12442.               {At the end of a pass, a stack defined by the program is
  12443.                not empty.}
  12444.               {the name of the stack and its remaining depth}
  12445. \errentry{ 240}{NUL character in string, result is undefined}
  12446.               {warning}
  12447.               {A string constant contains a NUL character. Though this
  12448.                works with the Pascal version, it is a problem for the
  12449.                C version of \asname{} since C itself terminates strings with
  12450.                a NUL character. i.e. the string would have its end for
  12451.                C just at this point...}
  12452.               {none}
  12453. \errentry{ 250}{instruction crosses page boundary}
  12454.               {warning}
  12455.               {The parts of a machine statement partiallly lie on
  12456.                different pages.  As the CPU's instruction counter does
  12457.                not get incremented across page boundaries, the processor
  12458.                would fetch at runtime the first byte of the old page
  12459.                instead of the instruction's following byte; the program
  12460.                would execute incorrectly.}
  12461.               {none}
  12462. \errentry{ 255}{range underflow}
  12463.               {warning}
  12464.               {A numeric value was below the allowed range.  \asname{} brought
  12465.                the value back into the allowed range by truncating upper
  12466.                bits, but it is not guaranteed that meaningful and correct
  12467.                code is generated by this.}
  12468.               {none}
  12469. \errentry{ 260}{range overflow}
  12470.               {warning}
  12471.               {A numeric value was above the allowed range.  \asname{} brought
  12472.                the value back into the allowed range by truncating upper
  12473.                bits, but it is not guaranteed that meaningful and correct
  12474.                code is generated by this.}
  12475.               {none}
  12476. \errentry{ 270}{negative argument for DUP}
  12477.               {warning}
  12478.               {The repetition argument of a DUP directive was smaller
  12479.                than 0.  Analogous to a count of exactly 0, no data is
  12480.                stored.}
  12481.               {none}
  12482. \errentry{ 280}{single X operand interpreted as indexed and not implicit
  12483.                addressing}
  12484.               {warning}
  12485.               {A single X operand may be interpreted either as register X
  12486.                or x-indexed addressing with zero displacement, since
  12487.                Motorola does not specify this variant.  \asname{} chooses the
  12488.                latter, which may not be the desired one.}
  12489.               {none}
  12490. \errentry{ 300}{bit number will be truncated}
  12491.               {warning}
  12492.               {This instruction only operates on byte resp. longword
  12493.                operands.  bit numbers beyond 7 resp. 31 will be treated
  12494.                modulo-8 resp. modulo-32 by the CPU.}
  12495.               {none}
  12496. \errentry{ 310}{invalid register pointer value}
  12497.               {warning}
  12498.               {Valid values for the RP register range from 0x00 to 0x70 resp.
  12499.                0xf0, because all other areas are unused on the Z8.}
  12500.               {none}
  12501. \errentry{ 320}{macro argument redefined}
  12502.               {warning}
  12503.               {A macro parameter was assigned two or more
  12504.                different values.  This may happen by usage of
  12505.                keyword arguments.  The last argument is actually
  12506.                used.}
  12507.               {name of the macro parameter}
  12508. \errentry{ 330}{deprecated instruction}
  12509.               {warning}
  12510.               {This instruction is deprecated and should not be used any
  12511.                more in new programs.}
  12512.               {the instruction that should be used instead.}
  12513. \errentry{ 340}{source operand is longer or same size as destination operand}
  12514.               {warning}
  12515.               {The source operand's size is larger than the destination operand's
  12516.                size, expressed in bits.  Sign or zero extension does not make sense
  12517.                with these arguments.  See the CPU's reference manual for its behaviour
  12518.                in this situation.}
  12519.               {none}
  12520. \errentry{ 350}{TRAP number represents valid instruction}
  12521.               {warning}
  12522.               {A TRAP with this number uses the same machine code as a
  12523.                machine instruction supported by the CPU.}
  12524.               {none}
  12525. \errentry{ 360}{Padding added}
  12526.               {warning}
  12527.               {The amount of bytes placed in memory is odd; one half of the last
  12528.                16 bit word remains unused.}
  12529.               {none}
  12530. \errentry{ 370}{register number wraparound}
  12531.               {warning}
  12532.               {The start register number plus the count of registers results
  12533.                in a last register beyond the end of the register bank.}
  12534.               {the argument holding the register count}
  12535. \errentry{ 380}{using indexed instead of indirect addressing}
  12536.               {warning}
  12537.               {Indirect addressing is not allowed at this place.
  12538.                Instead, indexed addressing with a dummy displacement of
  12539.                zero will be used.}
  12540.               {the argument holding the indirect addressing expression}
  12541. \errentry{ 390}{not allowed in normal mode}
  12542.               {warning}
  12543.               {This machine instruction is only allowed in panel mode,
  12544.                not during ''normal operation''.}
  12545.               {the machine instruction in question}
  12546. \errentry{ 400}{not allowed in panel mode}
  12547.               {warning}
  12548.               {This machine instruction is only allowed during ''normal
  12549.                operation'', not in panel mode.}
  12550.               {the machine instruction in question}
  12551. \errentry{ 410}{argument out of range}
  12552.               {warning}
  12553.               {The argument or the sum of two arguments is outside the
  12554.                range allowed for this instruction, though the instruction
  12555.                principally provides room for larger values.}
  12556.               {the argument in question}
  12557. \errentry{ 420}{attempt to skip multiword instruction}
  12558.               {warning}
  12559.               {The previous instruction was a skip instruction, which
  12560.                can only skip a single (half) word.  The current instruction
  12561.                is longer than one word, so a skip would jump into the middle
  12562.                of it.}
  12563.               {the multi-word instruction in question}
  12564. \errentry{ 430}{implicit sign extension}
  12565.               {warning}
  12566.               {As part of executing this instruction, the processor will
  12567.                perform a sign extension to the full register width.  For the
  12568.                given argument, this means the register's upper bits will be
  12569.                filled with ones and not zeros.  Depending on the usage that
  12570.                follows, this may be irrelevant or not.}
  12571.               {the value in question}
  12572. \errentry{ 440}{numeric value -128 means usage of E register's content (use literal 'E' to avoid this warning)}
  12573.               {warning}
  12574.               {On the SC/MP, a displacement of -128 means in this case that
  12575.                the actual displacement is not -128, but instead taken from
  12576.                the E register.  The assembler cannot decide for sure whether
  12577.                this was intended or the accidental result of a computation,
  12578.                and therefore warns.  Use the literal value 'E' or a register
  12579.                symbol defined to be 'E' to clarify your intent and avoid
  12580.                this warning.}
  12581.               {the displacement argument in question}
  12582. \errentry{ 450}{I/O address must be accessed via INS/OUTS}
  12583.               {warning}
  12584.               {I/O addresses in the range of 0 to 3 are located in the
  12585.                processor module and can only be accessed via the {\tt INS}
  12586.                and {\tt OUTS} instructios, not via {\tt IN} or {\tt OUT}.}
  12587.               {the address argument in question}
  12588. \errentry{ 460}{CASE limit does not match number of branch addresses}
  12589.               {warning}
  12590.               {The CASE instruction expects a branch table with as many
  12591.                entries, as the limit argument says, plus one.  The limit and
  12592.                the number of branch addresses do not fit together.}
  12593.               {the limit argument}
  12594. \errentry{ 470}{instruction assembled as NOP}
  12595.               {warning}
  12596.               {The machinne code assigned to this instruction is used
  12597.                for different purposes.  Since this instruction anyway does
  12598.                not perform any operation, it is assembled as a NOP.}
  12599.               {none}
  12600. \errentry{ 480}{argument treated as vector}
  12601.               {warning}
  12602.               {There is no way to umambiguously decide whether the argument is
  12603.                an address or a vector.  Since the argument is a plain numeric
  12604.                value not assigned to any segment, it is assumed to be a vector.}
  12605.               {the argument in question}
  12606. \errentry{ 490}{interpreting too large integer constant as float}
  12607.               {warning}
  12608.               {Though the argument is a syntactically correct integer constant,
  12609.                its value is outside of what can internally be represented as
  12610.                integer.  The number is therefore stored as a floating point
  12611.                number.}
  12612.               {the argument in question}
  12613. \errentry{1000}{symbol double defined}
  12614.               {error}
  12615.               {A new value is assigned to a symbol, using a label or a
  12616.                \tty{EQU, PORT, SFR, LABEL, SFRB} or \tty{BIT} instruction: however this
  12617.                can be done only using \tty{SET/EVAL}.}
  12618.               {the name of the offending symbol, and the line number where
  12619.                it was defined for the first time, according to the symbol
  12620.                table.}
  12621. \errentry{1010}{symbol undefined}
  12622.               {error}
  12623.               {A symbol is still not defined in the symbol table, also
  12624.                after a second pass.}
  12625.               {the name of the undefined symbol.}
  12626. \errentry{1020}{invalid symbol name}
  12627.               {error}
  12628.               {A symbol does not fulfill the requirements that symbols
  12629.                must have to be considered valid by \asname{}. Please pay
  12630.                attention that more stringent syntax rules exist for
  12631.                macros and function parameters.}
  12632.               {the wrong symbol name}
  12633. \errentry{1030}{reserved symbol name}
  12634.               {error}
  12635.               {A symbol is valid by itself, but this specific name is reserved
  12636.                for other purposes.  It therefore cannot be used for user-defined
  12637.                symbols.}
  12638.               {the symbol name in question}
  12639. \errentry{1090}{invalid format}
  12640.               {error}
  12641.               {The instruction format used does not exist for this
  12642.                instruction.}
  12643.               {the known formats for this command}
  12644. \errentry{1100}{useless attribute}
  12645.               {error}
  12646.               {The instruction (processor or pseudo) cannot be used with a
  12647.                point-suffixed attribute.}
  12648.               {none}
  12649. \errentry{1105}{attribute may only be one character long}
  12650.               {error}
  12651.               {The attribute following a point after an instruction must
  12652.                not be longer or shorter than one character.}
  12653.               {none}
  12654. \errentry{1107}{undefined attribute}
  12655.               {error}
  12656.               {This instruction uses an invalid attribute.}
  12657.               {none}
  12658. \errentry{1110}{wrong number of operands}
  12659.               {error}
  12660.               {The number of arguments issued for the instruction (processor or
  12661.                pseudo) does not conform with the accepted number of
  12662.                operands.}
  12663.               {the expected number of arguments resp. operands}
  12664. \errentry{1112}{failed splitting argument into parts}
  12665.               {error}
  12666.               {For some targets (e.g. DSP56000), the
  12667.                comma-separated have to be split into individual
  12668.                operands, which failed.}
  12669.               {none}
  12670. \errentry{1115}{wrong number of operations}
  12671.               {error}
  12672.               {The number of options given with this command is not
  12673.                correct.}
  12674.               {none}
  12675. \errentry{1120}{addressing mode must be immediate}
  12676.               {error}
  12677.               {The instruction can be used only with immediate operands
  12678.                (preceded by \tty{\#}).}
  12679.               {none}
  12680. \errentry{1130}{invalid operand size}
  12681.               {error}
  12682.               {Although the operand is of the right type, it does not have
  12683.                the correct length (in bits).}
  12684.               {none}
  12685. \errentry{1131}{conflicting operand sizes}
  12686.               {error}
  12687.               {The operands used have different length (in bits)}
  12688.               {none}
  12689. \errentry{1132}{undefined operand size}
  12690.               {error}
  12691.               {It is not possible to estimate, from the opcode and from
  12692.                the operands, the size of the operand (a trouble with
  12693.                8086 assembly). You must define it with a \tty{BYTE or WORD}
  12694.                \tty{PTR} prefix.}
  12695.               {none}
  12696. \errentry{1133}{expected integer or string, but got floating point number}
  12697.               {error}
  12698.               {A floating point number cannot be used as argument at this place.}
  12699.               {the argument in question}
  12700. \errentry{1134}{expected integer, but got floating point number}
  12701.               {error}
  12702.               {A floating point number cannot be used as argument at this place.}
  12703.               {the argument in question}
  12704. \errentry{1136}{expected floating point number, but got string}
  12705.               {error}
  12706.               {A string cannot be used as argument at this place.}
  12707.               {the argument in question}
  12708. \errentry{1137}{operand type mismatch}
  12709.               {Error}
  12710.               {The two arguments of an operator are not of same
  12711.                data type (integer/\-float/\-string).}
  12712.               {keines}
  12713. \errentry{1138}{expected string, but got integer}
  12714.               {error}
  12715.               {An integer cannot be used as argument at this place.}
  12716.               {the argument in question}
  12717. \errentry{1139}{expected string, but got floating point number}
  12718.               {error}
  12719.               {An floating point number cannot be used as argument at this place.}
  12720.               {the argument in question}
  12721. \errentry{1140}{too many arguments}
  12722.               {error}
  12723.               {No more than 20 arguments can be given to any instruction}
  12724.               {none}
  12725. \errentry{1141}{expected integer, but got string}
  12726.               {error}
  12727.               {A string cannot be used as argument at this place.}
  12728.               {the argument in question}
  12729. \errentry{1142}{expected integer or floating point number, but got string}
  12730.               {error}
  12731.               {A string cannot be used as argument at this place.}
  12732.               {the argument in question}
  12733. \errentry{1143}{expected string}
  12734.               {error}
  12735.               {Only a string (enclosed in single quotes) may be used as
  12736.                argument at this place.}
  12737.               {the argument in question}
  12738. \errentry{1144}{expected integer}
  12739.               {error}
  12740.               {Only an integer number may be used as argument at this place.}
  12741.               {the argument in question}
  12742. \errentry{1145}{expected integer, floating point number or string but got register}
  12743.               {error}
  12744.               {A register symbol may not be used as argument at this place.}
  12745.               {the argument in question}
  12746. \errentry{1146}{expected integer or string}
  12747.               {error}
  12748.               {A floating point number or register symbol may not be used as argument at this place.}
  12749.               {the argument in question}
  12750. \errentry{1147}{expected register}
  12751.               {error}
  12752.               {Only an register may be used as argument at this place.}
  12753.               {the argument in question}
  12754. \errentry{1148}{register symbol for different target}
  12755.               {error}
  12756.               {The used register symbol was defined for a target different from
  12757.                the current one and is not compatible.}
  12758.               {the argument in question}
  12759. \errentry{1149}{expected floating point argument but got integer}
  12760.               {error}
  12761.               {Only a floating point argument may be used at this place,
  12762.                but an integer argument was given.}
  12763.               {the argument in question}
  12764. \errentry{1151}{expected integer or floating point number but got register}
  12765.               {error}
  12766.               {Only an integer or floating point number argument may be used at this place,
  12767.                but a register was given.}
  12768.               {the argument in question}
  12769. \errentry{1152}{expected integer or string but got register}
  12770.               {error}
  12771.               {Only an integer or string argument may be used at this place,
  12772.                but a register was given.}
  12773.               {the argument in question}
  12774. \errentry{1153}{expected integer but got register}
  12775.               {error}
  12776.               {Only an integer argument may be used at this place,
  12777.                but a register was given.}
  12778.               {the argument in question}
  12779. \errentry{1154}{string too long}
  12780.               {error}
  12781.               {The string is too long to be represented with leading
  12782.                length byte.}
  12783.               {the argument in question}
  12784. \errentry{1200}{unknown instruction}
  12785.               {error}
  12786.               {An instruction was used that is neither an \asname{} instruction, nor a
  12787.                known macine instruction for the current processor type.}
  12788.               {none}
  12789. \errentry{1300}{number of opening/closing brackets does not match}
  12790.               {error}
  12791.               {The expression parser found an expression enclosed by
  12792.                parentheses, where the number of opening and closing
  12793.                parentheses does not match.}
  12794.               {the wrong expression}
  12795. \errentry{1310}{division by 0}
  12796.               {error}
  12797.               {An expression on the right side of a division or modulus
  12798.                operation was found to be equal to 0.}
  12799.               {none}
  12800. \errentry{1315}{range underflow}
  12801.               {error}
  12802.               {An integer word underflowed the allowed range.}
  12803.               {the value of the word and the allowed minimum (in most
  12804.                cases, maybe I will complete this one day...)}
  12805. \errentry{1320}{range overflow}
  12806.               {error}
  12807.               {An integer word overflowed the allowed range.}
  12808.               {the value of the world, and the allowed maximum (in most
  12809.                cases, maybe I will complete this one day...)}
  12810. \errentry{1322}{not a power of two}
  12811.               {error}
  12812.               {only powers of two (1,2,4,8,...) are allowed at this place.}
  12813.               {The value in question}
  12814. \errentry{1323}{invalid decimal digit}
  12815.               {error}
  12816.               {A string as argument to {\tt PACKED} may only contain the
  12817.                characters from 0 to 9, and optionally a plus or minus
  12818.                sign at the beginning.}
  12819.               {The argument in question}
  12820. \errentry{1324}{decimal string too long}
  12821.               {error}
  12822.               {A packed decimal number must not be longer than 31 digits.}
  12823.               {The argument in question}
  12824. \errentry{1325}{address is not properly aligned}
  12825.               {error}
  12826.               {The given address does not correspond with the size needed
  12827.                by the data transfer, i.e. it is not an integral multiple of
  12828.                the operand size. Not all processor types can use unaligned
  12829.                data.}
  12830.               {none}
  12831. \errentry{1330}{distance too big}
  12832.               {error}
  12833.               {The displacement used for an address is too large.}
  12834.               {none}
  12835. \errentry{1331}{target not on same page}
  12836.               {error}
  12837.               {Instruction and operand address must be located in the
  12838.                same memory page.}
  12839.               {the address argument in question}
  12840. \errentry{1340}{short addressing not allowed}
  12841.               {error}
  12842.               {The address of the operand is outside of the address space
  12843.                that can be accessed using short-addressing mode.}
  12844.               {none}
  12845. \errentry{1350}{addressing mode not allowed here}
  12846.               {error}
  12847.               {the addressing mode used, although usually possible,
  12848.                cannot be used here.}
  12849.               {none}
  12850. \errentry{1351}{address must be even}
  12851.               {error}
  12852.               {At this point, only even addresses are allowed, since the
  12853.                low order bits are used for other purposes or are reserved.}
  12854.               {the argument in question}
  12855. \errentry{1352}{address must be aligned}
  12856.               {error}
  12857.               {At this point, only aligned (i.e. a mulitple of 2,4,8...) addresses
  12858.                are allowed, since the low order bits are used for other purposes
  12859.                or are reserved.}
  12860.               {the argument in question}
  12861. \errentry{1355}{addressing mode not allowed in parallel operation}
  12862.               {error}
  12863.               {The addressing mode(s) used are allowed in sequential,
  12864.                but not in parallel instructions}
  12865.               {none}
  12866. \errentry{1360}{undefined condition}
  12867.               {error}
  12868.               {The branch condition used for a conditional jump does not
  12869.                exist.}
  12870.               {none}
  12871. \errentry{1365}{incompatible conditions}
  12872.               {error}
  12873.               {The used combination of conditions is not possible
  12874.                in a single instruction.}
  12875.               {the condition where the incompatibility was detected.}
  12876. \errentry{1366}{unknown flag}
  12877.               {error}
  12878.               {The given flag does not exist.}
  12879.               {the argument using the flag in question}
  12880. \errentry{1367}{duplicate flag}
  12881.               {error}
  12882.               {The given flag has already been used in the list of flags.}
  12883.               {the argument duplicating the flag}
  12884. \errentry{1368}{unknown interrupt}
  12885.               {error}
  12886.               {The given interrupt does not exist.}
  12887.               {the argument using the interrupt in question}
  12888. \errentry{1369}{duplicate interrupt}
  12889.               {error}
  12890.               {The given interrupt has already been used in the list of interrupt.}
  12891.               {the argument duplicating the interrupt}
  12892. \errentry{1370}{jump distance too big}
  12893.               {error}
  12894.               {the jump instruction and destination are too apart to
  12895.                execute the jump with a single step}
  12896.               {none}
  12897. \errentry{1371}{jump distance is zero}
  12898.               {error}
  12899.               {the jump destination is right behind the jump instruction,
  12900.                and a jump distance of zero cannot be encoded.}
  12901.               {the target address in source code}
  12902. \errentry{1375}{jump distance is odd}
  12903.               {error}
  12904.               {Since instruction must only be located at even addresses,
  12905.                the jump distance between two instructions must always be
  12906.                even, and the LSB of the jump distance is used otherwise.
  12907.                This issue was not verified here. The reason is usually the
  12908.                presence of an odd number of data in bytes or a wrong
  12909.                \tty{ORG}.}
  12910.               {none}
  12911. \errentry{1376}{skip target mismatch}
  12912.               {error}
  12913.               {The gien branch target is not the address the processor would
  12914.                jump to if the skip instruction were executed.}
  12915.               {the given (intended) jump target}
  12916. \errentry{1380}{invalid argument for shifting}
  12917.               {error}
  12918.               {only a constant or a data register can be used for defining
  12919.                the shift size. (only for 680x0)}
  12920.               {none}
  12921. \errentry{1390}{operand must be in range 1..8}
  12922.               {error}
  12923.               {constants for shift size or \tty{ADDQ} argument can be only
  12924.                within the 1..8 range (only for 680x0)}
  12925.               {none}
  12926. \errentry{1400}{shift amplitude too big}
  12927.               {error}
  12928.               {(no more used)}
  12929.               {none}
  12930. \errentry{1410}{invalid register list}
  12931.               {error}
  12932.               {The register list argument of \tty{MOVEM} or \tty{FMOVEM} has a
  12933.                wrong format (only for 680x0)}
  12934.               {none}
  12935. \errentry{1420}{invalid addressing mode for CMP}
  12936.               {error}
  12937.               {The operand combination used with the \tty{CMP} instruction is
  12938.                not allowed (only for 680x0)}
  12939.               {none}
  12940. \errentry{1430}{invalid CPU type}
  12941.               {error}
  12942.               {The processor type used as argument for \tty{CPU} command is
  12943.                unknown to \asname{}.}
  12944.               {the unknown processor type}
  12945. \errentry{1431}{invalid FPU type}
  12946.               {error}
  12947.               {The co-processor type used as argument for \tty{FPU} command is
  12948.                unknown to \asname{}.}
  12949.               {the unknown co-processor type}
  12950. \errentry{1432}{invalid PMMU type}
  12951.               {error}
  12952.               {The MMU type used as argument for \tty{PMMU} command is
  12953.                unknown to \asname{}.}
  12954.               {the unknown MMU type}
  12955. \errentry{1440}{invalid control register}
  12956.               {error}
  12957.               {The control register used by a \tty{MOVEC} is not (yet) available
  12958.                for the processor defined by the \tty{CPU} command.}
  12959.               {none}
  12960. \errentry{1445}{invalid register}
  12961.               {error}
  12962.               {The register used, although valid, cannot be used in this
  12963.                context.}
  12964.               {none}
  12965. \errentry{1446}{register(s) listed more than once}
  12966.               {error}
  12967.               {A register appears more than once in the list of registers
  12968.                to be saved or restored.}
  12969.               {none}
  12970. \errentry{1447}{register bank mismatch}
  12971.               {error}
  12972.               {An address expression uses registers from different banks.}
  12973.               {the register in question}
  12974. \errentry{1448}{undefined register length}
  12975.               {error}
  12976.               {Registers of different size may be used at this place, and
  12977.                 the register length cannot be deduced from the address alone.}
  12978.               {the argument in question}
  12979. \errentry{1449}{invalid operation on register}
  12980.               {error}
  12981.               {This operation may not be applied to this register, e.g. because
  12982.                the register is read-only or write-only.}
  12983.               {the register in question}
  12984. \errentry{1450}{RESTORE without SAVE}
  12985.               {error}
  12986.               {A \tty{RESTORE} command was found, that cannot be coupled with a
  12987.                corresponding \tty{SAVE}.}
  12988.               {none}
  12989. \errentry{1460}{missing RESTORE}
  12990.               {error}
  12991.               {After the assembling pass, a \tty{SAVE} command was missing.}
  12992.               {none.}
  12993. \errentry{1465}{unknown macro control instruction}
  12994.               {error}
  12995.               {A macro option parameter is unknown to \asname{}.}
  12996.               {the dubious option.}
  12997. \errentry{1470}{missing ENDIF/ENDCASE}
  12998.               {error}
  12999.               {after the assembling, some of the \tty{IF}- or \tty{CASE}- constructs
  13000.                were found without the closing command}
  13001.               {none}
  13002. \errentry{1480}{invalid IF-structure}
  13003.               {error}
  13004.               {The command structure in a \tty{IF}- or \tty{SWITCH}- sequence is
  13005.                wrong.}
  13006.               {none}
  13007. \errentry{1483}{section name double defined}
  13008.               {error}
  13009.               {In this program module a section with the same name still
  13010.                exists.}
  13011.               {the multiple-defined name}
  13012. \errentry{1484}{unknown section}
  13013.               {error}
  13014.               {In the current scope, there are no sections with this name}
  13015.               {the unknown name}
  13016. \errentry{1485}{missing ENDSECTION}
  13017.               {error}
  13018.               {Not all the sections were properly closed.}
  13019.               {none}
  13020. \errentry{1486}{wrong ENDSECTION}
  13021.               {error}
  13022.               {The given \tty{ENDSECTION} does not refer to the most
  13023.                deeply nested one.}
  13024.               {none}
  13025. \errentry{1487}{ENDSECTION without SECTION}
  13026.               {error}
  13027.               {An \tty{ENDSECTION} command was found, but the associated section
  13028.                was not defined before.}
  13029.               {none}
  13030. \errentry{1488}{unresolved forward declaration}
  13031.               {error}
  13032.               {A symbol declared with a \tty{FORWARD} or \tty{PUBLIC} statement could
  13033.                not be resolved.}
  13034.               {the name of the unresolved symbol, plus the
  13035.                position of the forward declaration in the
  13036.                source.}
  13037. \errentry{1489}{conflicting FORWARD $<->$ PUBLIC-declaration}
  13038.               {error}
  13039.               {A symbol was defined both as public and private.}
  13040.               {the name of the symbol.}
  13041. \errentry{1490}{wrong numbers of function arguments}
  13042.               {error}
  13043.               {The number of arguments used for referencing a function
  13044.                does not match the number of arguments defined in the
  13045.                function definition.}
  13046.               {none}
  13047. \errentry{1491}{duplicate function argument name}
  13048.               {error}
  13049.               {Two or more arguments of a function have the same name.}
  13050.               {the argument with duplicate name.}
  13051. \errentry{1495}{unresolved literals (missing LTORG)}
  13052.               {error}
  13053.               {At the end of the program, or just before switching to
  13054.                another processor type, unresolved literals still remain.}
  13055.               {none}
  13056. \errentry{1500}{instruction not allowed on}
  13057.               {error}
  13058.               {Although the instruction is correct, it cannot be used with
  13059.                the selected member of the CPU family.}
  13060.               {The processor variants that would support this
  13061.                instruction.}
  13062. \errentry{1501}{FPU instructions are not enabled}
  13063.               {error}
  13064.               {FPU instruction set extensions must be enabled to
  13065.                use this instruction.}
  13066.               {none}
  13067. \errentry{1502}{PMMU instructions are not enabled}
  13068.               {error}
  13069.               {PMMU instruction set extensions must be enabled
  13070.                to use this instruction.}
  13071.               {none}
  13072. \errentry{1503}{full PMMU instruction set is not enabed}
  13073.               {error}
  13074.               {This instrction is only contained in the 68851's
  13075.                instruction set, not in the reduced instruction
  13076.                set of the integrated PMMU.}
  13077.               {none}
  13078. \errentry{1504}{Z80 syntax was not allowed}
  13079.               {error}
  13080.               {This instruction is only allowed if Z80 syntax
  13081.                for 8080/8085 instructions has been enabled.}
  13082.               {none}
  13083. \errentry{1505}{addressing mode not allowed on}
  13084.               {error}
  13085.               {Although the addressing mode used is correct, it cannot be
  13086.                used with the selected member of the CPU family.}
  13087.               {The processor variants that would support this
  13088.                addressing mode.}
  13089. \errentry{1506}{not allowed in exclusive Z80 syntax mode}
  13090.               {error}
  13091.               {This instrction is no longer allowed if exclusive
  13092.                Z80 syntax mode for 8080/8085 instructions has been set.}
  13093.               {none}
  13094. \errentry{1507}{FPU instruction not supported on ...}
  13095.               {error}
  13096.               {Although this FPU instruction exists, it cannot be used on
  13097.                the selected type of FPU.}
  13098.               {The instruction in question}
  13099. \errentry{1508}{Custom instructions are not enabled}
  13100.               {error}
  13101.               {Custom instruction set extensions must be enabled
  13102.                to use this instruction.}
  13103.               {The instruction in question}
  13104. \errentry{1509}{instruction extension not enabled}
  13105.               {error}
  13106.               {This instruction is part of an extension whose
  13107.                usage has not been enabled.}
  13108.               {The extension's name}
  13109. \errentry{1510}{invalid bit position}
  13110.               {error}
  13111.               {Either the number of bits specified is not allowed, or
  13112.                the command is not completely specified.}
  13113.               {none}
  13114. \errentry{1520}{only ON/OFF allowed}
  13115.               {error}
  13116.               {This pseudo command accepts as argument either \tty{ON} or
  13117.                \tty{OFF}}
  13118.               {none}
  13119. \errentry{1530}{stack is empty or undefined}
  13120.               {error}
  13121.               {It was tried to access a stack via a \tty{POPV} instruction
  13122.                that was either never defined or already emptied.}
  13123.               {the name of the stack in question}
  13124. \errentry{1540}{not exactly one bit set}
  13125.               {error}
  13126.               {Not exactly one bit was set in a mask passed to the
  13127.                \tty{BITPOS} function.}
  13128.               {none}
  13129. \errentry{1550}{ENDSTRUCT without STRUCT}
  13130.               {error}
  13131.               {An \tty{ENDSTRUCT} instruction was found though there is
  13132.                currently no structure definition in progress.}
  13133.               {none}
  13134. \errentry{1551}{open structure definition}
  13135.               {error}
  13136.               {After end of assembly, not all \tty{STRUCT} instructions
  13137.                have been closed with appropriate \tty{ENDSTRUCT}s.}
  13138.               {the innermost, unfinished structure definition}
  13139. \errentry{1552}{wrong ENDSTRUCT}
  13140.               {error}
  13141.               {the name parameter of an \tty{ENDSTRUCT} instruction does
  13142.                not correspond to the innermost open structure
  13143.                definition.}
  13144.               {none}
  13145. \errentry{1553}{phase definition not allowed in structure definition}
  13146.               {error}
  13147.               {What should I say about that?  \tty{PHASE} inside a record
  13148.                simply does not make sense and only leads to
  13149.                confusion...}
  13150.               {none}
  13151. \errentry{1554}{invalid \tty{STRUCT} directive}
  13152.               {error}
  13153.               {Only \tty{EXTNAMES}, \tty{NOEXTNAMES}, \tty{DOTS},
  13154.                and \tty{NODOTS} are allowed as directives of a
  13155.                \tty{STRUCT} statement.}
  13156.               {the unknown directive}
  13157. \errentry{1555}{structure re-defined}
  13158.               {error}
  13159.               {A structure of this name has already been defined.}
  13160.               {the name of the structure}
  13161. \errentry{1556}{unresolvable structure element reference}
  13162.               {error}
  13163.               {An element in a structure references to another
  13164.                element, however this referenced element was not
  13165.                defined or itself has an unresolvable reference.}
  13166.               {the name of the element itself and the referenced one}
  13167. \errentry{1557}{duplicate structure element}
  13168.               {error}
  13169.               {The structure already contains an element of this name.}
  13170.               {name of the element}
  13171. \errentry{1560}{instruction is not repeatable}
  13172.               {error}
  13173.               {This machine instruction cannot be repeated via a {\tt
  13174.                RPT} construct.}
  13175.               {none}
  13176. \errentry{1600}{unexpected end of file}
  13177.               {error}
  13178.               {It was tried to read past the end of a file with a
  13179.                \tty{BINCLUDE} statement.}
  13180.               {none}
  13181. \errentry{1700}{ROM-offset must be in range 0..63}
  13182.               {error}
  13183.               {The ROM table of the 680x0 coprocessor has only 64 entries.}
  13184.               {none}
  13185. \errentry{1710}{invalid function code}
  13186.               {error}
  13187.               {The only function code arguments allowed are SFC, DFC, a
  13188.                data register, or a constant in the interval of 0..15 (only
  13189.                for 680x0 MMU).}
  13190.               {none}
  13191. \errentry{1720}{invalid function code mask}
  13192.               {error}
  13193.               {Only a number in the interval 0..15 can be used as
  13194.                function code mask (only for 680x0 MMU)}
  13195.               {none}
  13196. \errentry{1730}{invalid MMU register}
  13197.               {error}
  13198.               {The MMU does not have a register with this name (only for
  13199.                680x0 MMU).}
  13200.               {none}
  13201. \errentry{1740}{level must be in range 0..7}
  13202.               {error}
  13203.               {The level for \tty{PTESTW} and \tty{PTESTR} must be a constant in the
  13204.                range of 0...7 (only for 680x0 MMU).}
  13205.               {none}
  13206. \errentry{1750}{invalid bit mask}
  13207.               {error}
  13208.               {The bit mask used for a bit field command has a wrong
  13209.                format (only for 680x0).}
  13210.               {none}
  13211. \errentry{1760}{invalid register pair}
  13212.               {error}
  13213.               {The register here defined cannot be used in this context,
  13214.                or there is a syntactic error (only for 680x0).}
  13215.               {none}
  13216. \errentry{1800}{open macro definition}
  13217.               {error}
  13218.               {An incomplete macro definition was found. Probably an
  13219.                \tty{ENDM} statement is missing.}
  13220.               {none}
  13221. \errentry{1801}{IRP without ENDM}
  13222.               {error}
  13223.               {An incomplete IRP block was found. Probably an
  13224.                \tty{ENDM} statement is missing.}
  13225.               {none}
  13226. \errentry{1802}{IRPC without ENDM}
  13227.               {error}
  13228.               {An incomplete IRPC block was found. Probably an
  13229.                \tty{ENDM} statement is missing.}
  13230.               {none}
  13231. \errentry{1803}{REPT without ENDM}
  13232.               {error}
  13233.               {An incomplete REPT block was found. Probably an
  13234.                \tty{ENDM} statement is missing.}
  13235.               {none}
  13236. \errentry{1804}{WHILE without ENDM}
  13237.               {error}
  13238.               {An incomplete WHILE block was found. Probably an
  13239.                \tty{ENDM} statement is missing.}
  13240.               {none}
  13241. \errentry{1805}{EXITM not called from within macro}
  13242.               {error}
  13243.               {\tty{EXITM} is designed to terminate a macro expansion.  This
  13244.                instruction only makes sense within macros and an attempt
  13245.                was made to call it in the absence of macros.}
  13246.               {none}
  13247. \errentry{1810}{more than 10 macro parameters}
  13248.               {error}
  13249.               {A macro cannot have more than 10 parameters}
  13250.               {none}
  13251. \errentry{1811}{keyword argument not defined in macro}
  13252.               {error}
  13253.               {a keyword argument referred to a parameter the
  13254.                called macro does not provide.}
  13255.               {used keyword resp. macro parameter}
  13256. \errentry{1812}{positional argument no longer allowed after keyword argument}
  13257.               {Fehler}
  13258.               {position and keyword arguments  may be mixed in
  13259.                one macro call, however only keyword arguments
  13260.                are allowed after the first keyword argument.}
  13261.               {none}
  13262. \errentry{1815}{macro double defined}
  13263.               {error}
  13264.               {A macro was defined more than once in a program section.}
  13265.               {the multiply defined macro name.}
  13266. \errentry{1820}{expression must be evaluatable in first pass}
  13267.               {error}
  13268.               {The command used has an influence on the length of the
  13269.                emitted code, so that forward references cannot be resolved
  13270.                here.}
  13271.               {none}
  13272. \errentry{1830}{too many nested IFs}
  13273.               {error}
  13274.               {(no more implemented)}
  13275.               {none}
  13276. \errentry{1840}{ELSEIF/ENDIF without IF}
  13277.               {error}
  13278.               {A \tty{ELSEIF}- or \tty{ENDIF}- command was found, that is not preceded
  13279.                by an \tty{IF}- command.}
  13280.               {none}
  13281. \errentry{1850}{nested / recursive macro call}
  13282.               {error}
  13283.               {(no more implemented)}
  13284.               {none}
  13285. \errentry{1860}{unknown function}
  13286.               {error}
  13287.               {The function invoked was not defined before.}
  13288.               {The name of the unknown function}
  13289. \errentry{1870}{function argument out of definition range}
  13290.               {error}
  13291.               {The argument does not belong to the allowed argument range
  13292.                associated to the referenced function.}
  13293.               {none}
  13294. \errentry{1880}{floating point overflow}
  13295.               {error}
  13296.               {Although the argument is within the range allowed to the
  13297.                function arguments, the result is not valid}
  13298.               {none}
  13299. \errentry{1890}{invalid value pair}
  13300.               {error}
  13301.               {The base-exponent pair used in the expression cannot be
  13302.                computed}
  13303.               {none}
  13304. \errentry{1900}{instruction must not start on this address}
  13305.               {error}
  13306.               {No jumps can be performed by the selected CPU from this
  13307.                address.}
  13308.               {none}
  13309. \errentry{1905}{invalid jump target}
  13310.               {error}
  13311.               {No jumps can be performed by the selected CPU to this
  13312.                address.}
  13313.               {none}
  13314. \errentry{1910}{jump target not on same page}
  13315.               {error}
  13316.               {Jump command and destination must be in the same memory
  13317.                page.}
  13318.               {none}
  13319. \errentry{1911}{jump target not in same section}
  13320.               {error}
  13321.               {Jump command and destination must be in the same (64K)
  13322.                memory section.}
  13323.               {none}
  13324. \errentry{1920}{code overflow}
  13325.               {error}
  13326.               {An attempt was made to generate more than 1024 code or
  13327.                data bytes in a single memory page.}
  13328.               {none}
  13329. \errentry{1925}{address overflow}
  13330.               {error}
  13331.               {The address space for the processor type actually used was
  13332.                filled beyond the maximum allowed limit.}
  13333.               {none}
  13334. \errentry{1930}{constants and placeholders cannot be mixed}
  13335.               {error}
  13336.               {Instructions that reserve memory, and instructions that define
  13337.                constants cannot be mixed in a single pseudo instruction.}
  13338.               {none}
  13339. \errentry{1940}{code must not be generated in structure definition}
  13340.               {error}
  13341.               {a \tty{STRUCT} construct is only designed to describe a
  13342.                data structure and not to create one; therefore, no
  13343.                instructions are allowed that generate code.}
  13344.               {none}
  13345. \errentry{1950}{parallel construct not possible here}
  13346.               {error}
  13347.               {Either these instructions cannot be executed in parallel,
  13348.                or they are not close enough each other, to do parallel
  13349.                execution.}
  13350.               {none}
  13351. \errentry{1960}{invalid segment}
  13352.               {error}
  13353.               {The referenced segment cannot be used here.}
  13354.               {The name of the segment used.}
  13355. \errentry{1961}{unknown segment}
  13356.               {error}
  13357.               {The segment referenced with a \tty{SEGMENT} command does not
  13358.                exist for the CPU used.}
  13359.               {The name of the segment used}
  13360. \errentry{1962}{unknown segment register}
  13361.               {error}
  13362.               {The segment referenced here does not exist (8086 only)}
  13363.               {none}
  13364. \errentry{1970}{invalid string}
  13365.               {error}
  13366.               {The string has an invalid format.}
  13367.               {none}
  13368. \errentry{1980}{invalid register name}
  13369.               {error}
  13370.               {The referenced register does not exist, or it cannot
  13371.                be used here.}
  13372.               {none}
  13373. \errentry{1985}{invalid argument}
  13374.               {error}
  13375.               {The command used cannot be performed with the \tty{REP}-prefix.}
  13376.               {none}
  13377. \errentry{1990}{indirect mode not allowed}
  13378.               {error}
  13379.               {Indirect addressing cannot be used in this way}
  13380.               {none}
  13381. \errentry{1995}{not allowed in current segment}
  13382.               {error}
  13383.               {(no more implemented)}
  13384.               {none}
  13385. \errentry{1996}{not allowed in maximum mode}
  13386.               {error}
  13387.               {This register can be used only in minimum mode}
  13388.               {none}
  13389. \errentry{1997}{not allowed in minimum mode}
  13390.               {error}
  13391.               {This register can be used only in maximum mode}
  13392.               {none}
  13393. \errentry{2000}{execution packet crosses address boundary}
  13394.               {error}
  13395.               {An execution packet must not cross a 32-byte address
  13396.                boundary}
  13397.               {none}
  13398. \errentry{2001}{multiple use of same execution unit}
  13399.               {error}
  13400.               {One of the CPU's execution units was used more than
  13401.                once in an execution packet}
  13402.               {the name of the execution unit}
  13403. \errentry{2002}{multiple long read operations}
  13404.               {error}
  13405.               {An execution packet contains more than one long read
  13406.                operation, which is not allowed}
  13407.               {one of the functional units executing a long read}
  13408. \errentry{2003}{multiple long write operations}
  13409.               {error}
  13410.               {An execution packet contains more than one long write
  13411.                operation, which is not allowed}
  13412.               {one of the functional units executing a long write}
  13413. \errentry{2004}{long read with write operation}
  13414.               {error}
  13415.               {An execution packet contains both a long read and a write
  13416.                operation, which is not allowed.}
  13417.               {one of the execution units executing the conflicting
  13418.                operations}
  13419. \errentry{2005}{too many reads of one register}
  13420.               {error}
  13421.               {The same register was referenced more than four times in
  13422.                the same execution packet.}
  13423.               {the name of the register referenced too often}
  13424. \errentry{2006}{overlapping destinations}
  13425.               {error}
  13426.               {The same register was written more than one time in the
  13427.                same instruction packet, which is not allowed.}
  13428.               {the name of the register in question}
  13429. \errentry{2008}{too many absolute branches in one execution packet}
  13430.               {error}
  13431.               {An execution packet contains more than one direct branch,
  13432.                which is not allowed.}
  13433.               {none}
  13434. \errentry{2009}{instruction cannot be executed on this unit}
  13435.               {error}
  13436.               {This instruction cannot be executed on this functional
  13437.                unit.}
  13438.               {none}
  13439. \errentry{2010}{invalid escape sequence}
  13440.               {error}
  13441.               {The special character defined using a backslash sequence
  13442.                is not defined}
  13443.               {none}
  13444. \errentry{2020}{invalid combination of prefixes}
  13445.               {error}
  13446.               {The prefix combination here defined is not allowed, or it
  13447.                cannot be translated into binary code}
  13448.               {none}
  13449. \errentry{2030}{constants cannot be redefined as variables}
  13450.               {error}
  13451.               {A symbol that has once been declared as constant with
  13452.                {\tt EQU} must not be modified afterwards with {\tt SET}.}
  13453.               {the name of the symbol in question}
  13454. \errentry{2035}{variables cannot be redefined as constants}
  13455.               {error}
  13456.               {A symbol that has once been declared as variable with
  13457.                {\tt SET} must not be redeclared afterwards as constant
  13458.                (e.g. with {\tt EQU}.}
  13459.               {the name of the symbol in question}
  13460. \errentry{2040}{structure name missing}
  13461.               {error}
  13462.               {A structure's definition lacks the identifier name for the
  13463.                new structure}
  13464.               {none}
  13465. \errentry{2050}{empty argument}
  13466.               {error}
  13467.               {Empty strings must not be used in the argument list for
  13468.                this statement}
  13469.               {none}
  13470. \errentry{2060}{unimplemented instruction}
  13471.               {error}
  13472.               {The used machinen instruction is principally known
  13473.                to the assembler, however, it is currently not
  13474.                implemented, du to lack of documentation from the
  13475.                processor manufacturer.}
  13476.               {the instruction that was used}
  13477. \errentry{2070}{unnamed structure is not part of another structure}
  13478.               {error}
  13479.               {An unnamed structure or union always must be part
  13480.                of another structure or union.}
  13481.               {none}
  13482. \errentry{2080}{STRUCT ended by ENDUNION}
  13483.               {error}
  13484.               {ENDUNION may only be used to finalize the definition
  13485.                of a union and not of a structure.}
  13486.               {name of the structure (if available)}
  13487. \errentry{2090}{Memory address mot on active memory page}
  13488.               {error}
  13489.               {The target address is not within the page
  13490.                that is currently addressable via the page
  13491.                register.}
  13492.               {none}
  13493. \errentry{2100}{unknown macro expansion argument}
  13494.               {error}
  13495.               {An argument to \tty{MACEXP} could not be
  13496.                interpreted.}
  13497.               {the unknown argument}
  13498. \errentry{2105}{too many macro expansion arguments}
  13499.               {error}
  13500.               {The number macro expansion arguments exceeds the allowed limit.}
  13501.               {the argument that busted the limit}
  13502. \errentry{2110}{contradicting macro expansion specifications}
  13503.               {error}
  13504.               {A specification about macro expansion and its
  13505.                precise opposite may not be used in the same
  13506.                \tty{MACEXP} instruction.}
  13507.               {none}
  13508. \errentry{2130}{erwarteter Fehler nicht eingetreten}
  13509.               {error}
  13510.               {An error or warning announced via {\tt EXPECT} did not occur in the
  13511.                instruction block terminated via {\tt ENDEXPECT}.}
  13512.               {The error that was expected}
  13513. \errentry{2140}{nesting of EXPECT/ENDEXPECT not allowed}
  13514.               {error}
  13515.               {Code blocks framed via {\tt EXPECT/ENDEXPECT} must not contain
  13516.                nested {\tt EXPECT/ENDEXPECT} blocks.}
  13517.               {none}
  13518. \errentry{2150}{missing ENDEXPECT}
  13519.               {error}
  13520.               {An instruction block opened via {\tt EXPECT} was not closed via
  13521.                {\tt ENDEXPECT}.}
  13522.               {none}
  13523. \errentry{2160}{ENDEXPECT without EXPECT}
  13524.               {error}
  13525.               {There is no matching previous {\tt EXPECT} to an {\tt ENDEXPECT}.}
  13526.               {none}
  13527. \errentry{2170}{no default checkpoint register defined}
  13528.               {error}
  13529.               {No checkpoint register was specified for a type 12 instruction
  13530.                and no default checkpoint register had previously been defined
  13531.                via the {\tt CKPT} statement.}
  13532.               {none}
  13533. \errentry{2180}{invalid bit field}
  13534.               {error}
  13535.               {The bit field is not in the required syntax {\tt (start,count)}.}
  13536.               {the argument in question}
  13537. \errentry{2190}{argument value missing}
  13538.               {error}
  13539.               {Arguments must have the form 'variable=value'.}
  13540.               {the argument in question}
  13541. \errentry{2200}{unknown argument}
  13542.               {error}
  13543.               {This variable is not supported by the selected target platform.}
  13544.               {the argument in question}
  13545. \errentry{2210}{index register must be 16 bit}
  13546.               {error}
  13547.               {Z8000 index registers must have a size of 16 bits (Rn).}
  13548.               {the argument in question}
  13549. \errentry{2211}{I/O address register must be 16 bit}
  13550.               {error}
  13551.               {Z8000 registers used to address I/O addresses must have a size of 16 bits (Rn).}
  13552.               {the argument in question}
  13553. \errentry{2212}{address register in segmented mode must be 32 bit}
  13554.               {error}
  13555.               {Z8000 registers to address memory in segmented mode must have a size of 32 bits (RRn).}
  13556.               {the argument in question}
  13557. \errentry{2213}{address register in non-segmented mode must be 16 bit}
  13558.               {error}
  13559.               {Z8000 registers to address memory in non-segmented mode must have a size of 16 bits (Rn).}
  13560.               {the argument in question}
  13561. \errentry{2220}{invalid structure argument}
  13562.               {error}
  13563.               {The argument does not match any pattern of allowed arguments
  13564.                when expanding a structure.}
  13565.               {the argument in question}
  13566. \errentry{2221}{too many array dimensions}
  13567.               {error}
  13568.               {Arrays of structures are limited to being three-dimensional.}
  13569.               {the dimension argument that was 'too much'}
  13570. \errentry{2230}{unknown integer notation}
  13571.               {error}
  13572.               {The given integer notation does not exist, or the leading plus resp.
  13573.                minus sign is missing.}
  13574.               {the argument in question}
  13575. \errentry{2231}{invalid list of integer notations}
  13576.               {error}
  13577.               {The requested changes to the list of usable integer notations cannot
  13578.                be applied, because they would result in a contradiction.  Currently,
  13579.                the only such case are 0hex und 0oct which cannot be used at the same
  13580.                time.}
  13581.               {none}
  13582. \errentry{2240}{invalid scale}
  13583.               {error}
  13584.               {The given argument cannot be used as scaling factor.}
  13585.               {the argument in question}
  13586. \errentry{2250}{conflicting string options}
  13587.               {error}
  13588.               {The string option is in contradiction to a previously given option.}
  13589.               {the option in question}
  13590. \errentry{2251}{unknown string option}
  13591.               {error}
  13592.               {The string option does not exist.}
  13593.               {the option in question}
  13594. \errentry{2252}{invalid cache invalidate mode}
  13595.               {error}
  13596.               {Only data, instruction, or both caches may be invalidated.}
  13597.               {the argument in question}
  13598. \errentry{2253}{invalid config list}
  13599.               {error}
  13600.               {The configuration list is either syntactically incorrect or
  13601.                contains invalid elements.}
  13602.               {The list in question or one of its elements}
  13603. \errentry{2254}{conflicting config options}
  13604.               {error}
  13605.               {The option is in contradiction to a previously given option or repeats a previous one.}
  13606.               {the option in question}
  13607. \errentry{2255}{unknown config option}
  13608.               {error}
  13609.               {The option does not exist.}
  13610.               {the option in question}
  13611. \errentry{2260}{invalid CBAR value}
  13612.               {error}
  13613.               {This value for CBAR is not allowed (CA must be larger than BA).}
  13614.               {none}
  13615. \errentry{2270}{page not accessible}
  13616.               {error}
  13617.               {The target address is located in a memory page that is currently
  13618.                inaccessible.}
  13619.               {none}
  13620. \errentry{2280}{field not accessible}
  13621.               {error}
  13622.               {The target address is located in a memory field that is currently
  13623.                inaccessible.}
  13624.               {none}
  13625. \errentry{2281}{target not in same field}
  13626.               {error}
  13627.               {Instruction and target address must be located in the
  13628.                same memory field.}
  13629.               {none}
  13630. \errentry{2290}{invalid instruction combination}
  13631.               {error}
  13632.               {These instructions may not be combined with each other.}
  13633.               {none}
  13634. \errentry{2300}{unmapped character}
  13635.               {error}
  13636.               {The character string contains a charater that cannot be mapped.}
  13637.               {The string in question}
  13638. \errentry{2310}{invalid length of multi character constant}
  13639.               {error}
  13640.               {multi character constants must be between one and four characters long.}
  13641.               {none}
  13642. \errentry{2320}{no target set (use 'CPU ...' or '-cpu ...' to set one)}
  13643.               {fatal}
  13644.               {No target has been set so far.  The assembler therefore does
  13645.                not know which target to generate code for.}
  13646.               {none}
  13647. \errentry{2330}{invalid displacement length}
  13648.               {error}
  13649.               {This displacement length must not be used if this addressing
  13650.                mode is used.}
  13651.               {none}
  13652. \errentry{10001}{error in opening file}
  13653.               {fatal}
  13654.               {An error was detected while trying to open a file for input.}
  13655.               {description of the I/O error}
  13656. \errentry{10002}{error in writing listing}
  13657.               {fatal}
  13658.               {An error happened while \asname{} was writing the listing file.}
  13659.               {description of the I/O error}
  13660. \errentry{10003}{file read error}
  13661.               {fatal}
  13662.               {An error was detected while reading a source file.}
  13663.               {description of the I/O error}
  13664. \errentry{10004}{file write error}
  13665.               {fatal}
  13666.               {While \asname{} was writing a code or share file, an error happened.}
  13667.               {description of the I/O error}
  13668. \errentry{10006}{heap overflow}
  13669.               {fatal}
  13670.               {The memory available is not enough to store all the data
  13671.                needed by \asname{}. Try using the DPMI or OS/2 version of \asname{}.}
  13672.               {none}
  13673. \errentry{10007}{stack overflow}
  13674.               {fatal}
  13675.               {The program stack crashed, because too complex formulas, or
  13676.                a bad disposition of symbols and/or macros were used. Try
  13677.                again, using \asname{} with the option \tty{-A}.}
  13678.               {none}
  13679. \errentry{10008}{INCLUDE nested too deeply}
  13680.               {fatal}
  13681.               {The include nesting depth has exceeded the given limit (200
  13682.                by default). The limit may be raised via the {\tt -maxinclevel}
  13683.                command line argument, a wrong (recursive) inclusion is however
  13684.                the more probable cause.}
  13685.               {the INCLUDE statement that exceeded the limit}
  13686. \errentry{10010}{invalid place holder in listing per-line prefix format}
  13687.               {fatal}
  13688.               {Only  \%i, \%n, or \%a are allowed as place holder.}
  13689.               {the invalid format}
  13690. \errentry{10011}{place holder used too often in listing per-line prefix format}
  13691.               {fatal}
  13692.               {The place holders \%i and \%n each must not be used more than
  13693.                three times in the format string.  You're not satisfied with that?}
  13694.               {the format used more than once}
  13695. \end{description}
  13696.  
  13697. %%===========================================================================
  13698.  
  13699. \cleardoublepage
  13700. \chapter{I/O Error Messages}
  13701.  
  13702. The following error messages are generated not only by \asname{}, but also by
  13703. the auxiliary programs, like PLIST, BIND, P2HEX, and P2BIN. Only the most
  13704. probable error messages are here explained. Should you meet an undocumented
  13705. error message, then you probably met a program bug! Please inform us
  13706. immediately about this!!
  13707.  
  13708. \begin{description}
  13709. \item[2]{file not found\\
  13710.         The file requested does not exist, or it is stored on another
  13711.         drive.}
  13712. \item[3]{path not found\\
  13713.         The path of a file does not exist, or it is on another drive.}
  13714. \item[4]{too much open files\\
  13715.         There are no more file handles available to DOS. Increase
  13716.         their number changing the value associated to \tty{FILES=} in the file
  13717.         \tty{CONFIG.SYS}.}
  13718. \item[5]{file access not allowed\\
  13719.         Either the network access rights do not allow the file access, or
  13720.         an attempt was done to rewrite or rename a protected file.}
  13721. \item[6]{invalid file handler}
  13722. \item[12]{invalid access mode}
  13723. \item[15]{invalid drive letter\\
  13724.         The required drive does not exist.}
  13725. \item[16]{The file cannot be deleted}
  13726. \item[17]{RENAME cannot be done on this drive}
  13727. \item[100]{Unexpected end of file\\
  13728.         A file access tried to go beyond the end of file, although according
  13729.         to its structure this should not happen. The file is probably
  13730.         corrupted.}
  13731. \item[101]{disk full\\
  13732.         This is self explaining! Please, clean up !}
  13733. \item[102]{ASSIGN failed}
  13734. \item[103]{file not open}
  13735. \item[104]{file not open for reading}
  13736. \item[105]{file not open for writing}
  13737. \item[106]{invalid numerical format}
  13738. \item[150]{the disk is write-protected\\
  13739.         When you don't use a hard disk as work medium storage, you should
  13740.         sometimes remove the protecting tab from your diskette!}
  13741. \item[151]{unknown device\\
  13742.         you tried to access a peripheral unit that is unknown to DOS. This
  13743.         should not usually happen, since the name should be automatically
  13744.         interpreted as a filename.}
  13745. \item[152]{drive not ready\\
  13746.         close the disk drive door.}
  13747. \item[153]{unknown DOS function}
  13748. \item[154]{invalid disk checksum\\
  13749.         A bad read error on the disk. Try again; if nothing changes,
  13750.         reformat the floppy disk resp. begin to take care of your hard
  13751.         disk!}
  13752. \item[155]{invalid FCB}
  13753. \item[156]{position error\\
  13754.         the diskette/hard disk controller has not found a disk track. See
  13755.         nr. 154 !}
  13756. \item[157]{format unknown\\
  13757.         DOS cannot read the diskette format}
  13758. \item[158]{sector not found\\
  13759.         As nr. 156, but the controller this time could not find a disk
  13760.         sector in the track.}
  13761. \item[159]{end of paper\\
  13762.         You probably redirected the output of \asname{} to a printer. Assembler
  13763.         printout can be veeery long...}
  13764. \item[160]{device read error\\
  13765.         The operating system detected an unclassificable read error}
  13766. \item[161]{device write error\\
  13767.         The operating system detected an unclassificable write error}
  13768. \item[162]{general failure error\\
  13769.         The operating system has absolutely no idea of what happened to the
  13770.         device.}
  13771. \end{description}
  13772.  
  13773. %%===========================================================================
  13774.  
  13775. \cleardoublepage
  13776. \chapter{Programming Examples}
  13777.  
  13778. I often get questions about how to realize certain things. Some of those are
  13779. asked frequently, and it might be worth documenting the solutions in a 'Tips
  13780. and Tricks' corner.  This chapter is meant to collect and document them:
  13781.  
  13782. \section{16 Bit Instructions via Macros}
  13783.  
  13784. Many 8 bit processors can only process eight bits at once (as the name already
  13785. implies...).  They however often contain enough registers to concatenate
  13786. two of them to a virtual '16 bit accumulator'.  If we define macros to operate
  13787. on this virtual accumulator, they ideally should provide the same addressing
  13788. modes as the 8 bit instructions implemented by the hardware.  To achieve this,
  13789. macros somehow have to 'parse' their arguments.  How can this be accomplished?
  13790.  
  13791. As an example, the Motorola 6800 contains two accumulators named A an B.  It
  13792. is straightforward to treat them also as a 16 bit accumulator.  Addressing modes
  13793. should be the same as for 8 bit arithmetic instructions, namely:
  13794. \begin{itemize}
  13795. \item{immediate}
  13796. \item{direct (address within first 256 bytes)}
  13797. \item{extended (arbitrary address)}
  13798. \item{indexed}
  13799. \end{itemize}
  13800. Therefore, a macro implementing a virtual 16 bit instruction has to analyze
  13801. the one or two arguments passsed to it:
  13802. \begin{enumerate}
  13803. \item{Indexed addressing is the only mode using two arguments.}
  13804. \item{Immediate addressing is recognized by the leading hash character.}
  13805. \item{Checking whether an address is within the first 256 bytes or not
  13806.      may be left to the assembler.}
  13807. \end{enumerate}
  13808. The (single) argument has to be transformed into a string to perform step 2.
  13809. This string can then also be used to strip the leading hash character, to evaluate
  13810. the actual immediate value.  The complete macro looks like this:
  13811. \begin{verbatim}
  13812. subd    macro   ARG1,ARG2
  13813.  if      "ARG2" != ""            ; indexed?
  13814.   suba    (ARG1)+1,ARG2
  13815.   sbcb    ARG1,ARG2
  13816.  elseif                          ; not indexed?
  13817. _SARG1   set     "ARG1"           ; convert to string
  13818.  if      substr(_SARG1,0,1)='#' ; immediate?
  13819. _SARG1    set     substr(_SARG1,1,strlen(_SARG1)-1) ; y->del #
  13820.   suba    #lo(VAL(_SARG1))      ; ...and subtract lo/hi bytes
  13821.   sbcb    #hi(VAL(_SARG1))
  13822.  elseif                         ; no immediate->ext. or direct
  13823.   suba    (ARG1)+1              ; and subtract lo/hi bytes
  13824.   sbcb    ARG1
  13825.  endif
  13826.  endif
  13827.  endm
  13828. \end{verbatim}
  13829. Macro arguments have deliberately been written in all-uppercase.  This way,
  13830. the macro works both in case-sensitive and non-case-sensitive mode.  The
  13831. usage of the macro looks like this:
  13832. \begin{verbatim}
  13833.        subd    $0007                   ; direct
  13834.        subd    $1234                   ; absolute
  13835.        subd    #$55aa                  ; immediate
  13836.        subd    $12,x                   ; indexed
  13837. \end{verbatim}
  13838. Of course, we want to have more 16 bit operations than just subtraction.  One
  13839. could write a similar macro for every type of operation. However, there is a
  13840. more elegant method.  A macro may itself contain a macro definition.  So we
  13841. can define a sort of 'meta macro' which gets the instruction names as arguments:
  13842. \begin{verbatim}
  13843. def16   macro   NEWINST,LOINST,HIINST
  13844. NEWINST macro   ARG1,ARG2
  13845.  if      "ARG2" != ""            ; indexed?
  13846.   LOINST  (ARG1)+1,ARG2
  13847.   HIINST  ARG1,ARG2
  13848.  elseif                          ; not indexed?
  13849. _SARG1   set     "ARG1"                 ; convert to string
  13850.  if      substr(_SARG1,0,1)='#' ; immediate?
  13851. _SARG1    set     substr(_SARG1,1,strlen(_SARG1)-1) ; y->del #
  13852.   LOINST  #lo(VAL(_SARG1))      ; ...and subtract lo/hi bytes
  13853.   HIINST  #hi(VAL(_SARG1))
  13854.  elseif                         ; no immediate->ext. or direct
  13855.   LOINST  (ARG1)+1              ; ...and subtract lo/hi bytes
  13856.   HIINST  ARG1
  13857.  endif
  13858.  endif
  13859.  endm
  13860.  endm
  13861. \end{verbatim}
  13862. The remaining definitions now become one-liners:
  13863. \begin{verbatim}
  13864.        def16   addd,adda,adcb
  13865.        def16   subd,suba,sbcb
  13866.        def16   andd,anda,andb
  13867.        def16   ord,ora,orb
  13868.        def16   eord,eora,eorb
  13869. \end{verbatim}
  13870.  
  13871.  
  13872. %%===========================================================================
  13873.  
  13874. \cleardoublepage
  13875. \chapter{Frequently Asked Questions}
  13876.  
  13877. In this chapter, I tried to collect some questions that arise very often
  13878. together with their answers.  Answers to the problems presented in
  13879. this chapter might also be found at other places in this manual, but
  13880. one maybe does not find them immediately...
  13881.  
  13882. \begin{description}
  13883. \item[Q:]{I am fed up with DOS.  Are there versions of \asname{} for other
  13884.   operating systems ?}
  13885. \item[A:]{Apart from the protected mode version that offers more memory when
  13886.   working under DOS, ports exist for OS/2 and Unix systems like
  13887.   Linux (currently in test phase).  Versions that help operating
  13888.   system manufacturers located in Redmont to become even richer are
  13889.   currently not planned.  I will gladly make the sources of \asname{}
  13890.   available for someone else who wants to become active in this
  13891.   direction.  The C variant is probably the best way to start a
  13892.   port into this direction.  He should however not expect support
  13893.   from me that goes beyond the sources themselves...}
  13894. \vspace{0.3cm}
  13895. \item[Q:]{Is a support of the XYZ processor planned for \asname{}?}
  13896. \item[A:]{New processors are appearing all the time and I am trying to keep
  13897.   pace by extending \asname{}.  The stack on my desk labeled ''undone''
  13898.   however never goes below the 4 inch watermark... Wishes coming
  13899.   from users of course play an important role in the decision which
  13900.   candidates will be done first.  The internet and the rising amount
  13901.   of documentation published in electronic form make the acquisition
  13902.   of data books easier than it used to be, but it always becomes
  13903.   difficult when more exotic or older architectures are wanted.  If
  13904.   the processor family in question is not in the list of families
  13905.   that are planned (see chapter 1), adding a data book to a request
  13906.   will have a highly positive influence.  Borrowing books is also
  13907.   fine.}
  13908. \vspace{0.3cm}
  13909. \item[Q:]{Having a free assembler is really fine, but I now also had use for
  13910.   a disassembler...and a debugger...a simulator would also really be
  13911.   cool!}
  13912. \item[A:]{\asname{} is a project I work on in leisure time, the time I have when I
  13913.   do not have to care of how to make my living.  \asname{} already takes a
  13914.   significant portion of that time, and sometimes I make a time-out
  13915.   to use my soldering iron, enjoy a Tangerine Dream CD, watch TV, or
  13916.   simply to fulfill some basic human needs... I once started to
  13917.   write the concept of a disassembler that was designed to create
  13918.   source code that can be assembled and that automatically
  13919.   separates code and data areas.  I quickly stopped this project
  13920.   again when I realized that the remaining time simply did not
  13921.   suffice.  I prefer to work on one good program than to struggle for
  13922.   half a dozen of mediocre apps.  Regarded that way, the answer to
  13923.   the question is unfortunately ''no''...}
  13924. \vspace{0.3cm}
  13925. \item[Q:]{The screen output of \asname{} is messed up with strange characters, e.g.
  13926.   arrows and brackets.  Why?}
  13927. \item[A:]{\asname{} will by default use some ANSI control sequences for screen
  13928.   control.  These sequences will appear unfiltered on your screen
  13929.   if you did not install an ANSI driver.  Either install an ANSI
  13930.   driver or use the DOS command \tty{SET USEANSI=N} to turn the
  13931.   sequences off.}
  13932. \vspace{0.3cm}
  13933. \item[Q:]{\asname{} suddenly terminates with a stack overflow error while
  13934.   assembling my program.  Did my program become to large?}
  13935. \item[A:]{Yes and No.  Your program's symbol table has grown a bit
  13936.   unsymmetrically what lead to high recursion depths while accessing
  13937.   the table.  Errors of this type especially happen in the
  13938.   16-bit-OS/2 version of \asname{} which has a very limited stack area.
  13939.   Restart \asname{} with the \tty{-A} command line switch.  If this does not
  13940.   help, too complex formula expression are also a possible cause of
  13941.   stack overflows.  In such a case, try to split the formula into
  13942.   intermediate steps.}
  13943. \vspace{0.3cm}
  13944. \item[Q:]{It seems that \asname{} does not assemble my program up to the end.  It
  13945.   worked however with an older version of \asname{} (1.39).}
  13946. \item[A:]{Newer versions of \asname{} no longer ignore the \tty{END} statement; they
  13947.   actually terminate assembly when an \tty{END} is encountered.
  13948.   Especially older include files made by some users tended to
  13949.   contain an \tty{END} statement at their end.  Simply remove the
  13950.   superfluous \tty{END} statements.}
  13951. \vspace{0.3cm}
  13952. \item[Q:]{I made an assembly listing of my program because I had some more
  13953.   complicated assembly errors in my program.  Upon closer
  13954.   investigation of the listing, I found that some branches do not
  13955.   point to the desired target but instead to themselves!}
  13956. \item[A:]{This effect happens in case of forward jumps in the first pass.
  13957.   The formula parser does not yet have the target address in its symbol
  13958.   table, and as it is a completely independent module, it has to think of
  13959.   a value that even does not hurt relative branches with short displacement
  13960.   lengths.  This is the current program counter itself...in the
  13961.   second pass, the correct values would have appeared, but the second
  13962.   pass did not happen due to errors in the first one.  Correct the
  13963.   other errors first so that \asname{} gets into the second pass, and the
  13964.   listing should look more meaningful again.}
  13965. \vspace{0.3cm}
  13966. \item[Q:]{Assembly of my program works perfectly, however I get an empty
  13967.   file when I try to convert it with P2HEX or P2BIN.}
  13968. \item[A:]{You probably did not set the address filter correctly.  By
  13969.   default, the filter is disabled, i.e. all data is copied to the
  13970.   HEX or binary file.  It is however possible to create an empty file
  13971.   if a manually set range does not fit to the addresses used by your
  13972.   program.}
  13973. \vspace{0.3cm}
  13974. \item[Q:]{I cannot enter the dollar character when using P2BIN or P2HEX
  13975.   under Unix.  The automatic address range setting does not work, instead
  13976.   I get strange error messages.}
  13977. \item[A:]{Unix shells use the dollar character for expansion of shell
  13978.   variables.  If you want to pass a dollar character to an application,
  13979.   prefix it with a backslash (\verb!\!).  In the special case of the
  13980.   address range specification for P2HEX and P2BIN, you may also use
  13981.   \tty{0x} instead of the dollar character, which removes this prblen
  13982.   completely.}
  13983. \item[Q:]{I use \asname{} on a Linux system, the loader program for my target
  13984.          system however runs on a Windows machine. To simplify things,
  13985.          both systems access the same network drive.  Unfortunately, the
  13986.          Windows side refuses to read the hex files created by the Linux
  13987.          side :-(}
  13988. \item[A:]{Windows and Linux systems use slightly different formats for
  13989.          text files (hex files are a sort of text files).  Windows
  13990.          terminates every line with the characters CR (carriage return)
  13991.          and LF (linefeed), however Linux only uses the linefeed.  It
  13992.          depends on the Windows program's 'goodwill' whether it will
  13993.          accept text files in the Linux format or not.  If not, it is
  13994.          possible to transfer the files via FTP in ASCII mode instead
  13995.          of a network drive.  Alternatively, the hex files can be
  13996.          converted to the Windows format.  For example, the program
  13997.          {\em unix2dos} can be used to do this, or a small script under
  13998.          Linux:
  13999.          \begin{verbatim}
  14000.          awk '{print $0"\r"}' test.hex >test_cr.hex
  14001.          \end{verbatim}}
  14002. \item[Q:]{I have a 16 bit address in my program and have to load its
  14003.          upper and lower half into separate CUP registers. How do I
  14004.          extract the byte halves? Other assemblers have built-in
  14005.          functions to accomodate this.}
  14006. \item[A:]{This can be done ''by hand'' with the built-in logical and
  14007.          shift operators.  However, there is also a file {\tt bitfuncs.inc}
  14008.          that defines the functions {\tt lo()} respectively {\tt hi()}.}
  14009. \end{description}
  14010.  
  14011. %%===========================================================================
  14012.  
  14013. \cleardoublepage
  14014. \chapter{Pseudo-Instructions and Integer Syntax}
  14015. \label{SectPseudoInst}
  14016.  
  14017. This appendix is designed as a quick reference to look up all pseudo
  14018. instructions provided by \asname{}.  The list is ordered in two parts: The
  14019. first part lists the instructions that are always available, and this
  14020. list is followed by lists that enumerate the instructions
  14021. additionally available for a certain processor family.
  14022.  
  14023. \subsubsection{Instructions that are always available}
  14024. \input{../doc_COM/pscomm.tex}
  14025. Additionally, there are:
  14026. \begin{itemize}
  14027. \item{\tty{SET} as an alias to \tty{EVAL}, unless \tty{SET} is already a machine
  14028.      instruction.}
  14029. \item{\tty{SHIFT} resp. \tty{SHFT}, in case \tty{SHIFT} is already a machine
  14030.      instruction.}
  14031. \item{\tty{RESTORE} as an alias to \tty{RESTOREENV}, unless \tty{RESTORE} is already a machine
  14032.      instruction.}
  14033. \item{\tty{SAVE} as an alias to \tty{SAVEENV}, unless \tty{SAVE} is already a machine
  14034.      instruction.}
  14035. \item{\tty{PAGE} resp. \tty{PAGESIZE}, in case \tty{PAGE} is already a machine
  14036.      instruction.}
  14037. \item{\tty{SWITCH} resp. \tty{SELECT}, in case \tty{SWITCH} is already a machine
  14038.      instruction.}
  14039. \end{itemize}
  14040.  
  14041. \input{../doc_COM/pscpu.tex}
  14042.  
  14043. %%===========================================================================
  14044.  
  14045. \cleardoublepage
  14046. \chapter{Predefined Symbols}
  14047. \label{AppInternSyms}
  14048.  
  14049. \begin{center}\begin{longtable}{|l|l|l|l|}
  14050. \hline
  14051. Name          & Data Type & Definition & Meaning \\
  14052. \hline
  14053. \hline
  14054. \endhead
  14055. ARCHITECTURE  & string    & predef.    & target platform \asname{} was \\
  14056.              &           &            & compiled for, in the style \\
  14057.              &           &            & processor-manufacturer- \\
  14058.              &           &            & operating system \\
  14059. BIGENDIAN     & boolean   & dyn.(0)    & storage of constants MSB \\
  14060.              &           &            & first? \\
  14061. CASESENSITIVE & boolean   & normal     & case sensitivity in symbol \\
  14062.              &           &            & names? \\
  14063. CONSTPI       & float     & normal     & constant Pi (3.1415.....) \\
  14064. DATE          & string    & predef.    & date of begin of assembly \\
  14065. FALSE         & boolean   & predef.    & 0 = logically ''false'' \\
  14066. HASFPU        & boolean   & dyn.(0)    & coprocessor instructions \\
  14067.              &           &            & enabled? \\
  14068. HASPMMU       & boolean   & dyn.(0)    & MMU instructions \\
  14069.              &           &            & enabled? \\
  14070. INEXTMODE     & boolean   & dyn.(0)    & XM flag set for 4 Gbyte \\
  14071.              &           &            & address space? \\
  14072. INLWORDMODE   & boolean   & dyn.(0)    & LW flag set for 32 bit \\
  14073.              &           &            & instructions? \\
  14074. INMAXMODE     & boolean   & dyn.(0)    & processor in maximum \\
  14075.              &           &            & mode? \\
  14076. INSUPMODE     & boolean   & dyn.(0)    & processor in supervisor \\
  14077.              &           &            & mode? \\
  14078. INSRCMODE     & boolean   & dyn.(0)    & processor in source mode? \\
  14079. FULLPMMU      & boolean   & dyn.(0/1)  & full PMMU instruction set \\
  14080.              &           &            & allowed? \\
  14081. LISTON        & boolean   & dyn.(1)    & listing enabled? \\
  14082. MACEXP        & boolean   & dyn.(1)    & expansion of macro con- \\
  14083.              &           &            & structs in listing enabled? \\
  14084. MOMCPU        & integer   & dyn.       & number of target CPU \\
  14085.               &           & (68008)    & currently set \\
  14086. MOMCPUNAME    & string    & dyn.       & name of target CPU \\
  14087.              &           & (68008)    & currently set \\
  14088. MOMFILE       & string    & special    & current source file \\
  14089.              &           &            & (including include files) \\
  14090. MOMLINE       & integer   & special    & current line number in  \\
  14091.              &           &            & source file \\
  14092. MOMPASS       & integer   & special    & number of current pass \\
  14093. MOMSECTION    & string    & special    & name of current section or \\
  14094.               &           &            & empty string if out of any \\
  14095.              &           &            & section \\
  14096. MOMSEGMENT    & string    & special    & name of address space \\
  14097.              &           &            & currently selected \\
  14098.              &           &            & with \tty{SEGMENT} \\
  14099. NESTMAX       &  Integer  & dyn.(256)  & maximum nesting level \\
  14100.              &           &            & of macro expansions \\
  14101. PADDING       & Boolean   & dyn.(1)    & pad byte field to even \\
  14102.              &           &            & count? \\
  14103. RELAXED       & Boolean   & dyn.(0)    & any syntax allowed integer \\
  14104.              &           &            & constants? \\
  14105. PC            & Integer   & special    & current program counter \\
  14106.              &           &            & (Thomson) \\
  14107. TIME          & String    & predef.    & time of begin of assembly \\
  14108.              &           &            & (1st pass) \\
  14109. TRUE          & Integer   & predef.    & 1 = logically ''true'' \\
  14110. VERSION       & Integer   & predef.    & version of \asname{} in BCD \\
  14111.               &           &            & coding, e.g. 1331 hex for \\
  14112.              &           &            & version 1.33p1 \\
  14113. WRAPMODE      & Integer   & predef.    & shortened program \\
  14114.              &           &            & counter assumed? \\
  14115. \verb!*!      & Integer   & special    & current program counter \\
  14116.              &           &            & (Motorola, Rockwell, \\
  14117.              &           &            & Microchip, Hitachi) \\
  14118. .             & Integer   & special    & curr. program counter \\
  14119.              &           &            & (IM61x0) \\
  14120. \$            & Integer   & special    & current program counter \\
  14121.              &           &            & Intel, Zilog, Texas, \\
  14122.              &           &            & Toshiba, NEC, Siemens, \\
  14123.              &           &            & AMD) \\
  14124. \hline
  14125. \end{longtable}\end{center}
  14126.  
  14127. To be exact, boolean symbols are just ordinary integer symbols with the
  14128. difference that \asname{} will assign only two different values to them (0 or 1,
  14129. corresponding to False or True).  \asname{} does not store special symbols
  14130. in the symbol table.  For performance reasons, they are realized with
  14131. hardcoded comparisons directly in the parser.  They therefore do not
  14132. show up in the assembly listing's symbol table.  Predefined symbols
  14133. are only set once at the beginning of a pass.  The values of dynamic
  14134. symbols may in contrast change during assembly as they reflect
  14135. settings made with related pseudo instructions.  The values added in
  14136. parentheses give the value present at the beginning of a pass.
  14137.  
  14138. The names given in this table also reflect the valid way to reference
  14139. these symbols in case-sensitive mode.
  14140.  
  14141. The names listed here should be avoided for own symbols; either one
  14142. can define but not access them (special symbols), or one will receive
  14143. an error message due to a double-defined symbol.  The ugliest case is
  14144. when the redefinition of a symbol made by \asname{} at the beginning of a
  14145. pass leads to a phase error and an infinite loop...
  14146.  
  14147. %%===========================================================================
  14148.  
  14149. \cleardoublepage
  14150. \chapter{Shipped Include Files}
  14151.  
  14152. The distribution of \asname{} contains a couple of include files.  Apart from
  14153. include files that only refer to a specific processor family (and whose
  14154. function should be immediately clear to someone who works with this
  14155. family), there are a few processor-independent files which include useful
  14156. functions.  The functions defined in these files shall be explained
  14157. briefly in the following sections:
  14158.  
  14159. \section{BITFUNCS.INC}
  14160.  
  14161. This file defines a couple of bit-oriented functions that might be
  14162. hardwired for other assemblers.  In the case of \asname{} however, thaey are
  14163. implemented with the help of user-defined functions:
  14164.  
  14165. \begin{itemize}
  14166. \item{{\em mask(start,bits)} returns an integer with {\em bits} bits set
  14167.      starting at position {\em start};}
  14168. \item{{\em invmask(start,bits)} returns one's complement to {\em
  14169.      mask()};}
  14170. \item{{\em cutout(x,start,bits)} returns {\em bits} bits masked out from
  14171.      {\em x} starting at position {\em start} without shifting them to
  14172.      position 0;}
  14173. \item{{\em hi(x)} returns the second lowest byte (bits 8..15) of {\em
  14174.      x};}
  14175. \item{{\em lo(x)} returns the lowest byte (bits 8..15) of {\em x};}
  14176. \item{{\em hiword(x)} returns the second lowest word (bits 16..31) of
  14177.      {\em x};}
  14178. \item{{\em loword(x)} returns the lowest word (bits 0..15) of {\em x};}
  14179. \item{{\em odd(x)} returns TRUE if {\em x} is odd;}
  14180. \item{{\em even(x)} returns TRUE if {\em x} is even;}
  14181. \item{{\em getbit(x,n)} extracts bit {\em n} out of {\em x} and returns
  14182.      it as 0 or 1;}
  14183. \item{{\em shln(x,size,n)} shifts a word {\em x} of length {\em size} to
  14184.      the left by {\em n} places;}
  14185. \item{{\em shrn(x,size,n)} shifts a word {\em x} of length {\em size} to
  14186.      the right by {\em n} places;}
  14187. \item{{\em rotln(x,size,n)} rotates the lowest {\em size} bits of an
  14188.      integer {\em x} to the left by {\em n} places;}
  14189. \item{{\em rotrn(x,size,n)} rotates the lowest {\em size} bits of an
  14190.      integer {\em x} to the right by {\em n} places;}
  14191. \end{itemize}
  14192.  
  14193. \section{CTYPE.INC}
  14194.  
  14195. This include file is similar to the C include file {\tt ctype.h} which
  14196. offers functions to classify characters.  All functions deliver either
  14197. TRUE or FALSE:
  14198.  
  14199. \begin{itemize}
  14200. \item{{\em isdigit(ch)} becomes TRUE if {\em ch} is a valid decimal
  14201.      digit (0..9);}
  14202. \item{{\em isxdigit(ch)} becomes TRUE if {\em ch} is a valid hexadecimal
  14203.      digit (0..9, A..F, a..f);}
  14204. \item{{\em isupper(ch)} becomes TRUE if {\em ch} is an uppercase
  14205.      letter, excluding special national characters);}
  14206. \item{{\em islower(ch)} becomes TRUE if {\em ch} is a lowercase
  14207.      letter, excluding special national characters);}
  14208. \item{{\em isalpha(ch)} becomes TRUE if {\em ch} is a letter, excluding
  14209.      special national characters);}
  14210. \item{{\em isalnum(ch)} becomes TRUE if {\em ch} is either a letter or
  14211.      a valid decimal digit;}
  14212. \item{{\em isspace(ch)} becomes TRUE if {\em ch} is an 'empty' character
  14213.      (space, form feed, line feed, carriage return, tabulator);}
  14214. \item{{\em isprint(ch)} becomes TRUE if {\em ch} is a printable character,
  14215.      i.e. no control character up to code 31;}
  14216. \item{{\em iscntrl(ch)} is the opposite to {\em isprint()};}
  14217. \item{{\em isgraph(ch)} becomes TRUE if {\em ch} is a printable and
  14218.      visible character;}
  14219. \item{{\em ispunct(ch)} becomes TRUE if {\em ch} is a printable special
  14220.      character (i.e. neither space nor letter nor number);}
  14221. \end{itemize}
  14222.  
  14223. %%===========================================================================
  14224.  
  14225. \cleardoublepage
  14226. \chapter{Acknowledgments}
  14227.  
  14228. \begin{quote}\it
  14229. ''If I have seen farther than other men, \\
  14230. it is because I stood on the shoulders of giants.'' \\
  14231. \hspace{2cm} --Sir Isaac Newton
  14232. \rm\end{quote}
  14233. \begin{quote}\it
  14234. ''If I haven't seen farther than other men, \\
  14235. it is because I stood in the footsteps of giants.'' \\
  14236. \hspace{2cm} --unknown
  14237. \rm\end{quote}
  14238. \par
  14239. There is a commaon saying that programs you write are like children
  14240. you put into the world.  It is now more than 30 years that I have been
  14241. working on this assembler, and I have come to the conclusion that such
  14242. a project is rather a journey for its author.  The people you meet
  14243. and learn to know on this journey are at least as important as the perceived
  14244. target itself.  Your learn a lot on this trip and in the best case, one
  14245. also understands that things can also be seen from a completely different
  14246. perspective.  If the discussions are fruitful, it is a win for both sides.
  14247. \par
  14248. While making this journey, some people have kept a special place in my
  14249. memories, because of the way they contributed to this project and to the
  14250. state it has now achieved.  The following enumeration of these people is
  14251. naturally incomplete, since my memories are not any more as good as they used
  14252. to be.  So the first 'thank you' goes to all the people I (accidentally)
  14253. omit in the following paragraphs.  The journey goes on, and maybe our
  14254. ways will be crossing again!
  14255. \par
  14256. The concept of \asname{} as a universal cross assembler came from Bernhard
  14257. (C.) Zschocke who needed a ''student friendly'', i.e. free cross
  14258. assembler for his microprocessor course and talked me into extending
  14259. an already existing 68000 assembler.  The rest is history...
  14260. The microprocessor course held at RWTH Aachen also always provided the
  14261. most engaged users (and bug-searchers) of new \asname{} features and
  14262. therefore contributed a lot to today's quality of \asname{}.
  14263.  
  14264. The Internet and FTP have proved to be a big help for spreading \asname{} and
  14265. reporting of bugs.  My thanks therefore go to the FTP admins (Bernd
  14266. Casimir in Stuttgart, Norbert Breidor in Aachen, and J\"urgen Mei\ss\-burger
  14267. in J\"ulich).  Especially the last one personally engaged a lot to
  14268. establish a practicable way in J\"ulich.
  14269.  
  14270. As we are just talking about the ZAM: Though Wolfgang E. Nagel never
  14271. involved personally into \asname{}, he however was my tutor and
  14272. boss.  He always had at least four eyes on what I was doing.
  14273. Regarding \asname{}, there seemed to be at least one that smiled...
  14274.  
  14275. A program like \asname{} cannot be done without appropriate data books and
  14276. documentation.  I received information from an enormous amount of
  14277. people, ranging from tips up to complete data books.  An enumeration
  14278. follows (as stated before, this is very probably incomplete!):
  14279.  
  14280. Ernst Ahlers, Charles Altmann, Marco Awater, Len Bayles,
  14281. Andreas Bolsch, Rolf Buchholz, Bernd Casimir, Nils Eilers,
  14282. Gunther Ewald, Michael Haardt, Stephan Hruschka,  Fred van Kempen,
  14283. Peter Kliegelh\"ofer, Ulf Meinke, Udo M\"oller, Matthias Paul,
  14284. Norbert Rosch, Curt J. Sampson, Steffen Schmid, Leonhard Schneider,
  14285. Ernst Schwab, Michael Schwingen, Oliver Sellke, Christian Stelter,
  14286. Patrik Str\"omdahl, Tadashi G. Takaoka, Oliver Thamm, Thorsten Thiele,
  14287. Leszek Ulman, Rob Warmelink, Andreas Wassatsch, John Weinrich.
  14288.  
  14289. ...and a somewhat ironic ''thank you'' to Rolf-Dieter-Klein and Tobias
  14290. Thiel, who gave me the initial impulse with their ASM68K.  Several things
  14291. did not work the way I wanted them to have, so I thought I could do
  14292. better or at least different.
  14293.  
  14294. And of course, I did not entirely write \asname{} on my own.  The DOS
  14295. version of \asname{} contained the OverXMS routines from Wilbert van
  14296. Leijen which can move the overlay modules into the extended memory.
  14297. A really nice library, easy to use without problems!
  14298.  
  14299. The TMS320C2x/5x code generators and the file \tty{STDDEF2x.INC} come
  14300. from Thomas Sailer, ETH Zurich.  It's surprising, he only needed one
  14301. weekend to understand my coding and to implement the new code
  14302. generator.  Either that was a long nightshift or I am slowly getting
  14303. old...the same praise goes to Haruo Asano for providing the
  14304. MN1610/MN1613, IM6100, CP1600, Renesas RX and HP NanoProcessor code
  14305. generators.
  14306.  
  14307. %%===========================================================================
  14308.  
  14309. \cleardoublepage
  14310. \chapter{Changes since Version 1.3}
  14311.  
  14312. \begin{itemize}
  14313. \item{version 1.31:
  14314.      \begin{itemize}
  14315.      \item{additional MCS-51 processor type 80515.  The number
  14316.            is again only stored by the assembler.  The file
  14317.            \tty{STDDEF51.INC} was extended by the necessary SFRs.
  14318.            \bb{CAUTION!} Some of the 80515 SFRs have moved to other
  14319.            addresses!}
  14320.      \item{additional support for the Z80 processor;}
  14321.      \item{faster 680x0 code generator.}
  14322.      \end{itemize}}
  14323. \item{version 1.32:
  14324.      \begin{itemize}
  14325.      \item{syntax for zero page addresses for the 65xx family
  14326.            was changed from \tty{addr.z} to \tty{$<$addr} (similar to 68xx);}
  14327.      \item{additional support for the 6800, 6805, 6301, and
  14328.            6811 processors;}
  14329.      \item{the 8051 part now also understands \tty{DJNZ, PUSH}, and
  14330.            \tty{POP} (sorry);}
  14331.      \item{the assembly listing now not also list the symbols
  14332.            but also the macros that have been defined;}
  14333.      \item{additional instructions \tty{IFDEF/IFNDEF} for conditional
  14334.            assembly based on the existence of a symbol;}
  14335.      \item{additional instructions \tty{PHASE/DEPHASE} to support code
  14336.            that shall be moved at runtime to a different address;}
  14337.      \item{additional instructions \tty{WARNING, ERROR}, and \tty{FATAL} to print
  14338.            user-defined error messages;}
  14339.      \item{the file \tty{STDDEF51.INC} additionally contains the macro
  14340.            \tty{USING} to simplify working with the MCS-51's register
  14341.            banks;}
  14342.      \item{command line option \tty{u} to print segment usage;}
  14343.      \end{itemize}}
  14344. \item{version 1.33:
  14345.      \begin{itemize}
  14346.      \item{additionally supports the 6809 processor;}
  14347.      \item{added string variables;}
  14348.      \item{The instructions \tty{TITLE, PRTINIT, PRTEXIT, ERROR},
  14349.            \tty{WARNING}, and \tty{FATAL} now expect a string expression.
  14350.            Constants therefore now have to be enclosed in
  14351.            '' instead of ' characters.  This is also true
  14352.            for \tty{DB}, \tty{DC.B}, and \tty{BYT};}
  14353.      \item{additional instruction \tty{ALIGN} to align the program
  14354.            counter for Intel processors;}
  14355.      \item{additional instruction \tty{LISTING} to turn the generation
  14356.            of an assembly listing on or off;}
  14357.      \item{additional instruction \tty{CHARSET} for user-defined
  14358.            character sets.}
  14359.      \end{itemize}}
  14360. \item{version 1.34:
  14361.      \begin{itemize}
  14362.      \item{the second pass is now omitted if there were errors
  14363.            in the first pass;}
  14364.      \item{additional predefined symbol \tty{VERSION} that contains
  14365.            the version number of \asname{};}
  14366.      \item{additional instruction \tty{MESSAGE} to generate additional
  14367.            messages under program control;}
  14368.      \item{formula parser is now accessible via string constants;}
  14369.      \item{if an error in a macro occurs, additionally the line
  14370.            number in the macro itself is shown;}
  14371.      \item{additional function \tty{UPSTRING} to convert a string to
  14372.            all upper-case.}
  14373.      \end{itemize}}
  14374. \item{version 1.35:
  14375.      \begin{itemize}
  14376.      \item{additional function \tty{TOUPPER} to convert a single
  14377.            character to upper case;}
  14378.      \item{additional instruction \tty{FUNCTION} for user-defined
  14379.            functions;}
  14380.      \item{additional command line option \tty{D} to define symbols
  14381.            from outside;}
  14382.      \item{the environment variable \tty{ASCMD} for commonly used
  14383.            command line options was introduced;}
  14384.      \item{the program will additionally be checked for double
  14385.            usage of memory areas if the u option is enabled;}
  14386.      \item{additional command line option \tty{C} to generate a cross
  14387.            reference list.}
  14388.      \end{itemize}}
  14389. \item{version 1.36:
  14390.      \begin{itemize}
  14391.      \item{additionally supports the PIC16C5x and PIC17C4x
  14392.            processor families;}
  14393.      \item{the assembly listing additionally shows the nesting
  14394.            depth of include files;}
  14395.      \item{the cross reference list additionally shows the
  14396.            definition point of a symbol;}
  14397.      \item{additional command line option \tty{A} to force a more
  14398.            compact layout of the symbol table.}
  14399.      \end{itemize}}
  14400. \item{version 1.37:
  14401.      \begin{itemize}
  14402.      \item{additionally supports the processors 8086, 80186,
  14403.            V30, V35, 8087, and Z180;}
  14404.      \item{additional instructions \tty{SAVE} and \tty{RESTORE} for an
  14405.            easier switching of some flags;}
  14406.      \item{additional operators for logical shifts and bit
  14407.            mirroring;}
  14408.      \item{command line options may now be negated with a
  14409.            plus sign;}
  14410.      \item{additional filter AS2MSG for a more comfortable
  14411.            work with \asname{} under Turbo-Pascal 7.0;}
  14412.      \item{\tty{ELSEIF} now may have an argument for construction
  14413.            of \tty{IF\--THEN\--ELSE} ladders;}
  14414.      \item{additional \tty{CASE} construct for a more comfortable
  14415.            conditional assembly;}
  14416.      \item{user-defined functions now may have more than one
  14417.            argument;}
  14418.      \item{P2HEX can now additionally generate hex files in
  14419.            a format suitable for 65xx processors;}
  14420.      \item{BIND, P2HEX, and P2BIN now have the same scheme
  14421.            for command line processing like \asname{};}
  14422.      \item{additional switch \tty{i} for P2HEX to select one out
  14423.            three possibilities for the termination record;}
  14424.      \item{additional functions \tty{ABS} and \tty{SGN};}
  14425.      \item{additional predefined symbols \tty{MOMFILE} and \tty{MOMLINE};}
  14426.      \item{additional option to print extended error messages;}
  14427.      \item{additional instruction \tty{IFUSED} and \tty{IFNUSED} to check
  14428.            whether a symbol has been used so far;}
  14429.      \item{The environment variables \tty{ASCMD, BINDCMD} etc. now
  14430.            optionally may contain the name of a file that
  14431.            provides more space for options;}
  14432.      \item{P2HEX can now generate the hex formats specified
  14433.            by Microchip (p4);}
  14434.      \item{a page length specification of 0 now allows to
  14435.            suppress automatic formfeeds in the assembly listing
  14436.            completely (p4);}
  14437.      \item{symbols defined in the command line now may be
  14438.            assigned an arbitrary value (p5).}
  14439.      \end{itemize}}
  14440. \item{version 1.38:
  14441.      \begin{itemize}
  14442.      \item{changed operation to multipass mode.  This enables
  14443.            \asname{} to generate optimal code even in case of forward
  14444.            references;}
  14445.      \item{the 8051 part now also knows the generic \tty{JMP} and
  14446.            \tty{CALL} instructions;}
  14447.      \item{additionally supports the Toshiba TLCS-900 series
  14448.            (p1);}
  14449.      \item{additional instruction \tty{ASSUME} to inform the assembler
  14450.            about the 8086's segment register contents (p2);}
  14451.      \item{additionally supports the ST6 series from
  14452.            SGS-Thomson (p2);}
  14453.      \item{..and the 3201x signal processors from Texas
  14454.            Instruments (p2);}
  14455.      \item{additional option \tty{F} for P2HEX to override the
  14456.            automatic format selection (p2);}
  14457.      \item{P2BIN now can automatically set the start resp.
  14458.            stop address of the address window by specifying
  14459.            dollar signs (p2);}
  14460.      \item{the 8048 code generator now also knows the 8041/42
  14461.            instruction extensions (p2);}
  14462.      \item{additionally supports the Z8 microcontrollers (p3).}
  14463.      \end{itemize}}
  14464. \item{version 1.39:
  14465.      \begin{itemize}
  14466.      \item{additional opportunity to define sections and local
  14467.            symbols;}
  14468.      \item{additional command line switch \tty{h} to force hexadecimal
  14469.            numbers to use lowercase;}
  14470.      \item{additional predefined symbol \tty{MOMPASS} to read the
  14471.            number of the currently running pass;}
  14472.      \item{additional command line switch \tty{t} to disable
  14473.            individual parts of the assembly listing;}
  14474.      \item{additionally knows the L variant of the TLCS-900
  14475.            series and the MELPS-7700 series from Mitsubishi
  14476.            (p1);}
  14477.      \item{P2HEX now also accepts dollar signs as start resp.
  14478.            stop address (p2);}
  14479.      \item{additionally supports the TLCS-90 family from
  14480.            Toshiba (p2);}
  14481.      \item{P2HEX now also can output data in Tektronix and
  14482.            16 bit Intel Hex format (p2);}
  14483.      \item{P2HEX now prints warnings for address overflows
  14484.            (p2);}
  14485.      \item{additional include file \tty{STDDEF96.INC} with address
  14486.            definitions for the TLCS-900 series (p3);}
  14487.      \item{additional instruction \tty{READ} to allow interactive
  14488.            input of values during assembly (p3);}
  14489.      \item{error messages are written to the STDERR channel
  14490.            instead of standard output (p3);}
  14491.      \item{the \tty{STOP} instruction missing for the 6811 is now
  14492.            available (scusi, p3);}
  14493.      \item{additionally supports the $\mu$PD78(C)1x family from
  14494.            NEC (p3);}
  14495.      \item{additionally supports the PIC16C84 from NEC (p3);}
  14496.      \item{additional command line switch \tty{E} to redirect error
  14497.            messages to a file (p3);}
  14498.      \item{The MELPS-7700's 'idol' 65816 is now also available
  14499.            (p4);}
  14500.      \item{the ST6 pseudo instruction \tty{ROMWIN} has been removed
  14501.            was integrated into the \tty{ASSUME} instruction (p4);}
  14502.      \item{additionally supports the 6804 from SGS-Thomson (p4);}
  14503.      \item{via the \tty{NOEXPORT} option in a macro definition, it is
  14504.            now possible to define individually for every macro
  14505.            whether it shall appear in the \tty{MAC} file or not (p4);}
  14506.      \item{the meaning of \tty{MACEXP} regarding the expansion of
  14507.            macros has changed slightly due to the additional
  14508.            \tty{NOEXPAND} option in the macro definition (p4);}
  14509.      \item{The additional \tty{GLOBAL} option in the macro definition
  14510.            now additionally allows to define macros that are
  14511.            uniquely identified by their section name (p4).}
  14512.      \end{itemize}}
  14513. \item{version 1.40:
  14514.      \begin{itemize}
  14515.      \item{additionally supports the DSP56000 from Motorola;}
  14516.      \item{P2BIN can now also extract the lower resp. upper
  14517.            half of a 32-bit word;}
  14518.      \item{additionally supports the TLCS-870 and TLCS-47
  14519.            families from Toshiba (p1);}
  14520.      \item{a prefixed \tty{!} now allows to reach machine instructions
  14521.            hidden by a macro (p1);}
  14522.      \item{the \tty{GLOBAL} instruction now allows to export symbols
  14523.            in a qualified style (p1);}
  14524.      \item{the additional \tty{r} command line switch now allows to
  14525.            print a list of constructs that forced additional
  14526.            passes (p1);}
  14527.      \item{it is now possible to omit an argument to the \tty{E}
  14528.            command line option; \asname{} will then choose a fitting
  14529.            default (p1);}
  14530.      \item{the \tty{t} command line option now allows to suppress
  14531.            line numbering in the assembly listing (p1);}
  14532.      \item{escape sequences may now also be used in ASCII style
  14533.            integer constants (p1);}
  14534.      \item{the additional pseudo instruction \tty{PADDING} now allows
  14535.            to enable or disable the insertion of padding bytes
  14536.            in 680x0 mode (p2);}
  14537.      \item{\tty{ALIGN} is now a valid instruction for all targets
  14538.            (p2);}
  14539.      \item{additionally knows the PIC16C64's SFRs (p2);}
  14540.      \item{additionally supports the 8096 from Intel (p2);}
  14541.      \item{\tty{DC} additionally allows to specify a repetition factor
  14542.            (r3);}
  14543.      \item{additionally supports the TMS320C2x family from Texas
  14544.            Instruments (implementation done by Thomas Sailer, ETH
  14545.            Zurich, r3); P2HEX has been extended appropriately;}
  14546.      \item{an equation sign may be used instead of \tty{EQU} (r3);}
  14547.      \item{additional \tty{ENUM} instruction to define enumerations
  14548.            (r3);}
  14549.      \item{\tty{END} now has a real effect (r3);}
  14550.      \item{additional command line switch \tty{n} to get the internal
  14551.            error numbers in addition to the error messages (r3);}
  14552.      \item{additionally supports the TLCS-9000 series from
  14553.            Toshiba (r4);}
  14554.      \item{additionally supports the TMS370xxx series from Texas
  14555.            Instruments, including a new \tty{DBIT} pseudo instruction
  14556.            (r5);}
  14557.      \item{additionally knows the DS80C320's SFR's (r5);}
  14558.      \item{the macro processor is now also able to include files
  14559.            from within macros.  This required to modify the
  14560.            format of error messages slightly.  If you use
  14561.            AS2MSG, replace it with the new version! (r5)}
  14562.      \item{additionally supports the 80C166 from Siemens (r5);}
  14563.      \item{additional \tty{VAL} function to evaluate string
  14564.            expressions (r5);}
  14565.      \item{it is now possible to construct symbol names with the
  14566.            help of string expressions enclosed in braces (r5);}
  14567.      \item{additionally knows the 80C167's peculiarities (r6);}
  14568.      \item{the MELPS740's special page addressing mode is now
  14569.            supported (r6);}
  14570.      \item{it is now possible to explicitly reference a symbol
  14571.            from a certain section by appending its name enclosed
  14572.            in brackets.  The construction with an \tty{@} sign has
  14573.            been removed! (r6)}
  14574.      \item{additionally supports the MELPS-4500 series from
  14575.            Mitsubishi (r7);}
  14576.      \item{additionally supports H8/300 and H8/300H series from
  14577.            Hitachi (r7);}
  14578.      \item{settings made with \tty{LISTING} resp. \tty{MACEXP} may now be
  14579.            read back from predefined symbols with the same names
  14580.            (r7);}
  14581.      \item{additionally supports the TMS320C3x series from Texas
  14582.            Instruments (r8);}
  14583.      \item{additionally supports the SH7000 from Hitachi (r8);}
  14584.      \item{the Z80 part has been extended to also support the
  14585.            Z380 (r9);}
  14586.      \item{the 68K part has been extended to know the
  14587.            differences of the 683xx micro controllers (r9);}
  14588.      \item{a label not any more has to be placed in the first
  14589.            row if it is marked with a double dot (r9);}
  14590.      \item{additionally supports the 75K0 series from NEC (r9);}
  14591.      \item{the additional command line option o allows to set
  14592.            a user-defined name for the code file (r9);}
  14593.      \item{the \verb!~~! operator has been moved to a bit more senseful
  14594.            ranking (r9);}
  14595.      \item{\tty{ASSUME} now also knows the 6809's DPR register and its
  14596.            implications (pardon, r9);}
  14597.      \item{the 6809 part now also knows the 6309's secret
  14598.            extensions (r9);}
  14599.      \item{binary constants now also may be written in a C-like
  14600.            notation (r9);}
  14601.      \end{itemize}}
  14602. \item{version 1.41:
  14603.      \begin{itemize}
  14604.      \item{the new predefined symbol \tty{MOMSEGMENT} allows to
  14605.            inquire the currently active segment;}
  14606.      \item{\tty{:=} is now allowed as a short form for \tty{SET/EVAL};}
  14607.      \item{the new command line switch \tty{q} allows to force a
  14608.            ''silent'' assembly;}
  14609.      \item{the key word \tty{PARENT} to reference the parent section
  14610.            has been extended by \tty{PARENT0..PARENT9};}
  14611.      \item{the PowerPC part has been extended by the
  14612.            microcontroller versions MPC505 and PPC403;}
  14613.      \item{symbols defined with \tty{SET} or \tty{EQU} may now be assigned
  14614.            to a certain segment (r1);}
  14615.      \item{the SH7000 part now also knows the SH7600's
  14616.            extensions (and should compute correct
  14617.            displacements...) (r1);}
  14618.      \item{the 65XX part now differentiates between the 65C02
  14619.            and 65SC02 (r1);}
  14620.      \item{additionally to the symbol \tty{MOMCPU}, there is now also
  14621.            a string symbol \tty{MOMCPUNAME} that contains the
  14622.            processor's full name (r1);}
  14623.      \item{P2HEX now also knows the 32-bit variant of the Intel
  14624.            hex format (r1);}
  14625.      \item{additionally knows the 87C750's limitations (r2);}
  14626.      \item{the internal numbers for fatal errors have been moved
  14627.            to the area starting at 10000, making more space for
  14628.            normal error messages (r2);}
  14629.      \item{unused symbols are now marked with a star in the
  14630.            symbol table (r2);}
  14631.      \item{additionally supports the 29K family from AMD (r2);}
  14632.      \item{additionally supports the M16 family from Mitsubishi
  14633.            (r2);}
  14634.      \item{additionally supports the H8/500 family from Hitachi
  14635.            (r3);}
  14636.      \item{the number of data bytes printed per line by P2HEX
  14637.            can now be modified (r3);}
  14638.      \item{the number of the pass that starts to output warnings
  14639.            created by the \tty{r} command line switch is now variable
  14640.            (r3);}
  14641.      \item{the macro processor now knows a \tty{WHILE} statement that
  14642.            allows to repeat a piece of code a variable number of
  14643.            times (r3);}
  14644.      \item{the \tty{PAGE} instruction now also allows to set the line
  14645.            with of the assembly listing (r3);}
  14646.      \item{CPU aliases may now be defined to define new pseudo
  14647.            processor devices (r3);}
  14648.      \item{additionally supports the MCS/251 family from Intel
  14649.            (r3);}
  14650.      \item{if the cross reference list has been enabled, the
  14651.            place of the first definition is given for double
  14652.            definitions of symbols (r3);}
  14653.      \item{additionally supports the TMS320C5x family from Texas
  14654.            Instruments (implementation done by Thomas Sailer,
  14655.            ETH Zurich, r3);}
  14656.      \item{the OS/2 version should now also correctly work with
  14657.            long file names.  If one doesn't check every s**t
  14658.            personally... (r3);}
  14659.      \item{the new pseudo instruction \tty{BIGENDIAN} now allows to
  14660.            select in MCS-51/251 mode whether constants should
  14661.            be stored in big endian or little endian format (r3);}
  14662.      \item{the 680x0 part now differentiates between the full
  14663.            and reduced MMU instruction set; a manual toggle can
  14664.            be done via the \tty{FULLPMMU} instruction (r3);}
  14665.      \item{the new command line option \tty{I} allows to print a list
  14666.            of all include files paired with their nesting level
  14667.            (r3);}
  14668.      \item{additionally supports the 68HC16 family from Motorola
  14669.            (r3);}
  14670.      \item{the \tty{END} statement now optionally accepts an argument
  14671.            as entry point for the program (r3);}
  14672.      \item{P2BIN and P2HEX now allow to move the contents of a
  14673.            code file to a different address (r4);}
  14674.      \item{comments appended to a \tty{SHARED} instruction are now
  14675.            copied to the share file (r4);}
  14676.      \item{additionally supports the 68HC12 family from Motorola
  14677.            (r4);}
  14678.      \item{additionally supports the XA family from Philips
  14679.            (r4);}
  14680.      \item{additionally supports the 68HC08 family from Motorola
  14681.            (r4);}
  14682.      \item{additionally supports the AVR family from Atmel (r4);}
  14683.      \item{to achieve better compatibility to the AS11 from
  14684.            Motorola, the pseudo instructions \tty{FCB, FDB, FCC}, and
  14685.            \tty{RMB} were added (r5);}
  14686.      \item{additionally supports the M16C from Mitsubishi (r5);}
  14687.      \item{additionally supports the COP8 from National
  14688.            Semiconductor (r5);}
  14689.      \item{additional instructions \tty{IFB} and \tty{IFNB} for conditional
  14690.            assembly (r5);}
  14691.      \item{the new \tty{EXITM} instruction now allows to terminate a
  14692.            macro expansion (r5);}
  14693.      \item{additionally supports the MSP430 from Texas
  14694.            Instruments (r5);}
  14695.      \item{\tty{LISTING} now knows the additional variants
  14696.            \tty{NOSKIPPED} and \tty{PURECODE} to remove code that
  14697.            was not assembled from the listing (r5);}
  14698.      \item{additionally supports the 78K0 family from NEC (r5);}
  14699.      \item{\tty{BIGENDIAN} is now also available in PowerPC mode
  14700.            (r5);}
  14701.      \item{additional \tty{BINCLUDE} instruction to include binary
  14702.            files (r5);}
  14703.      \item{additional \tty{TOLOWER} and \tty{LOWSTRING} functions to convert
  14704.            characters to lower case (r5);}
  14705.      \item{it is now possible to store data in other segments
  14706.            than \tty{CODE}.  The file format has been extended
  14707.            appropriately (r5);}
  14708.      \item{the \tty{DS} instruction to reserve memory areas is now
  14709.            also available in Intel mode (r5);}
  14710.      \item{the \tty{U} command line switch now allows to switch \asname{}
  14711.            into a case sensitive mode that differentiates
  14712.            between upper and lower case in the names of symbols,
  14713.            user-defined functions, macros, macro parameters, and
  14714.            sections (r5);}
  14715.      \item{\tty{SFRB} now also knows the mapping rules for bit
  14716.            addresses in the RAM areas; warnings are generated
  14717.            for addresses that are not bit addressable (r5);}
  14718.      \item{additional instructions \tty{PUSHV} and \tty{POPV} to save symbol
  14719.            values temporarily (r5);}
  14720.      \item{additional functions \tty{BITCNT, FIRSTBIT, LASTBIT}, and
  14721.            \tty{BITPOS} for bit processing (r5);}
  14722.      \item{the 68360 is now also known as a member of the CPU32
  14723.            processors (r5);}
  14724.      \item{additionally supports the ST9 family from SGS-Thomson
  14725.            (r6);}
  14726.      \item{additionally supports the SC/MP from National
  14727.            Semiconductor (r6);}
  14728.      \item{additionally supports the TMS70Cxx family from Texas
  14729.            Instruments (r6);}
  14730.      \item{additionally supports the TMS9900 family from Texas
  14731.            Instruments (r6);}
  14732.      \item{additionally knows the 80296's instruction set
  14733.            extensions (r6);}
  14734.      \item{the supported number of Z8 derivatives has been
  14735.            extended (r6);}
  14736.      \item{additionally knows the 80C504's mask defects (r6);}
  14737.      \item{additional register definition file for Siemens' C50x
  14738.            processors (r6);}
  14739.      \item{additionally supports the ST7 family from SGS-Thomson
  14740.            (r6);}
  14741.      \item{the Tntel pseudo instructions for data disposal are
  14742.            now also valid for the 65816/MELPS-7700 (r6);}
  14743.      \item{for the 65816/MELPS-7700, the address length may now
  14744.            be set explicitly via prefixes (r6);}
  14745.      \item{additionally supports the 8X30x family from Signetics
  14746.            (r6);}
  14747.      \item{from now on, \tty{PADDING} is enabled by default only
  14748.            for the 680x0 family (r7);}
  14749.      \item{the new predefined symbol \tty{ARCHITECTURE} can now be
  14750.            used to query the platform \asname{} was compiled for (r7);}
  14751.      \item{additional statements \tty{STRUCT} and \tty{ENDSTRUCT}
  14752.            to define data structures (r7);}
  14753.      \item{hex and object files for the AVR tools may now be generated
  14754.            directly (r7);}
  14755.      \item{\tty{MOVEC} now also knows the 68040's control registers
  14756.            (r7);}
  14757.      \item{additional \tty{STRLEN} function to calculate the length
  14758.            of a string (r7);}
  14759.      \item{additional ability to define register symbols (r7 currently
  14760.            only Atmel AVR);}
  14761.      \item{additionally knows the 6502's undocumented instructions (r7);}
  14762.      \item{P2HEX and P2BIN now optionally can erase the input files
  14763.            automatically (r7);}
  14764.      \item{P2BIN can additionally prepend the entry address to the
  14765.            resulting image (r7);}
  14766.      \item{additionally supports the ColdFire family from Motorola as a
  14767.            variation of the 680x0 core (r7);}
  14768.      \item{\tty{BYT/FCB, ADR/FDB}, and \tty{FCC} now also allow the
  14769.            repetition factor known from DC (r7);}
  14770.      \item{additionally supports Motorola's M*Core (r7);}
  14771.      \item{the SH7000 part now also knows the SH7700's
  14772.            extensions (r7);}
  14773.      \item{the 680x0 part now also knows the 68040's additional
  14774.            instructions (r7);}
  14775.      \item{the 56K part now also knows the instruction set extensions
  14776.            up to the 56300 (r7).}
  14777.      \item{the new \tty{CODEPAGE} statement now allows to keep several
  14778.            character sets in parallel (r8);}
  14779.      \item{The argument variations for \tty{CHARSET} have been extended
  14780.            (r8);}
  14781.      \item{New string functions \tty{SUBSTR} and \tty{STRSTR} (r8);}
  14782.      \item{additional \tty{IRPC} statement in the macro processor (r8);}
  14783.      \item{additional \tty{RADIX} statement to set the default numbering
  14784.            system for integer constants (r8);}
  14785.      \item{instead of {\tt ELSEIF}, it is now valid to simply write {\tt
  14786.            ELSE} (r8);}
  14787.      \item{$==$ may be used as equality operator instead of $=$ (r8);}
  14788.      \item{\tty{BRANCHEXT} for the Philips XA now allows to automatically
  14789.            extend the reach of short branches (r8);}
  14790.      \item{debug output is now also possible in NoICE format (r8);}
  14791.      \item{additionally supports the i960 family from Intel (r8);}
  14792.      \item{additionally supports the $\mu$PD7720/7725 signal processors
  14793.            from NEC (r8);}
  14794.      \item{additionally supports the $\mu$PD77230 signal processor from
  14795.            NEC (r8);}
  14796.      \item{additionally supports the SYM53C8xx SCSI processors from
  14797.            Symbios Logic (r8);}
  14798.      \item{additionally supports the 4004 from Intel (r8);}
  14799.      \item{additionally supports the SC14xxx series of National (r8);}
  14800.      \item{additionally supports the instruction extensions of the PPC
  14801.            403GC (r8);}
  14802.      \item{additional command line option {\tt cpu} to set the default
  14803.            target processor (r8);}
  14804.      \item{key files now also may be referenced from the command line
  14805.            (r8);}
  14806.      \item{additional command line option {\tt shareout} to set the
  14807.            output file for SHARED definitions (r8);}
  14808.      \item{new statement {\tt WRAPMODE} to support AVR processors with
  14809.            a shortened program counter (r8);}
  14810.      \item{additionally supports the C20x instruction subset in the C5x
  14811.            part (r8);}
  14812.      \item{hexadecimal address specifications for the tools now may also
  14813.            be made in C notation (r8);}
  14814.      \item{the numbering system for integer results in \verb!\{...}!
  14815.            expressions is now configurable via \tty{OUTRADIX} (r8);}
  14816.      \item{the register syntax for 4004 register pairs has been corrected
  14817.            (r8);}
  14818.      \item{additionally supports the F$^{2}$MC8L family from Fujitsu
  14819.            (r8);}
  14820.      \item{P2HEX now allows to set the minimum address length for S
  14821.            record addresses (r8);}
  14822.      \item{additionally supports the ACE family from Fairchild (r8);}
  14823.      \item{{\tt REG} is now also allowed for PowerPCs (r8);}
  14824.      \item{additional switch in P2HEX to relocate all addresses (r8);}
  14825.      \item{The switch \tty{x} now additionally allows a second level
  14826.            of detailness to print the source line in question (r8).}
  14827.      \end{itemize}}
  14828. \item{version 1.42:
  14829.      \begin{itemize}
  14830.      \item{the default integer syntax for Atmel AVR is now the C Syntax;}
  14831.      \item{additional command line option {\tt olist} to set the
  14832.            list file's name and location;}
  14833.      \item{additionally supports the F$^{2}$MC16L family from Fujitsu;}
  14834.      \item{additional instruction {\tt PACKING} for the AVR family;}
  14835.      \item{additional implicit macro parameters {\tt ALLARGS} and
  14836.            {\tt ARGCOUNT};}
  14837.      \item{additional instruction {\tt SHIFT} to process variable macro
  14838.            argument lists;}
  14839.      \item{support for temporary symbols;}
  14840.      \item{additional instruction {\tt MAXNEST} to set the maximum
  14841.            nesting depth of macro expansions;}
  14842.      \item{additional command line argument {\tt noicemask} to control
  14843.            the amount of segments listed in a NoICE debug info file;}
  14844.      \item{additionally supports the 180x family from Intersil;}
  14845.      \item{additionally supports the 68HC11K4 address windowing;}
  14846.      \item{P2HEX now allows to vary the address field length of AVR HEX
  14847.            files;}
  14848.      \item{the new command line option {\tt -gnuerrors} allows to output
  14849.            error messages in a GNU C-style format;}
  14850.      \item{additionally supports the TMS320C54x family from Texas
  14851.            Instruments;}
  14852.      \item{new macro option {\tt INTLABEL};}
  14853.      \item{added Atmel MegaAVR 8/16 instructions and register
  14854.            definitions;}
  14855.      \item{{\tt ENDIF/ENDCASE} show the line number of the corresponding
  14856.            opening statement in the listing;}
  14857.      \item{the 8051 part now also supports the extended address space of
  14858.            the Dallas DS80C390;}
  14859.      \item{added nameless temporary smbols;}
  14860.      \item{additionally supports the undocumented 8085 instructions;}
  14861.      \item{improved structure handling;}
  14862.      \item{added EXPRTYPE() function;}
  14863.      \item{allow line continuation;}
  14864.      \item{integrated support for KCPSM/PicoBlaze provided by Andreas
  14865.            Wassatsch;}
  14866.      \item{additionally supports the 807x family from National
  14867.            Semiconductor;}
  14868.      \item{additionally supports the Intel 4040;}
  14869.      \item{additionally supports the Zilog eZ8;}
  14870.      \item{additionally supports the 78K2 family from NEC;}
  14871.      \item{additionally supports the KCPSM3 variant from Xilinx;}
  14872.      \item{additionally supports the LatticeMico8;}
  14873.      \item{additionally supports the 12X instruction extensions and the
  14874.            XGATE core of the 68HC12 family;}
  14875.      \item{additionally supports the Signetics 2650;}
  14876.      \item{additionally supports the COP4 family from National
  14877.            Semiconductor;}
  14878.      \item{additionally supports the HCS08 extensions by Freesacle;}
  14879.      \item{additionally supports the RS08 family by Freescale;}
  14880.      \item{additionally supports the Intel 8008;}
  14881.      \item{add another optional syntax for integer constants;}
  14882.      \item{added function \tty{CHARFROMSTR};}
  14883.      \item{additionally allow Q for octal constants in Intel mode;}
  14884.      \item{add another variant for temporary symbols;}
  14885.      \item{the PowerPC part has been extended by the MPC821
  14886.            (contribution by Marcin Cieslak);}
  14887.      \item{implicit macro parameters are always case-insensitive;}
  14888.      \item{add \tty{REG} statement to MSP430;}
  14889.      \item{additionally supports the XMOS XS1;}
  14890.      \item{additional parameters \tty{GLOBALSYMBOLS} and
  14891.            \tty{NOGLOBALSYMBOLS} to control whether labels in
  14892.            macros are local or not;}
  14893.      \item{additionally supports the NEC 75xx series;}
  14894.      \item{additionally supports the TMS1000 controllers from
  14895.            TI;}
  14896.      \item{additionally supports the 78K2 family from NEC;}
  14897.      \item{all newer changes are only documented in the separate
  14898.            changelog file.}
  14899.      \end{itemize}}
  14900. \end{itemize}
  14901.  
  14902. %%===========================================================================
  14903.  
  14904. \cleardoublepage
  14905. \chapter{Hints for the \asname{} Source Code}
  14906. \label{ChapSource}
  14907.  
  14908. As I already mentioned in the introduction, I release the source code of
  14909. \asname{} on request.  The following shall give a few hints to their usage.
  14910.  
  14911. %%---------------------------------------------------------------------------
  14912.  
  14913. \section{Language Preliminaries}
  14914.  
  14915. In the beginning, \asname{} was a program written in Turbo-Pascal.  This was
  14916. roughly at the end of the eighties, and there were a couple of reasons for
  14917. this choice: First, I was much more used to it than to any C compiler, and
  14918. compared to Turbo Pascal's IDE, all DOS-based C compilers were just
  14919. crawling along.  In the beginning of 1997 however, it became clear that
  14920. things had changed: One factor was that Borland had decided to let its
  14921. confident DOS developers down (once again, explicitly no 'thank you', you
  14922. boneheads from Borland!) and replaced version 7.0 of Borland Pascal with
  14923. something called 'Delphi', which is probably a wonderful tool to develop
  14924. Windows programs which consist of 90\% user interface and accidentaly a
  14925. little bit of content, however completely useless for command-line driven
  14926. programs like \asname{}.  Furthermore, my focus of operating systems had made a
  14927. clear move towards Unix, and I probably could have waited arbitrarily long
  14928. for a Borland Pascal for Linux (to all those remarking now that Borland
  14929. would be working on something like that: this is {\em Vapourware}, don\'t
  14930. believe them anything until you can go into a shop and actually buy it!).
  14931. It was therefore clear that C was the way to go.
  14932.  
  14933. After this eperience what results the usage of 'island systems' may have,
  14934. I put a big emphasize on portability while doing the translation to C;
  14935. however, since \asname{} for example deals with binary data in an exactly format
  14936. and uses operating systen-specific functions at some places which may need
  14937. adaptions when one compliles \asname{} the first time for a new platform.
  14938.  
  14939. \asname{} is tailored for a C compiler that conforms to the ANSI C standard; C++
  14940. is explicitly not required.  If you are still using a compiler conforming
  14941. to the outdated Kernighan\&Ritchie standard, you should consider getting a
  14942. newer compiler: The ANSI C standard has been fixed in 1989 and there
  14943. should be an ANSI C compiler for every contemporary platform, maybe by
  14944. using the old compiler to build GNU-C.  Though there are some switches in
  14945. the source code to bring it nearer to K\&R, this is not an officially
  14946. supported feature which I only use internally to support a quite antique
  14947. Unix.  Everything left to say about K\&R is located in the file {\tt
  14948. README.KR}.
  14949.  
  14950. The inclusion of some additional features not present in the Pascal
  14951. version (e.g. dynamically loadable message files, test suite, automatic
  14952. generation of the documentation from {\em one} source format) has made the
  14953. source tree substantially more complicated.  I will attempt to unwire
  14954. everything step by step:
  14955.  
  14956. %%---------------------------------------------------------------------------
  14957.  
  14958. \section{Capsuling System dependencies}
  14959.  
  14960. As I already mentioned, As has been tailored to provide maximum platform
  14961. independence and portability (at least I believe so...).  This means
  14962. packing all platform dependencies into as few files as possible.  I will
  14963. describe these files now, and this section is the first one because it is
  14964. probably one of the most important:
  14965.  
  14966. The Build of all components of \asname{} takes place via a central {\tt
  14967. Makefile}.  To make it work, it has to be accompanied by a fitting {\tt
  14968. Makefile.def} that gives the platform dependent settings like compiler
  14969. flags.  The subdirectory {\tt Makefile.def-samples} contains a couple of
  14970. includes that work for widespread platforms (but which need not be
  14971. optimal...).  In case your platform is not among them, you may take the
  14972. file {\tt Makefile.def.tmpl} as a starting point (and send me the
  14973. result!).
  14974.  
  14975. A further component to capure system dependencies is the file {\tt
  14976. sysdefs.h}.  Practically all compilers predefine a couple of preprocessor
  14977. symbols that describe the target processor and the used operating system.
  14978. For example, on a Sun Sparc under Solaris equipped with the GNU compiler,
  14979. the symbols \verb!__sparc! and \verb!__SVR4!.  {\tt sysdefs.h} exploits
  14980. these symbols to provide a homogeneous environment for the remaining,
  14981. system-independent files.  Especially, this covers integer datatypes of a
  14982. specific length, but it may also include the (re)definition of C functions
  14983. which are not present or non-standard-like on a specific platform.  It's
  14984. best to read this files yourself if you like to know which things may
  14985. occur...  Generally, the \verb!#ifdef! statement are ordered in two
  14986. levels: First, a specific processor platform is selected, the the
  14987. operating systems are sorted out in such a section.
  14988.  
  14989. If you port \asname{} to a new platform, you have to find two symbols typical for
  14990. this platform and extend {\tt sysdefs.h} accordingly.  Once again, I'm
  14991. interested in the result...
  14992.  
  14993. %%---------------------------------------------------------------------------
  14994.  
  14995. \section{System-Independent Files}
  14996.  
  14997. ...represent the largest part of all modules.  Describing all functions in
  14998. detail is beyond the scope of this description (those who want to know
  14999. more probably start studying the sources, my programming style isn't that
  15000. horrible either...), which is why I can only give a short list at this
  15001. place with all modules their function:
  15002.  
  15003. \subsection{Modules Used by \asname{}}
  15004.  
  15005. \subsubsection{as.c}
  15006.  
  15007. This file is \asname{}'s root: it contains the {\em main()} function of \asname{}, the
  15008. processing of all command line options, the overall control of all passes
  15009. and parts of the macro processor.
  15010.  
  15011. \subsubsection{asmallg.c}
  15012.  
  15013. This module processes all statements defined for all processor targets,
  15014. e.g. \tty{EQU} and \tty{ORG}.  The \tty{CPU} pseudo-op used to switch
  15015. among different processor targets is also located here.
  15016.  
  15017. \subsubsection{asmcode.c}
  15018.  
  15019. This module contains the bookkeping needed for the code output file.  It
  15020. exports an interface that allows to open and close a code file and offers
  15021. functions to write code to (or take it back from) the file.  An important
  15022. job of this module is to buffer the write process, which speeds up
  15023. execution by writing the code in larger blocks.
  15024.  
  15025. \subsubsection{asmdebug.c}
  15026.  
  15027. \asname{} can optionally generate debug information for other tools like
  15028. simulators or debuggers, allowing a backward reference to the source code.
  15029. They get collected in this module and can be output after assembly in one
  15030. of several formats.
  15031.  
  15032. \subsubsection{asmdef.c}
  15033.  
  15034. This modules only contains declarations of constants used in different
  15035. places and global variables.
  15036.  
  15037. \subsubsection{asmfnums.c}
  15038.  
  15039. \asname{} assigns internally assigns incrementing numbers for each used source
  15040. file.  These numbers are used for quick referencing.  Assignment of
  15041. numbers and the conversion between names and numbers takes place here.
  15042.  
  15043. \subsubsection{asmif.c}
  15044.  
  15045. Here ara ll routines located controlling conditional assembly.  The most
  15046. important exported variable is a flag called \tty{IfAsm} which controls
  15047. whether code generation is currently turned on or off.
  15048.  
  15049. \subsubsection{asminclist.c}
  15050.  
  15051. This module holds the definition of the list stucture that allows \asname{} to
  15052. print the nesting of include files to the assembly list file.
  15053.  
  15054. \subsubsection{asmitree.c}
  15055.  
  15056. When searching for the mnemonic used in a line of code, a simple linear
  15057. comparison with all available machine instructions (as it is still done in
  15058. most code generators, for reasons of simplicity and laziness) is not
  15059. necessary the most effective method.  This module defines two improved
  15060. structures (binary tree and hash table) which provide a more efficient
  15061. search and are destined to replace the simple linear search on a
  15062. step-by-step basis...priorities as needed...
  15063.  
  15064. \subsubsection{asmmac.c}
  15065.  
  15066. Routines to store and execute macro constructs are located in this module.
  15067. The real macro processor is (as already mentioned) in {\tt as.c}.
  15068.  
  15069. \subsubsection{asmpars.c}
  15070.  
  15071. Here we really go into the innards: This module stores the symbol tables
  15072. (global and local) in two binary trees.  Further more, there is a quite
  15073. large procedure {\tt EvalExpression} which analyzes and evaluates a (formula)
  15074. expression.  The procedure returns the result (integer, floating point, or
  15075. string) in a varaint record.  However, to evaluate expressions during code
  15076. generation, one should better use the functions  \tty{EvalIntExpression,
  15077. EvalFloatExpression}, and \tty{EvalStringExpression}.  Modifications for
  15078. tha esake of adding new target processors are unnecessary in this modules
  15079. and should be done with extreme care, since you are touching something
  15080. like '\asname{}'s roots'.
  15081.  
  15082. \subsubsection{asmsub.c}
  15083.  
  15084. This module collects a couple of commonly used subroutines which primarily
  15085. deal with error handling and 'advanced' string processing.
  15086.  
  15087. \subsubsection{bpemu.c}
  15088.  
  15089. As already mentioned at the beginning, \asname{} originally was a program written
  15090. in Borland Pascal.  For some intrinsic functions of the compiler, it was
  15091. simpler to emulate those than to touch all places in the source code where
  15092. they are used.  Well...
  15093.  
  15094. \subsubsection{chunks.c}
  15095.  
  15096. This module defines a data type to deal with a list of address ranges.
  15097. This functionality is needed by \asname{} for allocation lists; furthermore,
  15098. P2BIN and P2HEX use such lists to warn about overlaps.
  15099.  
  15100. \subsubsection{cmdarg.c}
  15101.  
  15102. This module implements the overall mechanism of command line arguments.
  15103. It needs a specification of allowed arguments, splits the command line and
  15104. triggers the appropriate callbacks.   In detail, the mechanism includes
  15105. the following:
  15106. \begin{itemize}
  15107. \item{Processing of arguments located in an environment variable or
  15108.      a corresponding file;}
  15109. \item{Return of a set describing which command line arguments have not
  15110.      been processed;}
  15111. \item{A backdoor for situations when an overlaying IDE converts the passed
  15112.      command line completely into upper or lower case.}
  15113. \end{itemize}
  15114.  
  15115. \subsubsection{codepseudo.c}
  15116.  
  15117. You will find at this place pseudo instructions that are used by
  15118. a subset of code generators.  On the one hand, this is the Intel group of
  15119. \tty{DB..DO}, and on the other hand their counterparts for 8/16 bit CPUs
  15120. from Motorola or Rockwell.  Someone who wants to extend \asname{} by a
  15121. processor fitting into one of these groups can get the biggest part
  15122. of the necessary pseudo instructions with one call to this module.
  15123.  
  15124. \subsubsection{codevars.c}
  15125.  
  15126. For reasons of memory efficiency, some variables commonly used by diverse
  15127. code generators.
  15128.  
  15129. \subsubsection{endian.c}
  15130.  
  15131. Yet another bit of machine dependence, however one you do not have to
  15132. spend attention on: This module automatically checks at startup whether
  15133. a host machine is little or big endian.  Furthermore, checks are made if
  15134. the type definitions made for integer variables in {\tt sysdefs.h} really
  15135. result in the correct lengths.
  15136.  
  15137. \subsubsection{headids.c}
  15138.  
  15139. At this place, all processor families supported by \asname{} are collected with
  15140. their header IDs (see chapter \ref{SectCodeFormat}) and the output format
  15141. to be used by default by P2HEX.  The target of this table is to centralize
  15142. the addition of a new processor as most as possible, i.e. in contrast to
  15143. earlier versions of \asname{}, no further modifications of tool sources are
  15144. necessary.
  15145.  
  15146. \subsubsection{ioerrs.c}
  15147.  
  15148. The conversion from error numbers to clear text messages is located here.
  15149. I hope I'll never hit a system that does not define the numbers as macros,
  15150. because I would have to rewrite this module completely...
  15151.  
  15152. \subsubsection{nlmessages.c}
  15153.  
  15154. The C version of \asname{} reads all messages from files at runtime after the
  15155. language to be used is clear.  The format of message files is not a simple
  15156. one, but instead a special compact and preindexed format that is generated
  15157. at runtime by a program called 'rescomp' (we will talk about it later).
  15158. This module is the counterpart to rescomp that reads the correct language
  15159. part into a character field and offers functions to access the messages.
  15160.  
  15161. \subsubsection{nls.c}
  15162.  
  15163. This module checks which country-dependent settings (date and time format,
  15164. country code) are present at runtime.  Unfortunately, this is a highly
  15165. operating system-dependend task, and currently, there are only three
  15166. methods defines: The MS-DOS method, the OS/2 method and the typical Unix
  15167. method via {\em locale} functions.  For all other systems, there is
  15168. unfortunately currently only \verb!NO_NLS! available...
  15169.  
  15170. \subsubsection{stdhandl.c}
  15171.  
  15172. On the one hand, here is a special open function located knowing the
  15173. special strings {\tt !0...!2} as file names and creating duplicates of the
  15174. standard file handles {\em stdin, stdout,} and {\em stderr}.  On the other
  15175. hand, investiagations are done whether the standard output has been
  15176. redirected to a device or a file.  On no-Unix systems, this unfortunately
  15177. also incorporates some special operations.
  15178.  
  15179. \subsubsection{stringlists.c}
  15180.  
  15181. This is just a little 'hack' that defines routines to deal with linear
  15182. lists of strings, which are needed e.g. in the macro processor of \asname{}.
  15183.  
  15184. \subsubsection{strutil.c}
  15185.  
  15186. Some commonly needed string operations have found their home here.
  15187.  
  15188. \subsubsection{version.c}
  15189.  
  15190. The currently valid version is centrally stored here for \asname{} and all other
  15191. tools.
  15192.  
  15193. \subsubsection{code????.c}
  15194.  
  15195. These modules form the main part of \asname{}: each module contains the code
  15196. generator for a specific processor family.
  15197.  
  15198. \subsection{Additional Modules for the Tools}
  15199.  
  15200. \subsubsection{hex.c}
  15201.  
  15202. A small module to convert integer numbers to hexadecimal strings.  It's
  15203. not absolutely needed in C any more (except for the conversion of {\em
  15204. long long} variables, which unfortunately not all {\tt printf()}'s
  15205. support), but it somehow survived the porting from Pascal to C.
  15206.  
  15207. \subsubsection{p2bin.c}
  15208.  
  15209. The sources of P2BIN.
  15210.  
  15211. \subsubsection{p2hex.c}
  15212.  
  15213. The sources of P2HEX.
  15214.  
  15215. \subsubsection{pbind.c}
  15216.  
  15217. The sources of BIND.
  15218.  
  15219. \subsubsection{plist.c}
  15220.  
  15221. The sources of PLIST.
  15222.  
  15223. \subsubsection{toolutils.c}
  15224.  
  15225. All subroutines needed by several tools are collected here, e.g. for
  15226. reading of code files.
  15227.  
  15228. \section{Modules Needed During the Build of \asname{}}
  15229.  
  15230. \subsubsection{a2k.c}
  15231.  
  15232. This is a minimal filter converting ANSI C source files to
  15233. Kernighan-Ritchie style.  To be exact: only function heads are converted,
  15234. even this only when they are roughly formatted like my programming style.
  15235. Noone should therefore think this were a universal C parser!
  15236.  
  15237. \subsubsection{addcr.c}
  15238.  
  15239. A small filter needed during installation on DOS- or OS/2-systems.  Since
  15240. DOS and OS/2 use a CR/LF for a newline, inc ontrast to the single LF of
  15241. Unix systems, all assembly include files provided with \asname{} are sent through
  15242. this filter during assembly.
  15243.  
  15244. \subsubsection{bincmp.c}
  15245.  
  15246. For DOS and OS/2, this module takes the task of the {\em cmp} command,
  15247. i.e. the binary comparison of files during the test run.  While this would
  15248. principally be possible with the {\em comp} command provided with the OS,
  15249. {\em bincmp} does not have any nasty interactive questions (which seem to
  15250. be an adventure to get rid of...)
  15251.  
  15252. \subsubsection{findhyphen.c}
  15253.  
  15254. This is the submodule in {\em tex2doc} providing hyphenation of words.
  15255. The algorithm used for this is shamelessly stolen from TeX.
  15256.  
  15257. \subsubsection{grhyph.c}
  15258.  
  15259. The definition of hyphenation rules for the german language.
  15260.  
  15261. \subsubsection{rescomp.c}
  15262.  
  15263. This is \asname{}'s 'resource compiler', i.e. the tool that converts a readable
  15264. file with string resources into a fast, indexed format.
  15265.  
  15266. \subsubsection{tex2doc.c}
  15267.  
  15268. A tool that converts the LaTeX documentation of \asname{} into an ASCII format.
  15269.  
  15270. \subsubsection{tex2html.c}
  15271.  
  15272. A tool that converts the LaTeX documentation of \asname{} into an HTML document.
  15273.  
  15274. \subsubsection{umlaut.c and unumlaut.c}
  15275.  
  15276. These tiny programs convert national special characters between their
  15277. coding in ISO8859-1 (all \asname{} files use this format upon delivery) and their
  15278. system-specific coding.  Apart from a plain ASCII7 variant, there are
  15279. currently the IBM character sets 437 and 850.
  15280.  
  15281. \subsubsection{ushyph.c}
  15282.  
  15283. The definition of hyphenation rules for the english language.
  15284.  
  15285. %%---------------------------------------------------------------------------
  15286.  
  15287. \section{Generation of Message Files}
  15288.  
  15289. As already mentioned, the C source tree of \asname{} uses a dynamic load
  15290. principle for all (error) messages.  In contrast to the Pasacl sources
  15291. where all messages were bundled in an include file and compiled into the
  15292. programs, this method eliminates the need to provide \asname{} in multiple
  15293. language variants; there is only one version which checks for the
  15294. langugage to be used upon runtime and loads the corresponding component
  15295. from the message files.  Just to remind: Under DOS and OS/2, the {\tt
  15296. COUNTRY} setting is queried, while under Unix, the environment variables
  15297. {\tt LC\_MESSAGES, LC\_ALL,} and {\tt LANG} are checked.
  15298.  
  15299. \subsection{Format of the Source Files}
  15300.  
  15301. A source file for the message compiler {\em rescomp} usually has the
  15302. suffix {\tt .res}.  The message compiler generates one or two files from a
  15303. source:
  15304. \begin{itemize}
  15305. \item{a binary file which is read at runtime by \asname{} resp. its tools}
  15306. \item{optionally one further C header file assigning an index number to
  15307.      all messages. These index numbers in combination with an index
  15308.      table in the binary file allow a fast access to to individual
  15309.      messages at runtime.}
  15310. \end{itemize}
  15311.  
  15312. The source file for the message compiler is a pure ASCII file and can
  15313. therefore be modified with any editor.  It consists of a sequence of
  15314. control commands with parameters.  Empty lines and lines beginning with a
  15315. semicolon are ignored.  Inclusion of other files is possible via the {\tt
  15316. Include} statement:
  15317. \begin{verbatim}
  15318. Include <Datei>
  15319. \end{verbatim}
  15320.  
  15321. The first two statements in every source file must be two statements
  15322. describing the languages defined in the following.  The more important one
  15323. is {\tt Langs}, e.g.:
  15324. \begin{verbatim}
  15325. Langs DE(049) EN(001,061)
  15326. \end{verbatim}
  15327. describes that two languages will be defined in the rest of the file.  The
  15328. first one shall be used under Unix when the language has been set to {\tt
  15329. DE} via environment variable.  Similarly, It shall be used under DOS and
  15330. OS/2 when the country code was set to 049.  Similarly, the second set
  15331. shall be used for the settings {\tt DE} resp. 061 or 001.  While multiple
  15332. 'telephone numbers' may point to a single language, the assignment to a
  15333. Unix language code is a one-to-one correspondence.  This is no problem in
  15334. practice since the {\tt LANG} variables Unix uses describe subversions via
  15335. appendices, e.g.:
  15336. \begin{verbatim}
  15337. de.de
  15338. de.ch
  15339. en.us
  15340. \end{verbatim}
  15341. \asname{} only compares the beginning of the strings and therefore still comes to
  15342. the right decision.
  15343. The {\tt Default} statement defines the language that shall be used if
  15344. either no language has been set at all or a language is used that is not
  15345. mentioned in the asrgument list of {\tt Langs}.  This is typically the
  15346. english language:
  15347. \begin{verbatim}
  15348. Default EN
  15349. \end{verbatim}
  15350. These definitions are followed by an arbitrary number of {\tt Message}
  15351. statements, i.e. definitions of messages:
  15352. \begin{verbatim}
  15353. Message ErrName
  15354. ": Fehler "
  15355. ": error "
  15356. \end{verbatim}
  15357. In case {\em n} languages were announced via the {\tt Langs} statement,
  15358. the message compiler takes {\bf exactly} the following {\em n} as the
  15359. strings to be stored.  It is therefore impossible to leave out certain
  15360. languages for individual messages, and an empty line following the strings
  15361. should in no way be misunderstood as an end marker for the list; inserted
  15362. lines between statements only serve purposes of better readability.  It is
  15363. however allowed to split individual messages across multiple lines in the
  15364. source file; all lines except for the last one have to be ended with a
  15365. backslash as continuation character:
  15366. \begin{verbatim}
  15367. Message TestMessage2
  15368. "Dies ist eine" \
  15369. "zweizeilige Nachricht"
  15370. "This is a" \
  15371. "two-line message"
  15372. \end{verbatim}
  15373. As already mentioned, source files are pure ASCII files; national special
  15374. characters may be placed in message texts (and the compiler will correctly
  15375. pass them to the resulting file), a big disadvantage however is that such
  15376. a file is not fully portable any more: in case it is ported to another
  15377. system using a different coding for national special characters, the user
  15378. will probably be confronted with funny characters at runtime...special
  15379. characters should therefore always be written via special sequences
  15380. borrowed from HTML resp. SGML (see table \ref{TabSpecChars}).  Linefeeds
  15381. can be inserted into a line via \verb!\n!, similar to C.
  15382. \begin{table*}[htb]
  15383. \begin{center}\begin{tabular}{|l|l|}
  15384. \hline
  15385. Sequence... & results in... \\
  15386. \hline
  15387. \hline
  15388. \verb!&auml; &ouml; &uuml;! & "a "o "u (Umlauts)\\
  15389. \verb!&Auml; &Ouml; &Uuml;! & "A "O "U \\
  15390. \verb!&szlig;!              & "s (sharp s) \\
  15391. \verb!&agrave; &egrave; &igrave; &ograve;! & \'a \'e \'i \'o \\
  15392. \verb!&ugrave;! & \'u \\
  15393. \verb!&Agrave; &Egrave; &Igrave; &Ograve;! & \'A \'E \'I \'O \\
  15394. \verb!&Ugrave;! & \'U (Accent grave) \\
  15395. \verb!&aacute; &eacute; &iacute; &oacute;! & \`a \`e \`i \`o \\
  15396. \verb!&uacute;! & \`u \\
  15397. \verb!&Aacute; &Eacute; &Iacute; &Oacute;! & \`A \`E \`I \`O \\
  15398. \verb!&Uacute;! & \`U (Accent agiu) \\
  15399. \verb!&acirc; &ecirc; &icirc; &ocirc;! & \^a \^e \^i \^o \\
  15400. \verb!&ucirc;! & \^u \\
  15401. \verb!&Acirc; &Ecirc; &Icirc; &Ocirc;! & \^A \^E \^I \^O \\
  15402. \verb!&Ucirc;! & \^U (Accent circonflex) \\
  15403. \verb!&ccedil; &Ccedil;! & \c{c} \c{C}(Cedilla) \\
  15404. \verb!&ntilde; &Ntilde;! & \~n \~N \\
  15405. \verb!&aring; &Aring;! & \aa  \AA \\
  15406. \verb!&aelig; &Aelig;! & \ae  \AE \\
  15407. \verb!&iquest; &iexcl;! & inverted ! or ? \\
  15408. \hline
  15409. \end{tabular}\end{center}
  15410. \caption{Syntax for special character in {\em rescomp}\label{TabSpecChars}}
  15411. \end{table*}
  15412.  
  15413. %%---------------------------------------------------------------------------
  15414.  
  15415. \section{Creation of Documentation}
  15416.  
  15417. A source distribution of \asname{} contains this documentation in LaTeX format
  15418. only.  Other formats are created from this one automatically  via tools
  15419. provided with \asname{}.  One reason is to reduce the size of the source
  15420. distribution, another reason is that changes in the documentation only
  15421. have to be made once, avoiding inconsistencies.
  15422.  
  15423. LaTex was chosen as the master format because...because...because it's
  15424. been there all the time before.  Additionally, TeX is almost arbitrarily
  15425. portable and fits quite well to the demands of \asname{}.  A standard
  15426. distribution therefore allows a nice printout on about any printer; for a
  15427. conversion to an ASCII file that used to be part of earlier distributions,
  15428. the converter {\em tex2doc} is included, additionally the converter {\em
  15429. tex2html} allowing to put the manual into the Web.
  15430.  
  15431. Generation of the documentation is started via a simple
  15432. \begin{verbatim}
  15433. make docs
  15434. \end{verbatim}
  15435. The two converters mentioned are be built first, then applied to the TeX
  15436. documentation and finally, LaTeX itself is called.  All this of course for
  15437. all languages...
  15438.  
  15439. %%---------------------------------------------------------------------------
  15440.  
  15441. \section{Test Suite}
  15442.  
  15443. Since \asname{} deals with binary data of a precisely defined structure, it is
  15444. naturally sensitive for system and compiler dependencies.  To reach at
  15445. least a minimum amount of secureness that everything went right during
  15446. compilation, a set of test sources is provided in the subdirectory {\tt
  15447. tests} that allows to test the freshly built assembler.  These programs
  15448. are primarily trimmed to find faults in the translation of the machine
  15449. instruction set, which are commonplace when integer lenghts vary.
  15450. Target-independent features like the macro processors or conditional
  15451. assembly are only casually tested, since I assume that they work
  15452. everywhere when they work for me...
  15453.  
  15454. The test run is started via a simple {\em make test}.  Each test program
  15455. is assembled, converted to a binary file, and compared to a reference
  15456. image.  A test is considered to be passed if and only if the reference
  15457. image and the newly generated one are identical on a bit-by-bit basis.  At
  15458. the end of the test, the assembly time for every test is printed (those
  15459. who want may extend the file BENCHES with these results), accompanied with
  15460. a success or failure message.  Track down every error that occurs, even if
  15461. it occurs in a processor target you are never going to use!  It is always
  15462. possible that this points to an error that may also come up for other
  15463. targets, but by coincidence not in the test cases.
  15464.  
  15465. %%---------------------------------------------------------------------------
  15466.  
  15467. \section{Adding a New Target Processor}
  15468.  
  15469. The probably most common reason to modify the source code of \asname{} is to add
  15470. a new target processor.   Apart from adding the new module to the
  15471. Makefile, there are few places in other modules that need a modification.
  15472. The new module will do the rest by registering itself in the list of code
  15473. generators.  I will describe the needed steps in a cookbook style in the
  15474. following sections:
  15475.  
  15476. \subsubsection{Choosing the Processor's Name}
  15477.  
  15478. The name chosen for the new processor has to fulfill two criterias:
  15479. \begin{enumerate}
  15480. \item{The name must not be already in use by another processor.  If one
  15481.      starts \asname{} without any parameters, a list of the names already in
  15482.      use will be printed.}
  15483. \item{If the name shall appear completely in the symbol \tty{MOMCPU}, it may
  15484.      not contain other letters than A..F (except right at the
  15485.      beginning).  The variable \tty{MOMCPUNAME} however will always report
  15486.      the full name during assembly.  Special characters are generally
  15487.      disallowed, lowercase letters will be converted by the \tty{CPU}
  15488.      command to uppercase letters and are therefore senseless in the
  15489.      processor name.}
  15490. \end{enumerate}
  15491.  
  15492. The first step for registration is making an entry for the new processor
  15493. (family) in the file {\tt headids.c}.  As already mentioned, this file is
  15494. also used by the tools and specifies the code ID assigned to a processor
  15495. family, along with the default hex file format to be used.  I would like
  15496. to have some coordination before choosing the ID...
  15497.  
  15498. \subsubsection{Definition of the Code Generator Module}
  15499.  
  15500. The unit's name that shall be responsible for the new processor
  15501. should bear at least some similarity to the processor's name (just
  15502. for the sake of uniformity) and should be named in the style of
  15503. \tty{code....}.  The head with include statements is best taken from
  15504. another existing code generator.
  15505.  
  15506. Except for an initialization function that has to be called at the
  15507. begginning of the {\tt main()} function in module {\tt as.c}, the new
  15508. module neither has to export variables nor functions as the complete
  15509. communication is done at runtime via indirect calls.  They are simply done
  15510. by a call to the function
  15511. \tty{AddCPU} for each processor type that shall be treated by this unit:
  15512. \begin{verbatim}
  15513.   CPUxxxx:=AddCPU('XXXX',SwitchTo_xxxx);
  15514. \end{verbatim}
  15515. \tty{'XXXX'} is the name chosen for the processor which later must be used
  15516. in assembler programs to switch \asname{} to this target processor.
  15517. \tty{SwitchTo\_xxxx} (abbreviated as the ''switcher'' in the following) is
  15518. a procedure without parameters that is called by \asname{} when the switch to the
  15519. new processor actually takes place.  \tty{AddCPU} delivers an integer
  15520. value as result that serves as an internal ''handle'' for the new
  15521. processor.  The global variable \tty{MomCPU} always contains the handle of
  15522. the target processor that is currently set.  The value returned by
  15523. \tty{AddCPU} should be stored in a private variable of type \tty{CPUVar}
  15524. (called \tty{CPUxxxx} in the example above).  In case a code generator
  15525. module implements more than one processor (e.g. several processors of a
  15526. family), the module can find out which instruction subset is currently
  15527. allowed by comparing \tty{MomCPU} against the stored handles.
  15528.  
  15529. The switcher's task is to ''reorganize'' \asname{} for the new target
  15530. processor.  This is done by changing the values of several global
  15531. variables:
  15532. \begin{itemize}
  15533. \item{\tty{ValidSegs}: Not all processors have all address spaces defined
  15534.      by \asname{}.  This set defines which subset the \tty{SEGMENT} instruction
  15535.      will enable for the currently active target processor.  At least the
  15536.      \tty{CODE} segment has to be enabled.  The complete set of allowed
  15537.      segments can be looked up the file \tty{fileformat.h} (\tty{Seg....}
  15538.      constants).}
  15539. \item{\tty{SegInits}: This array stores the initial program counter values
  15540.      for the individual segments (i.e. the values the program counters
  15541.      will initially take when there is no \tty{ORG} statement).  There are
  15542.      only a few exceptions (like logically separated address spaces
  15543.      that physically overlap) which justify other initial values than
  15544.      0.}
  15545. \item{\tty{Grans}: This array specifies the size of the smallest addressable
  15546.      element in bytes for each segment, i.e. the size of an element
  15547.      that increases an address by 1.  Most processors need a value of
  15548.      1, even if they are 16- or 32-bit processors, but the PICs and
  15549.      signal processors are cases where higher values are required.}
  15550. \item{\tty{ListGrans}: This array specifies the size of byte groups that shall
  15551.      be shown in the assembly listing.  For example, instruction words
  15552.      of the 68000 are always 2 bytes long though the code segment's
  15553.      granularity is 1.  The \tty{ListGran} entry therefore has to be set to
  15554.      2.}
  15555. \item{\tty{SegLimits}: This array stores the highest possible address for
  15556.      each segment, e.g. 65535 for a 16-bit address space.  This array
  15557.      need not be filled in case the code generator takes over the
  15558.      {\tt ChkPC} method.}
  15559. \item{\tty{ConstMode}: This variable may take the values
  15560.      \tty{ConstModeIntel}, \tty{ConstModeMoto}, or \tty{ConstModeC}
  15561.      and rules which syntax has to be used to specify the base of
  15562.      integer constants.}
  15563. \item{\tty{PCSymbol}: This variable contains the string an assembler program
  15564.      may use to to get the current value of the program counter.
  15565.      Intel processors for example usually use a dollar sign.}
  15566. \item{\tty{TurnWords}: If the target processor uses big-endian addressing and
  15567.      one of the fields in \tty{ListGran} is larger than one, set this flag
  15568.      to true to get the correct byte order in the code output file.}
  15569. \item{\tty{SetIsOccupied}: Some processors have a \tty{SET} machine instruction.
  15570.      If this callback is set to a non-NULL value, the code generator
  15571.      may report back whether \tty{SET} shall not be interpreted as
  15572.      pseudo instruction.  The return value may be constant \tty{True} or
  15573.      or e.g. depend on the number of argument if a differentiation is
  15574.      possible.}
  15575. \item{\tty{HeaderID}: This variable contains the ID that is used to mark the
  15576.      current processor family in the the code output file (see the
  15577.      description of the code format described by \asname{}).  I urge to
  15578.      contact me before selecting the value to avoid ambiguities.
  15579.      Values outside the range of \$01..\$7f should be avoided as they
  15580.      are reserved for special purposes (like a future extension to
  15581.      allow linkable code). Even though this value is still hard-coded
  15582.      in most code generators, the preferred method is now to fetch this
  15583.      value from {\tt headids.h} via {\tt FindFamilyByName}.}
  15584. \item{\tty{NOPCode}: There are some situations where \asname{} has to fill unused
  15585.      code areas with NOP statements.  This variable contains the
  15586.      machine code of the NOP statement.}
  15587. \item{\tty{DivideChars}: This string contains the characters that are valid
  15588.      separation characters for instruction parameters.  Only extreme
  15589.      exotics like the DSP56 require something else than a single comma
  15590.      in this string.}
  15591. \item{\tty{HasAttrs}: Some processors like the 68k series additionally split
  15592.      an instruction into mnemonic and attribute.  If the new processor
  15593.      also does something like that, set this flag to true and \asname{} will
  15594.      deliver the instructions' components readily split in the string
  15595.      variables \tty{OpPart} and \tty{AttrPart}.  If this flag is however set to
  15596.      false, no splitting will take place and the instruction will be
  15597.      delivered as a single piece in \tty{OpPart}.  \tty{AttrPart} will stay empty
  15598.      in this case.  One really should set this flag to false if the
  15599.      target processor does not have attributes as one otherwise looses
  15600.      the opportunity to use macros with a name containing dots (e.g.
  15601.      to emulate other assemblers).}
  15602. \item{\tty{AttrChars}: In case \tty{HasAttrs} is true, this string has to contain
  15603.      all characters that can separate mnemonic and attribute.  In most
  15604.      cases, this string only contains a single dot.}
  15605. \end{itemize}
  15606. Do not assume that any of these variables has a predefined value; set
  15607. them \bb{all}!!
  15608.  
  15609. Apart from these variables, some function pointers have to be set that
  15610. form the link form \asname{} to the ''active'' parts of the code
  15611. generator:
  15612. \begin{itemize}
  15613. \item{\tty{MakeCode}: This routine is called after a source line has been
  15614.      split into mnemonic and parameters.  The mnemonic is stored into
  15615.      the variable \tty{OpPart}, and the parameters can be looked up in the
  15616.      array \tty{ArgStr}.  The number of arguments may be read from
  15617.      \tty{ArgCnt}.
  15618.      The binary code has to be stored into the array \tty{BAsmCode}, its
  15619.      length into \tty{CodeLen}.  In case the processor is word oriented
  15620.      like the 68000 (i.e. the \tty{ListGran} element corresponding to the
  15621.      currently active segment is 2), the field may be addressed
  15622.      wordwise via \tty{WAsmCode}.  There is also \tty{DAsmCode} for extreme
  15623.      cases... The code length has to be given in units corresponding
  15624.      to the current segment's granularity.}
  15625. \item{\tty{SwitchFrom}: This parameter-less procedure enables the code generator
  15626.      module to do ''cleanups'' when \asname{} switches to another target processor.
  15627.      This hook allows e.g. to free memory that has been allocated in the
  15628.      generator and that is not needed as long as the generator is not
  15629.      active.  It may point to an empty procedure in the simplest case.
  15630.      One example for the usage of this hook is the module \tty{CODE370} that
  15631.      builds its instruction tables dynamically and frees them again after
  15632.      usage.}
  15633. \item{\tty{IsDef}: Some processors know additional instructions that impose
  15634.      a special meaning on a label in the first row like \tty{EQU} does.  One
  15635.      example is the \tty{BIT} instruction found in an 8051 environment.  This
  15636.      function has to return TRUE if such a special instruction is
  15637.      present.  In the simplest case (no such instructions), the routine
  15638.      may return a constant FALSE.}
  15639. \end{itemize}
  15640.  
  15641. Optionally, the code generator may additionally set the following function
  15642. pointers:
  15643. \begin{itemize}
  15644. \item{\tty{ChkPC} : Though \asname{} internally treats all program counters as
  15645.      either 32 or 64 bits, most processors use an address space that is
  15646.      much smaller.  This function informs \asname{} whether the current program
  15647.      counter has exceeded its allowed range.  This routine may of course
  15648.      be much more complicated in case the target processor has more than
  15649.      one address space.  One example is in module \tty{code16c8x.c}.  In
  15650.      case everything is fine, the function has to return TRUE, otherwise
  15651.      FALSE.  The code generator only has to implement this function if
  15652.      it did not set up the array {\tt SegLimits}.  This may e.g. become
  15653.      necessary when the allowed range of addresses in a segment is
  15654.      non-continuous.}
  15655. \item{\tty{InternSymbol} : Some processorcs, e.g. such with a register
  15656.      bank in their internal RAM, predefine such 'registers' as symbols,
  15657.      and it wouldn't make much sense to define them in a separate include
  15658.      file with 256 or maybe more {\tt EQU}s.  This hook allows access to
  15659.      the code generator of \asname{}: It obtains an expression as an ASCII
  15660.      string and sets up the passed structure of type {\em TempResult}
  15661.      accordingly when one of these 'built-in' symbols is detected.  The
  15662.      element {\tt Typ} has to be set to {\tt TempNone} in case the check
  15663.      failed.  Errors messages from this routine should be avoided as
  15664.      unidentified names could signify ordinary symbols (the parser will
  15665.      check this afterwards).  Be extreme careful with this routine as
  15666.      it allows you to intervene into the parser's heart!}
  15667. \item{\tty{DissectBit} : In case the target platform supports bit objects,
  15668.      i.e. objects that pack both a register or memory address and a bit
  15669.      position into one integer number, this is the callback to dissect
  15670.      such a packed representation and transform it back into a source-code
  15671.      like, human-readable form.  This provides better readability of the
  15672.      listing.}
  15673. \item{\tty{DissectReg} : In case the target platform supports register
  15674.      symbols, this is the callback that translates register number and size
  15675.      back to a source-code like, human-readable form.  Again, this function
  15676.      is used for the listing.}
  15677. \item{\tty{QualifyQuote} : This optional callback allows to define on a
  15678.      per-platform base situations when a single quotation character does
  15679.      {\em not} lead in a character string.  An example for this is the
  15680.      Z80's alternate register bank, which is written as \tty{AF'}, or
  15681.      the hexadecimal constant syntax \tty{H'...} used on some Hitachi
  15682.      processors.}
  15683. \end{itemize}
  15684.  
  15685. By the way: People who want to become immortal may add a copyright
  15686. string.  This is done by adding a call to the procedure \tty{AddCopyright}
  15687. in the module's initialization part (right next to the \tty{AddCPU} calls):
  15688. \begin{verbatim}
  15689.   AddCopyright(
  15690.      "Intel 80986 code generator (C) 2010 Jim Bonehead");
  15691. \end{verbatim}
  15692. The string passed to \tty{AddCopyright} will be printed upon program start
  15693. in addition to the standard message.
  15694.  
  15695. If needed, the unit may also use its initialization part to hook into
  15696. a list of procedures that are called prior to each pass of assembly.
  15697. Such a need for example arises when the module's code generation
  15698. depends on certain flags that can be modified via pseudo
  15699. instructions.  An example is a processor that can operate in either
  15700. user or supervisor mode.  In user mode, some instructions are
  15701. disabled.  The flag that tells \asname{} whether the following code executes
  15702. in user or supervisor mode might be set via a special pseudo
  15703. instruction.  But there must also be an initialization that assures
  15704. that all passes start with the same state.  The hook offered via
  15705. \tty{AddInitPassProc} offers a chance to do such initializations.  The
  15706. callback function passed to it is called before a new pass is
  15707. started.
  15708.  
  15709. The function chain built up via calls to \tty{AddCleanUpProc}
  15710. operates similar to \tty{AddInitPassProc}: It enables code
  15711. generators to do clean-ups after assembly (e.g.  freeing of
  15712. literal tables).  This makes sense when multiple files are
  15713. assembled with a single call of \asname{}.  Otherwise, one would risk to
  15714. have 'junk' in tables from the previous run.  No module currently
  15715. uses this feature.
  15716.  
  15717. \subsubsection{Writing the Code Generator itself}
  15718.  
  15719. Now we finally reached the point where your creativity is challenged:
  15720. It is up to you how you manage to translate mnemonic and parameters
  15721. into a sequence of machine code.  The symbol tables are of course
  15722. accessible (via the formula parser) just like everything exported
  15723. from \tty{ASMSUB}.  Some general rules (take them as advises and not as
  15724. laws...):
  15725. \begin{itemize}
  15726. \item{Try to split the instruction set into groups of instructions that
  15727.      have the same operand syntax and that differ only in a few bits
  15728.      of their machine code.  For example, one can do all instructions
  15729.      without parameters in a single table this way.}
  15730. \item{Most processors have a fixed spectrum of addressing modes.  Place
  15731.      the parsing of an address expression in a separate routine so you
  15732.      an reuse the code.}
  15733. \item{The subroutine \tty{WrError} defines a lot of possible error codes and
  15734.      can be easily extended.  Use this!  It is no good to simply issue
  15735.      a ''syntax error'' on all error conditions!}
  15736. \end{itemize}
  15737. Studying other existing code generators should also prove to be
  15738. helpful.
  15739.  
  15740. \subsubsection{Modifications of Tools}
  15741.  
  15742. A microscopic change to the tolls' sources is still necessary, namely to
  15743. the routine {\tt Granularity()} in {\tt toolutils.c}: in case one of the
  15744. processor's address spaces has a granularity different to 1, the swich
  15745. statement in this place has to be adapted accordingly, otherwise PLIST,
  15746. P2BIN, and P2HEX start counting wrong...
  15747.  
  15748. \section{Localization to a New Language}
  15749.  
  15750. You are interested in this topic?  Wonderful!  This is an issue that is
  15751. often neglected by other programmers, especially when they come from the
  15752. country on the other side of the big lake...
  15753.  
  15754. The localization to a new language can be split into two parts: the
  15755. adaption of program messages and the translation of the manual.  The
  15756. latter one is definitely a work of gigantic size, however, the adaption of
  15757. program messages should be a work doable on two or three weekends, given
  15758. that one knows both the new and one of the already present messages.
  15759. Unfortunately, this translation cannot be done on a step-by-step basis
  15760. because the resource compiler currently cannot deal with a variable amount
  15761. of languages for different messages, so the slogan is 'all or nothing'.
  15762.  
  15763. The first oeration is to add the new language to {\tt header.res}.  The
  15764. two-letter-abbreviation used for this language is best fetched from the
  15765. nearest Unix system (in case you don't work on one anyway...), the
  15766. international telephone prefix from a DOS manual.
  15767.  
  15768. When this is complete, one can rebuild all necessary parts with a simple
  15769. {\em make} and obtains an assembler that supports one more language.  Do
  15770. not forget to forward the results to me.  This way, all users will benefit
  15771. from this with the next release :-)
  15772.  
  15773. %%===========================================================================
  15774.  
  15775. \cleardoublepage
  15776. \begin{thebibliography}{99}
  15777.  
  15778. \input{../doc_COM/biblio.tex}
  15779.  
  15780. \end{thebibliography}
  15781.  
  15782. \cleardoublepage
  15783.  
  15784. \printindex
  15785.  
  15786. \end{document}
  15787.