››››     XE-Bank User's Manual›     ›     Copyright 1992, by Duane Tribe›     September 28, 1992›     ›     ›     OVERVIEW›     ›     This package provides CC65 programs access to the 64K of extended›     memory in an Atari 130XE or compatibly-expanded Atari computer as a›     single alternate memory space.  Although the access may be slow, the›     routines enable C programs to perform many new and larger tasks.›     ›     The package consists of several .OBJ files that must be linked›     immediately after RUNTIME.OBJ:›     ›         XCORE.OBJ Contains a routine to check for the availability of XE›                   memory, and utility subroutines that are used by all the›                   other routines.  This object file must be used; the rest›                   may be used as needed.›      XDYNAMIC.OBJ Contains routines that allocate blocks of memory for›                   use, or release previously allocated blocks for re-use. ›                   The memory blocks can be allocated and released in any›                   order.›       XACCESS.OBJ Contains routines that reference and optionally assign›                   the primitive C data types integer, character, and›                   float.›       XSTRING.OBJ Contains routines that find the length of a string in XE›                   memory, compare a string in main memory to one in XE›                   memory, and set a value to a range of XE memory.›        XTRANS.OBJ Contains routines that transfer blocks of bytes to and›                   from XE memory.›         XFILE.OBJ Contains routines that read directly from a file to XE›                   memory, or write directly from XE memory to a file.›     ›     The dynamic memory routines will never use 0x0000 as a valid address›     for any memory block, so the standard C use of NULL pointers still›     applies.  If only a fixed amount of XE memory is needed, the user can›     skip the dynamic memory routines and treat the XE memory as a giant›     array of 65536 bytes.  The pointer to the list of free blocks is›     available from C, see the Programmer's Manual for details.›     ›     There is no restriction on where the user's C program and data reside›     in main memory.  Data in XE memory can straddle 16K boundaries without›     problems.›     ›     This package claims all 64K of XE memory for use by C programs.  Users›     with only 64K of XE memory (such as unmodified 130XE computers) must›     give up their internal RAM disks and cannot use SpartaDOS X "USE›     BANKED" configurations.  Extra memory beyond the 64K XE memory (such›     as with a RamboXL upgraded computer) is unaffected and is free for use›     by other programs such as RAM disks or SpartaDOS X.›     ›››››››                                       1›››››››     The routines do not disable interrupts when accessing the XE memory. ›     If there is display list data in the memory from 0x4000 to 0x7FFF, the›     display will flicker when XE memory is accessed.  If the OS calls an›     interrupt routine located in memory from 0x4000 to 0x7FFF, the›     computer will lock up.  These problems can be prevented by being sure›     that any display lists or interrupt routines are located below 0x4000›     (such as page 6) or above 0x7FFF.›     ›     ›     PARAMETERS›     ›     Regular C pointers are used as pointers into the XE memory space. ›     Binary operations between pointers in XE memory are valid, but binary›     operations between a pointer in XE memory and one in main memory are›     meaningless.  All the regular C pointer operations are valid, except *›     -> and [] since CC65 will assume that the pointer is in main memory.›     ›     Many routines use two parameters, p and offset, to access one location›     in XE memory.  This is done to mimic the C operators ->, as in›     p->offset, or [], as in p[offset].  However, offset is always a byte›     offset away from p.›     ›     When simulating a C struct, offset is calculated by adding up the›     bytes used by the preceding fields.  For example, given the binary›     tree node structure›     ›         struct node›         {›           struct node *left;›           struct node *right;›           char word[10]›         };›     ›     to allocate a new node, use›     ›         a = xalloc(14);›     ›     The field right is at offset 2.  To access value of right, use›     ›         b = xint(a, 2);›     ›     When no offset is needed, use zero for the offset parameter.›     ›     Be sure to supply an appropriate number of parameters for each›     routine.  They do not check for an illegal number of parameters.  This›     may be a hard bug to spot because some routines accept two different›     parameter counts; see XACCESS.OBJ below.›     ›     ›››››››››››                                       2›››››››     XCORE.OBJ›     ›     xebank›     ›     int xebank()›     ›     Returns TRUE (1) if running on an Atari 130XE or a compatibly-expanded›     Atari computer, otherwise returns FALSE (0).  Use to prevent system›     lock-up on unexpanded computers.›     ›     ›     XDYNAMIC.OBJ›     ›     xinit›     ›     xinit()›     ›     Initialize the XE memory space for allocation.  At first, the memory›     is one 65534 byte free block.  May be used to deallocate all the›     memory at once.›     ›     xalloc›     ›     char *xalloc(size)›     int size - Number of bytes to allocate›     ›     Returns pointer to first free block of memory capable of holding size›     bytes.  The memory is not initialized.  If there is not a contiguous›     block of size bytes free in XE memory, returns NULL.›     ›     xfree›     ›     xfree(p)›     char *p - pointer to memory block›     ›     Frees up memory block at p in XE memory for later use by xalloc(). ›     The value of p must have been returned from a previous call to›     xalloc.›     ›     ›     XACCESS.OBJ›     ›     xint›     ›     int xint(p, offset)›     char *p    - pointer to memory block›     int offset - byte offset into block›     ›     Returns integer at p+offset in XE memory.›     ››››››››››                                       3›››››››     int xint(p, offset, value)›     char *p    - pointer to memory block›     int offset - byte offset into block›     int value  - replacement value›     ›     Sets integer at p+offset in XE memory to value and returns the›     previous integer at that location.  The return value may be ignored.›     ›     xchar›     ›     int xchar(p, offset)›     char *p    - pointer to memory block›     int offset - byte offset into block›     ›     Returns character at p+offset in XE memory.›     ›     int xchar(p, offset, value)›     char *p    - pointer to memory block›     int offset - byte offset into block›     int value  - replacement value›     ›     Sets character at p+offset in XE memory to value and returns the›     previous character at that location.  The return value may be›     ignored.›     ›     xfloat›     ›     char *xfloat(f, p, offset)›     char *f    - pointer to float buffer›     char *p    - pointer to memory block›     int offset - byte offset into block›     ›     Copies 6 bytes (a ROM float) from p+offset in XE memory to f in main›     memory.  Returns f.›     ›     char *xfloat(f, p, offset, value)›     char *f     - pointer to float buffer›     char *p     - pointer to memory block›     int offset  - byte offset into block›     char *value - replacement value›     ›     If f is not NULL, copies 6 bytes (a ROM float) from p+offset in XE›     memory to f in main memory.  Copies 6 bytes from value in main memory›     to p+offset in XE memory.  Returns f.›     ›     ››››››››››››››                                       4›››››››     XSTRING.OBJ›     ›     xmemset›     ›     xmemset(p, offset, byte, length)›     char *p    - pointer to memory block›     int offset - byte offset into block›     int byte   - byte to write to XE bank›     int length - number of bytes to swap›     ›     Sets length bytes of XE memory starting at p+offset to byte.›     ›     xstrlen›     ›     xstrlen(p, offset)›     char *p    - pointer to memory block›     int offset - byte offset into block›     ›     Returns the length of the C string beginning at p+offset in XE memory.›     If no zero byte is found in XE memory, this routine locks up.›     ›     xstrcmp›     ›     int xstrcmp(p, offset, string)›     char *p      - pointer to memory block›     int offset   - byte offset into block›     char *string - string in main memory›     ›     Compares string in main memory to a C string in XE memory at p+offset.›     Returns comparison code as with strcmp.›     ›     ›     XTRANS.OBJ›     ›     x2main›     ›     x2main(addr, p, offset, length)›     char *addr - main memory buffer›     char *p    - pointer to memory block›     int offset - byte offset into block›     int length - byte transfer length›     ›     Copies length bytes from p+offset in XE memory to addr in main›     memory.›     ›     main2x›     ›     main2x(addr, p, offset, length)›     char *addr - main memory buffer›     char *p    - pointer to memory block›     int offset - byte offset into block›     int length - byte transfer length›     ›››››››                                       5›››››››     Copies length bytes from addr in main memory to p+offset in XE›     memory.›     ›     ›     XFILE.OBJ›     ›     xread›     ›     int xread(p, offset, length, stream)›     char *p      - pointer to memory block›     int offset   - byte offset into block›     int length   - number of bytes to read›     FILE *stream - source of bytes›     ›     Reads length bytes from stream directly to p+offset in XE memory. ›     Returns number of bytes actually read in.›     ›     xwrite›     ›     int xwrite(p, offset, length, stream)›     char *p      - pointer to memory block›     int offset   - byte offset into block›     int length   - number of bytes to write›     FILE *stream - destination of bytes›     ›     Writes length bytes directly from p+offset in XE memory to stream. ›     Returns number of bytes actually wrote out.›                                                                           ››››››››››››››››››››››››››››››››                                       6›››