From: Peter Johnson Date: Sat, 21 Oct 2006 18:52:29 +0000 (-0000) Subject: Add yasm_parsers(7), yasm_objfmts(7), and yasm_dbgfmts(7) man pages, X-Git-Tag: v0.6.0~118 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=47af5c24f1bd2cb2ae8b9305f13070f282f78ae0;p=yasm Add yasm_parsers(7), yasm_objfmts(7), and yasm_dbgfmts(7) man pages, mostly copied from the yasm manual. svn path=/trunk/yasm/; revision=1662 --- diff --git a/frontends/yasm/yasm.xml b/frontends/yasm/yasm.xml index a0d86001..8bdd1331 100644 --- a/frontends/yasm/yasm.xml +++ b/frontends/yasm/yasm.xml @@ -137,7 +137,7 @@ format. See - yasm_objfmt + yasm_objfmts 7 @@ -162,7 +162,7 @@ help as debug. See - yasm_dbgfmt + yasm_dbgfmts 7 @@ -514,11 +514,11 @@ 7 , - yasm_dbgfmt + yasm_dbgfmts 7 , - yasm_objfmt + yasm_objfmts 7 , diff --git a/modules/arch/yasm_arch.xml b/modules/arch/yasm_arch.xml index 91c57d77..46002919 100644 --- a/modules/arch/yasm_arch.xml +++ b/modules/arch/yasm_arch.xml @@ -7,9 +7,9 @@ - Yasm Supported Target Architectures + Yasm Supported Architectures October 2006 - YASM + Yasm Peter Johnson diff --git a/modules/dbgfmts/Makefile.inc b/modules/dbgfmts/Makefile.inc index cf0a5ffd..be53622c 100644 --- a/modules/dbgfmts/Makefile.inc +++ b/modules/dbgfmts/Makefile.inc @@ -9,3 +9,12 @@ include modules/dbgfmts/codeview/Makefile.inc include modules/dbgfmts/dwarf2/Makefile.inc include modules/dbgfmts/null/Makefile.inc include modules/dbgfmts/stabs/Makefile.inc + +dist_man_MANS += yasm_dbgfmts.7 + +if BUILD_MAN +yasm_dbgfmts.7: modules/dbgfmts/yasm_dbgfmts.xml + $(XMLTO) -o $(top_builddir) man $(srcdir)/modules/dbgfmts/yasm_dbgfmts.xml +endif + +EXTRA_DIST += modules/dbgfmts/yasm_dbgfmts.xml diff --git a/modules/dbgfmts/yasm_dbgfmts.xml b/modules/dbgfmts/yasm_dbgfmts.xml new file mode 100644 index 00000000..5b15925f --- /dev/null +++ b/modules/dbgfmts/yasm_dbgfmts.xml @@ -0,0 +1,127 @@ + + + + + + + + + Yasm Supported Debug Formats + October 2006 + Yasm + + Peter + Johnson + +
peter@tortall.net
+ + + + + 2006 + Peter Johnson + + + + + yasm_dbgfmts + 7 + + + + yasm_dbgfmts + Yasm Supported Debugging Formats + + + + + yasm + + + + + + + + + + + Description + + The standard Yasm distribution includes a number of modules + for different debugging formats. The debugging information is + embedded into the object file. Use of a non-null + debug format also causes Yasm to output all symbols to the object + file (including local symbols). + + The debug format is selected on the + + + yasm + 1 + + + command line by use of the command line + option. + + + + cv8 + + The CV8 debug format is used by Microsoft Visual Studio 2005 + (version 8.0) and is completely undocumented, although it bears + strong similarities to earlier CodeView formats. Yasm's support + for the CV8 debug format is currently limited to generating + assembly-level line number information (to allow some level of + source-level debugging). The CV8 debug information is stored in + the .debug$S and .debug$T sections of the Win64 object file. + + + + dwarf2 + + The DWARF 2 debug format is a complex, well-documented + standard for debugging information. It was created to overcome + shortcomings in STABS, allowing for much more detailed and compact + descriptions of data structures, data variable movement, and + complex language structures such as in C++. The debugging + information is stored in sections (just like normal program + sections) in the object file. Yasm supports full pass-through of + DWARF2 debugging information (e.g. from a C++ compiler), and can + also generate assembly-level line number information. + + + + null + + The null debug format is a placeholder; it adds + no debugging information to the output file. + + + + stabs + + The STABS debug format is a poorly documented, semi-standard + format for debugging information in COFF and ELF object files. The + debugging information is stored as part of the object file's symbol + table and thus is limited in complexity and scope. Despite this, + STABS is a common debugging format on older Unix and compatible + systems, as well as DJGPP. + + + + See Also + + + yasm + 1 + , + + + yasm_objfmts + 7 + + + diff --git a/modules/objfmts/Makefile.inc b/modules/objfmts/Makefile.inc index c4e562b5..4deb5725 100644 --- a/modules/objfmts/Makefile.inc +++ b/modules/objfmts/Makefile.inc @@ -19,3 +19,12 @@ include modules/objfmts/rdf/Makefile.inc include modules/objfmts/win32/Makefile.inc include modules/objfmts/win64/Makefile.inc include modules/objfmts/xdf/Makefile.inc + +dist_man_MANS += yasm_objfmts.7 + +if BUILD_MAN +yasm_objfmts.7: modules/objfmts/yasm_objfmts.xml + $(XMLTO) -o $(top_builddir) man $(srcdir)/modules/objfmts/yasm_objfmts.xml +endif + +EXTRA_DIST += modules/objfmts/yasm_objfmts.xml diff --git a/modules/objfmts/yasm_objfmts.xml b/modules/objfmts/yasm_objfmts.xml new file mode 100644 index 00000000..1e9f095f --- /dev/null +++ b/modules/objfmts/yasm_objfmts.xml @@ -0,0 +1,158 @@ + + + + + + + + + Yasm Supported Object Formats + October 2006 + Yasm + + Peter + Johnson + +
peter@tortall.net
+ + + + + 2006 + Peter Johnson + + + + + yasm_objfmts + 7 + + + + yasm_objfmts + Yasm Supported Object Formats + + + + + yasm + + + + + + + + + + + Description + + The standard Yasm distribution includes a number of modules + for different object formats (Yasm's primary output). + + The object format is selected on the + + + yasm + 1 + + + command line by use of the command line + option. + + + + bin + + The bin object format produces a flat-format, + non-relocatable binary file. It is appropriate for producing DOS + .COM executables or things like boot blocks. It supports only 3 + sections and those sections are written in a predefined order to + the output file. + + + + coff + + The COFF object format is an older relocatable object format + used on older Unix and compatible systems, and also (more recently) + on the DJGPP development system for DOS. + + + + dbg + + The dbg object format is not a + real object format; the output file it creates + simply describes the sequence of calls made to it by Yasm and the + final object and symbol table information in a human-readable text + format (that in a normal object format would get processed into + that object format's particular binary representation). This + object format is not intended for real use, but rather for + debugging Yasm's internals. + + + + elf + + The ELF object format really comes in two flavors: + elf32 (for 32-bit targets) and elf64 + (for 64-bit targets). ELF is a standard object format in common + use on modern Unix and compatible systems (e.g. Linux, FreeBSD). + ELF has complex support for relocatable and shared objects. + + + + rdf + + The RDOFF2 object format is a simple multi-section format + originally designed for NASM. It supports segment references but + not WRT references. It was designed primarily for simplicity and + has minimalistic headers for ease of loading and linking. A + complete toolchain (linker, librarian, and loader) is distributed + with NASM. + + + + win32 + + The Win32 object format produces object files compatible with + Microsoft compilers (such as Visual C++) that target the 32-bit x86 + Windows platform. The object format itself is an extended version + of COFF. + + + + win64 + + The Win64 object format produces object files compatible with + Microsoft compilers that target the 64-bit x64 + Windows platform. This format is very similar to the win32 object + format, but produces 64-bit objects. + + + + xdf + + The XDF object format is essentially a simplified version of + COFF. It's a multi-section relocatable format that supports 64-bit + physical and virtual addresses. + + + + See Also + + + yasm + 1 + , + + + yasm_arch + 7 + + + diff --git a/modules/parsers/Makefile.inc b/modules/parsers/Makefile.inc index eabd5f60..89bfd35b 100644 --- a/modules/parsers/Makefile.inc +++ b/modules/parsers/Makefile.inc @@ -5,3 +5,12 @@ EXTRA_DIST += modules/parsers/nasm/Makefile.inc include modules/parsers/gas/Makefile.inc include modules/parsers/nasm/Makefile.inc + +dist_man_MANS += yasm_parsers.7 + +if BUILD_MAN +yasm_parsers.7: modules/parsers/yasm_parsers.xml + $(XMLTO) -o $(top_builddir) man $(srcdir)/modules/parsers/yasm_parsers.xml +endif + +EXTRA_DIST += modules/parsers/yasm_parsers.xml diff --git a/modules/parsers/yasm_parsers.xml b/modules/parsers/yasm_parsers.xml new file mode 100644 index 00000000..d29421de --- /dev/null +++ b/modules/parsers/yasm_parsers.xml @@ -0,0 +1,114 @@ + + + + + + + + + Yasm Supported Parsers + October 2006 + Yasm + + Peter + Johnson + +
peter@tortall.net
+ + + + + 2006 + Peter Johnson + + + + + yasm_parsers + 7 + + + + yasm_parsers + Yasm Supported Parsers (Assembler Syntaxes) + + + + + yasm + + + + + + + + + + + + + + Description + + The standard Yasm distribution includes a number of modules + for different parsers (assembler syntaxes). + + The parser is selected on the + + + yasm + 1 + + + command line by use of the command line + option. + + + + NASM Parser + + NASM syntax, selected with , is the + most full-featured syntax supported by Yasm. Yasm is nearly 100% + compatible with NASM for 16-bit and 32-bit x86 code. Yasm + additionally supports 64-bit AMD64 code with Yasm extensions to the + NASM syntax; see + + + yasm_arch + 7 + + + for details. NASM syntax is the Yasm default. + + + + GAS Parser + + The GNU Assembler (GAS) is the de-facto cross-platform + assembler for modern Unix systems, and is used as the backend for + the GCC compiler. Yasm's support for GAS syntax is moderately + good, although immature: not all directives are supported, and only + 32-bit x86 and AMD64 architectures are supported. There is also no + support for the GAS preprocessor. Despite these limitations, + Yasm's GAS syntax support is good enough to handle essentially all + x86 and AMD64 GCC compiler output. The GAS parser can be selected + with . + + + + See Also + + + yasm + 1 + , + + + yasm_arch + 7 + + + diff --git a/yasm.1 b/yasm.1 index 9f91f5f4..a70a3a8e 100644 --- a/yasm.1 +++ b/yasm.1 @@ -74,7 +74,7 @@ Selects the output object format. The default object format is \(lqhelp\(rq as \fIformat\fR. See -\fByasm_objfmt\fR(7) +\fByasm_objfmts\fR(7) for a list of supported object formats. .TP 3n \fB\-g \fR\fB\fIdebug\fR\fR or \fB\-\-dformat=\fR\fB\fIdebug\fR\fR: Select debugging format @@ -84,7 +84,7 @@ will error when an invalid combination is selected. The default object format is \(lqhelp\(rq as \fIdebug\fR. See -\fByasm_dbgfmt\fR(7) +\fByasm_dbgfmts\fR(7) for a list of supported debugging formats. .TP 3n \fB\-h\fR or \fB\-\-help\fR: Print a summary of options @@ -261,8 +261,8 @@ There is no support for symbol maps. .SH "SEE ALSO" .PP \fByasm_arch\fR(7), -\fByasm_dbgfmt\fR(7), -\fByasm_objfmt\fR(7), +\fByasm_dbgfmts\fR(7), +\fByasm_objfmts\fR(7), \fByasm_parsers\fR(7) .PP Related tools: diff --git a/yasm_arch.7 b/yasm_arch.7 index 7694dd73..dd329c5b 100644 --- a/yasm_arch.7 +++ b/yasm_arch.7 @@ -2,10 +2,10 @@ .\" Author: Peter Johnson .\" Generator: DocBook XSL Stylesheets v1.70.1 .\" Date: October 2006 -.\" Manual: Yasm Supported Target Architectures -.\" Source: YASM +.\" Manual: Yasm Supported Architectures +.\" Source: Yasm .\" -.TH "YASM_ARCH" "7" "October 2006" "YASM" "Yasm Supported Target Architec" +.TH "YASM_ARCH" "7" "October 2006" "Yasm" "Yasm Supported Architectures" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) diff --git a/yasm_dbgfmts.7 b/yasm_dbgfmts.7 new file mode 100644 index 00000000..2227d8cf --- /dev/null +++ b/yasm_dbgfmts.7 @@ -0,0 +1,53 @@ +.\" Title: yasm_dbgfmts +.\" Author: Peter Johnson +.\" Generator: DocBook XSL Stylesheets v1.70.1 +.\" Date: October 2006 +.\" Manual: Yasm Supported Debug Formats +.\" Source: Yasm +.\" +.TH "YASM_DBGFMTS" "7" "October 2006" "Yasm" "Yasm Supported Debug Formats" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +yasm_dbgfmts \- Yasm Supported Debugging Formats +.SH "SYNOPSIS" +.HP 5 +\fByasm\fR \fB\-g\ \fR\fB\fIdbgfmt\fR\fR \fB\fI...\fR\fR +.SH "DESCRIPTION" +.PP +The standard Yasm distribution includes a number of modules for different debugging formats. The debugging information is embedded into the object file. Use of a non\-\(lqnull\(rq +debug format also causes Yasm to output all symbols to the object file (including local symbols). +.PP +The debug format is selected on the +\fByasm\fR(1) +command line by use of the +\fB\-g \fR\fB\fIdbgfmt\fR\fR +command line option. +.SH "CV8" +.PP +The CV8 debug format is used by Microsoft Visual Studio 2005 (version 8.0) and is completely undocumented, although it bears strong similarities to earlier CodeView formats. Yasm's support for the CV8 debug format is currently limited to generating assembly\-level line number information (to allow some level of source\-level debugging). The CV8 debug information is stored in the .debug$S and .debug$T sections of the Win64 object file. +.SH "DWARF2" +.PP +The DWARF 2 debug format is a complex, well\-documented standard for debugging information. It was created to overcome shortcomings in STABS, allowing for much more detailed and compact descriptions of data structures, data variable movement, and complex language structures such as in C++. The debugging information is stored in sections (just like normal program sections) in the object file. Yasm supports full pass\-through of DWARF2 debugging information (e.g. from a C++ compiler), and can also generate assembly\-level line number information. +.SH "NULL" +.PP +The +\(lqnull\(rq +debug format is a placeholder; it adds no debugging information to the output file. +.SH "STABS" +.PP +The STABS debug format is a poorly documented, semi\-standard format for debugging information in COFF and ELF object files. The debugging information is stored as part of the object file's symbol table and thus is limited in complexity and scope. Despite this, STABS is a common debugging format on older Unix and compatible systems, as well as DJGPP. +.SH "SEE ALSO" +.PP +\fByasm\fR(1), +\fByasm_objfmts\fR(7) +.SH "AUTHOR" +.PP +\fBPeter\fR \fBJohnson\fR +.sp -1n +.IP "" 3n +Author. +.SH "COPYRIGHT" +Copyright \(co 2006 Peter Johnson diff --git a/yasm_objfmts.7 b/yasm_objfmts.7 new file mode 100644 index 00000000..b36288d2 --- /dev/null +++ b/yasm_objfmts.7 @@ -0,0 +1,74 @@ +.\" Title: yasm_objfmts +.\" Author: Peter Johnson +.\" Generator: DocBook XSL Stylesheets v1.70.1 +.\" Date: October 2006 +.\" Manual: Yasm Supported Object Formats +.\" Source: Yasm +.\" +.TH "YASM_OBJFMTS" "7" "October 2006" "Yasm" "Yasm Supported Object Formats" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +yasm_objfmts \- Yasm Supported Object Formats +.SH "SYNOPSIS" +.HP 5 +\fByasm\fR \fB\-f\ \fR\fB\fIobjfmt\fR\fR \fB\fI...\fR\fR +.SH "DESCRIPTION" +.PP +The standard Yasm distribution includes a number of modules for different object formats (Yasm's primary output). +.PP +The object format is selected on the +\fByasm\fR(1) +command line by use of the +\fB\-f \fR\fB\fIobjfmt\fR\fR +command line option. +.SH "BIN" +.PP +The +\(lqbin\(rq +object format produces a flat\-format, non\-relocatable binary file. It is appropriate for producing DOS .COM executables or things like boot blocks. It supports only 3 sections and those sections are written in a predefined order to the output file. +.SH "COFF" +.PP +The COFF object format is an older relocatable object format used on older Unix and compatible systems, and also (more recently) on the DJGPP development system for DOS. +.SH "DBG" +.PP +The +\(lqdbg\(rq +object format is not a +\(lqreal\(rq +object format; the output file it creates simply describes the sequence of calls made to it by Yasm and the final object and symbol table information in a human\-readable text format (that in a normal object format would get processed into that object format's particular binary representation). This object format is not intended for real use, but rather for debugging Yasm's internals. +.SH "ELF" +.PP +The ELF object format really comes in two flavors: +\(lqelf32\(rq +(for 32\-bit targets) and +\(lqelf64\(rq +(for 64\-bit targets). ELF is a standard object format in common use on modern Unix and compatible systems (e.g. Linux, FreeBSD). ELF has complex support for relocatable and shared objects. +.SH "RDF" +.PP +The RDOFF2 object format is a simple multi\-section format originally designed for NASM. It supports segment references but not WRT references. It was designed primarily for simplicity and has minimalistic headers for ease of loading and linking. A complete toolchain (linker, librarian, and loader) is distributed with NASM. +.SH "WIN32" +.PP +The Win32 object format produces object files compatible with Microsoft compilers (such as Visual C++) that target the 32\-bit x86 Windows platform. The object format itself is an extended version of COFF. +.SH "WIN64" +.PP +The Win64 object format produces object files compatible with Microsoft compilers that target the 64\-bit +\(lqx64\(rq +Windows platform. This format is very similar to the win32 object format, but produces 64\-bit objects. +.SH "XDF" +.PP +The XDF object format is essentially a simplified version of COFF. It's a multi\-section relocatable format that supports 64\-bit physical and virtual addresses. +.SH "SEE ALSO" +.PP +\fByasm\fR(1), +\fByasm_arch\fR(7) +.SH "AUTHOR" +.PP +\fBPeter\fR \fBJohnson\fR +.sp -1n +.IP "" 3n +Author. +.SH "COPYRIGHT" +Copyright \(co 2006 Peter Johnson diff --git a/yasm_parsers.7 b/yasm_parsers.7 new file mode 100644 index 00000000..a418b6f1 --- /dev/null +++ b/yasm_parsers.7 @@ -0,0 +1,48 @@ +.\" Title: yasm_parsers +.\" Author: Peter Johnson +.\" Generator: DocBook XSL Stylesheets v1.70.1 +.\" Date: October 2006 +.\" Manual: Yasm Supported Parsers +.\" Source: Yasm +.\" +.TH "YASM_PARSERS" "7" "October 2006" "Yasm" "Yasm Supported Parsers" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +yasm_parsers \- Yasm Supported Parsers (Assembler Syntaxes) +.SH "SYNOPSIS" +.HP 5 +\fByasm\fR \fB\-p\ \fR\fB\fIparser\fR\fR [\fB\-r\ \fR\fB\fIpreproc\fR\fR] \fB\fI...\fR\fR +.SH "DESCRIPTION" +.PP +The standard Yasm distribution includes a number of modules for different parsers (assembler syntaxes). +.PP +The parser is selected on the +\fByasm\fR(1) +command line by use of the +\fB\-p \fR\fB\fIparser\fR\fR +command line option. +.SH "NASM PARSER" +.PP +NASM syntax, selected with +\fB\-p nasm\fR, is the most full\-featured syntax supported by Yasm. Yasm is nearly 100% compatible with NASM for 16\-bit and 32\-bit x86 code. Yasm additionally supports 64\-bit AMD64 code with Yasm extensions to the NASM syntax; see +\fByasm_arch\fR(7) +for details. NASM syntax is the Yasm default. +.SH "GAS PARSER" +.PP +The GNU Assembler (GAS) is the de\-facto cross\-platform assembler for modern Unix systems, and is used as the backend for the GCC compiler. Yasm's support for GAS syntax is moderately good, although immature: not all directives are supported, and only 32\-bit x86 and AMD64 architectures are supported. There is also no support for the GAS preprocessor. Despite these limitations, Yasm's GAS syntax support is good enough to handle essentially all x86 and AMD64 GCC compiler output. The GAS parser can be selected with +\fB\-p gas\fR. +.SH "SEE ALSO" +.PP +\fByasm\fR(1), +\fByasm_arch\fR(7) +.SH "AUTHOR" +.PP +\fBPeter\fR \fBJohnson\fR +.sp -1n +.IP "" 3n +Author. +.SH "COPYRIGHT" +Copyright \(co 2006 Peter Johnson