›››› phGXE-Bank User's ManualHhp› › 4Copyright 1992 by Duane Tribe› September 28, 19925› › › 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 per form 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 4byte5› 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› › GxebankH› › 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› › GxinitH› › 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.› › GxallocH› › 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.› › GxfreeH› › 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- 4must5 have been returned from a previous call to› xalloc.› › › XACCESS.OBJ› › GxintH› › 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.› › GxcharH› › 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.› › GxfloatH› › 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› › GxmemsetH› › 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-.› › GxstrlenH› › 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.› › GxstrcmpH› › 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› › Gx2mainH› › 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.› › Gmain2xH› › 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› › GxreadH› › 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.› › GxwriteH› › 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›››