geos-3.html

cc65 的编译器文档

can be found in <CODE>VLIRInfo.curRecord + 1</CODE>).</P>

<H3>ReadRecord and WriteRecord</H3>

<P><CODE>char ReadRecord (char *buffer, unsigned fLength)</CODE></P>
<P><CODE>char WriteRecord (char *buffer, unsigned fLength)</CODE></P>
<P>This function will load or save at most <CODE>fLength</CODE> bytes from currently pointed record into or from
<CODE>buffer</CODE>.</P>

<H2><A NAME="ss3.7">3.7</A> <A HREF="geos.html#toc3.7">Memory and Strings</A>
</H2>

<P>Functions covered in this section are common for whole C world - copying memory parts and
strings is one of the main computer tasks. GEOS also has interface to do this. These functions
are replacement for those like <CODE>memset, memcpy, strcpy</CODE> etc. from standard libraries.
If you are dealing with short strings (up to 255 characters) you should use these functions
instead of standard ones. E.g. <CODE>CopyString</CODE> instead of <CODE>strcpy</CODE>. It will work faster.</P>
<P>However some of them have slighty different calling convention (order of arguments to be specific),
so please check their syntax here before direct replacing.</P>
<P>Please note that the memory areas described here as <EM>strings</EM> are up to 255 characters (without
counting the terminating <CODE>NULL</CODE>), and <EM>regions</EM> can cover whole 64K of memory.</P>

<H3>CopyString</H3>

<P><CODE>void CopyString (char *dest, char *src)</CODE></P>
<P>This function copies string from <CODE>src</CODE> to <CODE>dest</CODE>, until it reaches <CODE>NULL</CODE>. <CODE>NULL</CODE>
is also copied.</P>

<H3>CmpString</H3>

<P><CODE>char CmpString (char *s1, char *s2)</CODE></P>
<P>This function compares string <CODE>s1</CODE> to <CODE>s2</CODE> for equality - this is case sensitive, and both
strings have to have the same length. It returns either <CODE>true</CODE> (non-zero) or <CODE>false</CODE> (zero).</P>

<H3>CopyFString and CmpFString</H3>

<P><CODE>void CopyFString (char length, char *dest, char *src)</CODE></P>
<P><CODE>char CmpFString (char length, char *s1, char *s2)</CODE></P>
<P>These two are similar to <CODE>CopyString</CODE> and <CODE>CmpString</CODE> except the fact, that you provide
the length of copied or compared strings. The strings can also contain several <CODE>NULL</CODE>
characters - they are not treated as delimiters.</P>

<H3>CRC</H3>

<P><CODE>unsigned CRC (char *src, unsigned length)</CODE></P>
<P>This function calculates the CRC checksum for given memory range. I don't know if it is
compatible with standard CRC routines.</P>

<H3>FillRam and ClearRam</H3>

<P><CODE>void *FillRam (char *dest, char value, unsigned length)</CODE></P>
<P><CODE>void *ClearRam (char *dest, unsigned length)</CODE></P>
<P>Both functions are filling given memory range. <CODE>ClearRam</CODE> fills with <CODE>0s</CODE>, while
<CODE>FillRam</CODE> uses given <CODE>value</CODE>. Be warned that these functions destroy <CODE>r0, r1 and
r2L</CODE> registers. These are aliases for <CODE>memset</CODE> and <CODE>bzero</CODE>, respectively.</P>

<H3>MoveData</H3>

<P><CODE>void *MoveData (char *dest, char *src, unsigned length)</CODE></P>
<P>This functions copies one memory region to another. There are checks for overlap and the
non-destructive method is chosen. Be warned that this function destroys contents of
<CODE>r0, r1 and r2</CODE> registers. This is also alias for <CODE>memcpy</CODE></P>

<H3>InitRam</H3>

<P><CODE>void InitRam (char *table)</CODE></P>
<P>This function allows to initialize multiple memory locations with single bytes or strings.
This is done with <CODE>table</CODE> where everything is defined. See structures chapter for description of
<CODE>InitRam's</CODE> command string.</P>

<H3>Stash, Fetch, Swap, and VerifyRAM</H3>

<P><CODE>void StashRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)</CODE></P>
<P><CODE>void FetchRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)</CODE></P>
<P><CODE>void SwapRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)</CODE></P>
<P><CODE> char VerifyRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)</CODE></P>
<P>These functions are interface to REU - Ram Expansion Unit. I think that they are self-explanatory.
You can check for REU presence by taking value of <CODE>ramExpSize</CODE>. You have to do it before
using any of these functions.</P>

<H2><A NAME="ss3.8">3.8</A> <A HREF="geos.html#toc3.8">Processes and Multitasking</A>
</H2>

