1 <!doctype linuxdoc system>
4 <title>co65 Users Guide
5 <author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
8 co65 is an object file conversion utility. It converts o65 object files into
9 the native object file format used by the cc65 tool chain. Since o65 is the
10 file format used by cc65 for loadable drivers, the co65 utility allows (among
11 other things) to link drivers statically to the generated executables instead
12 of loading them from disk.
15 <!-- Table of contents -->
18 <!-- Begin the document -->
23 co65 is an object file conversion utility. It converts o65 object files into
24 assembler files, which may be translated by ca65 to generate object files in
25 the native object file format used by the cc65 tool chain.
27 Since loadable drivers used by the library that comes with cc65 use the o65
28 relocatable object code format, using the co65 utility allows to link these
29 drivers statically. This enables the use of these drivers without loading
30 additional files from a disk or other secondary storage.
32 Another use would be to link object files generated by other development tools
33 to projects using the cc65 tool chain, but this has not been tested until now,
34 since such tools are currently rare.
40 The co65 utility converts one o65 file per run into one assembler files in
41 ca65 format. The utility tries to autodetect the type of the o65 input file
42 using the operating system identifier contained in the o65 option list.
45 <sect1>Command line option overview<p>
47 The converter may be called as follows:
50 ---------------------------------------------------------------------------
51 Usage: co65 [options] file
53 -V Print the version number
54 -g Add debug info to object file
56 -m model Override the o65 model
57 -n Don't generate an output file
58 -o name Name the output file
62 --bss-label name Define and export a BSS segment label
63 --bss-name seg Set the name of the BSS segment
64 --code-label name Define and export a CODE segment label
65 --code-name seg Set the name of the CODE segment
66 --data-label name Define and export a DATA segment label
67 --data-name seg Set the name of the DATA segment
68 --debug-info Add debug info to object file
69 --help Help (this text)
70 --no-output Don't generate an output file
71 --o65-model model Override the o65 model
72 --verbose Increase verbosity
73 --version Print the version number
74 --zeropage-label name Define and export a ZEROPAGE segment label
75 --zeropage-name seg Set the name of the ZEROPAGE segment
76 ---------------------------------------------------------------------------
80 <sect1>Command line options in detail<p>
82 Here is a description of all the command line options:
86 <tag><tt>--bss-label name</tt></tag>
88 Set the label used to mark the start of the bss segment. When this option is
89 given, the label is also exported and may be accessed from other code. When
90 accessing such a label from C code, be sure to include the leading
91 underscore. If you don't need to access the bss segment, there's no need to
95 <tag><tt>--bss-name seg</tt></tag>
97 Set the name of the bss segment. The default name is "BSS" which is
98 compatible with the standard ld65 linker configurations.
101 <tag><tt>--code-label name</tt></tag>
103 Set the label used to mark the start of the code segment. When this option
104 is given, the label is also exported and may be accessed from other code.
105 When accessing such a label from C code, be sure to include the leading
106 underscore. If you don't need to access the code segment, there's no need to
110 <tag><tt>--code-name seg</tt></tag>
112 Set the name of the code segment. The default name is "CODE" which is
113 compatible with the standard ld65 linker configurations.
116 <tag><tt>--data-label name</tt></tag>
118 Set the label used to mark the start of the data segment. When this option
119 is given, the label is also exported and may be accessed from other code.
120 When accessing such a label from C code, be sure to include the leading
121 underscore. If you don't need to access the data segment, there's no need to
125 <tag><tt>--data-name seg</tt></tag>
127 Set the name of the data segment. The default name is "DATA" which is
128 compatible with the standard ld65 linker configurations.
131 <tag><tt>-d, --debug</tt></tag>
133 Enables debug mode, something that should not be needed for mere mortals.
134 Currently the converter does only accept cc65 loadable modules generated by
135 ld65 when not in debug mode. Please note that correct conversion has never
136 been tested for o65 files from other sources, so be careful when using
140 <tag><tt>-g, --debug-info</tt></tag>
142 This will cause the converter to insert a <tt/.DEBUGINFO/ command into the
143 generated assembler code. This will cause the assembler to include all
144 symbols in a special section in the object file.
147 <tag><tt>-h, --help</tt></tag>
149 Print the short option summary shown above.
152 <tag><tt>-m model, --o65-model model</tt></tag>
154 Set an o65 model. This option changes the way, output is generated for the
155 given o65 file. For example, cc65 loadable drivers have a zero page segment,
156 but this segment must not be defined in the file itself, because the
157 standard module loader will overlay it with the zeropage space used by the
158 application that loads this module. So instead of allocating space in the
159 zero page segment, the converter will reference the start of the zero page
160 area used by the application.
162 Currently, the following models are defined:
170 The default is to autodetect the model to use from the input file, so
171 there's rarely a need to use this option.
174 <tag><tt>-n, --no-output</tt></tag>
176 Don't do the actual conversion, just read in the o65 file checking for
177 problems. This option may be used in conjunction with <tt/--verbose/ to
178 view some information about the input file.
181 <tag><tt>-o name</tt></tag>
183 Specify the name of the output file. If you don't specify a name, the
184 name of the o65 input file is used, with the extension replaced by ".s".
187 <tag><tt>-v, --verbose</tt></tag>
189 Using this option, the converter will be somewhat more verbose and print
190 some information about the o65 input file (among other things). You may use
191 this option together with <tt/--no-output/ to just get the o65 info.
194 <tag><tt>-V, --version</tt></tag>
196 Print the version number of the compiler. When submitting a bug report,
197 please include the operating system you're using, and the compiler
201 <tag><tt>--zeropage-label name</tt></tag>
203 Set the label used to mark the start of the zeropage segment. When this
204 option is given, the label is also exported and may be accessed from other
205 code. When accessing such a label from C code, be sure to include the
206 leading underscore. If you don't need to access the zeropage segment,
207 there's no need to use this option.
210 <tag><tt>--zeropage-name seg</tt></tag>
212 Set the name of the zeropage segment. The default name is "ZEROPAGE" which is
213 compatible with the standard ld65 linker configurations.
218 <sect>Input and output<p>
220 The converter will accept one o65 file per invocation and create a file with
221 the same base name, but with the extension replaced by ".s". The output
222 file contains assembler code suitable for the use with the ca65 macro
226 <sect>Converting loadable drivers<p>
228 <sect1>Differences between static linking and runtime loading<p>
230 One main use of the utility is conversion of loadable drivers, so they may be
231 linked statically to an application. Statically linking will cause a few
232 things to be different from runtime loading:
236 <item> Without changing the segment names, all segments take the default
237 names used by the standard linker configurations. This means that the
238 driver code is no longer contingous in memory, instead the code
239 segment is placed somewhere in between all other code segments, the
240 data segment is placed with all other data segments and so on. If the
241 driver doesn't do strange things this shouldn't be a problem.
243 <item> With statically linked code, data and bss segments will get intialized
244 once (when the application is loaded), while a loadable driver will
245 get its initialization each time the driver is loaded into memory
246 (which may be more than once in the lifetime of a program). It depends
247 on the driver if this is a problem. Currently, most drivers supplied
248 with cc65 behave correctly when linked statically.
253 <sect1>Additional requirements<p>
255 All loadable drivers used by cc65 have a header and a jump table at the start
256 of the code segment. The header is needed to detect the driver (it may also
257 contain some data that is necessary to access the driver). The jump table is
258 used to access the functions in the driver code.
260 When loading a driver at runtime, the load address of the driver is also the
261 address of the code segment, so the locations of the header and jump table are
262 known. However, when linking the driver statically, it is up to the programmer
263 to provide this information to the driver API.
265 For this purpose, it is necessary to define a code segment label that can be
266 accessed from the outside later. Please note that the converter does currently
267 <em/not/ create such a label without being ordered to do so, even if the input
268 file is a cc65 module.
270 To create such a label, use the <tt/--code-label/ option when calling the
271 converter. Be sure to begin the label with a leading underscore when accessing
272 it from C code. In your code, define an arbitrary variable with this name. Use
273 the address of this variable as the address of the code segment of the driver.
274 Be sure to never modify the variable which is in reality the start of your
278 <sect1>Example - Convert and link a graphics driver<p>
280 As an example, here are some instructions to convert and use the c64-hi.tgi
283 First, convert the driver, generating a label named "_c64_hi" for the code
284 segment. Use the assembler to generate an object file from the assembler
288 co65 --code-label _c64_hi c64-hi.tgi
292 Next, change your C code to declare a variable that is actually the address
296 extern void c64_hi[];
299 Instead of loading and unloading the driver, change the code to install and
300 uninstall the driver, which will be already in memory after linking:
303 /* Install the driver */
304 tgi_install (c64_hi);
308 /* Uninstall the driver */
312 Don't forget to link the driver object file to your application, otherwise you
313 will get an "undefined external" error for the _c64_hi symbol.
320 co65 is (C) Copyright 2003 Ullrich von Bassewitz. For usage of the binaries
321 and/or sources the following conditions apply:
323 This software is provided 'as-is', without any expressed or implied
324 warranty. In no event will the authors be held liable for any damages
325 arising from the use of this software.
327 Permission is granted to anyone to use this software for any purpose,
328 including commercial applications, and to alter it and redistribute it
329 freely, subject to the following restrictions:
332 <item> The origin of this software must not be misrepresented; you must not
333 claim that you wrote the original software. If you use this software
334 in a product, an acknowledgment in the product documentation would be
335 appreciated but is not required.
336 <item> Altered source versions must be plainly marked as such, and must not
337 be misrepresented as being the original software.
338 <item> This notice may not be removed or altered from any source