From 40eabefe89637cf69b7388d0210f68664b503600 Mon Sep 17 00:00:00 2001 From: uz Date: Fri, 30 Jul 2010 19:33:53 +0000 Subject: [PATCH] Added documentation for the od65 utility. git-svn-id: svn://svn.cc65.org/cc65/trunk@4770 b7a2c559-68d2-44c3-8de9-860c34a00d81 --- doc/Makefile | 1 + doc/od65.sgml | 214 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 215 insertions(+) create mode 100644 doc/od65.sgml diff --git a/doc/Makefile b/doc/Makefile index 13ea979c7..1a0050627 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -46,6 +46,7 @@ SGML = apple2.sgml \ lynx.sgml \ make.sgml \ nes.sgml \ + od65.sgml \ pet.sgml \ plus4.sgml \ supervision.sgml\ diff --git a/doc/od65.sgml b/doc/od65.sgml new file mode 100644 index 000000000..51f44b030 --- /dev/null +++ b/doc/od65.sgml @@ -0,0 +1,214 @@ + + +
+od65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2010-07-30 + +<abstract> +od65 is the object file dump utility. It is able to output most parts of +<htmlurl url="ca65.html" name="ca65"> generated object files in readable form. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + + +<sect>Overview<p> + +od65 is an object file dump utility. It is able to output most parts of +<htmlurl url="ca65.html" name="ca65"> generated object files in readable form. +Since the contents and format of the object files are not documented +elsewhere and may change at any time, this tool is a portable way to look at +the contents. + +Apart from curiosity, most people don't need to use this tool. + + + +<sect>Usage<p> + +The od65 utility dumps contents of one or more ca65 generated object file to +standard output. It has no cross-version compatibility, so you have to use +a version that matches the version of ca65 used to create the object files. + + +<sect1>Command line option overview<p> + +The program may be called as follows: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: od65 [options] file [options] [file] +Short options: + -h Help (this text) + -H Dump the object file header + -S Dump segments sizes + -V Print the version number and exit + +Long options: + --dump-all Dump all object file information + --dump-dbgsyms Dump debug symbols + --dump-exports Dump exported symbols + --dump-files Dump the source files + --dump-header Dump the object file header + --dump-imports Dump imported symbols + --dump-lineinfo Dump line information + --dump-options Dump object file options + --dump-segments Dump the segments in the file + --dump-segsize Dump segments sizes + --help Help (this text) + --version Print the version number and exit +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<p> + +Here is a description of all the command line options: + +<descrip> + + <tag><tt>--dump-all</tt></tag> + + This will output all information, od65 is able to process. The option is a + shortcut for specifying all the other <tt/--dump/ options. + + + <tag><tt>--dump-dbgsyms</tt></tag> + + Dump all debug symbols contained in the object file. + + + <tag><tt>--dump-exports</tt></tag> + + Dump all exported symbols contained in the object file. + + + <tag><tt>--dump-files</tt></tag> + + Dump the file table contained in the object file. + + + <tag><tt>-H, --dump-header</tt></tag> + + Dump the object file header. + + + <tag><tt>--dump-imports</tt></tag> + + Dump the list of imported symbols contained in the object file. + + + <tag><tt>--dump-segments</tt></tag> + + Dump the list of segments contained in the object file. + + + <tag><tt>-S, --dump-segsize</tt></tag> + + Dump the sizes of all segments contained in the object file. This option is + quite useful to determine the effect of measures that increase or decrease + code size. + + + <tag><tt>-h, --help</tt></tag> + + Print the short option summary shown above. + + + <tag><tt>-V, --version</tt></tag> + + Print the version number of the compiler. When submitting a bug report, + please include the operating system you're using, and the compiler + version. +</descrip> + + +<sect>Input and output<p> + +The converter will read one or more object files per invocation and write the +contents in readable format to standard output. Please note that you need to +specify and of the <tt/--dump/ options listed above, otherwise no useful +output will be generated. + +Example output for the command +<tscreen><verb> +od65 --dump-header --dump-files t.o +</verb></tscreen> +<tscreen><verb> +t.o: + Header: + Magic: 0x616E7A55 + Version: 12 + Flags: 0x0001 (OBJ_FLAGS_DBGINFO) + Options: + Offset: 88 + Size: 9 + Files: + Offset: 97 + Size: 10 + Segments: + Offset: 107 + Size: 101 + Imports: + Offset: 208 + Size: 1 + Exports: + Offset: 209 + Size: 1 + Debug symbols: + Offset: 210 + Size: 55 + Line infos: + Offset: 265 + Size: 1 + String pool: + Offset: 266 + Size: 80 + Files: + Count: 1 + Index: 0 + Name: "t.s" + Size: 402 + Modification time: 1280498435 (Fri Jul 30 16:00:35 2010) +</verb></tscreen> + + +<sect>Bugs/Feedback<p> + +If you have problems using the converter, if you find any bugs, or if you're +doing something interesting with the code, I would be glad to hear from you. +Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +od65 is (C) Copyright 2000-2009, Ullrich von Bassewitz. For usage of the +binaries and/or sources the following conditions apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + -- 2.39.5