<P>Weird? Not at all. GEOS has limited multitasking ability. You can set up a chain of functions
called in specified intervals and you can put the main program to sleep without disturbing other
tasks and making user interface unresponsive.</P>

<H3>InitProcesses</H3>

<P><CODE>void InitProcesses (char number, struct process *processTab)</CODE></P>
<P>This is the main initialization routine. After calling it processes are set up, but not
enabled. The parameters for <CODE>InitProcesses</CODE> are:
<UL>
<LI><CODE>number</CODE> - number of processes</LI>
<LI><CODE>processTab</CODE> - table of <CODE>struct process</CODE>, with size equal to <CODE>number</CODE></LI>
</UL>
</P>
<P>Single task is described by entry in <CODE>processTab</CODE>, it contains two values - <CODE>pointer</CODE> to
task function and number of <CODE>jiffies</CODE> which describe the delay between calls to task. On PAL
systems there are 50 jiffies per second, while on NTSC there are 60.</P>
<P>The maximum number of tasks is 20. Be warned that GEOS doesn't check if parameters are valid and
if <CODE>processTab</CODE> would be too large it would overwrite existing data in GEOS space.</P>
<P>There's one important thing - the last entry in <CODE>processTab</CODE> has to be <CODE>NULL,NULL</CODE>, so the
maximum size of <CODE>processTab</CODE> is equal to 21.</P>
<P>See description of <CODE>process</CODE> structure for more detailed discussion on this.</P>

<H3>RestartProcess and EnableProcess</H3>

<P><CODE>void RestartProcess (char processNumber)</CODE></P>
<P><CODE>void EnableProcess (char processNumber)</CODE></P>
<P>These two functions start the task counter. <CODE>RestartProcess</CODE> for each process should be called
after <CODE>InitProcesses</CODE>, because it resets all flags and counters and it starts the counters.</P>
<P><CODE>RestartProcess</CODE> enables counters and sets their initial value to that given in <CODE>processTab</CODE>.</P>
<P><CODE>EnableProcess</CODE> forces given process to execute by simulating the timer running out of time.</P>

<H3>BlockProcess and UnBlockProcess</H3>

<P><CODE>void BlockProcess (char processNumber)</CODE></P>
<P><CODE>void UnBlockProcess (char processNumber)</CODE></P>
<P><CODE>BlockProcess</CODE> disables the execution of given process, but this does not disable the timers.
It means that if you call <CODE>UnBlockProcess</CODE> before timer runs out, the process will be executed.</P>
<P><CODE>UnBlockProcess</CODE> does the opposite.</P>

<H3>FreezeProcess and UnFreezeProcess</H3>

<P><CODE>void FreezeProcess (char processNumber)</CODE></P>
<P><CODE>void UnFreezeProcess (char processNumber)</CODE></P>
<P><CODE>FreezeProcess</CODE> disables timer for given process. <CODE>UnFreezeProcess</CODE> does the opposite.
This is not equal to <CODE>RestartProcess</CODE> as timers are not reloaded with initial value.</P>

<H3>Sleep</H3>

<P><CODE>void Sleep (unsigned jiffies)</CODE></P>
<P>This function is multitasking sleep - the program is halted, but it doesn't block other functions
e.g. callbacks from menus and icons.
The only argument here is the number of jiffies to wait until app will wake up. It depends on
video mode (PAL or NTSC) how many jiffies there are per second (50 or 60, respectively).
If you don't want to worry about it and need only full second resolution, call standard
<CODE>sleep</CODE> function from <CODE>unistd.h</CODE>.</P>

<H2><A NAME="ss3.9">3.9</A> <A HREF="geos.html#toc3.9">System Functions</A>
</H2>

<H3>FirstInit</H3>

<P><CODE>void FirstInit (void)</CODE></P>
<P>This function initializes some GEOS variables and mouse parameters. This is called on GEOS boot
up. You shouldn't use this unless you know what you are doing.</P>

<H3>InitForIO and DoneWithIO</H3>

<P><CODE>void InitForIO (void)</CODE></P>
<P><CODE>void DoneWithIO (void)</CODE></P>
<P>These functions are called by some disk routines. You should call them only if you want to
do something with IO registers or call one of Kernal ROM routines. Note that this is rather an
expensive way of turning off IRQs and enabling IO.</P>

<H3>MainLoop</H3>

<P><CODE>void MainLoop (void)</CODE></P>
<P>Returns control to the system. Any code between call to <CODE>MainLoop</CODE> and the end of current
function will never be executed. When in <CODE>MainLoop</CODE> systems waits for your action - using
icons, keyboard or menus to force some specific action from program. You have to define
proper handlers before that.</P>

