Removed the old cc65.txt file, added documentation for the dio api.
git-svn-id: svn://svn.cc65.org/cc65/trunk@466 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
parent
c37d0e10d3
commit
9398c5cef0
3 changed files with 112 additions and 672 deletions
|
@ -8,7 +8,8 @@
|
|||
SGML = ar65.sgml \
|
||||
ca65.sgml \
|
||||
cc65.sgml \
|
||||
cl65.sgml
|
||||
cl65.sgml \
|
||||
dio.sgml
|
||||
|
||||
TXT = $(SGML:.sgml=.txt)
|
||||
HTML = $(SGML:.sgml=.html)
|
||||
|
|
671
doc/cc65.txt
671
doc/cc65.txt
|
@ -1,671 +0,0 @@
|
|||
|
||||
|
||||
cc65
|
||||
|
||||
A C Compiler for 6502 Systems
|
||||
|
||||
(C) Copyright 1989 John R. Dunning
|
||||
(C) Copyright 1998-2000 Ullrich von Bassewitz
|
||||
(uz@musoftware.de)
|
||||
|
||||
|
||||
|
||||
Contents
|
||||
--------
|
||||
|
||||
1. Overview
|
||||
|
||||
2. Usage
|
||||
|
||||
3. Input and output
|
||||
|
||||
4. Differences to the ISO standard
|
||||
|
||||
5. Extensions
|
||||
|
||||
6. Predefined macros
|
||||
|
||||
7. #pragmas
|
||||
|
||||
8. Bugs/Feedback
|
||||
|
||||
9. Copyright
|
||||
|
||||
|
||||
|
||||
1. Overview
|
||||
-----------
|
||||
|
||||
cc65 was originally a C compiler for the Atari 8-bit machines written by
|
||||
John R. Dunning. In prior releases I've described the compiler by listing
|
||||
up the changes made by me. I have made many more changes in the meantime
|
||||
(and rewritten major parts of the compiler), so I will no longer do that,
|
||||
since the list would be too large and of no use to anyone. Instead I will
|
||||
describe the compiler in respect to the ANSI/ISO C standard. In fact, I'm
|
||||
planning a complete rewrite (that is, a complete new compiler) for the
|
||||
next release, since there are too many limitations in the current code,
|
||||
and removing these limitations would mean a rewrite of many more parts of
|
||||
the compiler.
|
||||
|
||||
There is a separate document named "library.txt" that covers the library
|
||||
available for the compiler. If you know C and are interested in doing
|
||||
actual programming, the library documentation is probably of much more use
|
||||
than this document.
|
||||
|
||||
If you need some hints for getting the best code out of the compiler, you
|
||||
may have a look at "coding.txt" which covers some code generation issues.
|
||||
|
||||
|
||||
|
||||
2. Usage
|
||||
--------
|
||||
|
||||
The compiler translates C files into files containing assembler code that
|
||||
may be translated by the ca65 macroassembler (for more information about
|
||||
the assembler, have a look at ca65.txt).
|
||||
|
||||
The compiler may be called as follows:
|
||||
|
||||
---------------------------------------------------------------------------
|
||||
Usage: cc65 [options] file
|
||||
Short options:
|
||||
-d Debug mode
|
||||
-g Add debug info to object file
|
||||
-h Help (this text)
|
||||
-j Default characters are signed
|
||||
-o name Name the output file
|
||||
-t sys Set the target system
|
||||
-v Increase verbosity
|
||||
-A Strict ANSI mode
|
||||
-Cl Make local variables static
|
||||
-Dsym[=defn] Define a symbol
|
||||
-I dir Set an include directory search path
|
||||
-O Optimize code
|
||||
-Oi Optimize code, inline more code
|
||||
-Or Enable register variables
|
||||
-Os Inline some known functions
|
||||
-T Include source as comment
|
||||
-V Print the compiler version number
|
||||
-W Suppress warnings
|
||||
|
||||
Long options:
|
||||
--ansi Strict ANSI mode
|
||||
--cpu type Set cpu type
|
||||
--debug Debug mode
|
||||
--debug-info Add debug info to object file
|
||||
--help Help (this text)
|
||||
--include-dir dir Set an include directory search path
|
||||
--signed-chars Default characters are signed
|
||||
--static-locals Make local variables static
|
||||
--target sys Set the target system
|
||||
--verbose Increase verbosity
|
||||
--version Print the compiler version number
|
||||
---------------------------------------------------------------------------
|
||||
|
||||
|
||||
-A
|
||||
--ansi
|
||||
|
||||
This option disables any compiler exensions. Have a look at section 5
|
||||
for a discussion of compiler extensions. In addition, the macro
|
||||
|
||||
__STRICT_ANSI__
|
||||
|
||||
is defined, when using one of these options.
|
||||
|
||||
|
||||
--cpu CPU
|
||||
|
||||
A new, still experimental option. You may specify "6502" or "65C02" as
|
||||
the CPU. 6502 is the default, so this will not change anything.
|
||||
Specifying 65C02 will use a few 65C02 instructions when generating code.
|
||||
Don't expect too much from this option: It is still new (and may have
|
||||
bugs), and the additional instructions for the 65C02 are not that
|
||||
overwhelming.
|
||||
|
||||
|
||||
-d
|
||||
--debug
|
||||
|
||||
Enables debug mode, something that should not be needed for mere
|
||||
mortals:-)
|
||||
|
||||
|
||||
-D sym[=definition]
|
||||
|
||||
Define a macro on the command line. If no definition is given, the macro
|
||||
is defined to the value "1".
|
||||
|
||||
|
||||
-g
|
||||
--debug-info
|
||||
|
||||
This will cause the compiler 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.
|
||||
|
||||
|
||||
-j
|
||||
--signed-chars
|
||||
|
||||
Using this option, you can make the default characters signed. Since the
|
||||
6502 has no provisions for sign extending characters (which is needed on
|
||||
almost any load operation), this will make the code larger and slower. A
|
||||
better way is to declare characters explicitly as "signed" if needed.
|
||||
You can also use "#pragma signedchars" for better control of this option
|
||||
(see section 7).
|
||||
|
||||
|
||||
-t target
|
||||
--target target
|
||||
|
||||
This option is used to set the target system. The target system
|
||||
determines things like the character set that is used for strings and
|
||||
character constants. The following target systems are supported:
|
||||
|
||||
none
|
||||
c64
|
||||
c128
|
||||
ace (no library support)
|
||||
plus4
|
||||
cbm610
|
||||
pet (all CBM PET systems except the 2001)
|
||||
nes (Nintendo Entertainment System)
|
||||
apple2
|
||||
geos
|
||||
|
||||
|
||||
-v
|
||||
--verbose
|
||||
|
||||
Using this option, the compiler will be somewhat more verbose if errors
|
||||
or warnings are encountered.
|
||||
|
||||
|
||||
-Cl
|
||||
--static-locals
|
||||
|
||||
Use static storage for local variables instead of storage on the stack.
|
||||
Since the stack is emulated in software, this gives shorter and usually
|
||||
faster code, but the code is no longer reentrant. The difference between
|
||||
-Cl and declaring local variables as static yourself is, that
|
||||
initializer code is executed each time, the function is entered. So when
|
||||
using
|
||||
|
||||
void f (void)
|
||||
{
|
||||
unsigned a = 1;
|
||||
...
|
||||
}
|
||||
|
||||
the variable a will always have the value 1 when entering the function
|
||||
and using -Cl, while in
|
||||
|
||||
void f (void)
|
||||
{
|
||||
static unsigned a = 1;
|
||||
....
|
||||
}
|
||||
|
||||
the variable a will have the value 1 only the first time, the function
|
||||
is entered, and will keep the old value from one call of the function to
|
||||
the next.
|
||||
|
||||
You may also use #pragma staticlocals to change this setting in your
|
||||
sources (see section 7).
|
||||
|
||||
|
||||
-I dir
|
||||
--include-dir dir
|
||||
|
||||
Set a directory where the compiler searches for include files. You may
|
||||
use this option multiple times to add more than one directory to the
|
||||
search list.
|
||||
|
||||
|
||||
-o name
|
||||
|
||||
Specify the name of the output file. If you don't specify a name, the
|
||||
name of the C input file is used, with the extension replaced by ".s".
|
||||
|
||||
|
||||
-O, -Oi, -Or, -Os
|
||||
|
||||
Enable an optimizer run over the produced code.
|
||||
|
||||
Using -Oi, the code generator will inline some code where otherwise a
|
||||
runtime functions would have been called, even if the generated code is
|
||||
larger. This will not only remove the overhead for a function call, but
|
||||
will make the code visible for the optimizer.
|
||||
|
||||
-Or will make the compiler honor the "register" keyword. Local variables
|
||||
may be placed in registers (which are actually zero page locations).
|
||||
There is some overhead involved with register variables, since the old
|
||||
contents of the registers must be saved and restored. In addition, the
|
||||
current implementation does not make good use of register variables, so
|
||||
using -Or may make your program even slower and larger. Use with care!
|
||||
|
||||
Using -Os will force the compiler to inline some known functions from
|
||||
the C library like strlen. Note: This has two consequences:
|
||||
|
||||
* You may not use names of standard C functions in your own code. If
|
||||
you do that, your program is not standard compliant anyway, but
|
||||
using -Os will actually break things.
|
||||
|
||||
* The inlined string and memory functions will not handle strings or
|
||||
memory areas larger than 255 bytes. Similar, the inlined is..()
|
||||
functions will not work with values outside char range.
|
||||
|
||||
It is possible to concatenate the modifiers for -O. For example, to
|
||||
enable register variables and inlining of known functions, you may use
|
||||
-Ors.
|
||||
|
||||
|
||||
-T
|
||||
|
||||
This include the source code as comments in the generated code. This is
|
||||
normally not needed.
|
||||
|
||||
|
||||
-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.
|
||||
|
||||
|
||||
-W
|
||||
|
||||
This option will suppress any warnings generated by the compiler. Since
|
||||
any source file may be written in a manner that it will not produce
|
||||
compiler warnings, using this option is usually not a good idea.
|
||||
|
||||
|
||||
|
||||
3. Input and output
|
||||
-------------------
|
||||
|
||||
The compiler will accept one C 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.
|
||||
|
||||
In addition to the paths named in the -I option on the command line, the
|
||||
directory named in the environment variable CC65_INC is added to the
|
||||
search path for include files on startup.
|
||||
|
||||
|
||||
|
||||
4. Differences to the ISO standard
|
||||
----------------------------------
|
||||
|
||||
Here is a list of differences between the language, the compiler accepts,
|
||||
and the one defined by the ISO standard:
|
||||
|
||||
|
||||
* The compiler allows single line comments that start with //. This
|
||||
feature is disabled in strict ANSI mode.
|
||||
|
||||
* The compiler allows unnamed parameters in parameter lists. The
|
||||
compiler will not issue warnings about unused parameters that don't
|
||||
have a name. This feature is disabled in strict ANSI mode.
|
||||
|
||||
* The compiler has some additional keywords:
|
||||
|
||||
asm, __asm__, fastcall, __fastcall__, __AX__, __EAX__, __func__,
|
||||
__attribute__
|
||||
|
||||
The keywords without the underlines are disabled in strict ANSI mode.
|
||||
|
||||
* The "const" modifier is available, but has no effect.
|
||||
|
||||
* The datatypes "float" and "double" are not available.
|
||||
|
||||
* The compiler does not support bit fields.
|
||||
|
||||
* Initialization of local variables is only possible for scalar data
|
||||
types (that is, not for arrays and structs).
|
||||
|
||||
* Because of the "wrong" order of the parameters on the stack, there is
|
||||
an additional macro needed to access parameters in a variable
|
||||
parameter list in a C function.
|
||||
|
||||
* Functions may not return structs. However, struct assignment *is*
|
||||
possible.
|
||||
|
||||
* Part of the C library is available only with fastcall calling
|
||||
conventions (see below). This means, that you may not mix pointers to
|
||||
those functions with pointers to user written functions.
|
||||
|
||||
There may be some more minor differences, I'm currently not aware off. The
|
||||
biggest problem is the missing float data type. With this limitation in
|
||||
mind, you should be able to write fairly portable code.
|
||||
|
||||
|
||||
|
||||
5. Extensions
|
||||
-------------
|
||||
|
||||
This cc65 version has some extensions to the ISO C standard.
|
||||
|
||||
* The compiler allows // comments (like in C++ and in the proposed C9x
|
||||
standard). This feature is disabled by -A.
|
||||
|
||||
* The compiler allows to insert assembler statements into the output
|
||||
file. The syntax is
|
||||
|
||||
asm (<string literal>) ;
|
||||
|
||||
or
|
||||
|
||||
__asm__ (<string literal>) ;
|
||||
|
||||
The first form is in the user namespace and is disabled if the -A
|
||||
switch is given.
|
||||
|
||||
The given string is inserted literally into the output file, and a
|
||||
newline is appended. The statements in this string are not checked by
|
||||
the compiler, so be careful!
|
||||
|
||||
The asm statement may be used inside a function and on global file
|
||||
level.
|
||||
|
||||
* There is a special calling convention named "fastcall". This calling
|
||||
convention is currently only usable for functions written in
|
||||
assembler. The syntax for a function declaration using fastcall is
|
||||
|
||||
<return type> fastcall <function name> (<parameter list>)
|
||||
|
||||
or
|
||||
|
||||
<return type> __fastcall__ <function name> (<parameter list>)
|
||||
|
||||
An example would be
|
||||
|
||||
void __fastcall__ f (unsigned char c)
|
||||
|
||||
The first form of the fastcall keyword is in the user namespace and is
|
||||
therefore disabled in strict ANSI mode.
|
||||
|
||||
For functions declared as fastcall, the rightmost parameter is not
|
||||
pushed on the stack but left in the primary register when the function
|
||||
is called. This will reduce the cost when calling assembler functions
|
||||
significantly, especially when the function itself is rather small.
|
||||
|
||||
* There are two pseudo variables named __AX__ and __EAX__. Both refer to
|
||||
the primary register that is used by the compiler to evaluate
|
||||
expressions or return function results. __AX__ is of type unsigned int
|
||||
and __EAX__ of type long unsigned int respectively. The pseudo
|
||||
variables may be used as lvalue and rvalue as every other variable.
|
||||
They are most useful together with short sequences of assembler code.
|
||||
For example, the macro
|
||||
|
||||
#define hi(x) (__AX__=(x),asm("\ttxa\n\tldx\t#$00",__AX__)
|
||||
|
||||
will give the high byte of any unsigned value.
|
||||
|
||||
* Inside a function, the identifier __func__ gives the name of the
|
||||
current function as a string. Outside of functions, __func__ is
|
||||
undefined.
|
||||
Example:
|
||||
|
||||
#define PRINT_DEBUG(s) printf ("%s: %s\n", __func__, s);
|
||||
|
||||
The macro will print the name of the current function plus a given
|
||||
string.
|
||||
|
||||
|
||||
|
||||
6. Predefined macros
|
||||
--------------------
|
||||
|
||||
The compiler defines several macros at startup:
|
||||
|
||||
|
||||
__CC65__ This macro is always defined. Its value is the version
|
||||
number of the compiler in hex. Version 2.0.1 of the
|
||||
compiler will have this macro defined as 0x0201.
|
||||
|
||||
__CBM__ This macro is defined if the target system is one of the
|
||||
CBM targets.
|
||||
|
||||
__C64__ This macro is defined if the target is the c64 (-t c64).
|
||||
|
||||
__C128__ This macro is defined if the target is the c128 (-t c128).
|
||||
|
||||
__PLUS4__ This macro is defined if the target is the plus/4
|
||||
(-t plus4).
|
||||
|
||||
__CBM610__ This macro is defined if the target is one of the CBM
|
||||
600/700 family of computers (called B series in the US).
|
||||
|
||||
__PET__ This macro is defined if the target is the PET family of
|
||||
computers (-t pet).
|
||||
|
||||
__NES__ This macro is defined if the target is the Nintendo
|
||||
Entertainment System (-t nes).
|
||||
|
||||
__ATARI__ This macro is defined if the target is one of the Atari
|
||||
computers (400/800/130XL/800XL). Note that there is no
|
||||
runtime and C library support for atari systems.
|
||||
|
||||
__ACE__ This macro is defined if the target is Bruce Craigs ACE
|
||||
operating system. Note that there is no longer runtime
|
||||
and library support for ACE.
|
||||
|
||||
__APPLE2__ This macro is defined if the target is the Apple ][
|
||||
(-t apple2).
|
||||
|
||||
__GEOS__ This macro is defined if you are compiling for the GEOS
|
||||
system (-t geos).
|
||||
|
||||
__FILE__ This macro expands to a string containing the name of
|
||||
the C source file.
|
||||
|
||||
__LINE__ This macro expands to the current line number.
|
||||
|
||||
__STRICT_ANSI__ This macro is defined to 1 if the -A compiler option was
|
||||
given, and undefined otherwise.
|
||||
|
||||
__OPT__ Is defined if the compiler was called with the -O command
|
||||
line option.
|
||||
|
||||
__OPT_i__ Is defined if the compiler was called with the -Oi command
|
||||
line option.
|
||||
|
||||
__OPT_r__ Is defined if the compiler was called with the -Or command
|
||||
line option.
|
||||
|
||||
__OPT_s__ Is defined if the compiler was called with the -Os command
|
||||
line option.
|
||||
|
||||
|
||||
|
||||
7. #pragmas
|
||||
-----------
|
||||
|
||||
The compiler understands some pragmas that may be used to change code
|
||||
generation and other stuff.
|
||||
|
||||
|
||||
#pragma bssseg (<name>)
|
||||
|
||||
This pragma changes the name used for the BSS segment (the BSS segment
|
||||
is used to store uninitialized data). The argument is a string enclosed
|
||||
in double quotes.
|
||||
|
||||
Note: The default linker configuration file does only map the standard
|
||||
segments. If you use other segments, you have to create a new linker
|
||||
configuration file.
|
||||
|
||||
Beware: The startup code will zero only the default BSS segment. If you
|
||||
use another BSS segment, you have to do that yourself, otherwise
|
||||
uninitialized variables do not have the value zero.
|
||||
|
||||
Example:
|
||||
|
||||
#pragma bssseg ("MyBSS")
|
||||
|
||||
|
||||
#pragma codeseg (<name>)
|
||||
|
||||
This pragma changes the name used for the CODE segment (the CODE segment
|
||||
is used to store executable code). The argument is a string enclosed in
|
||||
double quotes.
|
||||
|
||||
Note: The default linker configuration file does only map the standard
|
||||
segments. If you use other segments, you have to create a new linker
|
||||
configuration file.
|
||||
|
||||
Example:
|
||||
|
||||
#pragma bssseg ("MyCODE")
|
||||
|
||||
|
||||
#pragma dataseg (<name>)
|
||||
|
||||
This pragma changes the name used for the DATA segment (the DATA segment
|
||||
is used to store initialized data). The argument is a string enclosed in
|
||||
double quotes.
|
||||
|
||||
Note: The default linker configuration file does only map the standard
|
||||
segments. If you use other segments, you have to create a new linker
|
||||
configuration file.
|
||||
|
||||
Example:
|
||||
|
||||
#pragma bssseg ("MyDATA")
|
||||
|
||||
|
||||
#pragma rodataseg (<name>)
|
||||
|
||||
This pragma changes the name used for the RODATA segment (the RODATA
|
||||
segment is used to store readonly data). The argument is a string
|
||||
enclosed in double quotes.
|
||||
|
||||
Note: The default linker configuration file does only map the standard
|
||||
segments. If you use other segments, you have to create a new linker
|
||||
configuration file.
|
||||
|
||||
Example:
|
||||
|
||||
#pragma bssseg ("MyRODATA")
|
||||
|
||||
|
||||
#pragma regvaraddr (<const int>)
|
||||
|
||||
The compiler does not allow to take the address of register variables.
|
||||
The regvaraddr pragma changes this. Taking the address of a register
|
||||
variable is allowed after using this pragma, if the argument is not
|
||||
zero. Using an argument of zero changes back to the default behaviour.
|
||||
|
||||
Beware: The C standard does not allow taking the address of a variable
|
||||
declared as register. So your programs become non-portable if you use
|
||||
this pragma. In addition, your program may not work. This is usually the
|
||||
case if a subroutine is called with the address of a register variable,
|
||||
and this subroutine (or a subroutine called from there) uses itself
|
||||
register variables. So be careful with this #pragma.
|
||||
|
||||
Example:
|
||||
|
||||
#pragma regvaraddr(1) /* Allow taking the address
|
||||
* of register variables
|
||||
*/
|
||||
|
||||
|
||||
#pragma signedchars (<const int>)
|
||||
|
||||
Changed the signedness of the default character type. If the argument
|
||||
is not zero, default characters are signed, otherwise characters are
|
||||
unsigned. The compiler default is to make characters unsigned since this
|
||||
creates a lot better code.
|
||||
|
||||
|
||||
#pragma staticlocals (<const int>)
|
||||
|
||||
Use variables in the bss segment instead of variables on the stack. This
|
||||
pragma changes the default set by the compiler option -Cl. If the argument
|
||||
is not zero, local variables are allocated in the BSS segment, leading to
|
||||
shorter and in most cases faster, but non-reentrant code.
|
||||
|
||||
|
||||
#pragma zpsym (<name>)
|
||||
|
||||
Tell the compiler that the - previously as external declared - symbol with
|
||||
the given name is a zero page symbol (usually from an assembler file).
|
||||
The compiler will create a matching import declaration for the assembler.
|
||||
|
||||
Example:
|
||||
|
||||
extern int foo;
|
||||
#pragma zpsym ("foo"); /* foo is in the zeropage */
|
||||
|
||||
|
||||
|
||||
8. Bugs/Feedback
|
||||
----------------
|
||||
|
||||
If you have problems using the compiler, if you find any bugs, or if
|
||||
you're doing something interesting with the compiler, I would be glad to
|
||||
hear from you. Feel free to contact me by email (uz@musoftware.de).
|
||||
|
||||
|
||||
|
||||
9. Copyright
|
||||
------------
|
||||
|
||||
This is the original compiler copyright:
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
-*- Mode: Text -*-
|
||||
|
||||
This is the copyright notice for RA65, LINK65, LIBR65, and other
|
||||
Atari 8-bit programs. Said programs are Copyright 1989, by John R.
|
||||
Dunning. All rights reserved, with the following exceptions:
|
||||
|
||||
Anyone may copy or redistribute these programs, provided that:
|
||||
|
||||
1: You don't charge anything for the copy. It is permissable to
|
||||
charge a nominal fee for media, etc.
|
||||
|
||||
2: All source code and documentation for the programs is made
|
||||
available as part of the distribution.
|
||||
|
||||
3: This copyright notice is preserved verbatim, and included in
|
||||
the distribution.
|
||||
|
||||
You are allowed to modify these programs, and redistribute the
|
||||
modified versions, provided that the modifications are clearly noted.
|
||||
|
||||
There is NO WARRANTY with this software, it comes as is, and is
|
||||
distributed in the hope that it may be useful.
|
||||
|
||||
This copyright notice applies to any program which contains
|
||||
this text, or the refers to this file.
|
||||
|
||||
This copyright notice is based on the one published by the Free
|
||||
Software Foundation, sometimes known as the GNU project. The idea
|
||||
is the same as theirs, ie the software is free, and is intended to
|
||||
stay that way. Everybody has the right to copy, modify, and re-
|
||||
distribute this software. Nobody has the right to prevent anyone
|
||||
else from copying, modifying or redistributing it.
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
|
||||
In acknowledgment of this copyright, I will place my own changes to the
|
||||
compiler under the same copyright. Please note however, that the library
|
||||
and all binutils are covered by another copyright, and that I'm planning
|
||||
to do a complete rewrite of the compiler, after which the compiler
|
||||
copyright will also change.
|
||||
|
||||
For the list of changes requested by this copyright see newvers.txt.
|
||||
|
||||
|
||||
|
110
doc/dio.sgml
Normal file
110
doc/dio.sgml
Normal file
|
@ -0,0 +1,110 @@
|
|||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
<title>Diskette Sector I/O Routines
|
||||
<author>Christian Groessler, <htmlurl url="mailto:cpg@aladdin.de" name="cpg@aladdin.de">
|
||||
<date>21.11.2000
|
||||
|
||||
<abstract>
|
||||
The cc65 library provides functions to read and write raw disk sectors.
|
||||
Include the dio.h header file to get the necessary definitions.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Opening the disk for low level I/O<p>
|
||||
|
||||
Prior to using these functions a handle to the drive has to be obtained. This
|
||||
is done with the <tt>dio_open</tt> function. After use, the handle should be
|
||||
released with the <tt>dio_close</tt> function.
|
||||
|
||||
<tscreen><verb>
|
||||
dhandle_t __fastcall__ dio_open (driveid_t drive_id);
|
||||
</verb></tscreen>
|
||||
|
||||
The <tt>drive_id</tt> specifies the drive to access, with 0 being the first
|
||||
disk drive, 1 the second, and so on.
|
||||
|
||||
<tscreen><verb>
|
||||
unsigned char __fastcall__ dio_close (dhandle_t handle);
|
||||
</verb></tscreen>
|
||||
|
||||
Closes a handle obtained by <tt>dio_open</tt>. Returns status code.
|
||||
<p>
|
||||
|
||||
<sect>Reading and writing sectors<p>
|
||||
|
||||
The read and write functions are:
|
||||
|
||||
<tscreen><verb>
|
||||
unsigned char __fastcall__ dio_read (dhandle_t handle,
|
||||
sectnum_t sect_num,
|
||||
void *buffer);
|
||||
</verb></tscreen>
|
||||
|
||||
This function will read the sector specified by sect_num into the memory
|
||||
location at buffer.
|
||||
|
||||
<tscreen><verb>
|
||||
unsigned char __fastcall__ dio_write (dhandle_t handle,
|
||||
sectnum_t sect_num,
|
||||
const void *buffer);
|
||||
</verb></tscreen>
|
||||
|
||||
This function will write the memory contents at buffer to the sector specified
|
||||
by <tt>sect_num</tt>. No verify is performed.
|
||||
|
||||
<tscreen><verb>
|
||||
unsigned char __fastcall__ dio_write_verify (dhandle_t handle,
|
||||
sectnum_t sect_num,
|
||||
const void *buffer);
|
||||
</verb></tscreen>
|
||||
|
||||
This function will write the memory contents at buffer to the sector specified
|
||||
by <tt>sect_num</tt>. A verification is performed.
|
||||
<p>
|
||||
|
||||
All these functions will return 0 for success and an OS specific error code in
|
||||
case of failure.
|
||||
<p>
|
||||
|
||||
|
||||
<sect>Converting sector numbers<p>
|
||||
|
||||
Since the read and write functions expect a sector number, for systems where
|
||||
the sectors aren't addressed by a logical sector number (e.g. CBM drives),
|
||||
there are 2 conversion functions. One of them converts a logical sector number
|
||||
to a head/track/sector triple. The other conversion function works the other
|
||||
way round.
|
||||
|
||||
<tscreen><verb>
|
||||
unsigned char __fastcall__ dio_phys_to_log (dhandle_t handle,
|
||||
const dio_phys_pos *physpos,
|
||||
sectnum_t *sectnum);
|
||||
</verb></tscreen>
|
||||
|
||||
This function converts track/head/sector to logical sector number.
|
||||
|
||||
<tscreen><verb>
|
||||
unsigned char __fastcall__ dio_log_to_phys(_dhandle_t handle,
|
||||
const _sectnum_t *sectnum,
|
||||
dio_phys_pos *physpos);
|
||||
</verb></tscreen>
|
||||
|
||||
This function converts a logical sector number to track/head/sector notation.
|
||||
<p>
|
||||
|
||||
Note, that on systems which natively use logical sector numbers (e.g. Atari),
|
||||
the conversion functions are dummies. They ignore head/track
|
||||
(<tt>dio_phys_to_log</tt>) or return them as zero (<tt>dio_log_to_phys</tt>).
|
||||
The logical sector number is returned as physical sector and vice versa.
|
||||
<p>
|
||||
|
||||
|
||||
</article>
|
||||
|
||||
|
||||
|
Loading…
Add table
Reference in a new issue