=================================================================== RCS file: /cvs/djgpp/djgpp/src/utils/Attic/djasm.txi,v retrieving revision 1.1 retrieving revision 1.2 diff -p -u -r1.1 -r1.2 --- djgpp/src/utils/Attic/djasm.txi 2001/01/17 19:38:57 1.1 +++ /cvs/djgpp/djgpp/src/utils/Attic/djasm.txi 2001/02/10 20:18:35 1.2 @@ -31,7 +31,7 @@ @comment The following two commands start the copyright page. @page @vskip 0pt plus 1filll -Copyright @copyright{} 1999, 2000 DJ Delorie +Copyright @copyright{} 1999--2001 DJ Delorie @end titlepage @comment node-name, next, previous, up @@ -45,10 +45,10 @@ the 16-bit stub that allows @sc{dos} to generated by @sc{djgpp}. This is Edition @value{EDITION} -of documentation for @code{djasm}, +of the documentation for @code{djasm}, @cite{The DJGPP 16-bit Assembler}, -last updated @value{UPDATED}. -@c for @code{DJGPP} Version 2.03. +last updated @value{UPDATED}, +for @acronym{DJGPP} Version @value{VERSION}. This manual incorporates the information in Bill Currie's LyX documentation for @code{djasm}, dated @value{BC_DJASM_DOC_DATE}. @end ifinfo @@ -61,7 +61,8 @@ LyX documentation for @code{djasm}, date * Reference:: Assembler language reference. * Examples:: Programming examples. * Contributors:: Contributors. -@c * Index:: Keyword index. +* Topic Index:: Index of topics. +* Keyword Index:: Index of djasm keywords. @end menu @comment node-name, next, previous, up @@ -78,7 +79,8 @@ LyX documentation for @code{djasm}, date @node Disclaimer @section Disclaimer -@ignore +@cindex disclaimer + @quotation This is an UNREVIEWED and UNGUARANTEED document describing *some* of the aspects of djasm. We think it might describe djasm, but then it might not. @@ -86,19 +88,15 @@ aspects of djasm. We think it might des ---DJ @end flushright @end quotation -@end ignore - -@c @display -To paraphrase DJ: -``This is an @emph{UNREVIEWED} and @emph{UNGUARANTEED} document -describing @strong{some} of the aspects of @code{djasm}. -It might describe @code{djasm}, but then again, it might not.'' -@c @end display Some features described herein may be specific to Bill Currie's latest version of @code{djasm}, available at @url{@value{BC_DJASM_HOME}}, and may not (yet) have found their way into the official @sc{djgpp} release. +Of course, the final authority regarding @code{djasm} is the Bison +source file @file{djasm.y} in the file @file{djlsrNNN.zip}. +Use the source, Luke. + @comment node-name, next, previous, up @node Description @section Description @@ -127,6 +125,13 @@ archive and should be available in the @ @node History @section A Brief History of @code{djasm} +@cindex history, of djasm +@cindex stub, DJGPP +@cindex NASM assembler +@cindex Borland +@cindex Cygnus +@cindex DJGPP + The need for @code{djasm} arose when when Cygnus, a major user of @sc{djgpp} for their @sc{dos}-based products, requested a version of @sc{djgpp} that was fully independent and self-bootstrapping. @@ -156,6 +161,8 @@ useful for more 16-bit applications than @node Overview @chapter An Overview of @code{djasm} +@cindex overview, of djasm + @menu * Features:: What @code{djasm} can do. * Differences:: Differences from other assemblers. @@ -167,6 +174,8 @@ useful for more 16-bit applications than @node Features @section What @code{djasm} can do +@cindex features, of djasm + Despite many limitations and some glaring omissions, @code{djasm} does have some nice features: @@ -177,7 +186,7 @@ so @code{djasm} is relatively easy to le and code written for @code{djasm} tends to be straightforward. @item @code{djasm} is released under the terms of the @sc{gpl} and comes -with @sc{djgpp} (@file{djdevXXX.zip}). +with @sc{djgpp} (@file{djdevNNN.zip}). @item @sc{gcc}/@sc{gas}-generated @code{coff} files can be linked with the code (the linking is done by @code{djasm}). @@ -188,7 +197,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 @sc{c} code. @item -Support for @sc{c}-style structures and unions. +Support for @sc{c}-style structure, union, and enumeration types. @item Most instructions and addressing modes are supported (a few are still missing). @@ -200,6 +209,9 @@ Full 32-bit addressing. @node Differences @section Differences between @code{djasm} and other assemblers +@cindex NASM 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). @@ -211,6 +223,10 @@ it is similar to the Intel syntax, but t @sc{gas} uses the @sc{at&t} syntax. Porting code to @code{djasm} shouldn't be difficult but will generally require a bit of editing. + +@cindex syntax, Intel +@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. @@ -240,8 +256,8 @@ However, @code{djasm} can build a raw bi Although @code{djasm} can do quite a bit as it stands, there are a number 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 general-purpose assembler, you -should consider @sc{gas} or @sc{nasm}. +these items, but again, if you need a sophisticated general-purpose +assembler, you should consider @sc{gas} or @sc{nasm}. @itemize @bullet{} @item @@ -251,25 +267,23 @@ Object files---what format(s)? @item A companion 16-bit linker. @item -Segments +Segments. (Is this really necessary? Is it worth it? Should one just use @sc{nasm} instead?) @item Macros. @item -Complete documentation. - +More documentation. @item Finish omf support (do you still want that, DJ?). @item -Enums (Done!). -@item Better symbol handling (allow forward references in most expressions). @item -Better section support---first stage, being able to swap between .text, -.data and .bss at will; later, maybe `real' segment support (esp 16/32 -bit control). +Better section support. +At first, just being able to swap between the @code{.text}, @code{.data}, +and @code{.bss} sections at will. +Later, maybe `real' segment support (especially 16/32-bit control). @item Finalize instruction support for 486. @item @@ -348,7 +362,10 @@ boot loaders, or micro-kernels. @menu * Syntax:: Assembler syntax. -* Directives:: Assembler directives. +* General:: General directives. +* Data:: Data directives. +* Structures:: Structure, union, and enumeration types. +* Prefixes:: Segment override prefixes. @end menu @comment node-name, next, previous, up @@ -368,19 +385,19 @@ examine the @sc{bison} source for @code{ to learn exactly what the instruction mnemonics and their arguments are. @comment node-name, next, previous, up -@node Directives -@section Assembler Directives - -@menu -* General:: General directives. -* Data:: Data directives. -* Structures and Unions:: Structures and unions. -* Prefixes:: Segment override prefixes. -@end menu - -@comment node-name, next, previous, up @node General -@subsection General Directives +@section General Directives + +@pindex .align +@pindex .bss +@pindex .copyright +@pindex .id +@pindex .include +@pindex .linkcoff +@pindex .org +@pindex .stack +@pindex .start +@pindex .type @table @code @@ -388,7 +405,7 @@ to learn exactly what the instruction mn Usage: .align @var{boundary} [, @var{fill}] Emit bytes (if necessary) so that the program counter @sc{cs:ip} -(denoted by `.') is a multiple of @var{boundary} +(denoted by @code{.}) is a multiple of @var{boundary} (i.e., such that @sc{cs:ip} % @var{boundary} == 0). The argument @var{fill} specifies what bytes to emit; the default is 0x90 (@sc{nop}). @@ -424,7 +441,7 @@ The id has the form: @c use `@w{Id}' below to prevent RCS from recognizing the keyword. @c the `Cederqvist' uses `$@asis{}Author$' constructions; does it matter? -@c NB sccs groks the `@(#)' sequence (cederqvist, p.70). +@c SCCS groks the `@(#)' sequence (Cederqvist, p.70). @example $@w{Id}: djasm.lyx,v 1.2 1999/06/22 07:08:56 bill Exp $ @@(#) foo.asm built 10/04/97 14:03:30 by djasm @@ -487,9 +504,16 @@ where @var{image} is one of The following table summarizes the effect of various combinations of output file extension and @code{.type} declaration. -@c @end table -@c End table here to avoid excessive indentation of following table. +@pindex .type, exe +@pindex .type, com +@pindex .type, bin +@pindex .type, sys +@pindex .type, h +@pindex .type, inc +@pindex .type, ah +@c This table is an ASCII hack, but trying to use `multitable' +@c is even worse. @example +---------+-----------------------------------------------------+ | Output | Value of @samp{.type} | @@ -521,7 +545,14 @@ The @file{.sys} type is a synonym for @f @comment node-name, next, previous, up @node Data -@subsection Data Directives +@section Data Directives + +@pindex .db +@pindex .dd +@pindex .dw +@pindex .dblist +@pindex .dwlist +@pindex .ddlist The data directives are used to reserve space for byte (8-bit), word (16-bit), and double word (32-bit) data. @@ -565,11 +596,11 @@ Repeat a block of data. @end table @comment node-name, next, previous, up -@node Structures and Unions -@subsection Structures and Unions +@node Structures +@section Structures -The following directives provide support for @sc{c}-style @code{struct} -and @code{union} constructs. +The following directives provide support for @sc{c}-style @code{struct}, +@code{union}, and @code{enum} constructs. @table @code @@ -579,11 +610,32 @@ Start a structure. @item .union Start a union. +@item .enum +Define an enumeration type. + @item .ends End a structure, union, or enumeration. @end table +@menu +* Structures and Unions:: Using structures and unions. +* Enumerations:: Using enumerations. +@end menu + +@comment node-name, next, previous, up +@node Structures and Unions +@subsection Structures and Unions + +@pindex .ends +@pindex .struct +@pindex .union +@cindex structure, struct +@cindex structure, union +@cindex type, struct +@cindex type, union +@cindex structure, ending + In their usage, @code{.struct} is the same as @code{struct} in @sc{c}, and @code{.union} is the same as @code{union} in @sc{c}. For example, the construct @@ -666,9 +718,9 @@ When declaring the members of a structur @code{.struct} and @code{.union} can be used interchangably without changing the resulting layout of the final construct. In other words, @code{.struct} could be used when defining unions -and @code{.union} can be used when defining structures, but this -practice can be confusing and is not recommended. -The appropriate directive should always be used, but this is not enforced +and @code{.union} can be used when defining structures. +This practice is confusing and is @strong{not} recommended; the +appropriate directive should always be used, but this is not enforced (mostly because there is no way of detecting it). Variables can be declared to be structures or unions. @@ -732,6 +784,8 @@ xms_move_packet.dst_offset.off = X + 12 xms_move_packet.dst_offset.seg = X + 14 @end smallexample +@cindex structure, initializing + The @code{(.)} form is useful for initializing structures---just follow the declaration line by anonymous @code{.db} or @code{.dw} or @code{.dd} lines. @@ -743,8 +797,91 @@ specific address (e.g., the @sc{psp} str system tables). @comment node-name, next, previous, up +@node Enumerations +@subsection Enumerations + +@pindex .enum +@cindex structure, enumeration +@cindex type, enumeration + +The enumeration type allows arbitrary mnemonic identifiers (the +`enumeration constants') to be mapped to a set of integer values. +The classical textbook example is that of defining a boolean variable. +The following construct defines @samp{boolean} as an enumeration +type that can take the values 0 (@samp{false}) or 1 (@samp{true}). + +@example +.enum boolean + false + true +.ends +@end example + +@noindent +In this example, @samp{pets} is defined to be an enumeration type +having integral values 0 (@samp{bird}), 1 (@samp{cat}), 2 (@samp{dog}), +or 3 (@samp{rock}). + +@example +.enum pets + bird + cat + dog + rock +.ends +@end example + +@noindent +In a @code{djasm} program the above enumeration types could +be referenced as follows: + +@example +.start + nop + mov ax,true ; ax <- 1 + mov bx,pets.dog ; bx <- 2 + mov cx,pets.rock ; cx <- 3 + mov dx,pets.bird ; dx <- 0 + int 0x20 +@end example + +If the enumeration constants are not explicitly initialized, then they +are assigned consecutive integer values starting with zero. +Explicitly and implicitly initialized enumeration constants can be +used within the same enumeration type, in which case an enumeration +constant without an initializer will be assigned the successor of the +previous enumeration constant. + +In this example, the enumeration constants @samp{foo}, @samp{bar}, +and @samp{e} are implicitly initialized. +A variable of enumeration type @samp{snafu} therefore takes one of the +following integer values: 0 (@samp{foo}), 1 (@samp{bar}), 1 (@samp{a}), +2 (@samp{b}), 4 (@samp{c}), 8 (@samp{d}), or 9 (@samp{e}). + +@example +.enum snafu + foo + bar + a=1 + b=2 + c=4 + d=8 + e +.ends +@end example + +@comment node-name, next, previous, up @node Prefixes -@subsection Segment Override Prefixes +@section Segment Override Prefixes + +@pindex .addrsize +@pindex .opsize +@pindex .segcs +@pindex .segds +@pindex .seges +@pindex .segss +@pindex .segfs +@pindex .seggs Each prefix directive causes the appropriate instruction prefix byte to be emitted into the instruction stream. @@ -879,7 +1016,8 @@ a 16-bit segment. The following individuals (in alphabetical order) have contributed to @code{djasm}, or to its documentation, or both. If you have contributed to @code{djasm} in some way and are not -listed here, please make yourself known! +listed here, please make yourself known. +You can also let us know if your e-mail address is okay. @itemize @bullet{} @item @email{fighteer@@cs.com,John M. Aldrich} @@ -888,6 +1026,7 @@ listed here, please make yourself known! @item @email{nate@@cartsys.com,Nate Eldredge} @item @email{sandmann@@clio.rice.edu,Charles Sandmann} @item @email{mschulter@@value.net,Margo Schulter} +@item @email{ams@@ludd.luth.se,Martin Str@"omberg} @item @email{ucko@@vax1.rockhurst.edu,Aaron Ucko} @item @email{tudor@@cam.org,Vic} @item @email{terra@@diku.dk,Morten Welinder} @@ -895,12 +1034,16 @@ listed here, please make yourself known! @item @email{eliz@@is.elta.co.il,Eli Zaretskii} @end itemize -@ignore -@node Index @comment node-name, next, previous, up -@chapter Index +@node Topic Index +@chapter Topic Index -Here be the index (eventually). +@printindex cp + +@comment node-name, next, previous, up +@node Keyword Index +@chapter Keyword Index + +@printindex pg @bye -@end ignore