-Document (here) @code{APP}.
-@item
-Take advantage of knowing no spaces except after opcode
-to speed up @code{as}. (Modify @code{app.c} to flush useless spaces:
-only keep space/tabs at begin of line or between 2
-symbols.)
-@item
-Put pointers in this documentation to @file{a.out} documentation.
-@item
-Split the assembler into parts so it can gobble direct binary
-from @emph{e.g.} @code{cc}. It is silly for@code{cc} to compose text
-just so @code{as} can parse it back to binary.
-@item
-Rewrite hash functions: I want a more modular, faster library.
-@item
-Clean up LOTS of code.
-@item
-Include all the non-@file{.c} files in the maintenance chapter.
-@item
-Document flonums.
-@item
-Implement flonum short literals.
-@item
-Change all talk of expression operands to expression quantities,
-or perhaps to expression arguments.
-@item
-Implement pass 2.
-@item
-Whenever a @code{.text} or @code{.data} statement is seen, we close
-of the current frag with an imaginary @code{.fill 0}. This is
-because we only have one obstack for frags, and we can't grow new
-frags for a new subsegment, then go back to the old subsegment and
-append bytes to the old frag. All this nonsense goes away if we
-give each subsegment its own obstack. It makes code simpler in
-about 10 places, but nobody has bothered to do it because C compiler
-output rarely changes subsegments (compared to ending frags with
-relaxable addresses, which is common).
-@end itemize
-
-@section Sources
-@c The following files in the @file{as} directory
-@c are symbolic links to other files, of
-@c the same name, in a different directory.
-@c @itemize @bullet
-@c @item
-@c @file{atof_generic.c}
-@c @item
-@c @file{atof_vax.c}
-@c @item
-@c @file{flonum_const.c}
-@c @item
-@c @file{flonum_copy.c}
-@c @item
-@c @file{flonum_get.c}
-@c @item
-@c @file{flonum_multip.c}
-@c @item
-@c @file{flonum_normal.c}
-@c @item
-@c @file{flonum_print.c}
-@c @end itemize
-
-Here is a list of the source files in the @file{as} directory.
-
-@table @file
-@item app.c
-This contains the pre-processing phase, which deletes comments,
-handles whitespace, etc. This was recently re-written, since app
-used to be a separate program, but RMS wanted it to be inline.
-
-@item append.c
-This is a subroutine to append a string to another string returning a
-pointer just after the last @code{char} appended. (JF: All these
-little routines should probably all be put in one file.)
-
-@item as.c
-Here you will find the main program of the assembler @code{as}.
-
-@item expr.c
-This is a branch office of @file{read.c}. This understands
-expressions, arguments. Inside @code{as}, arguments are called
-(expression) @emph{operands}. This is confusing, because we also talk
-(elsewhere) about instruction @emph{operands}. Also, expression
-operands are called @emph{quantities} explicitly to avoid confusion
-with instruction operands. What a mess.
-
-@item frags.c
-This implements the @b{frag} concept. Without frags, finding the
-right size for branch instructions would be a lot harder.
-
-@item hash.c
-This contains the symbol table, opcode table @emph{etc.} hashing
-functions.
-
-@item hex_value.c
-This is a table of values of digits, for use in atoi() type
-functions. Could probably be flushed by using calls to strtol(), or
-something similar.
-
-@item input-file.c
-This contains Operating system dependent source file reading
-routines. Since error messages often say where we are in reading
-the source file, they live here too. Since @code{as} is intended to
-run under GNU and Unix only, this might be worth flushing. Anyway,
-almost all C compilers support stdio.
-
-@item input-scrub.c
-This deals with calling the pre-processor (if needed) and feeding the
-chunks back to the rest of the assembler the right way.
-
-@item messages.c
-This contains operating system independent parts of fatal and
-warning message reporting. See @file{append.c} above.
-
-@item output-file.c
-This contains operating system dependent functions that write an
-object file for @code{as}. See @file{input-file.c} above.
-
-@item read.c
-This implements all the directives of @code{as}. This also deals
-with passing input lines to the machine dependent part of the
-assembler.
-
-@item strstr.c
-This is a C library function that isn't in most C libraries yet.
-See @file{append.c} above.
-
-@item subsegs.c
-This implements subsegments.
-
-@item symbols.c
-This implements symbols.
-
-@item write.c
-This contains the code to perform relaxation, and to write out
-the object file. It is mostly operating system independent, but
-different OSes have different object file formats in any case.
-
-@item xmalloc.c
-This implements @code{malloc()} or bust. See @file{append.c} above.
-
-@item xrealloc.c
-This implements @code{realloc()} or bust. See @file{append.c} above.
-
-@item atof-generic.c
-The following files were taken from a machine-independent subroutine
-library for manipulating floating point numbers and very large
-integers.
-
-@file{atof-generic.c} turns a string into a flonum internal format
-floating-point number.
-
-@item flonum-const.c
-This contains some potentially useful floating point numbers in
-flonum format.
-
-@item flonum-copy.c
-This copies a flonum.
-
-@item flonum-multip.c
-This multiplies two flonums together.
-
-@item bignum-copy.c
-This copies a bignum.
-
-@end table
-
-Here is a table of all the machine-specific files (this includes
-both source and header files). Typically, there is a
-@var{machine}.c file, a @var{machine}-opcode.h file, and an
-atof-@var{machine}.c file. The @var{machine}-opcode.h file should
-be identical to the one used by GDB (which uses it for disassembly.)
-
-@table @file
-
-@item atof-ieee.c
-This contains code to turn a flonum into a ieee literal constant.
-This is used by tye 680x0, 32x32, sparc, and i386 versions of @code{as}.
-
-@item i386-opcode.h
-This is the opcode-table for the i386 version of the assembler.
-
-@item i386.c
-This contains all the code for the i386 version of the assembler.
-
-@item i386.h
-This defines constants and macros used by the i386 version of the assembler.
-
-@item m-generic.h
-generic 68020 header file. To be linked to m68k.h on a
-non-sun3, non-hpux system.
-
-@item m-sun2.h
-68010 header file for Sun2 workstations. Not well tested. To be linked
-to m68k.h on a sun2. (See also @samp{-DSUN_ASM_SYNTAX} in the
-@file{Makefile}.)
-
-@item m-sun3.h
-68020 header file for Sun3 workstations. To be linked to m68k.h before
-compiling on a Sun3 system. (See also @samp{-DSUN_ASM_SYNTAX} in the
-@file{Makefile}.)
-
-@item m-hpux.h
-68020 header file for a HPUX (system 5?) box. Which box, which
-version of HPUX, etc? I don't know.
-
-@item m68k.h
-A hard- or symbolic- link to one of @file{m-generic.h},
-@file{m-hpux.h} or @file{m-sun3.h} depending on which kind of
-680x0 you are assembling for. (See also @samp{-DSUN_ASM_SYNTAX} in the
-@file{Makefile}.)
-
-@item m68k-opcode.h
-Opcode table for 68020. This is now a link to the opcode table
-in the @code{GDB} source directory.
-
-@item m68k.c
-All the mc680x0 code, in one huge, slow-to-compile file.
-
-@item ns32k.c
-This contains the code for the ns32032/ns32532 version of the
-assembler.
-
-@item ns32k-opcode.h
-This contains the opcode table for the ns32032/ns32532 version
-of the assembler.
-
-@item vax-inst.h
-Vax specific file for describing Vax operands and other Vax-ish things.
-
-@item vax-opcode.h
-Vax opcode table.
-
-@item vax.c
-Vax specific parts of @code{as}. Also includes the former files
-@file{vax-ins-parse.c}, @file{vax-reg-parse.c} and @file{vip-op.c}.
-
-@item atof-vax.c
-Turns a flonum into a Vax constant.
-
-@item vms.c
-This file contains the special code needed to put out a VMS
-style object file for the Vax.
-
-@end table
-
-Here is a list of the header files in the source directory.
-(Warning: This section may not be very accurate. I didn't
-write the header files; I just report them.) Also note that I
-think many of these header files could be cleaned up or
-eliminated.
-
-@table @file
-
-@item a.out.h
-This describes the structures used to create the binary header data
-inside the object file. Perhaps we should use the one in
-@file{/usr/include}?
-
-@item as.h
-This defines all the globally useful things, and pulls in <stdio.h>
-and <assert.h>.
-
-@item bignum.h
-This defines macros useful for dealing with bignums.
-
-@item expr.h
-Structure and macros for dealing with expression()
-
-@item flonum.h
-This defines the structure for dealing with floating point
-numbers. It #includes @file{bignum.h}.
-
-@item frags.h
-This contains macro for appending a byte to the current frag.
-
-@item hash.h
-Structures and function definitions for the hashing functions.
-
-@item input-file.h
-Function headers for the input-file.c functions.
-
-@item md.h
-structures and function headers for things defined in the
-machine dependent part of the assembler.
-
-@item obstack.h
-This is the GNU systemwide include file for manipulating obstacks.
-Since nobody is running under real GNU yet, we include this file.
-
-@item read.h
-Macros and function headers for reading in source files.
-
-@item struct-symbol.h
-Structure definition and macros for dealing with the gas
-internal form of a symbol.
-
-@item subsegs.h
-structure definition for dealing with the numbered subsegments
-of the text and data segments.
-
-@item symbols.h
-Macros and function headers for dealing with symbols.
-
-@item write.h
-Structure for doing segment fixups.
-@end table
-
-@comment ~subsection Test Directory
-@comment (Note: The test directory seems to have disappeared somewhere
-@comment along the line. If you want it, you'll probably have to find a
-@comment REALLY OLD dump tape~dots{})
-@comment
-@comment The ~file{test/} directory is used for regression testing.
-@comment After you modify ~@code{as}, you can get a quick go/nogo
-@comment confidence test by running the new ~@code{as} over the source
-@comment files in this directory. You use a shell script ~file{test/do}.
-@comment
-@comment The tests in this suite are evolving. They are not comprehensive.
-@comment They have, however, caught hundreds of bugs early in the debugging
-@comment cycle of ~@code{as}. Most test statements in this suite were naturally
-@comment selected: they were used to demonstrate actual ~@code{as} bugs rather
-@comment than being written ~i{a prioi}.
-@comment
-@comment Another testing suggestion: over 30 bugs have been found simply by
-@comment running examples from this manual through ~@code{as}.
-@comment Some examples in this manual are selected
-@comment to distinguish boundary conditions; they are good for testing ~@code{as}.
-@comment
-@comment ~subsubsection Regression Testing
-@comment Each regression test involves assembling a file and comparing the
-@comment actual output of ~@code{as} to ``known good'' output files. Both
-@comment the object file and the error/warning message file (stderr) are
-@comment inspected. Optionally ~@code{as}' exit status may be checked.
-@comment Discrepencies are reported. Each discrepency means either that
-@comment you broke some part of ~@code{as} or that the ``known good'' files
-@comment are now out of date and should be changed to reflect the new
-@comment definition of ``good''.
-@comment
-@comment Each regression test lives in its own directory, in a tree
-@comment rooted in the directory ~file{test/}. Each such directory
-@comment has a name ending in ~file{.ret}, where `ret' stands for
-@comment REgression Test. The ~file{.ret} ending allows ~code{find
-@comment (1)} to find all regression tests in the tree, without
-@comment needing to list them explicitly.
-@comment
-@comment Any ~file{.ret} directory must contain a file called
-@comment ~file{input} which is the source file to assemble. During
-@comment testing an object file ~file{output} is created, as well as
-@comment a file ~file{stdouterr} which contains the output to both
-@comment stderr and stderr. If there is a file ~file{output.good} in
-@comment the directory, and if ~file{output} contains exactly the
-@comment same data as ~file{output.good}, the file ~file{output} is
-@comment deleted. Likewise ~file{stdouterr} is removed if it exactly
-@comment matches a file ~file{stdouterr.good}. If file
-@comment ~file{status.good} is present, containing a decimal number
-@comment before a newline, the exit status of ~@code{as} is compared
-@comment to this number. If the status numbers are not equal, a file
-@comment ~file{status} is written to the directory, containing the
-@comment actual status as a decimal number followed by newline.
-@comment
-@comment Should any of the ~file{*.good} files fail to match their corresponding
-@comment actual files, this is noted by a 1-line message on the screen during
-@comment the regression test, and you can use ~@code{find (1)} to find any
-@comment files named ~file{status}, ~file {output} or ~file{stdouterr}.
-@comment
-@node Retargeting, License, Maintenance, Top
-@chapter Teaching the Assembler about a New Machine
-
-This chapter describes the steps required in order to make the
-assembler work with another machine's assembly language. This
-chapter is not complete, and only describes the steps in the
-broadest terms. You should look at the source for the
-currently supported machine in order to discover some of the
-details that aren't mentioned here.
-
-You should create a new file called @file{@var{machine}.c}, and
-add the appropriate lines to the file @file{Makefile} so that
-you can compile your new version of the assembler. This should
-be straighforward; simply add lines similar to the ones there
-for the four current versions of the assembler.
-
-If you want to be compatible with GDB, (and the current
-machine-dependent versions of the assembler), you should create
-a file called @file{@var{machine}-opcode.h} which should
-contain all the information about the names of the machine
-instructions, their opcodes, and what addressing modes they
-support. If you do this right, the assembler and GDB can share
-this file, and you'll only have to write it once. Note that
-while you're writing @code{as}, you may want to use an
-independent program (if you have access to one), to make sure
-that @code{as} is emitting the correct bytes. Since @code{as}
-and @code{GDB} share the opcode table, an incorrect opcode
-table entry may make invalid bytes look OK when you disassemble
-them with @code{GDB}.
-
-@section Functions You will Have to Write
-
-Your file @file{@var{machine}.c} should contain definitions for
-the following functions and variables. It will need to include
-some header files in order to use some of the structures
-defined in the machine-independent part of the assembler. The
-needed header files are mentioned in the descriptions of the
-functions that will need them.
-
-@table @code
-
-@item long omagic;
-This long integer holds the value to place at the beginning of
-the @file{a.out} file. It is usually @samp{OMAGIC}, except on
-machines that store additional information in the magic-number.
-
-@item char comment_chars[];
-This character array holds the values of the characters that
-start a comment anywhere in a line. Comments are stripped off
-automatically by the machine independent part of the
-assembler. Note that the @samp{/*} will always start a
-comment, and that only @samp{*/} will end a comment started by
-@samp{*/}.
-
-@item char line_comment_chars[];
-This character array holds the values of the chars that start a
-comment only if they are the first (non-whitespace) character
-on a line. If the character @samp{#} does not appear in this
-list, you may get unexpected results. (Various
-machine-independent parts of the assembler treat the comments
-@samp{#APP} and @samp{#NO_APP} specially, and assume that lines
-that start with @samp{#} are comments.)
-
-@item char EXP_CHARS[];
-This character array holds the letters that can separate the
-mantissa and the exponent of a floating point number. Typical
-values are @samp{e} and @samp{E}.
-
-@item char FLT_CHARS[];
-This character array holds the letters that--when they appear
-immediately after a leading zero--indicate that a number is a
-floating-point number. (Sort of how 0x indicates that a
-hexadecimal number follows.)
-
-@item pseudo_typeS md_pseudo_table[];
-(@var{pseudo_typeS} is defined in @file{md.h})
-This array contains a list of the machine_dependent directives
-the assembler must support. It contains the name of each
-pseudo op (Without the leading @samp{.}), a pointer to a
-function to be called when that directive is encountered, and
-an integer argument to be passed to that function.
-
-@item void md_begin(void)
-This function is called as part of the assembler's
-initialization. It should do any initialization required by
-any of your other routines.
-
-@item int md_parse_option(char **optionPTR, int *argcPTR, char ***argvPTR)
-This routine is called once for each option on the command line
-that the machine-independent part of @code{as} does not
-understand. This function should return non-zero if the option
-pointed to by @var{optionPTR} is a valid option. If it is not
-a valid option, this routine should return zero. The variables
-@var{argcPTR} and @var{argvPTR} are provided in case the option
-requires a filename or something similar as an argument. If
-the option is multi-character, @var{optionPTR} should be
-advanced past the end of the option, otherwise every letter in
-the option will be treated as a separate single-character
-option.
-
-@item void md_assemble(char *string)
-This routine is called for every machine-dependent
-non-directive line in the source file. It does all the real
-work involved in reading the opcode, parsing the operands,
-etc. @var{string} is a pointer to a null-terminated string,
-that comprises the input line, with all excess whitespace and
-comments removed.
-
-@item void md_number_to_chars(char *outputPTR,long value,int nbytes)
-This routine is called to turn a C long int, short int, or char
-into the series of bytes that represents that number on the
-target machine. @var{outputPTR} points to an array where the
-result should be stored; @var{value} is the value to store; and
-@var{nbytes} is the number of bytes in 'value' that should be
-stored.
-
-@item void md_number_to_imm(char *outputPTR,long value,int nbytes)
-This routine is called to turn a C long int, short int, or char
-into the series of bytes that represent an immediate value on
-the target machine. It is identical to the function @code{md_number_to_chars},
-except on NS32K machines.@refill
-
-@item void md_number_to_disp(char *outputPTR,long value,int nbytes)
-This routine is called to turn a C long int, short int, or char
-into the series of bytes that represent an displacement value on
-the target machine. It is identical to the function @code{md_number_to_chars},
-except on NS32K machines.@refill
-
-@item void md_number_to_field(char *outputPTR,long value,int nbytes)
-This routine is identical to @code{md_number_to_chars},
-except on NS32K machines.
-
-@item void md_ri_to_chars(struct relocation_info *riPTR,ri)
-(@code{struct relocation_info} is defined in @file{a.out.h})
-This routine emits the relocation info in @var{ri}
-in the appropriate bit-pattern for the target machine.
-The result should be stored in the location pointed
-to by @var{riPTR}. This routine may be a no-op unless you are
-attempting to do cross-assembly.
-
-@item char *md_atof(char type,char *outputPTR,int *sizePTR)
-This routine turns a series of digits into the appropriate
-internal representation for a floating-point number.
-@var{type} is a character from @var{FLT_CHARS[]} that describes
-what kind of floating point number is wanted; @var{outputPTR}
-is a pointer to an array that the result should be stored in;
-and @var{sizePTR} is a pointer to an integer where the size (in
-bytes) of the result should be stored. This routine should
-return an error message, or an empty string (not (char *)0) for
-success.
-
-@item int md_short_jump_size;
-This variable holds the (maximum) size in bytes of a short (16
-bit or so) jump created by @code{md_create_short_jump()}. This
-variable is used as part of the broken-word feature, and isn't
-needed if the assembler is compiled with
-@samp{-DWORKING_DOT_WORD}.
-
-@item int md_long_jump_size;
-This variable holds the (maximum) size in bytes of a long (32
-bit or so) jump created by @code{md_create_long_jump()}. This
-variable is used as part of the broken-word feature, and isn't
-needed if the assembler is compiled with
-@samp{-DWORKING_DOT_WORD}.
-
-@item void md_create_short_jump(char *resultPTR,long from_addr,
-@code{long to_addr,fragS *frag,symbolS *to_symbol)}
-This function emits a jump from @var{from_addr} to @var{to_addr} in
-the array of bytes pointed to by @var{resultPTR}. If this creates a
-type of jump that must be relocated, this function should call
-@code{fix_new()} with @var{frag} and @var{to_symbol}. The jump
-emitted by this function may be smaller than @var{md_short_jump_size},
-but it must never create a larger one.
-(If it creates a smaller jump, the extra bytes of memory will not be
-used.) This function is used as part of the broken-word feature,
-and isn't needed if the assembler is compiled with
-@samp{-DWORKING_DOT_WORD}.@refill
-
-@item void md_create_long_jump(char *ptr,long from_addr,
-@code{long to_addr,fragS *frag,symbolS *to_symbol)}
-This function is similar to the previous function,
-@code{md_create_short_jump()}, except that it creates a long
-jump instead of a short one. This function is used as part of
-the broken-word feature, and isn't needed if the assembler is
-compiled with @samp{-DWORKING_DOT_WORD}.
-
-@item int md_estimate_size_before_relax(fragS *fragPTR,int segment_type)
-This function does the initial setting up for relaxation. This
-includes forcing references to still-undefined symbols to the
-appropriate addressing modes.
-
-@item relax_typeS md_relax_table[];
-(relax_typeS is defined in md.h)
-This array describes the various machine dependent states a
-frag may be in before relaxation. You will need one group of
-entries for each type of addressing mode you intend to relax.
-
-@item void md_convert_frag(fragS *fragPTR)
-(@var{fragS} is defined in @file{as.h})
-This routine does the required cleanup after relaxation.
-Relaxation has changed the type of the frag to a type that can
-reach its destination. This function should adjust the opcode
-of the frag to use the appropriate addressing mode.
-@var{fragPTR} points to the frag to clean up.
-
-@item void md_end(void)
-This function is called just before the assembler exits. It
-need not free up memory unless the operating system doesn't do
-it automatically on exit. (In which case you'll also have to
-track down all the other places where the assembler allocates
-space but never frees it.)
-
-@end table
-
-@section External Variables You will Need to Use
-
-You will need to refer to or change the following external variables
-from within the machine-dependent part of the assembler.
-
-@table @code
-@item extern char flagseen[];
-This array holds non-zero values in locations corresponding to
-the options that were on the command line. Thus, if the
-assembler was called with @samp{-W}, @var{flagseen['W']} would
-be non-zero.
-
-@item extern fragS *frag_now;
-This pointer points to the current frag--the frag that bytes
-are currently being added to. If nothing else, you will need
-to pass it as an argument to various machine-independent
-functions. It is maintained automatically by the
-frag-manipulating functions; you should never have to change it
-yourself.
-
-@item extern LITTLENUM_TYPE generic_bignum[];
-(@var{LITTLENUM_TYPE} is defined in @file{bignum.h}.
-This is where @dfn{bignums}--numbers larger than 32 bits--are
-returned when they are encountered in an expression. You will
-need to use this if you need to implement directives (or
-anything else) that must deal with these large numbers.
-@code{Bignums} are of @code{segT} @code{SEG_BIG} (defined in
-@file{as.h}, and have a positive @code{X_add_number}. The
-@code{X_add_number} of a @code{bignum} is the number of
-@code{LITTLENUMS} in @var{generic_bignum} that the number takes
-up.
-
-@item extern FLONUM_TYPE generic_floating_point_number;
-(@var{FLONUM_TYPE} is defined in @file{flonum.h}.
-The is where @dfn{flonums}--floating-point numbers within
-expressions--are returned. @code{Flonums} are of @code{segT}
-@code{SEG_BIG}, and have a negative @code{X_add_number}.
-@code{Flonums} are returned in a generic format. You will have
-to write a routine to turn this generic format into the
-appropriate floating-point format for your machine.
-
-@item extern int need_pass_2;
-If this variable is non-zero, the assembler has encountered an
-expression that cannot be assembled in a single pass. Since
-the second pass isn't implemented, this flag means that the
-assembler is punting, and is only looking for additional syntax
-errors. (Or something like that.)
-
-@item extern segT now_seg;
-This variable holds the value of the segment the assembler is
-currently assembling into.
-
-@end table
-
-@section External functions will you need
-
-You will find the following external functions useful (or
-indispensable) when you're writing the machine-dependent part
-of the assembler.
-
-@table @code
-
-@item char *frag_more(int bytes)
-This function allocates @var{bytes} more bytes in the current
-frag (or starts a new frag, if it can't expand the current frag
-any more.) for you to store some object-file bytes in. It
-returns a pointer to the bytes, ready for you to store data in.
-
-@item void fix_new(fragS *frag, int where, short size, symbolS *add_symbol, symbolS *sub_symbol, long offset, int pcrel)
-This function stores a relocation fixup to be acted on later.
-@var{frag} points to the frag the relocation belongs in;
-@var{where} is the location within the frag where the relocation begins;
-@var{size} is the size of the relocation, and is usually 1 (a single byte),
- 2 (sixteen bits), or 4 (a longword).
-The value @var{add_symbol} @minus{} @var{sub_symbol} + @var{offset}, is added to the byte(s)
-at @var{frag->literal[where]}. If @var{pcrel} is non-zero, the address of the
-location is subtracted from the result. A relocation entry is also added
-to the @file{a.out} file. @var{add_symbol}, @var{sub_symbol}, and/or
-@var{offset} may be NULL.@refill
-
-@item char *frag_var(relax_stateT type, int max_chars, int var,
-@code{relax_substateT subtype, symbolS *symbol, char *opcode)}
-This function creates a machine-dependent frag of type @var{type}
-(usually @code{rs_machine_dependent}).
-@var{max_chars} is the maximum size in bytes that the frag may grow by;
-@var{var} is the current size of the variable end of the frag;
-@var{subtype} is the sub-type of the frag. The sub-type is used to index into
-@var{md_relax_table[]} during @code{relaxation}.
-@var{symbol} is the symbol whose value should be used to when relax-ing this frag.
-@var{opcode} points into a byte whose value may have to be modified if the
-addressing mode used by this frag changes. It typically points into the
-@var{fr_literal[]} of the previous frag, and is used to point to a location
-that @code{md_convert_frag()}, may have to change.@refill
-
-@item void frag_wane(fragS *fragPTR)
-This function is useful from within @code{md_convert_frag}. It
-changes a frag to type rs_fill, and sets the variable-sized
-piece of the frag to zero. The frag will never change in size
-again.
-
-@item segT expression(expressionS *retval)
-(@var{segT} is defined in @file{as.h}; @var{expressionS} is defined in @file{expr.h})
-This function parses the string pointed to by the external char
-pointer @var{input_line_pointer}, and returns the segment-type
-of the expression. It also stores the results in the
-@var{expressionS} pointed to by @var{retval}.
-@var{input_line_pointer} is advanced to point past the end of
-the expression. (@var{input_line_pointer} is used by other
-parts of the assembler. If you modify it, be sure to restore
-it to its original value.)
-
-@item as_warn(char *message,@dots{})
-If warning messages are disabled, this function does nothing.
-Otherwise, it prints out the current file name, and the current
-line number, then uses @code{fprintf} to print the
-@var{message} and any arguments it was passed.
-
-@item as_bad(char *message,@dots{})
-This function should be called when @code{as} encounters
-conditions that are bad enough that @code{as} should not
-produce an object file, but should continue reading input and
-printing warning and bad error messages.
-
-@item as_fatal(char *message,@dots{})
-This function prints out the current file name and line number,
-prints the word @samp{FATAL:}, then uses @code{fprintf} to
-print the @var{message} and any arguments it was passed. Then
-the assembler exits. This function should only be used for
-serious, unrecoverable errors.
-
-@item void float_const(int float_type)
-This function reads floating-point constants from the current
-input line, and calls @code{md_atof} to assemble them. It is
-useful as the function to call for the directives
-@samp{.single}, @samp{.double}, @samp{.float}, etc.
-@var{float_type} must be a character from @var{FLT_CHARS}.
-
-@item void demand_empty_rest_of_line(void);
-This function can be used by machine-dependent directives to
-make sure the rest of the input line is empty. It prints a
-warning message if there are additional characters on the line.
-
-@item long int get_absolute_expression(void)
-This function can be used by machine-dependent directives to
-read an absolute number from the current input line. It
-returns the result. If it isn't given an absolute expression,
-it prints a warning message and returns zero.
-
-@end table
-
-
-@section The concept of Frags
-
-This assembler works to optimize the size of certain addressing
-modes. (e.g. branch instructions) This means the size of many
-pieces of object code cannot be determined until after assembly
-is finished. (This means that the addresses of symbols cannot be
-determined until assembly is finished.) In order to do this,
-@code{as} stores the output bytes as @dfn{frags}.
-
-Here is the definition of a frag (from @file{as.h})
-@example
-struct frag
-@{
- long int fr_fix;
- long int fr_var;
- relax_stateT fr_type;
- relax_substateT fr_substate;
- unsigned long fr_address;
- long int fr_offset;
- struct symbol *fr_symbol;
- char *fr_opcode;
- struct frag *fr_next;
- char fr_literal[];
-@}
-@end example
-
-@table @var
-@item fr_fix
-is the size of the fixed-size piece of the frag.
-
-@item fr_var
-is the maximum (?) size of the variable-sized piece of the frag.
-
-@item fr_type
-is the type of the frag.
-Current types are:
-rs_fill
-rs_align
-rs_org
-rs_machine_dependent
-
-@item fr_substate
-This stores the type of machine-dependent frag this is. (what
-kind of addressing mode is being used, and what size is being
-tried/will fit/etc.
-
-@item fr_address
-@var{fr_address} is only valid after relaxation is finished.
-Before relaxation, the only way to store an address is (pointer
-to frag containing the address) plus (offset into the frag).
-
-@item fr_offset
-This contains a number, whose meaning depends on the type of
-the frag.
-for machine_dependent frags, this contains the offset from
-fr_symbol that the frag wants to go to. Thus, for branch
-instructions it is usually zero. (unless the instruction was
-@samp{jba foo+12} or something like that.)
-
-@item fr_symbol
-for machine_dependent frags, this points to the symbol the frag
-needs to reach.
-
-@item fr_opcode
-This points to the location in the frag (or in a previous frag)
-of the opcode for the instruction that caused this to be a frag.
-@var{fr_opcode} is needed if the actual opcode must be changed
-in order to use a different form of the addressing mode.
-(For example, if a conditional branch only comes in size tiny,
-a large-size branch could be implemented by reversing the sense
-of the test, and turning it into a tiny branch over a large jump.
-This would require changing the opcode.)
-
-@var{fr_literal} is a variable-size array that contains the
-actual object bytes. A frag consists of a fixed size piece of
-object data, (which may be zero bytes long), followed by a
-piece of object data whose size may not have been determined
-yet. Other information includes the type of the frag (which
-controls how it is relaxed),
-
-@item fr_next
-This is the next frag in the singly-linked list. This is
-usually only needed by the machine-independent part of
-@code{as}.
-
-@end table
-@end ignore
-
-@node License, , Retargeting, Top
-@unnumbered GNU GENERAL PUBLIC LICENSE
-@center Version 1, February 1989
-
-@display
-Copyright @copyright{} 1989 Free Software Foundation, Inc.
-675 Mass Ave, Cambridge, MA 02139, USA
-
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
-@end display
-
-@unnumberedsec Preamble
-
- The license agreements of most software companies try to keep users
-at the mercy of those companies. By contrast, our General Public
-License is intended to guarantee your freedom to share and change free
-software---to make sure the software is free for all its users. The
-General Public License applies to the Free Software Foundation's
-software and to any other program whose authors commit to using it.
-You can use it for your programs, too.
-
- When we speak of free software, we are referring to freedom, not
-price. Specifically, the General Public License is designed to make
-sure that you have the freedom to give away or sell copies of free
-software, that you receive source code or can get it if you want it,
-that you can change the software or use pieces of it in new free
-programs; and that you know you can do these things.
-
- To protect your rights, we need to make restrictions that forbid
-anyone to deny you these rights or to ask you to surrender the rights.
-These restrictions translate to certain responsibilities for you if you
-distribute copies of the software, or if you modify it.
-
- For example, if you distribute copies of a such a program, whether
-gratis or for a fee, you must give the recipients all the rights that
-you have. You must make sure that they, too, receive or can get the
-source code. And you must tell them their rights.
-
- We protect your rights with two steps: (1) copyright the software, and
-(2) offer you this license which gives you legal permission to copy,
-distribute and/or modify the software.
-
- Also, for each author's protection and ours, we want to make certain
-that everyone understands that there is no warranty for this free
-software. If the software is modified by someone else and passed on, we
-want its recipients to know that what they have is not the original, so
-that any problems introduced by others will not reflect on the original
-authors' reputations.
-
- The precise terms and conditions for copying, distribution and
-modification follow.
-
-@iftex
-@unnumberedsec TERMS AND CONDITIONS
-@end iftex
-@ifinfo
-@center TERMS AND CONDITIONS
-@end ifinfo
-
-@enumerate
-@item
-This License Agreement applies to any program or other work which
-contains a notice placed by the copyright holder saying it may be
-distributed under the terms of this General Public License. The
-``Program'', below, refers to any such program or work, and a ``work based
-on the Program'' means either the Program or any work containing the
-Program or a portion of it, either verbatim or with modifications. Each
-licensee is addressed as ``you''.