This is the mail archive of the
binutils@sources.redhat.com
mailing list for the binutils project.
Assembler documenation update
- To: binutils at sources dot redhat dot com
- Subject: Assembler documenation update
- From: Nick Clifton <nickc at redhat dot com>
- Date: 23 Mar 2001 11:37:15 -0800
Hi Guys,
I have checked in the patch below to add documentation for the
--listing-XXX series of command line switches supported by GAS. The
patch also includes a paragraph explaining why listings created when
-pipe is used do not include assembler comments in them.
Cheers
Nick
2001-03-23 Nick Clifton <nickc@redhat.com>
* doc/as.texinfo: Document --listing-XXX command line switches.
Explain why listings behave differently when -pipe is used.
Index: gas/doc/as.texinfo
===================================================================
RCS file: /cvs/src//src/gas/doc/as.texinfo,v
retrieving revision 1.35
diff -p -r1.35 as.texinfo
*** as.texinfo 2001/03/08 23:24:26 1.35
--- as.texinfo 2001/03/23 19:33:49
*************** Here is a brief summary of how to invoke
*** 202,207 ****
--- 202,209 ----
@smallexample
@value{AS} [ -a[cdhlns][=file] ] [ -D ] [ --defsym @var{sym}=@var{val} ]
[ -f ] [ --gstabs ] [ --gdwarf2 ] [ --help ] [ -I @var{dir} ] [ -J ] [ -K ] [ -L ]
+ [ --listing--lhs-width=NUM ][ --listing-lhs-width2=NUM ]
+ [ --listing-rhs-width=NUM ][ --listing-cont-lines=NUM ]
[ --keep-locals ] [ -o @var{objfile} ] [ -R ] [ --statistics ] [ -v ]
[ -version ] [ --version ] [ -W ] [ --warn ] [ --fatal-warnings ]
[ -w ] [ -x ] [ -Z ] [ --target-help ]
*************** Keep (in the symbol table) local symbols
*** 369,374 ****
--- 371,392 ----
these start with @samp{L}, but different systems have different local
label prefixes.
+ @item --listing-lhs-width=@var{number}
+ Set the maximum width, in words, of the output data column for an assembler
+ listing to @var{number}.
+
+ @item --listing-lhs-width2=@var{number}
+ Set the maximum width, in words, of the output data column for continuation
+ lines in an assembler listing to @var{number}.
+
+ @item --listing-rhs-width=@var{number}
+ Set the maximum width of an input source line, as displayed in a listing, to
+ @var{number} bytes.
+
+ @item --listing-cont-lines=@var{number}
+ Set the maximum number of lines printed in a listing for a single line of input
+ to @var{number} + 1.
+
@item -o @var{objfile}
Name the object-file output from @code{@value{AS}} @var{objfile}.
*************** assembler.)
*** 1154,1159 ****
--- 1172,1178 ----
@end ifset
* L:: -L to retain local labels
+ * listing:: --listing-XXX to configure listing output
* M:: -M or --mri to assemble in MRI compatibility mode
* MD:: --MD for dependency tracking
* o:: -o to name the object file
*************** listing-control directives have no effec
*** 1207,1212 ****
--- 1226,1238 ----
The letters after @samp{-a} may be combined into one option,
@emph{e.g.}, @samp{-aln}.
+ Note if the assembler source is coming from the standard input (eg because it
+ is being created by @code{@value{GCC}} and the @samp{-pipe} command line switch
+ is being used) then the listing will not contain any comments or preprocessor
+ directives. This is because the listing code buffers input source lines from
+ stdin only after they have been preprocessed by the assembler. This reduces
+ memory usage and makes the code more efficient.
+
@node D
@section @code{-D}
*************** target is allowed to redefine the local
*** 1291,1296 ****
--- 1317,1361 ----
@ifset HPPA
On the HPPA local labels begin with @samp{L$}.
@end ifset
+
+ @node listing
+ @section Configuringh listing output: @code{--listing}
+
+ The listing feature of the assembler can be enabled via the command line switch
+ @samp{-a} (@pxref{a}). This feature combines the input source file(s) with a
+ hex dump of the corresponding locations in the output object file, and displays
+ them as a listing file. The format of this listing can be controlled by pseudo
+ ops inside the assembler source (@pxref{List} @pxref{Title} @pxref{Sbttl}
+ @pxref{Psize} @pxref{Eject}) and also by the following switches:
+
+ @table @code
+ @item --listing-lhs-width=@samp{number}
+ @kindex --listing-lhs-width
+ @cindex Width of first line disassembly output
+ Sets the maximum width, in words, of the first line of the hex byte dump. This
+ dump appears on the left hand side of the listing output.
+
+ @item --listing-lhs-width2=@samp{number}
+ @kindex --listing-lhs-width2
+ @cindex Width of continuation lines of disassembly output
+ Sets the maximum width, in words, of any further lines of the hex byte dump for
+ a given inut source line. If this value is not specified, it defaults to being
+ the same as the value specified for @samp{--listing-lhs-width}. If neither
+ switch is used the default is to one.
+
+ @item --listing-rhs-width=@samp{number}
+ @kindex --listing-rhs-width
+ @cindex Width of source line output
+ Sets the maximum width, in characters, of the source line that is displayed
+ alongside the hex dump. The default value for this parameter is 100. The
+ source line is displayed on the right hand side of the listing output.
+
+ @item --listing-cont-lines=@samp{number}
+ @kindex --listing-cont-lines
+ @cindex Maximum number of continuation lines
+ Sets the maximum number of continuation lines of hex dump that will be
+ displayed for a given single line of source input. The default value is 4.
+ @end table
@node M
@section Assemble in MRI Compatibility Mode: @code{-M}