From ST2975@SIUCVMB.SIU.EDU Fri Mar 26 09:41:28 1993 Received: from calvin.sfasu.edu by umaxc.weeg.uiowa.edu (5.61.jnf/920629) on Fri, 26 Mar 93 09:41:24 -0600 id AA24787 with SMTP Received: from SIUCVMB.SIU.EDU by calvin.sfasu.EDU with SMTP (5.59/25-eef) id AA02397; Fri, 26 Mar 93 09:21:38 CST Return-Path: Message-Id: <9303261521.AA02397@calvin.sfasu.EDU> Received: from SIUCVMB.SIU.EDU by SIUCVMB.SIU.EDU (IBM VM SMTP V2R1) with BSMTP id 0288; Fri, 26 Mar 93 09:23:29 CST Date: Fri, 26 Mar 93 09:22:39 CST From: ST2975@SIUCVMB.SIU.EDU To: hyperc-l@calvin.sfasu.edu Subject: opsys globals Status: R Operating System Globals --------- ------ ------- Page 2 (really page 3) of the 6502 memory map contains a set of system wide global variables at its low end. These may be of use to your program. The diagram below shows a map of these variables and their names. The globals are accessed by C through the standard library. There is a code- less library module in the standard library named sysvars.o which contains these variables in its symbol table. When you refer to one of the system globals, the linker automatically includes this file with your program allowing access to them. You will also need to include the header file sysvars.h when you compile your program in order to properly declare the globals for use. The names shown in the following descriptions and in the map diagram are the C names. (Assembly programmers must prepend the names with an additional underscore character.) The names have been prefixed with an underscore to minimize the chance of name collisions with your program's variables. addr ---- ______ 0x200 | | _curDrive ------- 0x201 | | _prtpos --------------- 0x202 | | _exitVal --------------- 0x204 | | _pname --------------- 0x206 | | _errHdlr --------------- 0x208 | | _irq --------------- 0x20a | | _heapBase --------------- 0x20c | | _heapTop --------------- 0x20e | | _prtHook --------------- 0x210 | | _sysfcb --------------- | | | | | | --------------- 0x230 | | _putprt | | | | | | | | --------------- ------------------------- | The System Globals | ------------------------- _curDrive is a byte containing the current disk drive number (1 or 2). When you open files without a specific drive specifier (a: or b:) the system looks to the drive contained in this variable for the file. _prtpos is a byte which contains the printer column at which the next printed character will appear. It is placed here so that your programs can determine the placement of headings etc., in reports. It is otherwise not used by the operating system. It is maintained by the opsys printer driver when characters are sent to the printer. _exitVal contains the word of exit information from the last program to execute Your programs may wish to examine this in order to cooperate with each other. _pname is a string pointer which points to the name of your currently execut- ing program as obtained from the last command line. This is the same as command line argument[0]. _errHdlr is a pointer to a routine to execute in the event of a system error-- disk errors, open errors, file access errors, out of memory errors, etc. When your program starts up it contains the address of the opsys default handler, which simply prints an error message on the screen and then aborts your program. If you want to handle errors you should include the header file errors.h in your program so that you will know what the error codes are, and then place the address of your error handler routine in this vector. Your routine will be called with two parameters -- an error code, and possibly a string of additional information (such as the name of a file for an open error, etc.) of this vector so that you can call it for those error conditions you are unwilling to handle. If you place a zero in this vector then all system errors will be ignored. The individual I/O routines will indicate error conditions on return, which you should check. See the descriptions of the I/O functions themselves. _irq is the secondary IRQ interrupt vector which should point to an IRQ interrupt handler if you have any. The system does not use interrupts, and the default IRQ handler is garbage. Remember that interrupt handlers need to clear the cause of the interrupt before re-enabling interrupts! We don't know what the cause of an interrupt would be so providing a dummy routine would be useless. The operating system performs a 6502 sei instruction at cold start and so normal IRQ interrupts will be disabled unless you enable them yourself. In operation after cold start the operating system is entirely neutral with respect to interrupts. If it sees an IRQ it will vector through this location with an indirect jump, with all registers intact as they were at the time of the interrupt. _heapBase is a pointer to the base of the heap used by your program. When your program is loaded, the operating system sets this value to the address of the end of your text+date+bss sections and intializes the memory manager for you. You should not alter this address. It is here for your information. _heapTop is a pointer to the current top of the heap. When your program is first started up, _heapBase and _heapTop both point at the base of the heap. The heap is zero bytes long at this point. As calls to the memrooy manager are made, the _heapTop pointer is advanced higher in memroy by the sbreak function as long as at least 1K bytes exist between the new location and the top of the C stack. Allocation requests can only cause this value to grow. Freeing allocated memory never cuts it bacck. This is a high-water mark for heap size. _prtHook is a vector which points to the current non-file output driver routine used by the operating system whenever non-file output is attempted. When only video output is enabled, it points to a routine that drives the screen. When only printing is enabled, it points to a printer driver. When both are enabled it points to a routine which calls the video driver first, and then calls the printer driver. By changing this vector you can cause non-file output to perform any action you desire. The driver is called with the character to print in the a register of the 6502. The driver should return with an rts. If the driver switches memory banks it should restore the state of the memory before returning. _sysfcb contains the file control block used by the operating system in loading your program. It is located here as a global primarily for use by the overlay loader routines. When your program begins executing, this file is still open, but does not subtract from the number of file descriptors available to your program. _putprt contains a RAM patch routine to drive the printer. It is located here because the operating system is located in the extended memory of the Apple. If the printer card is one which might switch off the extended RAM, or needs to refer to the Apple II Monitor in ROM, then there would be trouble if this code were to reside in the extended memory banks. By default the printer driver patch is a routine which disables the extended memory, switches the Apple II ROMs back in, and calls the routine pointed to by Apple's own CSW soft switch at location 0x36 in page zero RAM. On return from that routine, it switches the extended memory back in and returns to the oper- ating system. The net result is that you should alter the CSW vector if you want to change the behavior of printer output calls. The routine pointed to by the CSW vector can assume a stock 48k Apple II BASIC configuration when it receives control, with the character to print in the 6502 accumulator. All 6502 registers are free for use. (Apple DOS is not present though.) The sysvars.h heaader file also contains a few other variable declarations which are not located in the globals page. These are: _iocb the location of the RWTS I/O control block used to communicate with the RWTS routine in high memory. This control block is located in page zero at address 0xf6 just above the C-Engine registers. _ioresult is a byte variable which contains the I/O result code of the last operating system call. It is located inside of _iocb at address _0xf7. Most operating system routines and RWTS provide an _ioresult value as part of their operation. This code will match the error code passed on to the error handler if it is called. _xcurs _ycurs are the locations of bytes which represent the current column and row of the cursor on the video display. They are assumed by the operating system to occupy single bytes at slot c3 RAM locations 0x57b and 0x5fb respectively. These locations correspond to the values placed there by Apple's own 80 column video control card. If your video controller does not place the cursor location at these memory addresses you will have to provide your own setcurs and getcurs routines. _rwts is the address of the RWTS disk control program at location 0xf900