]> git.sur5r.net Git - cc65/blob - doc/co65.sgml
some cleanup, checked usage of __bgcolor and __textcolor
[cc65] / doc / co65.sgml
1 <!doctype linuxdoc system>
2
3 <article>
4 <title>co65 Users Guide
5 <author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
6 <date>12.02.2003
7
8 <abstract>
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.
14 </abstract>
15
16 <!-- Table of contents -->
17 <toc>
18
19 <!-- Begin the document -->
20
21
22 <sect>Overview<p>
23
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.
27
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.
32
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.
36
37
38
39 <sect>Usage<p>
40
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.
44
45
46 <sect1>Command line option overview<p>
47
48 The converter may be called as follows:
49
50 <tscreen><verb>
51 ---------------------------------------------------------------------------
52 Usage: co65 [options] file
53 Short options:
54   -V                    Print the version number
55   -g                    Add debug info to object file
56   -h                    Help (this text)
57   -m model              Override the o65 model
58   -n                    Don't generate an output file
59   -o name               Name the output file
60   -v                    Increase verbosity
61
62 Long options:
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 ---------------------------------------------------------------------------
78 </verb></tscreen>
79
80
81 <sect1>Command line options in detail<p>
82
83 Here is a description of all the command line options:
84
85 <descrip>
86
87   <tag><tt>--bss-label name</tt></tag>
88
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
93   use this option.
94
95
96   <tag><tt>--bss-name seg</tt></tag>
97
98   Set the name of the bss segment. The default name is "BSS" which is
99   compatible with the standard ld65 linker configurations.
100
101
102   <tag><tt>--code-label name</tt></tag>
103
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
108   use this option.
109
110
111   <tag><tt>--code-name seg</tt></tag>
112
113   Set the name of the code segment. The default name is "CODE" which is
114   compatible with the standard ld65 linker configurations.
115
116
117   <tag><tt>--data-label name</tt></tag>
118
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
123   use this option.
124
125
126   <tag><tt>--data-name seg</tt></tag>
127
128   Set the name of the data segment. The default name is "DATA" which is
129   compatible with the standard ld65 linker configurations.
130
131
132   <tag><tt>-d, --debug</tt></tag>
133
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
138   <tt/-d/.
139
140
141   <tag><tt>-g, --debug-info</tt></tag>
142
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.
146
147
148   <tag><tt>-h, --help</tt></tag>
149
150   Print the short option summary shown above.
151
152
153   <tag><tt>-m model, --o65-model model</tt></tag>
154
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.
162
163   Currently, the following models are defined:
164
165   <itemize>
166   <item>lunix
167   <item>os/a65
168   <item>cc65-module
169   </itemize>
170
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.
173
174
175   <tag><tt>-n, --no-output</tt></tag>
176
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.
180
181
182   <tag><tt>-o name</tt></tag>
183
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".
186
187
188   <tag><tt>-v, --verbose</tt></tag>
189
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.
193
194
195   <tag><tt>-V, --version</tt></tag>
196
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
199   version.
200
201
202   <tag><tt>--zeropage-label name</tt></tag>
203
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.
209
210
211   <tag><tt>--zeropage-name seg</tt></tag>
212
213   Set the name of the zeropage segment. The default name is "ZEROPAGE" which is
214   compatible with the standard ld65 linker configurations.
215
216 </descrip>
217
218
219 <sect>Input and output<p>
220
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
224 assembler.
225
226
227 <sect>Converting loadable drivers<p>
228
229 <sect1>Differences between static linking and runtime loading<p>
230
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:
234
235 <itemize>
236
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.
243
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.
250
251 </itemize>
252
253
254 <sect1>Additional requirements<p>
255
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.
260
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.
265
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.
270
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
276 driver!
277
278
279 <sect1>Example - Convert and link a graphics driver<p>
280
281 As an example, here are some instructions to convert and use the c64-hi.tgi
282 graphics driver:
283
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
286 output.
287
288   <tscreen><verb>
289         co65 --code-label _c64_hi c64-hi.tgi
290         ca65 c64-hi.s
291   </verb></tscreen>
292
293 Next, change your C code to declare a variable that is actually the address
294 of the driver:
295
296   <tscreen><verb>
297         extern void c64_hi[];
298   </verb></tscreen>
299
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:
302
303   <tscreen><verb>
304         /* Install the driver */
305         tgi_install (c64_hi);
306
307         ...
308
309         /* Uninstall the driver */
310         tgi_uninstall ();
311   </verb></tscreen>
312
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.
315
316
317
318
319 <sect>Copyright<p>
320
321 co65 is (C) Copyright 2003 Ullrich von Bassewitz. For usage of the binaries
322 and/or sources the following conditions apply:
323
324 This software is provided 'as-is', without any expressed or implied
325 warranty.  In no event will the authors be held liable for any damages
326 arising from the use of this software.
327
328 Permission is granted to anyone to use this software for any purpose,
329 including commercial applications, and to alter it and redistribute it
330 freely, subject to the following restrictions:
331
332 <enum>
333 <item>  The origin of this software must not be misrepresented; you must not
334         claim that you wrote the original software. If you use this software
335         in a product, an acknowledgment in the product documentation would be
336         appreciated but is not required.
337 <item>  Altered source versions must be plainly marked as such, and must not
338         be misrepresented as being the original software.
339 <item>  This notice may not be removed or altered from any source
340         distribution.
341 </enum>
342
343 </article>
344