1 <!doctype linuxdoc system>
4 <title>co65 Users Guide
5 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
9 co65 is an object file conversion utility. It converts o65 object files into
10 the native object file format used by the cc65 tool chain. Since o65 is the
11 file format used by cc65 for loadable drivers, the co65 utility allows (among
12 other things) to link drivers statically to the generated executables instead
13 of loading them from disk.
16 <!-- Table of contents -->
19 <!-- Begin the document -->
24 co65 is an object file conversion utility. It converts o65 object files into
25 assembler files, which may be translated by ca65 to generate object files in
26 the native object file format used by the cc65 tool chain.
28 Since loadable drivers used by the library that comes with cc65 use the o65
29 relocatable object code format, using the co65 utility allows to link these
30 drivers statically. This enables the use of these drivers without loading
31 additional files from a disk or other secondary storage.
33 Another use would be to link object files generated by other development tools
34 to projects using the cc65 tool chain, but this has not been tested until now,
35 since such tools are currently rare.
41 The co65 utility converts one o65 file per run into one assembler files in
42 ca65 format. The utility tries to autodetect the type of the o65 input file
43 using the operating system identifier contained in the o65 option list.
46 <sect1>Command line option overview<p>
48 The converter may be called as follows:
51 ---------------------------------------------------------------------------
52 Usage: co65 [options] file
54 -V Print the version number
55 -g Add debug info to object file
57 -m model Override the o65 model
58 -n Don't generate an output file
59 -o name Name the output file
63 --bss-label name Define and export a BSS segment label
64 --bss-name seg Set the name of the BSS segment
65 --code-label name Define and export a CODE segment label
66 --code-name seg Set the name of the CODE segment
67 --data-label name Define and export a DATA segment label
68 --data-name seg Set the name of the DATA segment
69 --debug-info Add debug info to object file
70 --help Help (this text)
71 --no-output Don't generate an output file
72 --o65-model model Override the o65 model
73 --verbose Increase verbosity
74 --version Print the version number
75 --zeropage-label name Define and export a ZEROPAGE segment label
76 --zeropage-name seg Set the name of the ZEROPAGE segment
77 ---------------------------------------------------------------------------
81 <sect1>Command line options in detail<p>
83 Here is a description of all the command line options:
87 <tag><tt>--bss-label name</tt></tag>
89 Set the label used to mark the start of the bss segment. When this option is
90 given, the label is also exported and may be accessed from other code. When
91 accessing such a label from C code, be sure to include the leading
92 underscore. If you don't need to access the bss segment, there's no need to
96 <tag><tt>--bss-name seg</tt></tag>
98 Set the name of the bss segment. The default name is "BSS" which is
99 compatible with the standard ld65 linker configurations.
102 <tag><tt>--code-label name</tt></tag>
104 Set the label used to mark the start of the code segment. When this option
105 is given, the label is also exported and may be accessed from other code.
106 When accessing such a label from C code, be sure to include the leading
107 underscore. If you don't need to access the code segment, there's no need to
111 <tag><tt>--code-name seg</tt></tag>
113 Set the name of the code segment. The default name is "CODE" which is
114 compatible with the standard ld65 linker configurations.
117 <tag><tt>--data-label name</tt></tag>
119 Set the label used to mark the start of the data segment. When this option
120 is given, the label is also exported and may be accessed from other code.
121 When accessing such a label from C code, be sure to include the leading
122 underscore. If you don't need to access the data segment, there's no need to
126 <tag><tt>--data-name seg</tt></tag>
128 Set the name of the data segment. The default name is "DATA" which is
129 compatible with the standard ld65 linker configurations.
132 <tag><tt>-d, --debug</tt></tag>
134 Enables debug mode, something that should not be needed for mere mortals.
135 Currently the converter does only accept cc65 loadable modules generated by
136 ld65 when not in debug mode. Please note that correct conversion has never
137 been tested for o65 files from other sources, so be careful when using
141 <tag><tt>-g, --debug-info</tt></tag>
143 This will cause the converter to insert a <tt/.DEBUGINFO/ command into the
144 generated assembler code. This will cause the assembler to include all
145 symbols in a special section in the object file.
148 <tag><tt>-h, --help</tt></tag>
150 Print the short option summary shown above.
153 <tag><tt>-m model, --o65-model model</tt></tag>
155 Set an o65 model. This option changes the way, output is generated for the
156 given o65 file. For example, cc65 loadable drivers have a zero page segment,
157 but this segment must not be defined in the file itself, because the
158 standard module loader will overlay it with the zeropage space used by the
159 application that loads this module. So instead of allocating space in the
160 zero page segment, the converter will reference the start of the zero page
161 area used by the application.
163 Currently, the following models are defined:
171 The default is to autodetect the model to use from the input file, so
172 there's rarely a need to use this option.
175 <tag><tt>-n, --no-output</tt></tag>
177 Don't do the actual conversion, just read in the o65 file checking for
178 problems. This option may be used in conjunction with <tt/--verbose/ to
179 view some information about the input file.
182 <tag><tt>-o name</tt></tag>
184 Specify the name of the output file. If you don't specify a name, the
185 name of the o65 input file is used, with the extension replaced by ".s".
188 <tag><tt>-v, --verbose</tt></tag>
190 Using this option, the converter will be somewhat more verbose and print
191 some information about the o65 input file (among other things). You may use
192 this option together with <tt/--no-output/ to just get the o65 info.
195 <tag><tt>-V, --version</tt></tag>
197 Print the version number of the compiler. When submitting a bug report,
198 please include the operating system you're using, and the compiler
202 <tag><tt>--zeropage-label name</tt></tag>
204 Set the label used to mark the start of the zeropage segment. When this
205 option is given, the label is also exported and may be accessed from other
206 code. When accessing such a label from C code, be sure to include the
207 leading underscore. If you don't need to access the zeropage segment,
208 there's no need to use this option.
211 <tag><tt>--zeropage-name seg</tt></tag>
213 Set the name of the data segment. The default name is "ZEROPAGE" which is
214 compatible with the standard ld65 linker configurations.
219 <sect>Input and output<p>
221 The converter will accept one o65 file per invocation and create a file with
222 the same base name, but with the extension replaced by ".s". The output
223 file contains assembler code suitable for the use with the ca65 macro
227 <sect>Converting loadable drivers<p>
229 <sect1>Differences between static linking and runtime loading<p>
231 One main use of the utility is conversion of loadable drivers, so they may be
232 linked statically to an application. Statically linking will cause a few
233 things to be different from runtime loading:
237 <item> Without changing the segment names, all segments take the default
238 names used by the standard linker configurations. This means that the
239 driver code is no longer contingous in memory, instead the code
240 segment is placed somewhere in between all other code segments, the
241 data segment is placed with all other data segments and so on. If the
242 driver doesn't do strange things this shouldn't be a problem.
244 <item> With statically linked code, data and bss segments will get intialized
245 once (when the application is loaded), while a loadable driver will
246 get its initialization each time the driver is loaded into memory
247 (which may be more than once in the lifetime of a program). It depends
248 on the driver if this is a problem. Currently, most drivers supplied
249 with cc65 behave correctly when linked statically.
254 <sect1>Additional requirements<p>
256 All loadable drivers used by cc65 have a header and a jump table at the start
257 of the code segment. The header is needed to detect the driver (it may also
258 contain some data that is necessary to access the driver). The jump table is
259 used to access the functions in the driver code.
261 When loading a driver at runtime, the load address of the driver is also the
262 address of the code segment, so the locations of the header and jump table are
263 known. However, when linking the driver statically, it is up to the programmer
264 to provide this information to the driver API.
266 For this purpose, it is necessary to define a code segment label that can be
267 accessed from the outside later. Please note that the converter does currently
268 <em/not/ create such a label without being ordered to do so, even if the input
269 file is a cc65 module.
271 To create such a label, use the <tt/--code-label/ option when calling the
272 converter. Be sure to begin the label with a leading underscore when accessing
273 it from C code. In your code, define an arbitrary variable with this name. Use
274 the address of this variable as the address of the code segment of the driver.
275 Be sure to never modify the variable which is in reality the start of your
279 <sect1>Example - Convert and link a graphics driver<p>
281 As an example, here are some instructions to convert and use the c64-hi.tgi
284 First, convert the driver, generating a label named "_c64_hi" for the code
285 segment. Use the assembler to generate an object file from the assembler
289 co65 --code-label _c64_hi c64-hi.tgi
293 Next, change your C code to declare a variable that is actually the first byte
300 Instead of loading and unloading the driver, change the code to install and
301 uninstall the driver, which will be already in memory after linking:
304 /* Install the driver */
305 tgi_install (&c64_hi);
309 /* Uninstall the driver */
313 Don't forget to link the driver object file to your application, otherwise you
314 will get an "undefined external" error for the _c64_hi symbol.
319 <sect>Bugs/Feedback<p>
321 If you have problems using the converter, if you find any bugs, or if you're
322 doing something interesting with the code, I would be glad to hear from you.
323 Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
324 name="uz@cc65.org">).
330 co65 is (C) Copyright 2003 Ullrich von Bassewitz. For usage of the binaries
331 and/or sources the following conditions apply:
333 This software is provided 'as-is', without any expressed or implied
334 warranty. In no event will the authors be held liable for any damages
335 arising from the use of this software.
337 Permission is granted to anyone to use this software for any purpose,
338 including commercial applications, and to alter it and redistribute it
339 freely, subject to the following restrictions:
342 <item> The origin of this software must not be misrepresented; you must not
343 claim that you wrote the original software. If you use this software
344 in a product, an acknowledgment in the product documentation would be
345 appreciated but is not required.
346 <item> Altered source versions must be plainly marked as such, and must not
347 be misrepresented as being the original software.
348 <item> This notice may not be removed or altered from any source