co65 Users Guide

Ullrich von Bassewitz

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.

1. Overview

2. Usage

3. Input and output

4. Converting loadable drivers

5. Copyright

1. Overview

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.

2. Usage

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.

2.1 Command line option overview

The converter may be called as follows:


---------------------------------------------------------------------------
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
---------------------------------------------------------------------------

2.2 Command line options in detail

Here is a description of all the command line options:

--bss-label name

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.

--bss-name seg

Set the name of the bss segment. The default name is "BSS" which is compatible with the standard ld65 linker configurations.

--code-label name

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.

--code-name seg

Set the name of the code segment. The default name is "CODE" which is compatible with the standard ld65 linker configurations.

--data-label name

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.

--data-name seg

Set the name of the data segment. The default name is "DATA" which is compatible with the standard ld65 linker configurations.

-d, --debug

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 -d.

-g, --debug-info

This will cause the converter to insert a .DEBUGINFO command into the generated assembler code. This will cause the assembler to include all symbols in a special section in the object file.

-h, --help

Print the short option summary shown above.

-m model, --o65-model model

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:

lunix
os/a65
cc65-module

The default is to autodetect the model to use from the input file, so there's rarely a need to use this option.

-n, --no-output

Don't do the actual conversion, just read in the o65 file checking for problems. This option may be used in conjunction with --verbose to view some information about the input file.

-o name

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".

-v, --verbose

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 --no-output to just get the o65 info.

-V, --version

Print the version number of the compiler. When submitting a bug report, please include the operating system you're using, and the compiler version.

--zeropage-label name

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.

--zeropage-name seg

Set the name of the zeropage segment. The default name is "ZEROPAGE" which is compatible with the standard ld65 linker configurations.

3. Input and output

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.

4. Converting loadable drivers

4.1 Differences between static linking and runtime loading

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:

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 contiguous 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.
With statically linked code, data and bss segments will get initialized 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.

4.2 Additional requirements

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 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 --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!

4.3 Example - Convert and link a graphics 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.


        co65 --code-label _c64_hi c64-hi.tgi
        ca65 c64-hi.s

Next, change your C code to declare a variable that is actually the address of the driver:


        extern void c64_hi[];

Instead of loading and unloading the driver, change the code to install and uninstall the driver, which will be already in memory after linking:


        /* Install the driver */
        tgi_install (c64_hi);

        ...

        /* Uninstall the driver */
        tgi_uninstall ();

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.

5. Copyright

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:

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.
Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
This notice may not be removed or altered from any source distribution.