Page 1 V O L U M E THREE ------------------------------------------------ Sheldon Leemon Your passport to TOS, the input/output and fast graphics operating systems underlying GEM. Includes fully commented C and machine language programming examples. For the intermediate-to- advanced-level Atari ST programmer. COMPUTE! Books...
Page 3 COMPUTED Technical Reference Guide ATART ST VOLUME THREE Sheldon Leemon COMPUTE! Books Greensboro, North Carolina Radnor, Pennsylvania...
Page 4 27403, (919) 275-9809, is a Capital Cities/ABC, Inc. company and is not as sociated with any manufacturer of personal computers. Atari, ST, ST BASIC, 520ST, 1040ST, and TOS are trademarks or registered trademarks of Atari Corporation. GEM is a trademark of Digital Research, Inc.
Page 5: Table Of Contents
Contents Foreword ..................Chapters 1. The ST Operating System: An Overview......1 2. BIOS ..................9 3. XBIOS Device and System Functions......27 4. XBIOS Graphics and Sound Functions......61 5. GEMDOS Device I/O and Process Control ....85 6. GEMDOS File System Functions ........109 7.
Page 7: Foreword
Technical Reference Guide, Atari T E ! ’ ST—Volume Three: TOS is the third information-packed ST book from noted Atari ST author Sheldon Leemon. Inside you'll find complete information on the Basic Input/Output System (BIOS), the GEM Disk Operating System (GEMDOS),...
Page 8 just as GEM does, but with true 68000 speed and with no intermediary levels of operating systems. If you're a serious ST programmer, you probably already own highlighted, dogeared copies of the first two books in this series. This book will complete your collection and lead you into hitherto unsuspected levels of programming.
Page 9: Chapters
Chapter 1 The ST Operating System: An Overview...
Page 11 The Operating System, but is now more commonly thought of as an acronym for Tramiel Operating System, named after the Tramiel family that now owns Atari. The TOS ROMs contain all of the ST's system software. This...
Page 12 CHAPTER 1 gram, (which provides the desktop metaphor for working with the disk filing system). The VDI and GEM AES were subjects of earlier books in this series by the same author. These books are also available from COM PUTE! Books. BIOS The Basic Input/Output System (BIOS) is a collection of low-level I/O routines...
Page 13 The ST Operating System: An Overview communicating with the character de vices like the screen, keyboard, printer, and serial port. Line A routines Line A routines are the low-level graphics routines the GEM VDI calls for basic graphics functions. These functions include setting and reading individual pixels, drawing lines and filled polygons, and moving software...
Page 14 CHAPTER 1 computer is first turned on, or the re set button is pushed. It checks for ROM cartridges, configures the I/O ports and the screen, tests memory size, sets the exception handler vec tors, executes the programs in the AUTO folder, and jumps to the GEM Desktop program.
Page 15 The ST Operating System: An Overview Mshrink(). For now, it is sufficient to know that this step is necessary for programs using GEM or memory-management calls, and not for programs that only use TOS function calls. Calling the TOS Routines from C It's much simpler to call the TOS routines from C than from machine language, since most C compilers for the ST include library routines for the BIOS, XBIOS, and GEMDOS calls.
Page 16 The C programs in this book are designed to work specif ically with the Alcyon C compiler, the compiler officially sup ported by Atari, and with Megamax C, which also provides a very complete development environment. For these compi lers, the int data type refers to a 16-bit word of data. Some other compilers, such as the Lattice C compiler, use a 32-bit integer as the default data type.
Page 17: Bios
Chapter 2 BIOS...
Page 19 The lowest-level ST Input/Output routines are in the section of the operation system known as the BIOS (Basic Input/Output System). The BIOS contains three basic types of I/O routines. The first group of I/O routines contains routines for com munication with character-oriented I/O devices like the printer, the screen, the serial port, and MIDI port.
Page 20 CHAPTER 2 To call a BIOS function from machine language, you must push the command parameters onto the stack, followed by the command number, and execute a TRAP #13 state ment. The TRAP #13 instruction puts the program into su pervisor mode and begins executing the instructions found at the address stored in exception vector 45, whose address is 180 ($B4).
Page 21 BIOS This is a more readable than the other version. For this reason, the macros will be used in the discussions of BIOS routines and sample programs. To use BIOS functions in your C programs, you must #include OSBIND.H if you use the macros, and you must link your program with the library that contains the b ios() function.
Page 22 CHAPTER 2 plays them on the monitor. The intelligent keyboard device, on the other hand, permits communication with the ST key board's own 8-bit microprocessor. This keyboard processor controls the keyboard, mouse, joysticks, and time-of-day clock. Since this device is complex and has a large set of commands, it is treated separately in Appendix I.
Page 23 BIOS This shifts the keycode into the high byte of the low word, and discards the high word. Although the scan code tells what key was pressed and if it was pressed in combination with one of the shift keys, it still can't give you complete information about the Shift, Al...
Page 24 CHAPTER 2 There's one problem with relying on Kbshift() to supply the information that Bconin() omits: The console device saves incoming keystrokes in a memory buffer, which means that it's possible that a character received via Bconin() may actually be the result of a keypress that took place some time ago.
Page 25 BIOS int devnum; long status; status = Bconstat(devnum); where devnum is the number of the input device whose sta tus you wish to check. Since only devices 1-3 provide input, status checks should be limited to those devices. The value returned in status is a 0 if there are no characters waiting, and $FFFF ( - 1 ) if there is at least one character ready to be received.
Page 26 CHAPTER 2 Table 2-3. VT-52 Codes to Which Bconout() Responds Code Action Esc A Cursor Up Esc B Cursor Down Esc C Cursor Right Esc D Cursor Left Esc E Clear Screen and Home Cursor Esc H Home Cursor Esc I Cursor Up (scrolls screen down if at top line) Esc J Clear to End of Screen...
Page 27 BIOS ASCII Control Code Action Bell Backspace 10-12 Line feed Carriage Return Though the console device will not print the nonprinting ASCII characters (those whose values are below 32), it will print the ST's extended ASCII set (characters whose value is above 128).
Page 28 CHAPTER 2 Program 2-1. BCHARDEV.C BCHARDEV.C Demonstrates some of the BIOS character device functions /**********************************************/ #include <osbind.h> /* For BIOS macro definitions */ Idefine CON /* alias for Console device number */ main() long ch; int sh, count = 4999; w h i l e ((char)ch != 'q') /* End program when 'q' is struck */ w h i l e (!Bconstat(CON)) /* until then, wait for key */...
Page 29 BIOS so on up to bit 15, which corresponds to drive P (the current version of the ST operating system only recognizes 16 drives). If the bit that corresponds to a drive is set to 1, that drive is connected, otherwise, it is unavailable. The value re turned by Drvmap is the same one stored in the system vari...
Page 30 CHAPTER 2 This information tells you how much storage space is on the disk and how it's allocated. GEMDOS performs a Getbpb() operation when it first accesses a drive, or when it accesses a drive after a media change. For more information. on disk organization and the file system, see Chapter 6.
Page 31 BIOS changed. Its name is Mediach(), and its C macro call uses the following syntax: int drivenum; long status; status = Mediach(drivenum); where once again the drivenum parameter specifies the disk drive to check (0 = drive A:, 1 = drive B:, and so on). The status returned by this call can be one of three values.
Page 32 CHAPTER 2 long m__length; /* size of mem block (bytes) */ struct pd *m__own; /* ptr to MD owner's process- descriptor [NULL] */ The Getmpb() function fills the designated Memory Pa rameter Block with initial system values. At the beginning, the memory allocated list pointer is 0, since no memory blocks have been allocated by programs yet.
Page 33 BIOS gram should always save this vector and restore it before ter minating. For more information on the exception vectors, see the memory map in Appendix K, locations 0-1036 ($0-$40C). The final BIOS system call pertains to the system timer interrupt.
Page 35: Xbios Device And System Functions
Chapter 3 XBIOS Device and System Functions...
Page 37 Functions known as the XBIOS (extended Basic input/Output System) are at the next level up from the BIOS. Where the BIOS contains a small number of very low level I/O routines used mainly by other system routines, the XBIOS contains a larger number of functions that are more specific to the ST environment, and of greater interest to the applications programmer.
Page 38 CHAPTER 3 XBIOS handler, which reads the command number on the top of the stack, and directs program execution to the appro priate function. When the function terminates, the program returns to user mode, and the results, if any, are returned in register dO.
Page 39 XBIOS Device and System Functions Character Device Configuration Functions The XBIOS character functions are more device-specific than those in the BIOS. One group of functions enables you to set the configuration of specific devices. For example, there are two functions that affect the performance of the console de vice.
Page 40 CHAPTER 3 default setting works out to (2 * 30 / 60), or a blink every sec ond. Settings lower than 30 make the cursor blink faster. At a setting of 1, it's just a blur. Higher settings make it blink more slowly.
Page 41 Meaning of Value Print type 0 = Dot-matrix 1 = Daisywheel Color type 0 = Monochrome 1 = Color print 0 = Atari Control code type 1 = Epson Print quality 0 = Draft 1 = Final quality Printer port...
Page 42 CHAPTER 3 The speed parameter controls the communications speed, which is sometimes called the baud rate. The ST XBIOS sup ports 16 standard rates of communication, the most common of which are 300, 1200, 2400, and 9600 bps (bits per second). The rates represented by the various values of speed are: Communication speed Speed Value...
Page 43 XBIOS Device and System Functions Handshake Values Handshake Method No handshaking XON/XOFF RTS/CTS (not implemented in preblitter ROMs) Note that a setting of 3 turns on both XON/XOFF and RTS/CTS, which is meaningless. Also note that in the first (preblitter) TOS ROMs, the RTS/CTS handshake method was not supported.
Page 44 CHAPTER 3 Table 3-2. ucr Bits (continued) Function Clock 0 = Use clock directly for transfer frequency (synchronous transfer) 1 = Divide clock frequency by 16 The other input parameters control the Receive Status Register (rsr), Transmit Status Register (tsr) and Synchronous Character Register (scr).
Page 45 XBIOS Device and System Functions An output buffer record immediately follows the input buffer record for the RS-232 serial device only. Each input device has an input buffer where incoming characters are stored until retrieved by a call to Bconin(). As characters are stored, the ST Operating System increments the index to the buffer head, which is an offset from the be...
Page 46 CHAPTER 3 of data. Therefore, the XBIOS contains functions for sending an entire string of characters to either device. The Midiws() function sends a string of characters out the MIDI port, and Ikbdws() writes a string of characters to the IKBD. These two functions are called like this: int bytes;...
Page 47 XBIOS Device and System Functions Table 3-4. Data Block Pointed to by params Byte Description Offset Label Specifies origin of position topmode 0 = y origin (0 point) at bottom 1 = y origin at top The parameter for the IKBD set mouse buttons buttons command In relative mode,...
Page 48 CHAPTER 3 Table 3-5. Vector Table Structure Pointed to by vecbase (continued) Byte Vector Offset Name Routine Called statvec IKBD status packet handler mousevec IKBD mouse packet handler clockvec IKBD clock packet handler joyvec IKBD joystick packet handler midisys System MIDI ACIA handler ikbdsys System IKBD ACIA handler The MIDI port and Intelligent Keyboard Controller...
Page 49 XBIOS Device and System Functions point that it is entered, the address of the packet buffer will be on the stack, and in register AO. It should not spend more than one millisecond handling the interrupt (most of the time, it will just move the packet information to your own buffer), and should end with an RTS instruction.
Page 50 CHAPTER 3 0000 1111 1001 0111 0110 0111 0010 0011 and grouping the bits as required: 0000111 1100 10111 01100 111001 00011 1987 December 12:49:06 p.m. This gives a year of 7 (1987), a month of 12 (December), a day of 23, an hour of 12 (noon), a minute value of 49, and a seconds value of 3.
Page 51 XBIOS Device and System Functions quite possible that these two clocks will not be set to the same time. The new (blitter) ROMs, however, set the GEM DOS clock from the hardware clock at the termination of every process. Keyboard Vector Tables The console device uses three sets of tables to tell it what ASCII character to return when it receives a certain key code from the IKBD device.
Page 52 CHAPTER 3 function with which you may alter the console keyboard ta bles is called Keytbl(), and takes the following format: char unshift[128], shift[128], capslock[128]; long vectable; vectable = KeytbHunshift, shift, capslock); where unshift, shift, and capslock are pointers to your own 128-byte tables.
Page 53 ST sends commands to the printer that cause it to print a graphic representation of the screen display, providing it's the right type of printer (Atari- or Epson-compatible) and it's properly installed (see Setprt() function, above). This same function can be performed under software control, by the XBIOS routine Scrdmp(), which is called from C by the pro...
Page 54 CHAPTER 3 Chapter 5) and store its address in location $502. Since that location is in protected memory, first switch to Supervisor mode (see the Supexec() function below). If you want to keep the new driver installed after the program ends, use GEMDOS function 49 ($31) to keep the program code resi...
Page 55 Table 3-7. Structure of Table Pointed to by prtable (continued) Byte Element Number Name Description type Printer type 22-23 0 = Atari monochrome dot-matrix 1 = Atari monochrome daisywheel 2 = Atari color dot-matrix = Epson monochrome dot-matrix 24-25 port Printer port 0 = Parallel 1 = RS232 serial...
Page 56 CHAPTER 3 Floppy Disk Functions The XBIOS includes a few functions that deal specifically with floppy disks as opposed to the more general BIOS disk routines. Among other functions, they are used to format and initialize a floppy disk. This operation requires several steps.
Page 57 XBIOS Device and System Functions Atari format calls for nine sectors per track. The Atari drives may reliably read and write ten sectors per track, however, and many users prefer format programs that use this value to expand each floppy disk's storage from 360K (720K double sided) to 400K (800K double sided).
Page 58 CHAPTER 3 int status devnum, secnum, tracknum, sidenum, numsecs; long buf, resvd; status = Flopwr(buf, resvd, devnum, secnum tracknum, sidenum, numsecs); where buf contains the address of a buffer that contains the data for one or more sequential sectors in a track. Resvd is a longword reserved for future use, which is currently ignored, but must be present.
Page 59 XBIOS Device and System Functions Disktype Value Disk Format 40 tracks, single sided (180K) 40 tracks, double sided (360K) 80 tracks, single sided (360K) 80 tracks, double sided (720K) Formats 2 and 3 are normally used for ST 3V2-inch disks. Some 5VWnch drives for the ST are formatted as type 1.
Page 60 CHAPTER 3 The function used to read sectors is called Floprd(), and it's called this way: int status devnum, secnum, tracknum, sidenum, numsecs; long buf, resvd; status = Floprd(buf, resvd, devnum, secnum, tracknum, sidenum, numsecs); All of the parameters have the same meaning as in Flopwr( ), above.
Page 61 XBIOS Device and System Functions printf("Insert disk to format in drive A and press Return\n\n"); Bconin(2); /* wait for a key press */ /* format tracks 0-79 on both sides */ for(track=0;track<80;track++) /* for 80 tracks.. */ for(side=0;side<2;side++) /* on 2 sides */ printf("\33A Track %d, Side %d\n",track,side);...
Page 62 CHAPTER 3 that can help control two of these chips. One of them is the Programmable Sound Generator chip which will be discussed more fully in Chapter 4. In addition to its sound functions, this chip provides two 8-bit I/O ports. These are accessed through register 14 (I/O port A) and register 15 (I/O port B) of the sound chip.
Page 63 XBIOS Device and System Functions int bitnum; Offgibit(bitnum); int bitnum; Ongibit(bitnum); where bitnum is the number of the bit (0-7) to change. Offgi- bit changes the specified bit number to a 0, while Ongibit changes the bit to a one. The 68901 Multi-Function Peripheral (MFP) Chip is an...
Page 64 CHAPTER 3 able any MFP interrupt with one of the following XBIOS calls: int intnum; Jdisint(intnum); int intnum; J enabint(intnum); where intnum is the number of the interrupt (0-15), to enable or disable. Jdisint() is used to disable the interrupt, and Jen- abint() is used to enable it.
Page 65 XBIOS Device and System Functions where timernum is number from 0-3 that represents an MFP timer (0 = A, 1 = B, 2 = C, 3 = D). Control represents the value to place in the timers control register. This is an 8-bit register that controls the timer mode.
Page 66 With the Mega ST series, however, Atari introduced a hardware blitter chip to speed up screen drawing. The line A routines in the Mega machines use the blitter hardware rather than the soft...
Page 67 XBIOS Device and System Functions to that file in order to use the Blitmode() macro for this function. Once defined, Blitmode() is called like this: int status, value; status = Blitmode(value); where value is used to set the blitter configuration. If value is - 1 (OxFFFF), no new value is set, and the current blitter con...
Page 69: Xbios Graphics And Sound Functions
Chapter 4 XBIOS Graphics and Sound Functions...
Page 71 Graphics To understand the XBIOS graphics functions, you must first understand how the ST display is arranged in memory. The ST uses a bitmapped display. The bits in memory control the dots (picture elements or pixels) on the screen. On a bit mapped screen, everything, including text, is drawn using a number of dots.
Page 72 CHAPTER 4 Each bit of screen memory can hold either the number 0 or 1. On a monochrome system, only one bit is needed to represent a screen dot or pixel (picture element), because each dot on the screen is either white (off) or black (on). But with a color ST system, things are somewhat different.
Page 73 XBIOS Graphics and Sound Functions Figure 4-2. Lo-res color screen memory Color Registers B 1 2 3 4 5 6 7 8 9 IB 11 12 13 14 15 n==EE --- 1101 = 7 llllllllllllllllllllllllllllllll lllllllllllllll lllllllllllllllliH ■ Bit 2 Bit B Bit 1 Bit 3...
Page 74 CHAPTER 4 possible colors to choose from. The default values in the color registers at power-up time are: Table 4-1. Default Color Settings Register Green Blue Color White Green Yellow Blue Magenta Cyan Light Gray Dark Gray Light Red Light Green Light Yellow Light Blue Light Magenta...
Page 75 Green Cyan Purple Yellow White Unlike some computers, screen memory for the ST series is not fixed in any one particular place. To find the starting address of screen display memory, you may use the XBIOS function physbase(): long scraddr;...
Page 76 CHAPTER 4 dress. Operating System functions write on the logical screen when they output screen graphics. Normally, you'll want graphics output to go to the same memory area that is being displayed. There are some cases, however, where you'll want to draw a number of graphics objects sequentially and display them all at once so the user can't see you drawing each one in turn.
Page 77 The European (PAL) color monitor re freshes 50 times per second. Contrary to Atari's documentation, the Physbase( ) func tion doesn't wait until the next vblank to return the physical screen location, nor does Setscreen() wait for a vblank to change the physical screen (at least not in the preblitter ROMs).
Page 78 CHAPTER 4 from one physical screen to another, unless you call Vsync() before Setscreen(). Some users report that these glitches may be eliminated by making sure the high-order word of the start address is the same for both screens (both screens are in the same, even 64K block of memory).
Page 79 XBIOS Graphics and Sound Functions fill(ch) char ch; int x; Bconout(CON,27); /* home cursor */ Bconout(C O N ,'E '); Bconout(CON,27); /* turn on 'line wrap' */ Bconout(CON,'v'); /* for console device output */ for (x=0;x<1999;x++) /* fill screen with character x Bconout(CON,ch);...
Page 80 CHAPTER 4 *** Get pointer to 1st (default) screen in a4 move.w ,-(sp) * push XBIOS function # for Physbase() trap * call XBIOS addg.l * clean stack move.l d0,a4 * store pointer to default screen in a4 *** Set logical screen base to 2nd screen, and fill with X's m o v e .w #-l,-(sp) m o v e...
Page 81 XBIOS Graphics and Sound Functions endprog: move.l #0,-(sp) * Push command number for terminate program trap * call GEMDOS. Bye bye! ******** Fill subroutine. Fills screen with a single character fill: *** First, , print Esc-E to clear screen & home cursor m o v e .w #27,d7 * output ESC character...
Page 82 Chapter 5 when the Mshrink() func tion is explained. Sound Functions The ST series of computers use a Yamaha YM-2149, a version of the General Instruments AY-3-8190 Programmable Sound Generator (PSG) chip for music and sound effects. This chip has three sound channels, that can produce continuous tones, various envelope waveforms, or noise.
Page 83 XBIOS Graphics and Sound Functions number. In either case, the function returns the value stored in the register at the end of the call in the variable regvalue. The functions of each of the 16 registers of the PSG chip are shown in Table 4-3.
Page 84 CHAPTER 4 set the volume level, and set the tone period to determine the pitch of the tone. Enable a channel to produce a tone by setting the corresponding tone bit in register 7 to 0. Be very careful when setting this register, however, since the upper two bits are used to determine the direction of data flow for the two onboard I/O ports.
Page 85 XBIOS Graphics and Sound Functions To derive the period values for the next higher octave, divide the period values in this table in half. For the next lower octave, multiply each period value in the table by 2. The final step in sounding a constant tone is to set the volume level in register 8, 9, or 10, depending on which channel you're using.
Page 86 CHAPTER 4 cymbals. Those whose volume is varied according to a small- period waveform hum like a motor. Both noise and tones may be enabled in a single channel, which then produces both types of sound. Figure 4-3. Waveform Shapes and the Sounds They Create H a v e f o r n Con t r o l Bits Reg i s t e r Bit 3...
Page 87 XBIOS Graphics and Sound Functions 301, 415.3 HZ */ /* G# = 440.0 HZ V 284, /* A 466.2 HZ */ 268, /* A# = 493.9 Hz */ 253, 523.2 Hz */ /* c main() int c l i c k o n Q , clickoff(); /* address of "super" functions */ unsigned period, x;...
Page 88 CHAPTER 4 all of the low-memory variables are protected from access by programs running in user mode, switch into supervisor mode to change this system variable. The XBIOS routine Su- pexec() (explained more fully in Chapter 3) is used to exe cute the clickoff() and clickon() routines in supervisor mode.
Page 89 £ T3 0 1 -g u G «J 0 > O J o > ^ 13 5b c p r— t 6 « £ c 5-g n. U £ x> o > ■ > 2 > t o bo M > G O 0 1 a, c a - a...
Page 90 CHAPTER 4 effects like wailing sirens. The structure of these commands is like the FOR command in BASIC, which lets you run a loop a certain number of times by specifying a starting vari able value, an ending value, and the number added to the variable each time through the loop.
Page 91 XBIOS Graphics and Sound Functions 0X0800,0XFF05,0X080F,OxFFll,0x0800,0X001C,0x0101,0XFF03, 0X080F,OxFFll,0X0800,0XFF05,0X080F,OxFFll,0x0800,0X003F, 0x0101,0XFF03,0X080F,0XFF22,0x0800,OxFFOO int scale; /* scaling factor for delay loop.*/ /* Timer interrupt is always l/50th of a second. */ /* Vsync() is l/60th of a second on color monitor,*/ /* l/70th of a second on monochrome */ m a i n Q int x;...
Page 93: Gemdos Device I/O And Process Control
Chapter 5 GEMDOS Device I/O and Process Control...
Page 95 The functions that make up the GEMDOS (GEM Disk Operating System) form the highest level of TOS. These functions are also sometimes referred to as the BDOS (using the old CP/M and MS-DOS operating system terminol ogy). They include a wide variety of character device func tions, several process control and memory management func...
Page 96 CHAPTER 5 mode and begins executing the instructions found at the ad dress stored in exception vector 33, whose address is 132 ($84). This exception vector contains the address of the GEM DOS handler which reads the command number on the top of the stack and directs program execution to the appropriate function.
Page 97 GEMDOS Device I/O and Process Control Since this format is the more readable of the two, it will be used in the macros in the discussion of GEMDOS routines and sample programs. To use GEMDOS functions in your C programs, link your program with the compiler library that contains the gemdos() function, and #include OSBIND.H if you use the macros.
Page 98 CHAPTER 5 Again, both functions wait until a key is pressed and then return the ASCII character and scan code. Atari docu mentation indicates there is slight difference between these functions in that Crawcin() is supposed to pass all control codes, and Cnecin() is supposed to act on control codes like Control-S, Control-Q, and Control-C.
Page 99 GEMDOS Device I/O and Process Control ing characters to the character devices. Each output device has its own output function. The first, Cconout(), is used to send characters to the console screen. Its syntax is char ch; Cconout(ch); where ch is the ASCII character to write to the screen. Machine language programmers should note that they will pass the character to be printed as a word-length value, the low byte of which contains the character to be printed, and the high byte...
Page 100 CHAPTER 5 In addition to the normal character input and output functions, GEMDOS provides an unusual function that al lows you either to send characters to the console device or receive them. The macro name for this function is Crawio(), and it's called like this: int chin, chout;...
Page 101 GEMDOS Device I/O and Process Control char buffer[82]; int length; buffer[0] = 80; length = Cconrs(buffer); buffer[length + 2] = 0; Before calling the function, first set up a buffer, into which the function may read the characters. You must also store the maximum number of characters that may be read in the first byte of the buffer.
Page 102 CHAPTER 5 The Control-C key combination not only causes the Cconrs() function to return, but also terminates the entire program. This feature makes Cconrs() extremely dangerous, and suitable only for quick and dirty programs that you write for your own use. Any program written for use by others should implement its own input routine in a manner that doesn't allow the user to exit the program easily by mistake.
Page 103 GEMDOS Device I/O and Process Control System Functions In addition to character device functions, GEMDOS also con tains a number of system control functions. These include routines to manage system memory, to execute and termi nate programs, and to get and set the DOS clock and calen dar.
Page 104 CHAPTER 5 use of the Super() function may be found in the sample pro gram TOGGLE. S, below. Memory Management Functions The management of free memory is another common system function made easier by the DOS commands. When a GEM or TOS application program is first loaded and run, it takes control of the entire application RAM space.
Page 105 GEMDOS will automatically return them to the free pool when the program terminates. Atari documentation states that if more than 20 blocks of memory are allocated by Malloc() at one time, the memory management system will fail. Since some library functions like fopen() use Malloc() to allocate blocks for their own use, your program should use Malloc() very sparingly.
Page 106 CHAPTER 5 This diagram shows that the memory area not actually used by the program is divided between the stack and the heap. The stack is a temporary storage area used by pro grams for passing parameters, saving register contents, and saving subroutine return addresses.
Page 107 GEMDOS Device I/O and Process Control the beginning of the TPA is a 256-byte segment known as the basepage. As shown in Figure 5-1, the basepage contains information about the size and address of each program seg ment, as well as the command line that is passed to the pro gram (these are the extra characters you type in when you run a TOS Takes Parameters program whose name ends in .TTP).
Page 108: Process Control
CHAPTER 5 add.l bsslen(a5),dO * - i - length of uninitialized storage segment #stk+bp,dO * + (size of base page + stack/heap) add. *** Calculate the address of your stack *** and move it to the stack pointer (a7) new stack address = dO,dl size of program memory m o v e...
Page 109 GEMDOS Device I/O and Process Control Table 5-1. Four Modes for Pexec() Function (continued) Mode Function File Command Number Pointer to Pointer to Just load, Pointer to command string environment do not filename string string execute Just Unused Basepage unused execute address Unused...
Page 110 CHAPTER 5 cess receives as its environment string a copy of the environ ment string used by the program that called it. When mode 0 of Pexec() is used, the call loads the new program, sets up its basepage, passes the arguments and en vironment to it, and executes it.
Page 111 GEMDOS Device I/O and Process Control m a i n Q int status; int len, done= int index^l; Get command line Cconws("Enter command line [include filename extension]\n\r"); buffer[0]=80; prepare buffer for command string entry buf f e r [82]=0; Cconws("> "); /* prompt */ len = Cconrs(buffer);...
Page 112 CHAPTER 5 0. To pass a return code other than 0 to the calling process, you must use the function Pterm (): int retcode; Pterm(retcode); where retcode is a binary number you wish to pass to the call ing program. This code may be used to inform the calling program of the results of the child process.
Page 113 GEMDOS Device I/O and Process Control *** Program equates conterm * * $484 scr_dump = $502 *** Program starts here .text *** Branch to install code at end of program start: bra.w init *** The ID here lets us check to see if the resident program was *** already installed once, so you don't try to do it again if the *** program is run more than once.
Page 114 CHAPTER 5 msg2 m o v e .w #$9,-(a7) trap call GEMDOs addq.l #6, a7 clean stack bsr.w delay clr.w -(a7) end program trap Install: move.1 #toggle,scr_dump * install coggle in screendump vector move.1 oldstack,-(a7) * push old stack move.w #$20,-(a7) * out of super mode trap...
Page 115 GEMDOS Device I/O and Process Control and date, while the XBIOS functions get or set both at once. The DOS dock and IKBD clock are not necessarily the same, although in later versions of TOS (with ROMs that support the blitter chip), the DOS clock is reset from IKBD clock at the termination of each process.
Page 116 CHAPTER 5 GEMDOS also provides a function that returns the GEM DOS version number. This number refers only to the version of GEMDOS, not to the GEM or TOS version in general. The function used to find the GEMDOS version number is Sver- sion(), and it's called like this: int version;...
Page 117: Gemdos File System Functions
Chapter 6 GEMDOS File System Functions...
Page 119 In addition to the character device and system functions, many of which are similar to calls found in the BIOS and XBIOS, GEMDOS provides a number of unique functions involved with the disk filing system. Disk drives are unique among the I/O devices because they are random- access devices.
Page 120 CHAPTER 6 computer the letter you wrote with your word processing program is stored at locations 40,658 to 41,949? To avoid this problem, GEMDOS goes farther than merely dividing the disk into tracks and sectors. It also divides it into logical units known as files and directories.
Page 121 GEMDOS File System Functions Table 6-1. Organization of the Boot Sector Byte Number Description If disk is bootable, a BRA.S instruction to boot code starting at byte 31 is stored here. If disk is not bootable, two 0 bytes are stored here. Reserved for OEM use (unused on ST) 8-10 Volume serial number 24 bits long (used to determine is...
Page 122 CHAPTER 6 Table 6-2. Format for Directory Entry Bytes Contents Eight-character primary name (ASCII text) (if file is deleted, first character is $E5) 8-10 Three-character extension (ASCII text) Attribute byte, contains following bit flags Bit 0 = read-only file (can't be deleted or written to) Bit 1 = hidden file (excluded from normal directory searches) Bit 2 = system file (excluded from normal directory...
Page 123 GEMDOS File System Functions tains a pointer to the first file cluster. When you look up the FAT entry for that first cluster, you get a pointer to the next cluster. The FAT entry for that cluster contains a pointer to the next one, and so on until you get to a FAT entry that ■...
Page 124 CHAPTER 6 tended), GEMDOS searches the FAT for free clusters and as signs as many of them to the file as necessary. The physical location of the various disk data structures may be determined by values found in the BIOS Parameter Block.
Page 125 GEMDOS File System Functions (sometimes an error and list device as well). When a pro gram spawns a child process with Pexec(), that child inherits the parent's standard files. The third type of file handle is as signed to user files on a temporary basis. When a file is cre ated or opened, a small positive number greater than five is assigned to it as temporary ID number for the file.
Page 126 CHAPTER 6 Table 6-4. Meaning of Flag Bits Used in File Creation (continued) Number Value Description System file (excluded from normal directory searches) Volume label (can only exist in root) If the file didn't exist previously, Fcreate() both creates a directory entry for the new file and opens it for writing only.
Page 127 GEMDOS File System Functions where fname is a pointer to the null-terminated ASCII filen ame of the file to open, and mode is a flag that specifies which operations will be available once the file has been opened. Possible values for mode include: Mode Number Operations...
Page 128 CHAPTER 6 pointer wherever you want in the file by using the Fseek() function. Fseek() is called like this: long position, offset; int handle, seekmode; position = Fseek(offset, handle, seekmode); Fseek() moves the file pointer for the file referred to by han dle by offset number of bytes, in a manner designated by seek...
Page 129 GEMDOS File System Functions #include <osbind.h> /* For GEHDOS macro definitions */ #define F_ATTR /* file attribute for FCreate() #define APPEND #define READ Idefine WRITE char fname[ ] = "A:\TEST.FIL"; char test[]= "This is a test file"; char add[)= "nice"; main() int handle;...
Page 130 CHAPTER 6 functions facilitate navigation through a system where there may be several drives attached, each having several subdirec tories. A common example is the function used to set the de fault drive. This is the drive that GEMDOS assumes is re ferred to when only a filename is used.
Page 131 GEMDOS File System Functions keeps a default directory path for each drive in the system. The Dsetpath() function is the one used to set a default di rectory for the current drive: int status; char ’''path; status = Dsetpath(path) where path is a pointer to a null-terminated ASCII string specifying the default directory path to set for the current de...
Page 132 CHAPTER 6 The Ddelete() function is used to remove a subdirectory: int status; char ^pathname; status = Ddelete(pathname); where pathname points to a null-terminated ASCII string which contains the path name of the directory to delete. If GEMDOS is able to delete the directory, a 0 is returned in status, otherwise, a negative GEMDOS error number is re...
Page 133 GEMDOS File System Functions Fsetdta (olddta); /* then restore DTA */ /* if you're running this f r o m the Desktop, you nay want to add a pause to give the user a chance to read the output */ Cconws("\n\n\rPress any key to end");...
Page 134 CHAPTER 6 ting up one big buffer to get all of the names at once. There fore, GEMDOS uses a system by which you set up a buffer large enough to hold only the information for a single file, and then proceed to read the directory information a file at a time.
Page 135 GEMDOS File System Functions Table 6-5. Attribute Bits Number Attribute Read-only file (can't be deleted or written to) Hidden file (excluded from normal directory searches) System file (excluded from normal directory searches) Volume label (can only exist in root) Subdirectory Archive bit If the attributes argument is 0, the Fsfirst() function only searches for normal files (no subdirectories, hidden files, or...
Page 136 CHAPTER 6 set in Fsfirst() is found, you can obtain information about additional files with the function Fsnext(): int status; status = Fsnext(); where status indicates whether another file having the file specification and attributes given in the Fsfirst() call was found.
Page 137 GEMDOS File System Functions int status; char ’'‘filename; status = Fdelete(filename); where filename is a pointer to a null-terminated ASCII string that contains the name of the file to be deleted. If the file is successfully deleted, a 0 is returned in status. If the operation fails, a negative error number is returned instead.
Page 138 CHAPTER 6 Fdatime() gets or sets the timestamp for the file referred to by handle, according to the setting of mode. If mode is set to 1, the file's time stamp is set according to the value stored in the buffer pointed to by timeptr. If mode is set to 0, the file's time stamp is read into that buffer.
Page 139 GEMDOS File System Functions for that device. Then, after you finish the redirection, you can change the handle back, using the temporary copy. The second reason for duplicating a handle is that it gives you a temporary copy that can be used to substitute for another standard device.
Page 141: Line A Routines
Chapter 7 Line A Routines...
Page 143 High level support for graphics operations on the ST is provided by the GEM VDI, as described in COMPUTEl's Technical Reference Guide, Atari ST Volume One: The VDI. TOS, however, includes a set of graphics primitives known as the line A routines. These are the low-level graphics routines called by the VDI.
Page 144 CHAPTER 7 future models of the ST, even if the graphics hardware changes significantly. A good example of this is that software using line A routines automatically benefits from the blitter hardware in the Mega ST line, since the blitter ROMs use that hardware to implement the line A routines.
Page 145 A routines as well. The reader who wishes to learn more about the line A functions should look to the COMPUTEf's Technical Reference Guide, Atari ST Volume One: The VDI, which covers the VDI graphics functions in de...
Page 146 Complete information about the font headers may be found in Appendix C of COMPUTEI's Technical Reference Guide, Atari ST Volume One: The VDL The last item returned by the Init call is a function table which is placed in register A2. This table contains 16 entries, each of which is the longword address of one of the line A routines.
Page 147 Line A Routines mally spent handling the line A exception. To call these sub routines directly, however, you must first be in supervisor mode. Drawing Routines The simplest of the line A functions are those used to draw single points or straight lines on the screen. Function $A001, Put Pixel, is used to color a single point.
Page 148 CHAPTER 7 nextx: addq.w #2,point * skip even columns move.w #49,d4 * draw 50 dots vertically move.w d4,point+2 * starting at y of 51 nexty: addq.w #2,point+2 * skip even rows dc.w PutPixel * draw a point dbra d4,nexty * if the column's not done, do next dbra d3,nextx * if the row's not done, do next...
Page 149 Line A Routines = $28 * starting y coordinate = $2A * ending x coordinate = $2C * ending y coordinate The last four variables hold the coordinates for the start ing point and ending point on the line. The first four are used to store the color register value.
Page 150 CHAPTER 7 since it changes whatever color is there. Secondly, the XOR operation cancels itself the second time it's used. When a color is complemented, it changes to its opposite color, but when it's complemented again, it changes back to the origi nal.
Page 151 Line A Routines * or color 1 m o v e .w #0,COLBIT3(a0) 80,LSTLIN(aO) * draw last point on line move.w move.w 8$EEEE,LNMASK(aO) * dashed line #0,WMODE(aO) * replace mode jnove.w move.w #5,d3 * draw 6 lines fpoints,a3 * get address of array mo v e .
Page 152 CHAPTER 7 The first of the routines that use a fill pattern is the Hor izontal Line function ($A004). This function is similar to Arbi trary Line, except it is only used when Y1 and Y2 are the same. It is a bit faster in execution than Arbitrary Line. The input variables required for this function are shown in Table 7-1.
Page 153 Line A Routines Table 7-2. Input Values for Filled Rectangle Function (continued) Description Offset Name Offset Writing mode WMODE Starting x coordinate Starting y coordinate Ending x coordinate Ending y coordinate PATPTR Pointer to fill pattern array Pattern index (length - 1) PATMSK MFILL Multi-color fill pattern flag (zero = single...
Page 154 CHAPTER 7 Table 7*3. Input Values Used by Filled Polygon (continued) Offset Name Offset Description COLBIT3 Bit value for color plane 3 WMODE Writing mode y coordinate of horizontal line segment(s) to draw PATPTR Pointer to fill pattern array PATMSK Pattern index (length-1) MFILL Multicolor fill pattern flag (zero = single...
Page 155 Line A Routines Table 7-4. Line A Variables Used by Seed Fill Description Offset Name Offset CUR__WORK -$64 Pointer to the current virtual workstation variable table. The VDI fill color index is the 16th member of this word array. Pointer to a word array that contains the INTIN x and y coordinates of the initial fill point, in that order...
Page 156 CHAPTER 7 same as the hardware color registers numbers. The corre spondence between the two is shown in Table 7-5. Table 7-5. Correspondence Between Hardware Color Registers and VDI Color Indices Color Color Index Register Default Color White Black Green Blue Cyan Yellow...
Page 157 Line A Routines turns a zero in register DO, Seed Fill keeps going, but if it returns a nonzero value, Seed Fill aborts. Since Seed Fill will JSR through the SEED ABORT vector at the end of each scan line, you must place a pointer to subroutine in this vector, or Seed Fill will bomb after the first line.
Page 158 CHAPTER 7 move.w #$d0,XMAXCL(a5) to (0,0)-($d0.$b0) move.w # 0,YMINCL (a5) move.w #$bO,YMAXCL(a5) *** draw filled box with Horizontal line function m o v e .1 #$00800030,Xl(a5) * xl=$80, yl=$30 move.w #$0120,X2(a5) * x2=$120 move.w #31,d4 * draw 32 horiz. lines nextline: dc.w Hline...
Page 159 Line A Routines move.l #0,-(sp) * GEMDOS terminate command trap * call GEMDOS and exit *** SEEDABORT must point to this subroutine BEFORE *** you can use the SeedFill function NoAbort: move.l #0,d0 * return FALSE * and let SeedFill do the next line *** Data for input is stored here ■...
Page 160 CHAPTER 7 block and put the address of this block in the A6 register be fore making the call. The format of the BitBlt parameter block is shown in Table 7-6. Table 7-6. The Format of the BitBlt Parameter Block Name Offset Description...
Page 161 Line A Routines BitBlt takes a bit image from one memory area and com bines it with a bit image in another memory area, according to the logic operation selected. The source and destination image rectangles are the same size. The width of this block (in pixels) is stored in B__WD, and its height is stored in B__ HT, while the number of bit planes is passed in PLANE__CT (this value may be changed by the BitBlt call).
Page 162 CHAPTER 7 Table 7-7. The 16 Possible Logic Operations for Combining Source and Definition Blocks (continued) Opcode Logic Operation* Description D1 = S Replace mode D1 = (NOT S) AND D Erase mode D1 = D Destination unchanged D1 = S XOR D XOR mode D1 = S OR D Transparent mode...
Page 163 Line A Routines for the foreground color with a transparent background color (transparent mode), set OP__TAB to $7744. Note that FG__ COL and BG__COL may be changed by the BitBlt call. The BitBlt function also allows the use of fill patterns, which are ANDed with the source prior to the logic opera...
Page 164 CHAPTER 7 * * * adjust blit param< init line A dc.w Init et number of bit planes mo v e .w (aO),d0 s it monochrome? cmp. w #l,d no, leave screen width alone skip m o v e .w #$50,nxln yes, change screen width value skip:...
Page 165 Line A Routines The Copy Raster function ($A00E) does much the same thing as BitBlt, but in a format compatible with the Copy Raster Opaque and Copy Raster Transparent functions of the VDI. Copy Opaque is used where the source and destination have the same number of bit planes, while Copy Transparent is used to combine a single-plane source with a multiplane destination.
Page 166 INTIN array, and the background color from the third word in that array. For more information on the VDI bit-blit routines, see Chapter 6 of COMPUTEl's Technical Reference Guide, Atari ST Volume One: The VDI. Mouse and Sprite Operations The line A sprite and mouse pointer routines are specialized cases of the bit blit functions.
Page 167 Line A Routines second sprites save block. It's also a good idea to use the XBIOS Vsync() function before drawing sprites to avoid drawing them in the middle of a screen refresh. The Draw Sprite function ($A00D) is used to draw a soft ware sprite on the screen.
Page 168 CHAPTER 7 used to remove the sprite and restore the background. The only parameter it requires is a pointer to the save block, which is passed in register A2. The mouse pointer is a special type of sprite that the op erating system automatically moves in response to movement of the mouse.
Page 169 Line A Routines nal value afterwards). The current x and y positions of the mouse pointer are stored in GCURX (offset — 602) and GCURY (offset —600). The mouse button status is contained in MOUSE__BT (-5 9 6 ). Bit 0 covers the left button status, while bit one covers the right button.
Page 170 CHAPTER 7 *** Change mouse pointer to cross shape move.l #mdata,INTIN(a5) * address of mouse data block to INTIN dc.w MHide * hide the pointer dc.w MTrans * change its shape move.l #mdata+ ,INTIN(a 5) * make mouse show unconditional d c .w MShow * and show the mouse pointer...
Page 171 Line A Routines *** And wait for mouse button release wait: move.w M0USE_BT(a5),d3 btst #l,d3 wait *** end program move.l #0,-(sp) * GEMDOS terminate command trap * call GEMDOS and exit *** Data for input is stored here .data *** mouse pointer data 0 , 2 dc.
Page 172 CHAPTER 7 Table 7-11. The Primary Line A Variables That Influence Text Printing Variable Offset Description Name WMODE Writing mode (0-3 = VDI modes, 4-19 = BitBlt modes) CLIP Clipping flag (0 = off, 1 = on) XMINCL Left edge of clip rectangle XMAXCL Right edge of clip rectangle YMINCL...
Page 173 Line A Routines Table 7-11. The Primary Line A Variables That Influence Text Printing (continued) Variable Description Offset Name Mask used to italicize (usually $5555) SKEWMASK $5E Width by which to thicken text for boldface WEIGHT ROFF Offset above baseline for italicizing Offset below baseline for italicizing LOFF SCALE...
Page 174 Table 7-12 below. For complete infor mation on VDI fonts and font headers, see Appendix C of COMPUTEI's Technical Reference Guide, Atari ST Volume One: The VDI. Table 7-12. Information Found in the Font Header...
Page 175 Line A Routines the character to print, subtracting the ASCII value of the first printable character in the font (which is also found in the header), and multiplying by 2, you come up with the begin ning x offset for the character. SOURCEY is usually set to 0, indicating that you wish to print the character from the top line.
Page 176 CHAPTER 7 WEIGHT from the font header variable thick__width. For lightening, set LITEMASK to the value found in the font header at lite__mask. Text can also be rotated in increments of 90 degrees. If CHUP is set to 0, the text will be printed normally, but if set to a multiple of 900, the text will be ro...
Page 177 Line A Routines £ 3 $5E Mask used to italicize (usually $5555) SKEWMASK s $60 Width by which to thicken text for boldface WEIGHT = $62 Offset above baseline for italicizing ROFF = $64 Offset below baseline for italicizing LOFF Scaling flag (0=no scaling) SCALE Character rotation (0=no rotation)
Page 178 CHAPTER 7 move.w dO,DELX(a5) * = width of this character clr.w SOURCEY(a5) * start at top line of character dc.w Textblt * print the character blit_one * then do the next one *** wait for key press, then end exit: move.w #l,-(sp) * call conin() to wait for key press...
Page 179: Bios Functions
Appendix A BIOS Functions...
Page 181 The ST BIOS routines can be called from user mode, and are reentrant to three levels. They use registers A0-A2 and D0-D2 as scratch registers, which means that if you're programming in assembly language, and you're using these registers to store important information, you must save their contents before making a BIOS call, and restore them after the BIOS call.
Page 182 APPENDIX A move.w # 'X ', — (sp) * push character value on stack move.w # 2 , — (sp) * push console device number on stack move.w # 3 , — (sp) * push BIOS command number on stack trap # 1 3 * call BIOS handler...
Page 183 Getmpb Get Memory Parameter Block Getmpb() Opcode = 0 T h is c a ll is u s e d b y G E M D O S t o in itia liz e t h e m e m o r y m a n a g e m e n t s y s t e m .
Page 184 Bconstat Get Input Device Status Bconstat() Opcode = 1 T h is f u n c t i o n a l l o w s y o u t o d e t e r m i n e w h e t h e r t h e r e is a c h a r a c t e r w a i t i n g to b e r e c e i v e d f r o m a p a r t i c u l a r i n p u t d e v i c e .
Page 185 Bconin Read a Character Opcode = 2 Bconin() B c o n i n ( ) w a i t s f o r a s i n g l e c h a r a c t e r to b e c o m e a v a i la b l e f r o m o n e o f t h e i n p u t d e v i c e s , a n d t h e n r e a d s t h a t c h a r a c t e r .
Page 186 Bconout Write a Character Bconout() Opcode = 3 T h is f u n c t i o n s e n d s a s in g le c h a r a c t e r t o o n e o f t h e o u t p u t d e v i c e s . I t d o e s n 't r e t u r n u n til t h e c h a r a c t e r is a c t u a l l y s e n t .
Page 187 Rwabs Read/Write Disk Sectors Rwabs() Opcode = 4 T h is f u n c t i o n a l l o w s y o u t o r e a d o r w r i t e t o t h e d i s k , a s e c t o r a t a t i m e . C macro format in t m o d e , s e c t o r s , s t a r t , d r i v e n u m ;...
Page 188 Setexec Read/Change Exception Vector Setexec() Opcode = 5 T h is f u n c t i o n a l l o w s y o u t o r e a d o r c h a n g e o n e o f th e 6 8 0 0 0 e x c e p t i o n v e c to r s .
Page 189 Tickcal Get Timer Calibration Tickcal() Opcode = 6 T h is c a ll r e t u r n s t h e n u m b e r o f m i l l i s e c o n d s b e t w e e n t i m e r tic k i n t e r r u p t s . F o r t h e c u r r e n t S T m o d e l s , th i s v a l u e is 2 0 m i l l i s e c o n d s .
Page 190 Getbpb Get BIOS Parameter Block Getbpb() Opcode = 7 T h is f u n c t i o n r e t u r n s a p o i n t e r t o t h e B I O S P a r a m e t e r B lo c k , a d a t a s t r u c t u r e t h a t c o n t a i n s i n f o r m a t i o n a b o u t a d i s k 's s i z e a n d l a y o u t .
Page 191 Bcostat Get Output Device Status Bcostat() Opcode = 8 B c o s t a t ( ) te lls y o u w h e t h e r a p a r t i c u l a r o u t p u t d e v i c e is r e a d y to a c c e p t a c h a r a c t e r .
Page 192 Mediach Get Media Change Status Mediach() Opcode = 9 T h is f u n c t i o n is u s e d b y t h e d i s k o p e r a t i n g s y s t e m t o d e t e r m i n e w h e t h e r a d i s k h a s b e e n c h a n g e d .
Page 193 Drvmap Find Valid Drive Numbers Drvmap() Opcode = 10 D r v m a p ( ) m a y b e u s e d t o d i s c o v e r w h a t d i s k d r i v e s a r e c u r r e n t l y a t t a c h e d .
Page 194 Kbshift Read/Change Keyboard Shift Status Kbshift() Opcode = 11 T h is f u n c t i o n r e t u r n s i n f o r m a t i o n a b o u t t h e s t a t u s o f t h e s p e c ia l s h if t k e y s , i n c l u d i n g C o n t r o l a n d A l t e r n a t e .
Page 195: Xbios Functions
Appendix B XBIOS Functions...
Page 197 Like the BIOS functions, the XBIOS routines can be called from user mode. They use registers A0-A2 and D0-D2 as scratch registers, which means if you're program ming in machine language and your program uses these reg isters, you must save their contents before making an XBIOS call and restore them after the XBIOS call terminates.
Page 198 APPENDIX B move.w # 7 , - (sp) * push XBIOS command number on stack trap # 1 4 * call XBIOS handler addq.l #6,sp * pop parameters (6 bytes) off stack Calling the XBIOS routines from C is much simpler. Most C compilers come with a library routine called xbios(), that stacks the parameters and executes the TRAP #14 in...
Page 199 Initmous Initialize Mouse Initmous() Opcode = 0 T h is f u n c t i o n le t s y o u s e n d t h e in te l l i g e n t k e y b o a r d c o n t r o l l e r a ll o f th e c o m m a n d s r e q u i r e d t o in itia liz e t h e m o u s e p a c k e t m o d e .
Page 200 Initmous m o d e w o r d A f la g t h a t s p e c i f i e s t h e t y p e o f m o u s e i n f o r m a t i o n p a c k e t s t h e I K B D c o n t r o l l e r is t o s e n d .
Page 201 Physbase Get Screen RAM Physical Base Address Physbase() Opcode = 2 T h is f u n c t i o n r e t u r n s th e s t a r t i n g a d d r e s s o f s c r e e n d i s p l a y m e m o r y . C macro format l o n g s c r a d d r ;...
Page 202 Logbase Get Screen RAM Logical Base Address Logbase() Opcode = 3 T h is f u n c t i o n r e t u r n s t h e b e g i n n i n g a d d r e s s o f lo g ic a l s c r e e n d i s p l a y m e m o r y .
Page 203 Getrez Get Screen Resolution Mode Getrez() Opcode = 4 G e t r e z ( ) c a n b e u s e d to d e t e r m i n e t h e c u r r e n t d i s p l a y m o d e . T h e t h r e e d i s p l a y m o d e s c u r r e n t l y s u p p o r t e d b y t h e S T a r e l o - r e s ( 3 2 0 x 2 0 0 , 1 6 c o l o r s ) , m e d i u m - r e s ( 6 4 0 x 2 0 0 , 4 c o l o r s ) a n d h i - r e s ( 6 4 0 x 4 0 0 , b l a c k a n d...
Page 204 Setscreen Set Screen Parameters Setscreen() Opcode = 5 T h e S e t s c r e e n ( ) f u n c t i o n a l l o w s t h e p r o g r a m m e r to c h a n g e t h e p h y s i c a l s c r e e n a d d r e s s , t h e lo g ic a l s c r e e n a d d r e s s , a n d / o r t h e d i s p l a y r e s o l u t i o n m o d e .
Page 205 Setpalette Set Color Palette Setpalette() Opcode = 6 T h is f u n c t i o n a l l o w s y o u t o s e t a n e n t i r e c o l o r p a l e t t e o f 1 6 h a r d w a r e c o l o r r e g i s t e r s a t o n e t i m e .
Page 206 Setcolor Set Color Register Setcolor() Opcode = 7 T h is f u n c t i o n a l l o w s y o u to c h a n g e t h e c o l o r in a s in g le h a r d w a r e c o l o r r e g i s t e r .
Page 207 Floprd Read Floppy Disk Sector Floprd() Opcode = 8 T h is f u n c t i o n is u s e d to r e a d o n e o r m o r e s e c t o r s o f in f o r m a t i o n f r o m a f lo p p y d is k .
Page 208 Flopwr Write Floppy Disk Sector Flopwr() Opcode = 9 T h is f u n c t i o n is u s e d t o w r i t e o n e o r m o r e s e c t o r s o f i n f o r m a t i o n to a f l o p p y d i s k .
Page 209 Flopfmt Format Floppy Disk Track Flopfmt() Opcode = 10 F l o p f m t ( ) f o r m a t s a n d v e r if ie s a s i n g l e t r a c k o f a f l o p p y d i s k . T o f o r m a t a n d in itia liz e a d i s k , y o u m u s t c r e a t e a b o o t s e c t o r a n d c l e a r t h e f ir s t t w o tr a c k s , in a d d i t i o n t o f o r m a t t i n g a ll t h e t r a c k s .
Page 210 Flopfmt s k e w t a b l l o n g T h is p a r a m e t e r is i g n o r e d in t h e e a r l y (p r e - b l i t t e r ) v e r s i o n o f T O S , b u t in th e l a t e r v e r s i o n s o f T O S , m a y b e u s e d to interleave.
Page 211 Midiws Write String to MIDI Port Midiws() Opcode T h is f u n c t i o n s e n d s a s t r i n g o f c h a r a c t e r s o u t t h e M I D I p o r t . C macro format in t b y t e s ;...
Page 212 Mfpint Change MFP Interrupt Vector Mfpint() Opcode = 13 T h is f u n c t i o n is u s e d t o c h a n g e a n i n t e r r u p t v e c t o r o n t h e M F P c h i p . C macro format in t n u m b e r - l o n g v e c t o r ;...
Page 213 Iorec Get I/O Buffer Record Iorec() Opcode = 14 I o r e c ( ) r e t u r n s t h e a d d r e s s o f a d a t a s t r u c t u r e k n o w n a s t h e I /O b u f f e r r e c o r d , c o n t a i n s i n f o r m a t i o n a b o u t t h e i n p u t b u f f e r u s e d b y a s p e c if ie d d e ...
Page 214 Rsconf Configure RS-232 Port Opcode = 15 Rsconf( ) T h is f u n c t i o n le t s y o u c h a n g e t h e R S - 2 3 2 s e r i a l p o r t p a r a m e t e r s , s u c h a s c o m m u n i c a t i o n s s p e e d , h a n d s h a k i n g , p a r i t y , a n d s o o n .
Page 215 Rsconf D a t a b its I p e r w o r d N u m b e r o f d a t a b its B its 8 b its 7 b i ts 6 b i ts 5 b its C l o c k U s e c lo c k d i r e c t l y f o r t r a n s f e r f r e q u e n c y ( s y n c h r o n o u s...
Page 216 Keytbl Get/Set Keyboard Mapping Tables Keytbl() Opcode = 16 T h is f u n c t i o n a l l o w s y o u t o f in d a n d c h a n g e t h e ta b le s t h a t m a p k e y s to t h e i r A S C I I v a l u e s .
Page 217 Random Get Pseudo-Random Number Random() Opcode = 17 T h is f u n c ti o n r e t u r n s t h e n e x t 2 4 - b i t p s e u d o - r a n d o m n u m b e r in t h e s e r i e s g e n e r a t e d b y t h e a l g o r i t h m : SEED = (SEED * 3141592621) + 1 T h e v a l u e r e t u r n e d is t h e n e w s e e d v a l u e , s h if te d e i g h t b its t o t h e r i g h t .
Page 218 Protobt Produce Boot Sector Prototype Protobt() Opcode = 18 T h is f u n c t i o n is u s e d t o c r e a t e a b o o t s e c t o r in m e m o r y . T h is is a s p e c ia ll y f o r m a t t e d b lo c k o f i n f o r m a t i o n t h a t m u s t b e s t o r e d o n t h e f ir s t s e c t o r o f e a c h f l o p p y d i s k ( s i d e 0 , tr a c k 0 , s e c t o r 1 ) .
Page 219 Flopver Verify Floppy Disk Sector Flopver() Opcode = 19 T h is f u n c t i o n is u s e d to v e r if y o n e o r m o r e s e c t o r s o f in f o r m a t i o n o n a f lo p p y d is k .
Page 220 Scrdmp Output Graphics Screen to Printer Scrdmp() Opcode = 20 T h e S c r d m p ( ) f u n c t i o n p r i n t s a g r a p h i c r e p r e s e n t a t i o n o f t h e s c r e e n d i s p l a y o n a n A t a r i o r E p s o n - c o m p a t i b l e p r i n t e r .
Page 221 Cursconf Configure Text Cursor Cursconf() Opcode = 21 T h e C u r s c o n f ( ) f u n c t i o n a l l o w s y o u t o c o n t r o l t h e v is ib ility a n d b lin k r a t e o f th e s y s t e m 's t e x t c u r s o r .
Page 222 Settime Set System Time and Date Opcode = 22 Settim e() T h e S e t t i m e ( ) f u n c t i o n is u s e d t o s e t t h e in te l l i g e n t k e y b o a r d 's t i m e a n d d a t e c lo c k .
Page 223 Gettime Get System Time and Date Opcode = 23 Gettime() T h is f u n c t i o n a l l o w s y o u to r e a d t h e in te l l i g e n t k e y b o a r d s ti m e a n d d a t e c lo c k .
Page 224 Bioskeys Restore Default Keyboard Table Bioskeys() Opcode = 24 T h is f u n c t i o n r e p l a c e s t h e k e y b o a r d m a p p i n g ta b le y o u h a v e in s t a lle d u s i n g t h e K e y t b l ( ) f u n c t i o n w i th t h e d e f a u l t s y s t e m k e y m a p s .
Page 225 Ikbdws Write String to Intelligent Keyboard Ikbdws() Opcode = 25 T h is f u n c t i o n s e n d s a s t r i n g o f c h a r a c t e r s o u t t o t h e I n t e l l i g e n t K e y b o a r d c o n t r o l l e r .
Page 226 Jdisint Disable an MFP Interrupt Jdisint() Opcode = 26 D is a b l e s o n e o f t h e 1 6 M F P i n t e r r u p t s . C macro format i n t i n t n u m ;...
Page 227 Jenabint Enable an MFP Interrupt Jenabint() Opcode = 27 E n a b l e s o n e o f t h e 1 6 M F P i n t e r r u p t s . C macro format in t i n t n u m ;...
Page 228 Giaccess Read/Write Sound Chip Giaccess() Opcode = 28 T h is f u n c t i o n a l l o w s y o u to r e a d o r c h a n g e a n y r e g i s t e r in t h e P r o g r a m m a b le S o u n d G e n e r a t o r (P S G ) c h i p .
Page 229 Offgibit Clear a Bit on Sound Chip I/O Port Offgibit() Opcode = 29 A t o m i c a l l y c l e a r s a s i n g l e b it o f t h e P o r t A I /O r e g i s t e r o n t h e P S G s o u n d c h i p .
Page 230 Ongibit Set a Bit on Sound Chip I/O Port Ongibit() Opcode = 30 A t o m i c a l l y s e t s a s in g le b it o f t h e P o r t A I /O r e g i s t e r o n t h e P S G s o u n d c h ip .
Page 231 Xbtimer Set an MFP Timer Xbtimer() Opcode = 31 T h e X b t i m e r ( ) f u n c t i o n a l l o w s y o u to s e t t h e M F P t i m e r r e g i s t e r s a n d a s s ig n a n i n t e r r u p t v e c t o r t o a t i m e r .
Page 232 Xbtimer ti m e r n u m w o r d A n u m b e r f r o m 0 - 3 t h a t r e p r e s e n t s t h e M F P t i m e r to c h a n g e .
Page 233 Dosound Start Sound Interrupt Processing Dosound() Opcode = 32 T h e D o s o u n d ( ) f u n c t i o n e n a b l e s a n i n t e r r u p t - d r i v e n r o u t i n e t h a t c a n p l a y m u s i c o r s o u n d e f f e c t s in t h e b a c k g r o u n d .
Page 234 Dosound (Command Number) First Byte Second Byte Third Byte Fourth Byte 1 3 0 - 2 5 5 P a u s e T h e n u m b e r o f t i m e r tic k s to f o r a s p e c if ie d n u m b e r o f t i m e r p a u s e ( 1 - 2 5 5 ) .
Page 235 Setprt Set Printer Configuration Opcode = 33 Setprt() T h is f u n c t i o n a ll o w s y o u to s e t t h e p r i n t e r c o n f i g u r a t i o n , a c o d e n u m b e r t h a t c o n t a i n s in f o r m a t i o n a b o u t th e t y p e o f p r i n t e r t h a t is a t t a c h e d .
Page 236 Setprt R e s e r v e d f o r f u t u r e u s e R e s e r v e d f o r f u t u r e u s e M u s t b e 0 Results c o d e...
Page 237 Kbdvbase Get Keyboard Vector Table Base Address Kbdvbase() Opcode = 34 T h is f u n c t i o n r e t u r n s p o i n t e r s t o s e v e r a l o f t h e i n t e r r u p t r o u t i n e s t h a t a r e u s e d to h a n d l e t h e i n p u t f u n c t i o n s .
Page 238 Kbrate Set Keyboard Repeat Rate Kbrate() Opcode = 35 T h e K b r a t e ( ) f u n c t i o n is u s e d t o c o n t r o l t h e r e p e a t r a t e o f t h e c o n s o l e d e v i c e k e y b o a r d .
Page 239 Prtblk Output Graphics Block to Printer Prtblk() Opcode = 36 T h is f u n c t i o n c a n b e u s e d to p r i n t t h e e n t i r e s c r e e n , o r a n y p o r t i o n o f it, to a g r a p h i c s p r i n t e r .
Page 240 Vsync Wait for Vertical Blank Vsync() Opcode = 37 T h is f u n c t i o n s i m p l y w a i t s u n til t h e v e r t i c a l b l a n k i n t e r r u p t is f in i s h e d , a n d r e t u r n s .
Page 241 Supexec Execute Supervisor Mode Function Supexec() Opcode = 38 R u n s a s u b r o u t i n e in t h e 6 8 0 0 0 p r o c e s s o r 's s u p e r v i s o r m o d e . C macro format l o n g s u b ;...
Page 242 Blitmode Get/Set Blitter Configuration Blitmode() Opcode = 64 T h is f u n c t i o n is u s e d to f in d o u t if a b l itt e r c h i p is a v a i la b l e , a n d w h e t h e r it is b e i n g u s e d f o r d r a w i n g r o u t i n e s .
Page 243: Gemdos Functions
Appendix C GEMDOS Functions...
Page 245 routines can be called from user mode. They use registers A0-A2 and D0-D2 as scratch registers. If you are programming in machine language and your pro gram uses these registers, you must save their contents be fore making a GEMDOS call and restore them after the call terminates.
Page 246 APPENDIX C The following program fragment demonstrates how you would print the character A on the console screen using GEMDOS command 2: move.w # 'A ', — (sp) * push the character value on stack move.w # 2, — (sp) * push GEMDOS command number on * stack trap...
Page 247 PtermO Terminate Process PtermO() Opcode = 0 ($00) T h is f u n c t i o n t e r m i n a t e s t h e c u r r e n t p r o c e s s , c l o s e s a ll o p e n f ile s , c l e a r s t h e m e m o r y s p a c e u s e d b y t h e p r o c e s s , a n d r e t u r n s t o t h e p r o g r a m t h a t c a lle d it ( n o r m a l l y t h e G E M D e s k t o p ) .
Page 248 Cconin Wait for Keyboard Character Cconin() Opcode = 1 ($01) T h is f u n c t i o n w a i t s u n til a c h a r a c t e r is a v a i la b l e f r o m t h e c o n s o l e k e y b o a r d , e c h o e s it to t h e s c r e e n , a n d r e t u r n s it s A S C I I v a l u e a n d s c a n c o d e .
Page 249 Cconout Send Character to Screen Cconout() Opcode = 2 ($02) T h is f u n c t i o n s e n d s a s in g le c h a r a c t e r to t h e c o n s o l e s c r e e n d e v i c e . C macro format c h a r c h ;...
Page 250 Cauxin Wait for RS-232 Character Cauxin() Opcode = 3 ($03) T h is f u n c t i o n w a i t s u n til a c h a r a c t e r is a v a i la b l e f r o m t h e R S - 2 3 2 s e r i a l d e v i c e , a n d r e t u r n s it s A S C I I v a l u e .
Page 251 Cauxout Send Character to RS-232 Port Cauxout() Opcode = 4 ($04) T h is f u n c t i o n s e n d s a s i n g l e c h a r a c t e r to t h e R S - 2 3 2 s e r i a l d e v i c e . I t d o e s n o t r e t u r n u n til t h e c h a r a c t e r h a s b e e n s e n t .
Page 252 Cprnout Send Character to Printer Cprnout() Opcode = 5 ($05) T h is f u n c t i o n s e n d s a s in g le c h a r a c t e r t o t h e C e n t r o n i c s p a r a lle l p r i n t e r d e v i c e .
Page 253 Crawio Input/Output Console Character Crawio() Opcode = 6 ($06) T h is f u n c t i o n a l l o w s y o u e i t h e r t o s e n d c h a r a c t e r s t o t h e c o n s o l e d e v i c e , o r to r e c e i v e t h e m .
Page 254 Crawcin Raw Keyboard Input Without Echo Crawcin() Opcode = 7 ($07) T h is f u n c t i o n w a i t s u n til a c h a r a c t e r is a v a i la b l e f r o m t h e c o n s o l e k e y b o a r d , a n d r e t u r n s its A S C I I v a l u e a n d s c a n c o d e .
Page 255 Cnecin Keyboard Input Without Echo Cnecin() Opcode = 8 ($08) T h is f u n c t i o n w a i t s u n til a c h a r a c t e r is a v a i la b l e f r o m t h e c o n s o l e k e y b o a r d , d o e s n o t e c h o t h e c h a r a c t e r t o t h e s c r e e n , a n d r e t u r n s it s A S C I I v a l u e a n d s c a n c o d e .
Page 256 Cconws Write String to Screen Cconws() Opcode = 9 ($09) A ll o w s y o u t o p r i n t a n e n t i r e s t r i n g o f c h a r a c t e r s t o t h e c o n s o l e d e v i c e s c r e e n a t o n c e .
Page 257 Cconrs Read String from Keyboard Cconrs() Opcode = 10 ($0A) T h is f u n c t i o n r e a d s a n e n t i r e s t r i n g o f c h a r a c t e r s f r o m t h e c o n s o l e k e y b o a r d , e c h o i n g e a c h c h a r a c t e r t o t h e s c r e e n a s it is r e a d .
Page 258 Cconis Get Keyboard Input Status Cconis() Opcode = 11 ($0B) A ll o w s y o u t o d e t e r m i n e w h e t h e r t h e r e is a c h a r a c t e r w a i t i n g t o b e r e c e i v e d f r o m t h e c o n s o l e d e v i c e k e y b o a r d .
Page 259 Dsetdrv Set Default Drive Number Opcode = 14 ($0E) Dsetdrv() T h e d e f a u l t d r i v e is t h e o n e G E M D O S a s s u m e s is r e f e r r e d to w h e n o n l y a f ile n a m e is u s e d .
Page 260 Cconos Get Screen Output Status Cconos() Opcode=16 ($10) T h is f u n c t i o n a l l o w s y o u t o d e t e r m i n e w h e t h e r t h e c o n s o l e d e v i c e s c r e e n is r e a d y t o a c c e p t a c h a r a c t e r .
Page 261 Cprnos Get Printer Output Status Cprnos() Opcode = 17 ($11) T h is f u n c t i o n a l l o w s y o u to d e t e r m i n e w h e t h e r t h e C e n t r o n i c s p a r a ll e l p r i n t e r d e v i c e is r e a d y t o a c c e p t a c h a r a c t e r .
Page 262 Cauxis Get RS-232 Input Status Cauxis() Opcode = 18 ($12) T h is f u n c t i o n a l l o w s y o u t o d e t e r m i n e w h e t h e r t h e r e is a c h a r a c t e r w a i t i n g to b e r e c e i v e d f r o m t h e R S - 2 3 2 s e r i a l d e v i c e .
Page 263 Cauxos Get RS-232 Output Status Cauxos() Opcode = 19 ($13) T h is f u n c t i o n a l l o w s y o u t o d e t e r m i n e w h e t h e r t h e R S - 2 3 2 s e r i a l d e v i c e is r e a d y t o a c c e p t a c h a r a c t e r .
Page 264 Dgetdrv Get Default Drive Number Dgetdrv() Opcode = 25 ($19) T h is f u n c t i o n a l l o w s y o u t o f in d t h e d r i v e n u m b e r o f t h e c u r r e n t d e f a u l t d r i v e .
Page 265 Fsetdta Set Disk Transfer Address Fsetdta() Opcode = ($1A) This function allows you to change the Disk Transfer Address, which points to the buffer used for disk read operations. This buffer is used as a scratch area for directory searches. C macro format char dta[44];...
Page 266 Super Set User/Supervisor Mode Super() Opcode = 32 ($20) This function is used to change between the 68000 processor's user and supervisor modes. Though most programs operate in user mode, certain operations on the ST can only be performed from supervisor mode. These include reading or writing to system variables stored in memory locations below 2048 ($800), and reading or writing to hardware registers located above 167444482 ($FF80000).
Page 267 Tgetdate Get GEMDOS Date Tgetdate() Opcode = 42 ($2A) Gets current date according to GEMDOS. C macro format int date; date = Tgetdate(); Machine language format move.w #$2A, - (sp) trap addq.l #2,sp Inputs None Results date word A 16-bit code that specifies the GEMDOS date. Interpretation of GEMDOS date: Bit Number...
Page 268 Tsetdate Set GEMDOS Date Tsetdate() Opcode = 43 ($2B) Sets current date for GEMDOS. C macro format int date; Tsetdate(date); Machine language format move.w #date, - (sp) move.w #$2B, - (sp) trap addq.l #4,sp Inputs date word A 16-bit code that specifies the GEMDOS date.
Page 269 Tgettime Get GEMDOS Time Tgettime() Opcode = 44 ($2C) This function is used to get the GEMDOS version of the current time. C macro format int time; time = Tgettime(); Machine language format move.w #$2C, - (sp) trap addq.l #2,sp Inputs None Results...
Page 270 Tsettime Set GEMDOS Time Tsettime() Opcode = 45 ($2D) Allows you to set the GEMDOS time. C macro format int time; Tsettime(time); Machine language format move.w #time, - (sp) move.w #$2D, - (sp) trap addq.l #4,sp Inputs time word A 16-bit code that indicates the time. Interpretation of GEMDOS time: Bit Number...
Page 271 Fgetdta Get Disk Transfer Address Fgetdta() Opcode = 47 ($2F) This function finds the current Disk Transfer Address that points to the buffer used for disk read operations. This buffer is used as a scratch area for directory searches. C macro format char *dta;...
Page 272 Sversion Get GEMDOS Version Number Sversion() Opcode = 48 ($30) This function returns the GEMDOS version number. This number refers only to the version of GEMDOS, not to the GEM or TOS version in gen eral. C macro format int version; version = Sversion();...
Page 273 Ptermres Terminate and Stay Resident Ptermres() Opcode = 49 ($31) Like the Pterm() and PtermO() functions, this one terminates the current process, closes all open files, and exits to the calling program, usually the GEM Desktop. It allows a return code to be passed to the calling program as well.
Page 274 Dfree Get Disk Free Space Dfree() Opcode = 54 ($36) The Dfree() function is used to find the amount of free space left on a disk. C macro format long buffer[4]; int drivenum; Dfree(buffer, drivenum); Machine language format move.w #drivenum, - (sp) move.l buffer, - (sp) move.w...
Page 275 Dcreate Create Directory Opcode = 57 ($39) Dcreate() This function is used to create a new subdirectory. C macro format int status; char ^pathname; status = Dcreate(pathname); Machine language format move.l pathname, - (sp) move.w #$39, - (sp) trap addq.l #6,sp Inputs pathname...
Page 276 Ddelete Delete Directory Ddelete() Opcode = 58 ($3A) Used to delete a subdirectory, provided that it contains no files. C macro format int status; char ^pathname; status = Ddelete(pathname); Machine language format move.l pathname, - (sp) move.w #$3A, - (sp) trap #6,sp addq.l...
Page 277 Dsetpath Set Default Directory Path Dsetpath() Opcode = 59 ($3B) This function is used to set a default directory on a drive, which is where GEMDOS will search first for a named file. C macro format int status; char *path; status = Dsetpath(path) Machine language format move.l...
Page 278 Fcreate Create File Fcreate() Opcode = 60 ($3C) Creates a new file, or if the specified file already exists, truncates it to length 0. The file is opened, and a 16-bit handle is returned that can be used for further access to the file, f w- C macro format char *fname;...
Page 279 Fopen Open File Opcode = 61 ($3D) Fopen() O p e n s a s p e c if ie d f ile , a n d r e t u r n s a 1 6 - b i t h a n d l e t h a t c a n b e u s e d f o r f u r t h e r a c c e s s to t h e file .
Page 280 Fclose Close File Fclose() Opcode = 62 ($3E) W h e n a p r o g r a m is f in i s h e d w i t h a f ile , i t m u s t u s e th is f u n c t i o n to c l o s e t h e file .
Page 281 Fread Read File Fread() Opcode = 63 ($3F) T h is f u n c ti o n r e a d s a s p e c if ie d n u m b e r o f b y t e s f r o m a n o p e n file . C macro format l o n g s t a t u s , c o u n t ;...
Page 282 Fwrite Write File Fwrite() Opcode = 64 ($40) T h is f u n c t i o n w r i t e s a s p e c if ie d n u m b e r o f b y t e s to a n o p e n file . C macro format l o n g s t a t u s , b y t e s ;...
Page 283: Delete File
Fdelete Delete File Opcode = 65 ($41) Fdelete() D e l e t e s a s p e c i f i e d file f r o m i t s d i r e c t o r y . C macro format i n t s t a t u s ;...
Page 284 Fseek Seek File Opcode = 66 ($42) Fseek() A l l o w s y o u t o m o v e t h e file p o i n t e r to c h a n g e t h e p o s i tio n in t h e file a t w h i c h d a t a w ill b e r e a d o r w r i t t e n .
Page 285 Fattrib Get/Set File Attributes Fattrib() Opcode = 67 ($43) T h is f u n c t i o n c a n b e u s e d t o r e a d o r c h a n g e f ile 's a tt r i b u t e s . C macro format in t a t t r i b u t e s , m o d e , n e w a t t r ;...
Page 286 Fdup Duplicate Standard File Handle Fdup() Opcode = 69 ($45) T h is f u n c t i o n is u s e d a s p a r t o f t h e file r e d i r e c t i o n p r o c e s s . I t c r e a t e s a u s e r - d e s i g n a t e d file h a n d l e t h a t d u p l i c a t e s t h e f u n c ti o n o f o n e o f t h e s t a n ...
Page 287 Fforce Replace Standard File Handle Fforce() Opcode = 70 ($46) P e r m i t s y o u to r e d i r e c t I /O f r o m a s t a n d a r d d e v i c e h a n d l e t o a u s e r - d e s i g n a t e d o n e .
Page 288 Dgetpath Get Default Directory Path Dgetpath() Opcode = 71 ($47) T h is f u n c t i o n is u s e d to f in d t h e d e f a u l t d i r e c t o r y o n a d r i v e , w h i c h is w h e r e G E M D O S s e a r c h e s f ir s t f o r a n a m e d file .
Page 289 Malloc Allocate Memory Block Malloc() Opcode = 72 ($48) U s e d to a l l o c a t e s o m e o f t h e s y s t e m 's f r e e m e m o r y , a n d r e s e r v e it f o r u s e b y t h e p r o g r a m .
Page 290 Mfree Free Memory Block Mfree() Opcode = 73 ($49) T h i s f u n c t i o n is u s e d to r e t u r n m e m o r y t h a t w a s a l l o c a t e d w i t h M a l l o c ( ) b a c k t o t h e s y s t e m .
Page 291 Mshrink Shrink Memory Block Opcode = 74 ($4A) Mshrink() W h e n a p r o g r a m is r u n , it is a l l o c a t e d a ll t h e s y s t e m 's f r e e m e m o r y . T h is f u n c t i o n is u s e d t o r e t u r n a n y e x c e s s m e m o r y b a c k t o t h e s y s t e m .
Page 292 Pexec Execute Process Pexec() Opcode = 75 ($4B) T h is f u n c t i o n is u s e d to lo a d a p r o g r a m file a n d e x e c u t e it. C macro format * c h a r file , c o m m a n d , e n v ;...
Page 293 Pterm Terminate Process with Return Code Pterm() Opcode = 76 ($4C) L ik e P t e r m O ( ) , P t e r m ( ) t e r m i n a t e s t h e c u r r e n t p r o c e s s , c l o s e s a ll o p e n f ile s , c l e a r s t h e m e m o r y s p a c e u s e d b y t h e p r o c e s s , a n d e x i t s t o th e c a lli n g p r o g r a m , u s u a l l y t h e G E M D e s k t o p .
Page 294 Fsfirst Find First File in Directory Chain Fsfirst() Opcode = 78 ($4E) T h is f u n c t i o n is u s e d to f in d t h e f ir s t file in a d i r e c t o r y t h a t m a t c h e s a p a r t i c u l a r d e s c r i p t i o n .
Page 295 Fsnext Find Next File in Directory Chain Fsnext() Opcode = 79 ($4F) T h is f u n c t i o n is u s e d to f in d a d d i t i o n a l file s in a d i r e c t o r y c h a i n t h a t m e e t th e c r i t e r i a s e t f o r t h in a p r e v i o u s F s f i r s t ( ) c a ll.
Page 296 Frename Rename File Frename() Opcode = 86 ($56) C h a n g e s t h e n a m e o f a file . C macro format i n t s t a t u s ; c h a r * o l d n a m e ;...
Page 297 Fdatime Get/Set File Date/Time Stamp Fdatime() Opcode = 87 ($57) T h is f u n c t i o n is u s e d t o r e a d o r c h a n g e t h e ti m e a n d d a t e s t a m p o f a n o p e n file .
Page 299: Error Codes
Appendix D Error Codes...
Page 301 BIOS Errors Error Description Number Macro Name Action successful (no error) ERROR General error DRIVE__NOT_READY Device not ready, not connected, or busy UNKNOWN__CMD The device doesn't know how to respond to this command CRC_ERROR A soft error occured while reading a sector BAD_REQUEST Device can't handle this command, possibly because...
Page 302 APPENDIX D — 16 BAD_SECTORS Format operation resulted in one or more bad sectors -1 7 INSERT_DISK Ask user to insert disk GEMDOS Errors GEMDOS Error Error Macro Number Description Number Name -3 2 EINVFN Invalid function number EFILNF -3 3 File not found EPTHNF -3 4...
Page 303: Escape Sequences
Appendix E VT-52 Console Escape Sequences...
Page 305 Unlike GEM graphics text functions, which output any character for which there is image data, the con sole device screen emulates a DEC VT-52 display terminal, and treats the ASCII characters from 0 to 31 as nonprinting control characters. This means that it interprets the ASCII character 13 as a carriage return, an instruction to move the cursor to the beginning of the line, rather than as a character that should be printed.
Page 306 APPENDIX E Esc o Clear from Beginning of Line Esc p Reverse Video On Esc q Reverse Video Off Esc v Line Wrap On Esc w Line Wrap Off In addition to the escape codes, the ST terminal emulation also responds to the following ASCII control codes: Backspace 10-12 Linefeed Carriage Return...
Page 307: The Mfp Chip
Appendix F The MFP Chip...
Page 309 The 68901 Multi-Function Peripheral (MFP) chip handles a variety of input/output chores on the ST. It con tains an 8-bit parallel I/O port, each bit of which is used for a different purpose. The port is used for monochrome monitor detection, RS-232 carrier detect, ring detect, and clear to send (CTS), parallel port and blitter-busy detection a unit, and data requests from the floppy drives, DMA port, intelligent...
Page 310 APPENDIX F Jdisint(), Jenabint() and Mfpint(). The MFP registers, and their functions, are: Register 1. General Purpose I/O Interrupt Port (GPIP). This is the data register for the 8-bit parallel I/O port, where the data is read and written. Register 2. Active Edge Register (AER). For parallel port input bits.
Page 311 The MFP Chip Internal Priority Interrupt Level Source Function Number Timer C System Clock (200 Hz) Timer D RS-232 baud rate generator Graphics blitter chip I/O Port Bit 3 done RS-232 Clear To Send I/O Port Bit 2 (CTS) I/O Port Bit 1 RS-232 Data Carrier Detect (DCD) I/O Port Bit 0...
Page 312 APPENDIX F register, and an 8-bit interval counter, whose value decre ments by one at every impulse. When the interval counter timer reaches 0, the value of the data register is loaded into the counter, and an interrupt will be generated if enabled. The source of the impulse that causes the counter to dec...
Page 313 The MFP Chip Table F-4. Control Register Values for Timers C and D Timer C Timer D Value Value Timer Mode Delay mode, clock divided by 16 Delay mode, clock divided by 50 Delay mode, clock divided by 64 Delay mode, clock divided by 100 Delay mode, clock divided by 200 Registers 16-19.
Page 314 APPENDIX F Table F-5. USART Control Register (UCR) Function Clock. 0 = Use clock directly for transfer frequency (synchronous transfer). 1 = Divide clock frequency by 16. Register 22. Receiver Status Register (RSR). This register contains information about serial port reception as shown in Table F-6.
Page 315 The MFP Chip Table F-7. Transmitter Status Register (TSR) Function High/Low Output. 0 = High output. 1 = Low output. 2 = High output. 3 = Loop-back mode. Break. In asynchronous mode, a break is sent when this bit is set. End of Transmission.
Page 317: System Characters
Appendix G System Characters...
Page 319 This appendix includes all the system font. The font supports all characters from 0 through 255. « > 1 6 Q « < • S p a c e • » © £| 1 0 * 1 1 J ' &...
Page 320 APPENDIX G 94 A 80 P 52 4 66 B 95 _ 67 (J 81 Q 53 5 82 R 68 P 54 g 83 S 69 E 55 7 84 J 70 F 56 8 71 G 85 U 57 9 £...
Page 321 System Characters 150 jj 123 { 1 0 9 no n 153 0 1 2 5 154 |j " 113 q 127 A 114 p 156 £ 128 (J 157 y 115 S 129 ij 130 e 158 0 116 t 131 a 117 U £...
Page 322 APPENDIX G 1 6 4 1 9 2 2 0 6 1 7 8 2 0 7 1 6 5 1 7 9 1 9 3 2 0 8 1 6 6 1 9 4 1 8 0 2 0 9 1 6 7 1 9 5 1 8 1...
Page 323 System Characters 2 3 4 2 4 8 ° § 2 4 9 2 3 5 2 5 0 2 3 6 2 5 1 2 3 7 2 2 3 £ 2 5 2 2 2 4 2 3 8 2 3 9 2 5 3 2 2 5...
Page 325: The Line A Variable Table
Appendix H The Line A Variable Table...
Page 327 The line A routines use about IK of variable space, in which much of the system's graphics data is stored. The location of this variable table may vary from machine to machine, and from one version of TOS to another, but it can always be found by calling the Line A Initialization function (see Chapter 7 for more details).
Page 328 APPENDIX H The x offset of the mouse hot spot within the 16 x 16 image area. -8 5 4 -8 5 1 (-$ 3 5 4 -$353) M__POS__HY The y offset of the mouse hot spot within the 16 x 16 image area.
Page 329 The Line A Variable Table Reference Guide, Atari ST Volume One: The VDI for more infor mation. -6 9 2 to -6 0 3 ( — $2B4 to -$25B ) DEV_TAB This table contains the first 45 words of information returned by the VDI function v__opnwk().
Page 330 VDI function v__opnwk(). Three words of storage are reserved at the end of the table, making it 15 words in length. See COMPUTEI's Technical Reference Guide, Atari ST Volume One: The VDI to read more about the information re...
Page 331 The Line A Variable Table -4 4 0 to -4 3 7 ( — $1B8 to -$1B 7) FONT__COUNT The number of fonts in the FONT__RING lists. -4 3 8 to -3 4 9 ( — $1B6 to -$15D ) RESERVED This area is reserved for internal use.
Page 332 APPENDIX H blank interrupt handler, which draws the mouse pointer, to determine where and whether to redraw the mouse pointer during the next vertical blank. - 342 to - 341 ( - $156 to - $155) UR__Y Vertical position at which the mouse pointer is to be drawn. -3 4 0 (-$154) CUR__FLAG...
Page 333 ( - $03A - $037) USER__BUT The Button Change vector. For more information, see the de scription of the VDI function vex__butv() in COMPUTE!'s Technical Reference Guide, Atari ST Volume One: The VDI. - 054 - 050 ( - $036 - $033) USER__CUR The Cursor Change vector.
Page 334 APPENDIX H - 046 to - 045 ( - $02E to - $02D) V CEL_ _ HT _____ Text cell height (in pixels). - 044 to - 043 ( - $02C to - $02B) V CEL_ _ MX _____ Maximum horizontal text position (in characters). This equals the maximum number of characters on a line, minus one.
Page 335 The Line A Variable Table -0 2 4 (-$018) V PERIOD Text cursor blink rate (in vertical blanking intervals). -0 2 3 (-$017) V CUR__CT Text cursor countdown timer to next blink toggle. - 022 to - 019 ( - $016 to - $013) V FNT__ AD ______ Address of monospaced font data.
Page 336 APPENDIX H -0 0 2 to -0 0 1 (-$ 0 0 2 to -$001) BYTES__LIN Width of the destination memory form; set to the save value as WIDTH. + 000 to +001 ( + $000 to +$001) PLANES Number of color bit planes for current screen resolution. + 003 to +003 ( + $002 to +$003) WIDTH...
Page 337 The Line A Variable Table + 026 to +027 ( + $01A to + $01B) COLBIT1 for plane 1 of the display. The color bit plane value ( + $01C to +$01D) + 028 to +029 COLBIT2 for plane 2 of the display. The color bit plane value ( + $01E to +$01F) + 030 to +031...
Page 338 APPENDIX H Mode Logic Operation Description D1 = D Destination unchanged D1 = S XOR D XOR mode D1 = S OR D Transparent mode D1 = NOT (S OR D)‘ D1 = NOT (S XOR D) D1 = NOT D D1 = S OR (NOT D) D1 = NOT S D1 = (NOT S) OR D...
Page 339 The Line A Variable Table pattern, while a nonzero value indicates a multiplane fill pat tern. + 054 to +055 ( + $036 to + $037) CLIP Clipping flag. A 0 here turns clipping off, while any other value turns it on. + 056 to +057 ( + $038 to +$039) XINCL...
Page 340 APPENDIX H Value Meaning Font is not monospaced, or size may vary due to special effects. Font is monospaced, and uses no special effects other than thickening (boldface). + 072 to +073 ( + $048 to + $049) SOURCEX The x coordinate of character to be printed in font form. SOURCEX can usually be computed from information in the font header: ch = character to be printed - first_ade...
Page 341 The Line A Variable Table dress may be at an offset of 76 bytes from the beginning of the font header, in the dat__table variable. + 088 to +089 ( + $058 to +$059) FWDITH Width the font form in bytes (the sum of the pixel width of all of the characters in the font, divided by 8).
Page 342 APPENDIX H +100 to +101 (+ $064 to + $065) LOFF Offset below baseline for italicizing (0 if skewing is not used). Can be obtained from the skewmask variable of the font header. + 102 to +103 ( + $066 to +$067) SCALE Text scaling flag (0 = no scaling used).
Page 343 The Line A Variable Table + 116 to +117 (+$074 to +$075) COPYTRAN line A Copy Raster mode: Value Meaning Zero Copy Raster Opaque Nonzero Copy Raster Transparent + 118 to +121 ( + $076 to +$079) SEEDABORT Pointer to a routine called by the SeedFill function after each horizontal line is filled.
Page 345: The Intelligent Keyboard Controller
Appendix I The Intelligent Keyboard Controller...
Page 347 On the ST 9 there are two ways of receiving input from the keyboard. The normal method is to use the GEM DOS console device. You can, however, communicate di rectly with the keyboard itself. That's because on the ST, the keyboard isn't just a dumb, passive hardware device.
Page 348 APPENDIX I Header Information Packet Type IKBD status record Absolute mouse position record $F8-$FB Relative mouse position record (bits 0 and 1 indicate button status) Time-of-day record Joystick report (both sticks) Joystick 0 event record Joystick 1 event record Mouse Functions The IKBD enables the ST mouse to operate in one of three modes.
Page 349 The Intelligent Keyboard Controller mode, mouse position changes are translated into the equiva lent cursor key strokes (up arrow, right arrow, and so on). The user may set a scale factor that determines how far the mouse must move before a cursor keycode is generated. A right mouse button press is reported as keycode $74, while a left mouse button press is reported as keycode $75.
Page 350 APPENDIX I When this mode is in effect, joystick information is only sent after a joystick interrogation command ($16). In keycode mode, stick position changes are translated into the equivalent cursor key strokes (up arrow, right arrow, and so on). The user may set a time factor that determines how long the stick must be held in one position before the cursor keycode is repeated.
Page 351 The Intelligent Keyboard Controller Communicating with the IKBD on the ST As you have seen, the IKBD supports several different func tions, each with several modes of operation. To select a func tion and mode, merely send a message to the controller, us ing the BIOS function Bconout(), or the XBIOS functions Ikbdws() or Initmous().
Page 352 APPENDIX I tered, the address of the packet buffer will be on the stack and in register AO. Your routine should begin by saving all registers that you will use, and restoring those registers before ending. It should not spend more than one millisecond handling the in terrupt (most of the time, just moving the packet information to your own buffer), and should end with an RTS instruc...
Page 353 The Intelligent Keyboard Controller $07 Set Mouse Button Action D e t e r m i n e s w h e t h e r t h e I K B D t r e a t s t h e m o u s e b u t t o n s a s k e y b o a r d k e y s . I n a b s o l u t e p o s i t i o n i n g m o d e , th i s f u n c t i o n c a n a l s o b e u s e d t o c a u s e a m o u s e b u t t o n p r e s s o r r e l e a s e t o r e t u r n t h e a b s o l u t e m o u s e p o s i tio n .
Page 354 APPENDIX I $08 Set Relative Mouse Position Reporting T h is c o m m a n d p u t s t h e m o u s e i n t o r e l a t i v e p o s i t i o n m o d e . In th is m o d e , t h e I K B D s e n d s m o u s e p o s i t i o n p a c k e t s w h e n e v e r t h e m o u s e is m o v e d m o r e t h a n t h e t h r e s h o l d d i s t a n c e in t h e o r y d i r e c t i o n .
Page 355 The Intelligent Keyboard Controller Packet returned Byte Number Description $ F 8 - $ F B ( m o u s e r e l a t i v e p o s i t i o n p a c k e t h e a d e r ) . B its 0 a n d 1 r e c o r d th e r i g h t a n d le f t m o u s e b u t t o n s t a t e : $ F 8 n e i t h e r b u t t o n p r e s s e d...
Page 356 APPENDIX I $09 Set Absolute Mouse Positioning T h i s c o m m a n d p u t s t h e m o u s e i n t o a b s o l u t e p o s i t i o n m o d e . I n th is m o d e , a m o u s e p o s i t i o n p a c k e t t h a t r e t u r n s t h e c u r r e n t m o u s e p o s i t i o n a s a n a b ...
Page 357 The Intelligent Keyboard Controller $0A Set Mouse Keycode Mode T h is c o m m a n d p u t s t h e m o u s e in t o k e y c o d e m o d e . I n th is m o d e , t h e I K B D s e n d s c u r s o r a r r o w k e y c o d e s w h e n e v e r t h e m o u s e is m o v e d m o r e t h a n th e t h r e s h o l d d i s t a n c e in t h e d i r e c t i o n .
Page 358 APPENDIX I $0B Set Mouse Threshold T h is c o m m a n d s e t s t h e m o v e m e n t t h r e s h o l d n e c e s s a r y b e f o r e a m o u s e p o s iti o n r e p o r t is s e n t in r e l a t i v e p o s i t i o n m o d e .
Page 359 The Intelligent Keyboard Controller $0C Set Mouse Scale T h is c o m m a n d s e t s t h e s c a l e f a c t o r f o r a b s o l u t e p o s i t i o n m o d e . T h i s is t h e n u m b e r o f m o u s e u n i t s y o u m u s t m o v e b e f o r e t h e in t e r n a l p o s i t i o n s e t t i n g s c h a n g e .
Page 360 APPENDIX I $0D Interrogate Mouse Position T h is f u n c t i o n is u s e d t o r e a d t h e m o u s e p o s i t i o n w h e n in a b s o l u t e p o s i tio n m o d e .
Page 361 The Intelligent Keyboard Controller $0E Load Mouse Position In a b s o l u t e p o s i t i o n m o d e , th is c o m m a n d is u s e d t o r e s e t t h e a b s o l u t e a n d y p o s i t i o n v a l u e s .
Page 362 APPENDIX I $0F Set Origin at Bottom T h is c o m m a n d s e t s t h e o r ig i n o f t h e y c o o r d i n a t e s y s t e m a t t h e b o t t o m , w h i c h m e a n s t h a t d o w n w a r d m o v e m e n t ( t o w a r d s t h e u s e r ) is t r e a t e d a s n e g a t i v e , a n d u p w a r d m o v e m e n t ( a w a y f r o m t h e u s e r ) is t r e a t e d a s p o s i ...
Page 363 The Intelligent Keyboard Controller $10 Set Origin at Top T h is c o m m a n d s e t s t h e o r ig i n o f t h e c o o r d i n a t e s y s t e m a t t h e b o t t o m , w h i c h m e a n s t h a t d o w n w a r d m o v e m e n t ( t o w a r d s t h e u s e r ) is t r e a t e d a s p o s i t i v e , a n d u p w a r d m o v e m e n t ( a w a y f r o m t h e u s e r ) is t r e a t e d a s n e g a ...
Page 364 APPENDIX I $11 Resume T h is c o m m a n d c a u s e s th e I K B D t o r e s u m e s e n d i n g d a t a p a c k e t s a f t e r it h a s b e e n p a u s e d w i t h c o m m a n d $ 1 3 .
Page 365 The Intelligent Keyboard Controller $12 Disable Mouse T h is c o m m a n d d i s a b l e s a ll m o u s e m o v e m e n t a n d m o u s e b u t t o n s c a n n i n g a n d r e p o r t i n g .
Page 366 APPENDIX I $13 Pause Output T h is c o m m a n d s t o p s a ll t r a n s f e r o f d a t a t o th e m a in p r o c e s s o r . S c a n n i n g c o n t i n u e s i n t e r n a l l y , a n d k e y s t r o k e s , m o u s e m o v e m e n t s , a n d j o y s tic k e v e n t s (if e n a b l e d ) w ill b e q u e u e d u p to c a p a c i t y o f t h e 6 3 0 1 m i c r o p r o c e s ...
Page 367 The Intelligent Keyboard Controller $14 Set Joystick Event Reporting T h is c o m m a n d p u t s t h e jo y s t i c k p o r t s i n t o e v e n t r e p o r t i n g m o d e . I n th is m o d e , e a c h m o v e m e n t o f t h e s tic k o r b u t t o n c a u s e s a j o y s t i c k e v e n t p a c k e t t o b e s e n t .
Page 368 APPENDIX I $15 Set Joystick Interrogation Mode T h is c o m m a n d p u t s t h e j o y s t i c k p o r t s in t o i n t e r r o g a t i o n m o d e . I n th is m o d e , jo y s t i c k e v e n t s w ill o n l y b e r e p o r t e d w h e n t h e i n t e r r o g a t e j o y s tic k c o m m a n d ($ 1 6 ) is s e n t to t h e I K B D .
Page 369 The Intelligent Keyboard Controller $16 Interrogate Joystick T h is f u n c t i o n c a n b e u s e d t o r e a d t h e c u r r e n t s t a t u s o f t h e j o y s tic k s w h e n in e v e n t r e p o r t i n g m o d e o r i n t e r r o g a t i o n m o d e .
Page 370 APPENDIX I $17 Set Joystick Monitoring T h i s c o m m a n d s e t s t h e I K B D i n t o j o y s t i c k m o n i t o r i n g m o d e . W h e n i n th is m o d e , t h e I K B D d o e s n o t h i n g b u t m o n i t o r t h e jo y s t i c k , c o m m u n i c a t e o v e r t h e s e r i a l lin e , a n d m a i n t a i n t h e t i m e - o f - d a y c lo c k .
Page 371 The Intelligent Keyboard Controller $18 Set Fire Button Monitoring T h is c o m m a n d s e t s t h e I K B D i n t o f ire b u t t o n m o n i t o r i n g m o d e . W h e n in th is m o d e , t h e I K B D d o e s n o t h i n g b u t m o n i t o r t h e f ir e b u t t o n o n j o y s t i c k 1 , c o m m u n i c a t e o v e r t h e s e r i a l li n e , a n d m a i n t a i n th e ti m e - o f - d a y c lo c k .
Page 372 APPENDIX I $19 Set Joystick Keycode Mode T h is c o m m a n d p u t s t h e j o y s t i c k p o r t s i n t o k e y c o d e m o d e . I n th is m o d e , t h e I K B D s e n d s c u r s o r a r r o w k e y c o d e s w h e n e v e r jo y s t i c k 0 is m o v e d f r o m t h e c e n t e r p o s i t i o n .
Page 373 The Intelligent Keyboard Controller $1A Disable Joysticks T h is c o m m a n d d i s a b le s a ll j o y s t i c k m o v e m e n t a n d j o y s tic k b u t t o n s c a n n i n g a n d r e p o r t i n g .
Page 374 APPENDIX I $1B Set Time-of-Day Clock T h is c o m m a n d s e t s t h e d a t e a n d ti m e f o r t h e i n t e r n a l t i m e - o f - d a y c lo c k . T h e v a l u e s a r e p a s s e d in p a c k e d B i n a r y C o d e d D e c im a l (B C D ) f o r m a t .
Page 375 The Intelligent Keyboard Controller $1C Interrogate Time-of-Day Clock T h is c o m m a n d c a u s e s t h e I K B D t o s e n d a p a c k e t w h i c h g i v e s i n f o r m a t i o n a b o u t t h e c u r r e n t t i m e - o f - d a y c l o c k s e t t i n g s .
Page 376 APPENDIX I $20 Memory Load T h i s c o m m a n d a l l o w s y o u t o l o a d a r b i t r a r y v a l u e s i n t o t h e 1 2 8 b y t e s o f p r o c e s s o r R A M w h i c h is f o u n d a t l o c a t i o n s $ 8 0 - $ F F o n t h e 6 3 0 1 p r o c e s s o r c h i p .
Page 377: Memory Read
The Intelligent Keyboard Controller $21 Memory Read T h is c o m m a n d a l l o w s y o u t o r e a d t h e 6 3 0 1 p r o c e s s o r R O M o r R A M , s ix b y t e s a t a ti m e .
Page 378 APPENDIX I $22 Controller Execute T h is c o m m a n d a l l o w s y o u t o e x e c u t e a 6 3 0 1 p r o c e s s o r s u b r o u t i n e f r o m a c e r t a i n p o i n t in p r o c e s s o r m e m o r y .
Page 379 The Intelligent Keyboard Controller $80 Reset T h is c o m m a n d p e r f o r m s a s i m p l e s e l f - t e s t , a n d r e t u r n s t h e k e y b o a r d c o n tr o ll e r t o it s d e f a u l t m o d e a n d p a r a m e t e r s e t t i n g s .
Page 380 APPENDIX I $87 Inquire Mouse Button Action T h is c o m m a n d c a u s e s t h e I K B D t o s e n d a p a c k e t w h i c h g i v e s i n f o r m a t i o n a b o u t w h e t h e r t h e m o u s e b u t t o n s a r e t r e a t e d lik e k e y b o a r d k e y s , a n d if, in a b s o l u t e p o s i t i o n m o d e , a b u t t o n p r e s s o r r e l e a s e w ill c a u s e a m o u s e e v e n t p a c k e t t o b e s e n t .
Page 381 The Intelligent Keyboard Controller $88, $89, $8A Inquire Mouse Mode T h is c o m m a n d c a u s e s t h e I K B D t o s e n d a p a c k e t w h i c h c o n t a i n s i n f o r m a ti o n a b o u t t h e m o u s e m o d e , a n d s e t t i n g s r e l e v a n t t o t h a t m o d e .
Page 382 APPENDIX I $8B Inquire Mouse Threshold T h i s c o m m a n d c a u s e s t h e I K B D t o s e n d a p a c k e t w h i c h c o n t a i n s i n f o r m a t i o n a b o u t t h e t h r e s h o l d v a l u e s u s e d f o r r e l a t i v e p o s i t i o n m o d e .
Page 383 The Intelligent Keyboard Controller $8C Inquire Mouse Scale T h is c o m m a n d c a u s e s t h e I K B D t o s e n d a p a c k e t w h i c h c o n t a i n s i n f o r m a ti o n a b o u t t h e s c a l e f a c t o r u s e d f o r a b s o l u t i o n p o s i t i o n m o d e .
Page 384 APPENDIX I $8F, $90 Inquire Mouse Origin T h is c o m m a n d c a u s e s t h e I K B D t o s e n d a p a c k e t w h i c h c o n t a i n s i n f o r m a ti o n a b o u t w h e t h e r t h e o r ig i n is s e t a t th e b o t t o m p o s i t i o n (in w h i c h th e m o u s e is c l o s e s t t o t h e u s e r ) o r t h e t o p p o s i t i o n (in w h i c h th e m o u s e is...
Page 385 The Intelligent Keyboard Controller $92 Inquire Mouse Enabled/Disabled T h is c o m m a n d c a u s e s t h e I K B D to s e n d a p a c k e t w h i c h c o n t a i n s i n f o r m a ti o n a b o u t w h e t h e r m o u s e s c a n n i n g a n d r e p o r t i n g is e n a b l e d o r d i s a b le d .
Page 386 APPENDIX I $94, $95, $99 Inquire Joystick Mode T h is c o m m a n d c a u s e s t h e I K B D t o s e n d a p a c k e t t h a t c o n t a i n s in f o r m a t i o n a b o u t t h e c u r r e n t j o y s t i c k m o d e .
Page 387 The Intelligent Keyboard Controller $9A Inquire Joystick Enabled/Disabled Input parameters T h is c o m m a n d c a u s e s t h e I K B D t o s e n d a p a c k e t t h a t c o n t a i n s in f o r m a t i o n a b o u t w h e t h e r m o u s e s c a n n i n g a n d r e p o r t i n g is e n a b l e d o r d i s a b le d .
Page 389: Keycodes
Appendix J Keycodes...
Page 391 The GEMDOS function Cconin(), and the BIOS function Bconin() (when used to read the console de vice keyboard), both return a two-byte keycode, which is ex tended into a longword. The first byte of the keycode, which is found in the second byte of the longword, is usually a unique key identifier that refers to the physical key that was struck, regardless of shift-key combinations.
Page 392 APPENDIX J Unshifted Shift CTRL 1600 1655 1615 1675 2F00 2F56 2F16 2F76 1157 1117 1177 1 1 0 0 2D58 2D18 2D00 2D78 1559 1519 1500 1579 2C5A 2C1A 2C00 2C7A 7800 0231 0 2 2 1 0 2 1 1 0332 0340 0300...
Page 393: Function Keys
Keycodes Unshifted Shift CTRL Up-Arrow 4800 4838 (move mouse up) 4800 Dn-Arrow 5000 5032 5000 (move mouse down) Lft-Arrow 4B00 4B34 7300 (move mouse left) Rt-Arrow 4D00 4D36 7400 (move mouse right) Numeric Pad Unshifted Shift CTRL 6328 6328 6308 6328 6429 6429...
Page 395: St Memory Map
Appendix K ST Memory Map...
Page 397 In order to maintain upward compatibility, pro grammers are cautioned to use only documented system variables, and to avoid writing directly to the hardware. All RAM below location 2048 ($800) is reserved for use by the system. This is protected memory, and may only be accessed from supervisor mode.
Page 398 APPENDIX K Table K-2. Auto-Vector Interrupts Vector Number Address Vector $070 Level 4 Interrupt: Vertical blanking sync (Vblank) $074 Level 5 Interrupt $078 Level 6 Interrupt: MK68901 MFP chip interrupts Level 7 Interrupt: Nonmaskable interrupt $07C Table K-3. TRAP Instruction Vectors Vector Number Address...
Page 399 ST Memory Map clouds equal to the exception number. TOS uses the following portion of the User Interrupt Vector space to save the processor state information when a crash occurs. This memory area is not cleared by a system reset, but may be overwritten by subsequent crashes.
Page 400 APPENDIX K etv_timer 1 0 2 4 - 1 0 2 7 ( $ 4 0 0 - $ 4 0 3 ) T i m e r tic k h a n d o f f v e c t o r (l o g ic a l v e c t o r $ 1 0 0 ) . T h e s y s t e m t i m e r i n t e r r u p t h a n d l e r (c a ll e d e v e r y 2 0 m i l l i s e c o n d s ) is u s e d t o m a i n t a i n t h e G E M D O S t i m e - o f - d a y c lo c k , d r i v e t h e X B I O S b a c k g r o u n d s o u n d r o u t i n e , h a n d l e k e y r e p e a t , a n d p e r f o r m o t h e r h o u s e k e e p i n g c h o r e s .
Page 401 ST Memory Map System Variables T h e f o llo w in g s y s t e m v a r i a b l e l o c a t i o n s a r e t h e o n l y o n e s t h a t A t a r i g u a r a n t e e s n o t t o c h a n g e b e t w e e n T O S v e r s i o n s .
Page 402 APPENDIX K __membot 1 0 7 4 - 1 0 7 7 ( $ 4 3 2 - $ 4 3 5 ) A p o i n t e r t o t h e l o w e s t a v a i la b l e m e m o r y l o c a t i o n . T h e B I O S G e t m p b ( ) f u n c t i o n u s e s th is v a l u e a s t h e s t a r t o f t h e G E M D O S T r a n s i e n t P r o g r a m A r e a ( T P A ) .
Page 403 ST Memory Map o n d . T h is is t h e v a l u e t h a t is r e t u r n e d b y t h e B I O S f u n c t i o n T i c k c a l ( ) . T h is v a l u e is a l s o p l a c e d o n t h e s t a c k b e f o r e t h e t i m e r i n t e r r u p t h a n d l e r c a lls t h e t i m e r h a n d o f f v e c t o r .
Page 404 APPENDIX K vblsem 1 1 0 6 - 1 1 0 7 < $ 4 5 2 - $ 4 5 3 ) A s e m a p h o r e f o r v e r t i c a l b l a n k i n t e r r u p t p r o c e s s i n g . A v a l u e o f 0 h e r e d i s a b l e s v b l a n k p r o c e s s i n g , w h i l e a v a l u e o f 1 e n a b l e s p r o c e s s i n g .
Page 405 ST Memory Map colorptr 1 1 1 4 - 1 1 1 7 ( $ 4 5 A - $ 4 5 D ) If th is v a l u e is n o n z e r o , t h e n a t t h e n e x t v e r t i c a l b l a n k i n t e r r u p t , th e ta b le o f 1 6 c o l o r v a l u e s t h a t s t a r t a t t h e a d d r e s s s t o r e d h e r e a r e l o a d e d i n t o t h e 1 6 c o l o r r e g i s t e r s .
Page 406 APPENDIX K hdv_rw 1142-1145 ($476-$479) T h e v e c t o r t o t h e r o u t i n e t o u s e w h e n T O S f u n c t i o n s w i s h to r e a d o r w r i t e to th e h a r d d i s k .
Page 407 ST Memory Map trpl4ret 1 1 5 8 - 1 1 6 1 ( $ 4 8 6 - $ 4 8 9 ) S a v e d t r a p 1 4 r e t u r n a d d r e s s . criticret 1 1 6 2 - 1 1 6 5 ( $ 4 8 A - $ 4 8 D )
Page 408 APPENDIX K sav__contxt 1198-1201 ($4AE-$4B1) P o i n t e r to a t e m p o r a r y b u f f e r w h e r e t h e p r o c e s s o r c o n t e x t is s a v e d . __bufl 1202-1209 ($4B2-$4B9)
Page 409 ST Memory Map __dskbufp 1 2 2 2 - 1 2 2 5 ( $ 4 C 6 - $ 4 C 9 ) P o i n t e r t o a I K d i s k b u f f e r . T h is b u f f e r is a l s o u s e d b y s o m e g r a p h i c s o p e r a t i o n s , a n d s h o u l d n o t b e u s e d b y i n t e r r u p t r o u t i n e s .
Page 410 APPENDIX K end__os 1274-1275 ($4FA-$4FD) P o i n t s t o th e f ir s t b y t e p a s t t h e l o w R A M a r e a u s e d b y T O S . T h is is u s e d f o r t h e s t a r t i n g a d d r e s s o f t h e T P A (e n d _ _ o s is c o p i e d i n t o _ _ m e m b o t ) .
Page 411: Function Index
Index by Function Name T e rm C o d e P a g e B c o n i n ( ) O p c o d e = 2 1 7 7 1 7 8 B c o n o u t ( ) O p c o d e = 3 B c o n s t a t ( ) O p c o d e = 1...
Page 412 Index by Function Name T e rm C o d e P a g e F d u p ( ) O p c o d e = 6 9 2 7 8 F f o r c e ( ) O p c o d e = 7 0 2 7 9 F g e t d t a ( )
Page 413 Index by Function Name Term Code Page P t e r m r e s ( ) O p c o d e = 4 9 2 6 5 R a n d o m ( ) O p c o d e = 1 7 2 0 9 R s c o n f ( ) O p c o d e = 1 5...
Page 415: Index
Index 68901 Multi-Function Peripheral chip. C auxout() 91 C compilers 7 ,1 2 , 30, 88 See MFP ACIA 40, 343 Cconin() 89 AES 3 C conis() 90 Alqfon C compiler 8 C con os() 91 Arbitrary Line routine 140 C conout() 91 ASCII control codes 18-19, 298 C con rs() 92-94...
Page 416 Index disk drives 20-23 GEM 3 Disk Transfer Address. See DTA Desktop program 3-4 disk, XBIOS functions 48-53 GEM Disk Operating System. See D osound() 80 GEMDOS drawing GEMDOS 4, 22, 86-108 calling from C 88 filled shapes 143-51 horizontal lines 143-44 calling from machine language 87-88 character device functions 89-94 routines 139-43...
Page 417 Index printer, setting the configuration 32 line A functions, bit block transfer oper printing ations 151-58 and line A variables 164-65 line A initialization command 137-39 from screen 45 line A routines 5, 58, 135-70 special effects 167-68 calling from C 137 text 163-68 line A variable table 136-38, 319-35 process 100...
Page 418 Index Settim e() 41 Transient Program Area. Sec TPA shiftcode, bit assignments 15 TRAP instruction vectors 390 skewing 167 Tsettim e() 107 snapshot program 46 TSR programs 104 software blit routines 58 software sprites 5 user interrupt vectors 390 source blocks 153-54 user mode 29, 57 speed parameter 34 sprite operations 158-60...
Page 420 With this book, noted author and programmer Sheldon Leemon completes COMPUTEI’ s series of comprehensive ref erence guides to the inner workings of the Atari ST. Here's a list of just some of the topics covered inside: • The Basic Input/Output System (BIOS) •...

Atari ST series Technical Reference Manual

Quick Links

Related Manuals for Atari ST series

Summary of Contents for Atari ST series

Table of Contents