From ee9aa47e60f649569a352da6f0b9b60024addb9d Mon Sep 17 00:00:00 2001 From: cuz Date: Wed, 12 Feb 2003 12:48:26 +0000 Subject: [PATCH] First doc version for the co65 utility git-svn-id: svn://svn.cc65.org/cc65/trunk@1973 b7a2c559-68d2-44c3-8de9-860c34a00d81 --- doc/Makefile | 1 + doc/co65.sgml | 349 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 350 insertions(+) create mode 100644 doc/co65.sgml diff --git a/doc/Makefile b/doc/Makefile index f90918b97..1934926d4 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -9,6 +9,7 @@ SGML = ar65.sgml \ ca65.sgml \ cc65.sgml \ cl65.sgml \ + co65.sgml \ coding.sgml \ debugging.sgml \ dio.sgml \ diff --git a/doc/co65.sgml b/doc/co65.sgml new file mode 100644 index 000000000..584ae9b9e --- /dev/null +++ b/doc/co65.sgml @@ -0,0 +1,349 @@ + + +
+co65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>12.02.2003 + +<abstract> +co65 is an object file conversion utility. It converts o65 object files into +the native object file format used by the cc65 tool chain. Since o65 is the +file format used by cc65 for loadable drivers, the co65 utility allows (among +other things) to link drivers statically to the generated executables instead +of loading them from disk. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + + +<sect>Overview<p> + +co65 is an object file conversion utility. It converts o65 object files into +assembler files, which may be translated by ca65 to generate object files in +the native object file format used by the cc65 tool chain. + +Since loadable drivers used by the library that comes with cc65 use the o65 +relocatable object code format, using the co65 utility allows to link these +drivers statically. This enables the use of these drivers without loading +additional files from a disk or other secondary storage. + +Another use would be to link object files generated by other development tools +to projects using the cc65 tool chain, but this has not been tested until now, +since such tools are currently rare. + + + +<sect>Usage<p> + +The co65 utility converts one o65 file per run into one assembler files in +ca65 format. The utility tries to autodetect the type of the o65 input file +using the operating system identifier contained in the o65 option list. + + +<sect1>Command line option overview<p> + +The converter may be called as follows: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: co65 [options] file +Short options: + -V Print the version number + -g Add debug info to object file + -h Help (this text) + -m model Override the o65 model + -n Don't generate an output file + -o name Name the output file + -v Increase verbosity + +Long options: + --bss-label name Define and export a BSS segment label + --bss-name seg Set the name of the BSS segment + --code-label name Define and export a CODE segment label + --code-name seg Set the name of the CODE segment + --data-label name Define and export a DATA segment label + --data-name seg Set the name of the DATA segment + --debug-info Add debug info to object file + --help Help (this text) + --no-output Don't generate an output file + --o65-model model Override the o65 model + --verbose Increase verbosity + --version Print the version number + --zeropage-label name Define and export a ZEROPAGE segment label + --zeropage-name seg Set the name of the ZEROPAGE segment +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<p> + +Here is a description of all the command line options: + +<descrip> + + <tag><tt>--bss-label name</tt></tag> + + Set the label used to mark the start of the bss segment. When this option is + given, the label is also exported and may be accessed from other code. When + accessing such a label from C code, be sure to include the leading + underscore. If you don't need to access the bss segment, there's no need to + use this option. + + + <tag><tt>--bss-name seg</tt></tag> + + Set the name of the bss segment. The default name is "BSS" which is + compatible with the standard ld65 linker configurations. + + + <tag><tt>--code-label name</tt></tag> + + Set the label used to mark the start of the code segment. When this option + is given, the label is also exported and may be accessed from other code. + When accessing such a label from C code, be sure to include the leading + underscore. If you don't need to access the code segment, there's no need to + use this option. + + + <tag><tt>--code-name seg</tt></tag> + + Set the name of the code segment. The default name is "CODE" which is + compatible with the standard ld65 linker configurations. + + + <tag><tt>--data-label name</tt></tag> + + Set the label used to mark the start of the data segment. When this option + is given, the label is also exported and may be accessed from other code. + When accessing such a label from C code, be sure to include the leading + underscore. If you don't need to access the data segment, there's no need to + use this option. + + + <tag><tt>--data-name seg</tt></tag> + + Set the name of the data segment. The default name is "DATA" which is + compatible with the standard ld65 linker configurations. + + + <tag><tt>-d, --debug</tt></tag> + + Enables debug mode, something that should not be needed for mere mortals. + Currently the converter does only accept cc65 loadable modules generated by + ld65 when not in debug mode. Please note that correct conversion has never + been tested for o65 files from other sources, so be careful when using + <tt/-d/. + + + <tag><tt>-g, --debug-info</tt></tag> + + This will cause the converter to insert a <tt/.DEBUGINFO/ command into the + generated assembler code. This will cause the assembler to include all + symbols in a special section in the object file. + + + <tag><tt>-h, --help</tt></tag> + + Print the short option summary shown above. + + + <tag><tt>-m model, --o65-model model</tt></tag> + + Set an o65 model. This option changes the way, output is generated for the + given o65 file. For example, cc65 loadable drivers have a zero page segment, + but this segment must not be defined in the file itself, because the + standard module loader will overlay it with the zeropage space used by the + application that loads this module. So instead of allocating space in the + zero page segment, the converter will reference the start of the zero page + area used by the application. + + Currently, the following models are defined: + + <itemize> + <item>lunix + <item>os/a65 + <item>cc65-module + </itemize> + + The default is to autodetect the model to use from the input file, so + there's rarely a need to use this option. + + + <tag><tt>-n, --no-output</tt></tag> + + Don't do the actual conversion, just read in the o65 file checking for + problems. This option may be used in conjunction with <tt/--verbose/ to + view some information about the input file. + + + <tag><tt>-o name</tt></tag> + + Specify the name of the output file. If you don't specify a name, the + name of the o65 input file is used, with the extension replaced by ".s". + + + <tag><tt>-v, --verbose</tt></tag> + + Using this option, the converter will be somewhat more verbose and print + some information about the o65 input file (among other things). You may use + this option together with <tt/--no-output/ to just get the o65 info. + + + <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. + + + <tag><tt>--zeropage-label name</tt></tag> + + Set the label used to mark the start of the zeropage segment. When this + option is given, the label is also exported and may be accessed from other + code. When accessing such a label from C code, be sure to include the + leading underscore. If you don't need to access the zeropage segment, + there's no need to use this option. + + + <tag><tt>--zeropage-name seg</tt></tag> + + Set the name of the data segment. The default name is "ZEROPAGE" which is + compatible with the standard ld65 linker configurations. + + + +<sect>Input and output<p> + +The converter will accept one o65 file per invocation and create a file with +the same base name, but with the extension replaced by ".s". The output +file contains assembler code suitable for the use with the ca65 macro +assembler. + + +<sect>Converting loadable drivers<p> + +<sect1>Differences between static linking and runtime loading<p> + +One main use of the utility is conversion of loadable drivers, so they may be +linked statically to an application. Statically linking will cause a few +things to be different from runtime loading: + +<itemize> + +<item> Without changing the segment names, all segments take the default + names used by the standard linker configurations. This means that the + driver code is no longer contingous in memory, instead the code + segment is placed somewhere in between all other code segments, the + data segment is placed with all other data segments and so on. If the + driver doesn't do strange things this shouldn't be a problem. + +<item> With statically linked code, data and bss segments will get intialized + once (when the application is loaded), while a loadable driver will + get its initialization each time the driver is loaded into memory + (which may be more than once in the lifetime of a program). It depends + on the driver if this is a problem. Currently, most drivers supplied + with cc65 behave correctly when linked statically. + +</itemize> + + +<sect1>Additional requirements<p> + +All loadable drivers used by cc65 have a header and a jump table at the start +of the code segment. The header is needed to detect the driver (it may also +contain some data that is necessary to access the driver). The jump table is +used to access the functions in the driver code. + +When loading a driver at runtime, the load address of the driver is also the +address of the code segment, so the locations of the header and jump table are +known. However, when linking the driver statically, it is up to the programmer +to provide this information to the driver API. + +For this purpose, it is necessary to define a code segment label that can be +accessed from the outside later. Please note that the converter does currently +<em/not/ create such a label without being ordered to do so, even if the input +file is a cc65 module. + +To create such a label, use the <tt/--code-label/ option when calling the +converter. Be sure to begin the label with a leading underscore when accessing +it from C code. In your code, define an arbitrary variable with this name. Use +the address of this variable as the address of the code segment of the driver. +Be sure to never modify the variable which is in reality the start of your +driver! + +As an example, here are some instructions to convert and use the c64-hi.tgi +graphics driver: + +First, convert the driver, generating a label named "_c64_hi" for the code +segment. Use the assembler to generate an object file from the assembler +output. + + <tscreen><verb> + co65 --code-label _c64_hi c64-hi.tgi + ca65 c64-hi.s + </verb></tscreen> + +Next, change your C code to declare a variable that is actually the first byte +of the driver: + + <tscreen><verb> + extern char c64_hi; + </verb></tscreen> + +Instead of loading and unloading the driver, change the code to install and +uninstall the driver, which will be already in memory after linking: + + <tscreen><verb> + /* Install the driver */ + tgi_install (&c64_hi); + + ... + + /* Uninstall the driver */ + tgi_uninstall (); + </verb></tscreen> + +Don't forget to link the driver object file to your application, otherwise you +will get an "undefined external" error for the _c64_hi symbol. + + + + +<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> + +co65 is (C) Copyright 2003 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