=================================================================== RCS file: /cvs/djgpp/djgpp/src/utils/Attic/djasm.txi,v retrieving revision 1.4 retrieving revision 1.5 diff -p -u -r1.4 -r1.5 --- djgpp/src/utils/Attic/djasm.txi 2001/05/30 15:27:24 1.4 +++ /cvs/djgpp/djgpp/src/utils/Attic/djasm.txi 2001/06/19 15:51:34 1.5 @@ -13,10 +13,10 @@ @c %**end of header @end ignore -@set EDITION 1.04 +@set EDITION 1.05 @set DJGPP_VERSION 2.03 -@set UPDATED 30 May 2001 -@set UPDATED_MONTH May 2001 +@set UPDATED 19 June 2001 +@set UPDATED_MONTH June 2001 @set NASM_HOME www.cryogen.com/Nasm @set BC_DJASM_DOC_DATE 19 November 1999 @@ -41,7 +41,8 @@ Copyright @copyright{} 1999, 2000, 2001 @ifinfo @code{djasm} is a special-purpose 16-bit assembler used to compile the -16-bit stub that allows DOS to run the COFF files generated by DJGPP. +16-bit stub that allows @acronym{DOS} to run the @acronym{COFF} files +generated by DJGPP. This is Edition @value{EDITION} of the documentation for @code{djasm}, @@ -102,24 +103,25 @@ The final authority regarding @code{djas @code{djasm} is a restricted assembler that was developed for a single purpose: to compile the 16-bit startup stub that is prepended to all DJGPP-built executables. -The purpose of the stub is to check for @sc{dpmi} services (and load -@sc{cwsdpmi} if a @sc{dpmi} server is not found), switch into protected -mode, and load and execute a DJGPP-generated COFF image. +The purpose of the stub is to (i) check for @acronym{DPMI} services, +(ii) load @acronym{CWSDPMI} if another @acronym{DPMI} server is not +found, (iii) switch into protected mode, and (iv) load and execute +a DJGPP-generated @acronym{COFF} image. With @code{djasm} the DJGPP distribution can be made completely self-contained; you don't need commercial (or otherwise non-DJGPP) 16-bit tools to build any part of the DJGPP distribution. Be aware, however, that although @code{djasm} can be used in other applications, it is @emph{not} a full-featured assembler; if you need -a sophisticated, general-purpose assembler then consider using @sc{gas} -(the GNU Assembler) or @sc{nasm} (the Netwide Assembler). +a sophisticated, general-purpose assembler then consider using @acronym{AS} +(the @acronym{GNU} assembler) or @acronym{NASM} (the Netwide Assembler). Give some thought to what you want to do, and choose the right tool for the job. -The GNU assembler @sc{gas} (@file{as.exe}) is part of the DJGPP -@file{bnuNNNb.zip} archive and should be available in the @file{bin} -subdirectory of your DJGPP tree (i.e., in @file{$DJDIR/bin}) if you -have installed @sc{gcc}. -The Netwide Assembler @sc{nasm} lives at @url{@value{NASM_HOME}}. +The @acronym{GNU} assembler @acronym{AS} (@file{as.exe}) is part of +the DJGPP @file{bnuNNNb.zip} archive and should be available in the +@file{bin} subdirectory of your DJGPP tree (i.e., in @file{$DJDIR/bin}) +if you have installed @acronym{GCC}. +The Netwide Assembler @acronym{NASM} lives at @url{@value{NASM_HOME}}. @comment node-name, next, previous, up @node History @@ -127,13 +129,13 @@ The Netwide Assembler @sc{nasm} lives at @cindex history, of djasm @cindex stub, DJGPP -@cindex NASM assembler +@cindex NASM, Netwide assembler @cindex Borland @cindex Cygnus @cindex DJGPP The need for @code{djasm} arose when when Cygnus, a major user of -DJGPP for their DOS-based products, requested a version of +DJGPP for their @acronym{DOS}-based products, requested a version of DJGPP that was fully independent and self-bootstrapping. The existing DJGPP 1.x system didn't entirely meet their need, however, because a Borland 16-bit compiler (Turbo C 2.0) was required @@ -142,8 +144,8 @@ to build the @file{go32.exe} program use The first task, therefore, in making a version 2.x of DJGPP that would be entirely self-contained was to write an assembler that could compile the 16-bit stub required by all DJGPP executables. -The stub could have been written to use @sc{nasm}, but -(1) @sc{nasm} wasn't around at the time, and +The stub could have been written to use @acronym{NASM}, but +(1) @acronym{NASM} wasn't around at the time, and (2) a dedicated 16-bit compiler would make DJGPP independent of any other product. Thus @code{djasm} was designed and written for a specific purpose---to @@ -185,11 +187,11 @@ The syntax was designed to be easy to pa so @code{djasm} is relatively easy to learn and use, and code written for @code{djasm} tends to be straightforward. @item -@code{djasm} is released under the terms of the @sc{gpl} and comes +@code{djasm} is released under the terms of the @acronym{GPL} and comes with DJGPP (@file{djdevNNN.zip}). @item -@sc{gcc}/@sc{gas}-generated COFF files can be linked with the -code (the linking is done by @code{djasm}). +@acronym{GCC}- and @acronym{AS}-generated @acronym{COFF} files can be +linked with the code (the linking is done by @code{djasm}). @item @code{djasm} produces 16-bit code (currently this is the only available mode). @@ -197,7 +199,7 @@ code (the linking is done by @code{djasm There is support for several output formats, including raw hex output for subsequent use with assembler and C code. @item -Support for C-style structure, union, and enumeration types. +C-style structure, union, and enumeration types are supported. @item Most instructions and addressing modes are supported. @item @@ -208,12 +210,13 @@ Full 32-bit addressing. @node Differences @section Differences between @code{djasm} and other assemblers -@cindex NASM assembler -@cindex GAS, GNU Assembler +@cindex NASM, Netwide assembler +@cindex AS, GNU assembler +@cindex GAS, GNU assembler There are some important differences between @code{djasm} and -other assemblers, such as @sc{gas} (the GNU Assembler) and -@sc{nasm} (Netwide Assembler). +other assemblers, such as @acronym{NASM} or the @acronym{GNU} +assembler @acronym{AS}. @itemize @bullet{} @item @@ -225,11 +228,11 @@ and porting code to @code{djasm} shouldn @cindex syntax, ATT @item -@code{djasm} generates 16-bit code, @sc{gas} generates 32-bit code, -and @sc{nasm} can generate both 16- and 32-bit code. +@code{djasm} generates 16-bit code, @acronym{AS} generates 32-bit code, +and @acronym{NASM} can generate both 16- and 32-bit code. @item @code{djasm} is incompletely documented and has incomplete opcode support; -@sc{gas} and @sc{nasm} are fully supported. +@acronym{AS} and @acronym{NASM} are fully supported. @item @code{djasm} does not support macros. @item @@ -242,7 +245,8 @@ so all source must be in a single file. there is no linker. @item Code generated by @code{djasm} cannot be linked with DJGPP programs; -@sc{gas} and @sc{nasm} can produce standard COFF objects. +both @acronym{NASM} and the @acronym{GNU} assembler @acronym{AS} can +produce standard @acronym{COFF} objects. However, @code{djasm} @strong{can} build a raw binary image for inclusion in other code. @end itemize @@ -255,7 +259,7 @@ Although @code{djasm} can do quite a bit of things that experienced assembly-language programmers will miss. Future versions of @code{djasm} may add support for some or all of these items, but again, if you need a sophisticated general-purpose -assembler, you should consider @sc{gas} or @sc{nasm}. +assembler, you should consider @acronym{AS} or @acronym{NASM}. @itemize @bullet{} @item @@ -268,13 +272,14 @@ A companion 16-bit linker. Segments. (Is this really necessary? Is it worth it? -Should one just use @sc{nasm} instead?) +Should one just use @acronym{NASM} instead?) @item Macros. @item More documentation. @item -Finish omf support. +Finish support for the Tool Interface Standards (@acronym{TIS}) +Relocatable Object Module Format (@acronym{OMF}). @item Better symbol handling (allow forward references in most expressions). @item @@ -309,11 +314,12 @@ The following output formats are support @table @file @item .exe -Generate a normal DOS @file{.exe} (@sc{mz}-signature) executable. +Generate a normal @acronym{DOS} @file{.exe} +executable (@acronym{MZ}-signature). Does not support more than one segment. This is the only output format that supports the @code{.copyright} directive. @item .com -Generate a normal DOS @file{.com} file. +Generate a normal @acronym{DOS} @file{.com} file. Program offset is at 0x100. @item .bin @itemx .sys @@ -327,7 +333,7 @@ surrounding @{@}s). @item .inc Produce a @file{.db} array for other @code{djasm} @file{.asm} files. @item .ah -Produce a @file{.byte} array for @sc{gas} @file{.s} or @file{.S} files. +Produce a @file{.byte} array for @acronym{AS} @file{.s} or @file{.S} files. @end table For the @file{.h}, @file{.inc}, and @file{.ah} output types, @@ -338,16 +344,16 @@ type to emit (@pxref{General,.type}). @node Applications @section When would I want to use @code{djasm}? -Ordinarily, assembly language programmers should use @sc{gas}, or a -16/32-bit assembler like @sc{nasm}, for most programming purposes. +Ordinarily, assembly language programmers should use @acronym{AS}, or a +16/32-bit assembler like @acronym{NASM}, for most programming purposes. However, there are a few reasons why you might want to use @code{djasm}: @itemize @bullet{} @item -If you are looking for a free (@i{sensu} @sc{gpl}) 16-bit assembler. +If you are looking for a free (@i{sensu} @acronym{GPL}) 16-bit assembler. @item To keep a project compatible with the spirit of DJGPP, -without requiring the use of @sc{nasm} or some other assembler +without requiring the use of @acronym{NASM} or some other assembler to compile 16-bit code. @item For small 16-bit projects, such as device drivers, TSRs, @@ -371,17 +377,19 @@ boot loaders, or micro-kernels. @node Syntax @section Assembler Syntax -As a general rule, @code{djasm} uses the @sc{tasm}/@sc{masm} -ordering of operands, and usually the same instruction names. +As a general rule, @code{djasm} uses the same ordering of operands, +and usually the same instruction names, as do @acronym{TASM} and +@acronym{MASM}. For ambiguous operand sizes, @code{djasm} uses operand suffixes instead of the @code{word ptr}, etc., operand modifiers used by other 16-bit assemblers. For example, @code{djasm} uses @code{cmpb} instead of @code{cmp byte}. -Until documentation for @code{djasm} is completed, however, you should -examine the @sc{bison} source for @code{djasm} (in the file @file{djasm.y}) -to learn exactly what the instruction mnemonics and their arguments are. +Until documentation for @code{djasm} is completed, however, you +should examine the @code{bison} source for @code{djasm} (in the file +@file{djasm.y}) to learn exactly what the instruction mnemonics and +their arguments are. @comment node-name, next, previous, up @node General @@ -403,11 +411,11 @@ to learn exactly what the instruction mn @item .align Usage: .align @var{boundary} [, @var{fill}] -Emit bytes (if necessary) so that the program counter @sc{cs:ip} +Emit bytes (if necessary) so that the program counter @var{cs:ip} (denoted by @code{.}) is a multiple of @var{boundary} -(i.e., such that @sc{cs:ip} % @var{boundary} == 0). +(i.e., such that @var{cs:ip} % @var{boundary} == 0). The argument @var{fill} specifies what bytes to emit; -the default is 0x90 (@sc{nop}). +the default is 0x90 (@acronym{NOP}). @smallexample .align 4 ; align on a 4-byte boundary, pad using 0x90 @@ -435,7 +443,7 @@ This directive is currently supported on @item .id Usage: .id -Emit @sc{sccs} and @sc{rcs} identification strings into the +Emit @acronym{SCCS} and @acronym{RCS} identification strings into the instruction stream. These strings have the form: @@ -461,19 +469,19 @@ but @var{file}.inc itself can include a @item .linkcoff Usage: .linkcoff "@var{file}.o" -Link in a @sc{gas}-generated 32-bit COFF file +Link in an @acronym{AS}-generated 32-bit @acronym{COFF} file (e.g., the output from @code{gcc -c foo.c}). -Currently supports only i386 COFF files with @code{.text}, +Currently supports only i386 @acronym{COFF} files with @code{.text}, @code{.data}, and @code{.bss} sections; these @emph{must} be the -first three sections in the COFF file and @emph{must} appear +first three sections in the @acronym{COFF} file and @emph{must} appear in that order. Any other sections will be ignored. These three sections will be placed into the output image in the same -order as in the COFF file. -The @code{.bss} section of the COFF file will be placed into the -output image by emitting the appropriate number of zeros---this means -that the @code{.bss} section from the COFF file will occupy space -in the output image rather than being implicit. +order as in the @acronym{COFF} file. +The @code{.bss} section of the @acronym{COFF} file will be placed into +the output image by emitting the appropriate number of zeros---this +means that the @code{.bss} section from the @acronym{COFF} file will +occupy space in the output image rather than being implicit. As with @code{.include}, no path searching is done for @code{.linkcoff}, but @var{file}.o itself can include a path specification. @@ -481,20 +489,20 @@ but @var{file}.o itself can include a pa @item .org Usage: .org @var{offset} -Sets the instruction pointer @sc{ip} to @var{offset}. -The @sc{ip} can only be increased using @code{.org}, never decreased. +Sets the instruction pointer @var{ip} to @var{offset}. +The @var{ip} can only be increased using @code{.org}, never decreased. @item .stack Usage: .stack For @file{.exe} files only, sets the initial value of the stack pointer -@sc{sp} to the current value of the instruction pointer @sc{ip}. +@var{sp} to the current value of the instruction pointer @var{ip}. @item .start Usage: .start For @file{.exe} files only, sets the initial value of the instruction -pointer @sc{ip} to the current value of the program counter @sc{cs:ip}. +pointer @var{ip} to the current value of the program counter @var{cs:ip}. @item .type Usage: .type "@var{image}" @@ -533,7 +541,7 @@ output file extension and @code{.type} d @enumerate a @item -The first 0x100 bytes of the program are 0x90 (@sc{nop}), +The first 0x100 bytes of the program are 0x90 (@acronym{NOP}), followed by the generated code. @item The @file{.sys} type is a synonym for @file{.bin}. @@ -790,9 +798,9 @@ or @code{.dd} lines. Unfortunately this is prone to error, but it is currently the only way of doing this. Any expression that @code{djasm} can handle as a relocation is permitted -in the parentheses; this can be useful for declaring structures at some -specific address (e.g., the @sc{psp} structure or some of the DOS -system tables). +in the parentheses; this can be useful for declaring structures at +some specific address (e.g., the @acronym{PSP} structure or some of the +@acronym{DOS} system tables). @comment node-name, next, previous, up @node Enumerations @@ -809,7 +817,7 @@ The following construct defines @samp{bo type that can take the values 0 (@samp{false}) or 1 (@samp{true}). @example -.enum boolean +.enum boolean false true .ends @@ -821,7 +829,7 @@ having integral values 0 (@samp{bird}), or 3 (@samp{rock}). @example -.enum pets +.enum pets bird cat dog @@ -857,7 +865,7 @@ following integer values: 0 (@samp{foo}) 2 (@samp{b}), 4 (@samp{c}), 8 (@samp{d}), or 9 (@samp{e}). @example -.enum snafu +.enum snafu foo bar a=1 @@ -996,8 +1004,8 @@ generally follows that of Triebel (1992) @node Shift Instructions @subsection Shift Instructions -[Not this release.] -@c @include shift.txi +@c [Not this release.] +@include shift.txi @comment node-name, next, previous, up @node Rotate Instructions @@ -1065,6 +1073,7 @@ Some examples of programming with @code{ @menu * Hello world:: ``Hello, world'' demo program. +* Enumeration types:: Examples of enumeration types. * Opcode prefixes:: Example of opcode prefix usage. @end menu @@ -1086,13 +1095,114 @@ msg: @end example Enter the above code into a file @file{hello.asm}, -then make a DOS @file{.com} executable using the command +then make a @acronym{DOS} @file{.com} executable using the command @example djasm hello.asm hello.com hello.map @end example @comment node-name, next, previous, up +@node Enumeration types +@section Examples of enumeration types + +Here are a few examples of using enumeration types in @code{djasm}. +These are taken directly from the section on enumeration types +(@pxref{Enumerations}). + +@enumerate + +@item +Use an enumeration to define a new type, @samp{boolean}. +Load register @var{ax} with the value @samp{false} and +register @var{bx} with the value @samp{true}. + +@example +.type "com" +.org 0x100 +.enum boolean + false + true +.ends + mov ax,boolean.false + mov bx,boolean.true + int 0x20 +@end example + + +@noindent +If you assemble this program with @code{djasm}, + +@example +djasm.exe bool.asm bool.com bool.map +@end example + +@noindent +and inspect the resulting @file{.map} file, you will find the +following enumeration definition: + +@example +Address Symbols by Value + +0000:0000 __zero__ (?) +0000:0000 boolean.false (?) +0000:0001 boolean.true (?) +@end example + +@noindent +If you inspect the assembled code using @acronym{DOS} @code{debug}, +you will see that the registers are indeed loaded with the proper values: + +@example +% debug bool.exe +-u 0100 l 08 +1600:0100 B80000 MOV AX,0000 +1600:0103 BB0100 MOV BX,0001 +1600:0106 CD20 INT 20 +-q +@end example + +@item +This example defines an enumeration type @samp{snafu} and demonstrates +both implicit and explicit initialization of the enumeration constants. +In this example, the enumeration constants @samp{foo}, @samp{bar}, +and @samp{e} are implicitly initialized with the values 0, 1, and 9, +respectively. + +@example +.type "com" +.org 0x100 +.enum snafu + foo + bar + a=1 + b=2 + c=4 + d=8 + e +.ends + int 0x20 +@end example + +@noindent +The @file{.map} file generated by @code{djasm} shows the enumeration +constants and how they were defined: + +@example +Address Symbols by Value + +0000:0000 __zero__ (?) +0000:0000 snafu.foo (?) +0000:0001 snafu.a (?) +0000:0001 snafu.bar (?) +0000:0002 snafu.b (?) +0000:0004 snafu.c (?) +0000:0008 snafu.d (?) +0000:0009 snafu.e (?) +@end example + +@end enumerate + +@comment node-name, next, previous, up @node Opcode prefixes @section Example of opcode prefix usage @@ -1133,7 +1243,7 @@ You can also let us know if your e-mail @itemize @bullet{} @item @email{fighteer@@cs.com,John M. Aldrich} -@item @email{billc@@taniwha.org,Bill Currie} +@item @email{bill@@taniwha.org,Bill Currie} @item @email{dj@@delorie.com,DJ Delorie} @item @email{nate@@cartsys.com,Nate Eldredge} @item @email{sandmann@@clio.rice.edu,Charles Sandmann}