<H3>EnterDeskTop</H3>

<P><CODE>void EnterDeskTop (void)</CODE></P>
<P>This is an alias for <CODE>exit(0)</CODE> so you will never burn yourself. Anyway, you should not
use it. Always use <CODE>exit()</CODE> instead. Library destructors and functions registered with
<CODE>atexit()</CODE> are called.</P>

<H3>ToBASIC</H3>

<P><CODE>void ToBASIC (void)</CODE></P>
<P>This one is another way of finishing application - forcing GEOS to shutdown and exit to BASIC.
I was considering whether to include it or not, but maybe someone will need it. Which is I doubt.</P>
<P><EM>WARNING:</EM> library destructors and functions registered with <CODE>atexit()</CODE> will not be called
so it is quite unsafe way to finish your program.</P>

<H3>Panic</H3>

<P><CODE>void Panic (void)</CODE></P>
<P>This calls system's <CODE>Panic</CODE> handler - it shows dialog box with message
<BLOCKQUOTE><CODE>
<PRE>
System error at:xxxx
</PRE>
</CODE></BLOCKQUOTE>

where <CODE>xxxx</CODE> is last known execution address (caller). By default this is bound to <CODE>BRK</CODE>
instruction, but it might be usable in debugging as kind of <CODE>assert</CODE>. (Note that <CODE>assert</CODE>
is available as a separate function and will give you more information than that).</P>
<P>System is halted after call to <CODE>Panic</CODE> which means that library destructors will not be
called and some data may be lost (no wonder you're panicking).</P>

<H3>CallRoutine</H3>

<P><CODE>void CallRoutine (void &ast;myFunct)</CODE></P>
<P>This is system caller routine. You need to provide pointer to a function and it will be immediately
called, unless the pointer is equal to <CODE>NULL</CODE>. This is the main functionality of this function -
you don't need to check if the pointer is valid.</P>

<H3>GetSerialNumber</H3>

<P><CODE>unsigned GetSerialNumber (void)</CODE></P>
<P>This function returns the serial number of system. It might be used for copy-protection.
However, please remember that the Free Software is a true power and you are using it
right now.</P>

<H3>GetRandom</H3>

<P><CODE>char GetRandom (void)</CODE></P>
<P>This function returns a random number. It can be also read from <CODE>random</CODE> e.g.
<BLOCKQUOTE><CODE>
<PRE>
a=random;
</PRE>
</CODE></BLOCKQUOTE>

but by calling this function you are sure that the results will be always different.
<CODE>random</CODE> is updated once a frame (50Hz PAL) and on every call to <CODE>GetRandom</CODE>.</P>
<P>Note that it is not the same as <CODE>rand</CODE> function from the standard library. <CODE>GetRandom</CODE>
will give you unpredictable results (if IRQs would occur between calls to it) while
<CODE>rand</CODE> conforms to the standard and for given seed (<CODE>srand</CODE>) it always returns with the
same sequence of values.</P>

<H3>SetDevice</H3>

<P><CODE>void SetDevice (char device)</CODE></P>
<P>This function sets current device to given. It might be used together with <CODE>InitForIO</CODE>,
<CODE>DoneWithIO</CODE> and some Kernal routines. Unless new device is a disk drive this only sets
new value in <CODE>curDevice</CODE>, in other case new disk driver is loaded from REU or internal RAM.</P>

<H3>get_ostype</H3>

<P><CODE>char get_ostype (void)</CODE></P>
<P>This function returns GEOS Kernal version combined (by logical OR) with machine type. Read
<CODE>gsys.h</CODE> for definitions of returned values.</P>

<H3>get_tv</H3>

<P><CODE>char get_tv (void)</CODE></P>
<P>This function returns PAL/NTSC flag combined (by logical OR) with 40/80 columns flag. This is
not the best way to check if screen has 40 or 80 columns since PAL/NTSC check is always
performed and it can take as long as full raster frame. If you just want to know if
screen has 40 or 80 columns use expression <CODE>graphMode &amp; 0x80</CODE> which returns <CODE>0</CODE> for
40 columns and <CODE>0x80</CODE> for 80 columns. Remember that this parameter can be changed during
runtime. It is unclear if this will work for GEOS 64 so you probably do not want to test
anything if not running under GEOS128. Use <CODE>get_ostype</CODE> to check it. Read <CODE>gsys.h</CODE> for
definitions of returned values.</P>

<HR>
<A HREF="geos-4.html">Next</A>
<A HREF="geos-2.html">Previous</A>
<A HREF="geos.html#toc3">Contents</A>
</BODY>
</HTML>