XBIOS Reference, Master

XBIOS Function Reference

Bconmap()

LONG Bconmap( devno )

WORD devno;

	Bconmap() maps a serial device to BIOS device #1. It is also used to add serial device drivers to the system.

Opcode	44 (0x2C)

Availability	To reliably check that Bconmap() is supported, the TOS version must be 1.02 or higher and the following function should return a TRUE value. #define BMAP_EXISTS 0 BOOL IsBconmap( VOID ) { return (Bconmap(0) == BMAP_EXISTS); }

Parameters	The value of devno has the following effect:

	Name	devno	Meaning
	BMAP_CHECK	0	Verify the existence of the call (systems without Bconmap() will return the function opcode 44).
	-	1-5	These are illegal values (will return 0).
	See XBIOS* Serial Port Mapping for constants*.	6-	Redefine BIOS device 1 (the GEMDOS 'aux:' device) to map to the named serial device. All Bcon...(1,...), Rsconf(), and Iorec() calls will return information for the named device. Returns the old value.
	BMAP_INQUIRE	-1	Don't change anything, simply return the old value.
	BMAP_MAPTAB	-2	Return a pointer to the serial device vector table (see below).

Binding	move.w devno,-(sp) move.w #$2C,-(sp) trap #14 addq.l #4,sp

Return Value	See above.

Caveats	You should never install the 38th device (BIOS device number 44). It would be indistinguishable from the case where Bconmap() was unavailable. In the unlikely event that this case arises, you should install two new devices and assign your new device to the second one. All current versions of Falcon030 TOS (4.00 - 4.04) contain a bug that prevents the BIOS from accessing the extra available devices. A patch program named FPATCH2.PRG is available from Atari Corporation to correct this bug in software.

Comments	To add a serial device to the table, use Bconmap(-2) to return a pointer to a BCONMAP structure. maptab points to a list of MAPTAB structures (the first entry in MAPTAB is the table for device number 6). The list will contain maptabsize devices. Allocate a block of memory large enough to store the old table plus your new entry and copy the old table and your new device structure there making sure to increment maptabsize. Finally, alter maptab to point to your new structure. typedef struct { WORD (Bconstat)(); LONG (Bconin)(); LONG (Bcostat)(); VOID (Bconout)(); ULONG (Rsconf)(); IOREC iorec; /* See Iorec() / } MAPTAB; typedef struct { MAPTAB maptab; WORD maptabsize; } BCONMAP;

See Also	Bconin(), Bconout(), Rsconf(), Iorec()

Bioskeys()

VOID Bioskeys( VOID )

	Bioskeys() is used to reset to the power-up defaults of the keyboard configuration tables.

Opcode	24 (0x18)

Availability	All TOS versions.

Binding	move.w #$18,-(sp) trap #14 addq.l #2,sp

Comments	This call is only necessary to restore changes made by modifying the tables given by Keytbl().

See Also	Keytbl()

Blitmode()

WORD Blitmode( mode )

WORD mode;

	Blitmode() detects a hardware BLiTTER chip and can alter its configuration if present.

Opcode	64 (0x40)

Availability	This call is available as of TOS 1.02.

Parameters	mode is used to set the BLiTTER configuration. If mode is BLIT_INQUIRE (1), the call will return the current state of the BLiTTER without modifying its state. To change the method of OS blit operations, call Blitmode() with one of the following values:

	Name	mode	Meaning
	BLIT_SOFT	0	If set, use hardware BLiTTER chip, otherwise use software routines.
	BLIT_HARD	1	If set, hardware BLiTTER chip is available.

Binding	move.w mode,-(sp) move.w #$40,-(sp) trap #14 addq.l #4,sp

Return Value	Blitmode() returns the old mode value. Bit #0 of mode contains the currently set blitter mode as shown above. Bit #1 is set to indicate the presence of a hardware blitter chip or clear if no blitter chip is installed.

Comments	You should use this call once to verify the existence of the BLiTTER prior to attempting to change its configuration.

Buffoper()

LONG Buffoper( mode )

WORD mode;

	Buffoper() sets/reads the state of the hardware sound system.

Opcode	136 (0x88)

Availability	Available if '_SND' cookie has third bit set.

Parameters	mode is a bit array which may be composed of all or none of the following flags indicating the desired sound system state as follows:

	Name	Bit Mask	Meaning
	PLAY_ENABLE	0x01	Enable DMA Sound Playback. The sound must have been previously identified to the XBIOS with the Buffptr() function.
	PLAY_REPEAT	0x02	Setting this flag will cause any sound currently playing or started as a result of this call to be looped indefinitely (until Buffoper(0) is used).
	RECORD_ENABLE	0x04	Enable DMA Sound Recording. The sound must have been previously identified to the XBIOS with the Buffptr() function.
	RECORD_REPEAT	0x08	Setting this flag during a record will cause the recording to continue indefinitely within the currently set recording buffer (as set by Buffptr())

	Alternately, calling this function with a mode parameter of SND_INQUIRE (1) will return a bit mask indicating the current sound system state as shown above.

Binding	move.w mode,-(sp) move.w #$88,-(sp) trap #14 addq.l #4,sp

Return Value	Buffoper() normally returns 0 for no error or non-zero otherwise (except in inquire mode as indicated above.

Comments	The sound system uses a 32 bit FIFO. The FIFO is only guaranteed to be clear when the record enable bit is clear. When transferring new data to the record buffers, the record enable bit should be cleared to flush the FIFO.

See Also	Setbuffer()

Buffptr()

LONG Buffptr( sptr )

SBUFPTR *sptr;

	Buffptr() returns the current position of the playback and record pointers.

Opcode	141 (0x8D)

Availability	Available if '_SND' cookie has third bit set.

Parameter	sptr is a pointer to a SBUFPTR structure which is filled in with the current pointer values. SBUFPTR is defined as follows: typedef struct { VOIDP playptr; VOIDP recordptr; VOIDP reserved1; VOIDP reserved2; } SBUFPTR;

Binding	pea sptr move.w #$8d,-(sp) trap #14 addq.l #6,sp

Return Value	Buffptr() returns 0 if the operation was successful or non-zero otherwise.

See Also	Setbuffer(), Buffoper()

Cursconf()

WORD Cursconf( mode, rate )

WORD mode, rate;

	Cursconf() configures the VT-52 cursor.

Opcode	21 (0x15)

Availability	All TOS versions.

Parameters	mode defines the operation as follows:

		Name	mode	Meaning
		CURS_HIDE	0	Hide cursor.
		CURS_SHOW	1	Show cursor.
		CURS_BLINK	2	Enable cursor blink.
		CURS_NOBLINK	3	Disable cursor blink.
		CURS_SETRATE	4	Set blink rate to rate.
		CURS_GETRATE	5	Return current blink rate.

Binding	move.w rate,-(sp) move.w mode,-(sp) move.w #$15,-(sp) trap #14 addq.l #6,sp

Return Value	Cursconf() only returns a meaningful value under mode 5 in which it returns the current blink rate.

Comments	The blink rate is specified in number of vertical blanks per blink.

Dbmsg()

VOID Dbmsg( rsrvd, msg_num, msg_arg )

WORD rsrvd, msg_num;

LONG msg_arg;

	Dbmsg() allows special debugging messages to be sent to a resident debugger application.

Opcode	11 (0x0B)

Availability	The only debugger that currently supports this call is the Atari Debugger.

Parameters	rsrvd is currently reserved and should always be 5. msg_num is the message number which you want to send to the debugging host. Values of 0x0000 to 0xEFFF are reserved for applications to define. Values of 0xF000 to 0xFFFF are reserved for special debugging messages.If msg_num is in the application defined range, it and the LONG contained in msg_arg will be displayed by the debugger and the application will be halted.If msg_num is between 0xF001 and 0xF0FF inclusive then msg_arg is interpreted as a character pointer pointing to a string to be output by the debugger and debugging to halt. The string length is determined by the low byte of msg_num. If msg_num is DB_NULLSTRING (0xF000), the string will be output until a NULL is reached.If msg_num is DB_COMMAND (0xF100), msg_arg is interpreted as a character pointer to a string containing a debugger command. The command format is specific to the debugger which you are running.A useful example of this format when running under the Atari debugger allows a string to be output to the debugger without terminating debugging as shown in the following example: Dbmsg( 5, DB_COMMAND, "echo 'Debugging Message';g" );

Binding	move.l msg_arg,-(sp) move.w msg_num,-(sp) move.w #$5,-(sp) move.w #$0B,-(sp) trap #14 lea 10(sp),sp

Comments	The Atari Debugger only understands the value DB_COMMAND (0xF100) for msg_num as of version 3.Though it is normally harmless to run an application with embedded debugging messages when no debugger is present in the system, distribution versions of applications should have these instructions removed.

Devconnect()

LONG Devconnect( source, dest, clk, prescale, protocol )

WORD source, dest, clk, prescale, protocol;

	Devconnect() attaches a source device in the sound system to one or multiple destination devices through the use of the connection matrix.

Opcode	139 (0x8B)

Availability	Available if '_SND' cookie has third bit set.

Parameters	source indicates the source device to connect as follows:

		Name	source		Meaning
		DMAPLAY	0		DMA Playback
		DSPXMIT	1		DSP Transmit
		EXTINP	2		External Input
		ADC	3		Microphone/Yamaha PSG

	dest is a bit mask which is used to choose which destination devices to connect as follows:

		Name	Mask			Meaning
		DMAREC	0x01			DMA Record
		DSPRECV	0x02			DSP Receive
		EXTOUT	0x04			External Out
		DAC	0x08			DAC (Headphone or Internal Speaker)

	clk is the clock the source device will use as follows:

		Name	clk			Meaning
		CLK_25M	0			Internal 25.175 MHz clock
		CLK_EXT	1			External clock
		CLK_32M	2			Internal 32 MHz clock

	prescale chooses the source clock prescaler. Sample rate is determined by the formula: Valid prescaler values for the internal CODEC using the 25.175 MHz clock are:

		Name		prescale			Meaning/Sample Rate
		CLK_COMPAT		0			TT030/STe compatiblity mode. Use prescale value set with Soundcmd().
		CLK_50K		1			49170 Hz
		CLK_33K		2			32880 Hz
		CLK_25K		3			24585 Hz
		CLK_20K		4			19668 Hz
		CLK_16K		5			16390 Hz
		CLK_12K		7			12292 Hz
		CLK_10K		9			9834 Hz
		CLK_8K		11			8195 Hz

	protocol sets the handshaking mode. A value of HANDSHAKE (0) enables handshaking, NO_SHAKE (1) disables it. When transferring sound or video data through the CODEC it is usually recommended that handshaking be disabled. When incoming data must be 100% error free, however, handshaking should be enabled.

Binding	move.w protocol,-(sp) move.w prescale,-(sp) move.w clk,-(sp) move.w dest,-(sp) move.w source,-(sp) move.w #$8B,-(sp) trap #14 lea 12(sp),sp

Return Value	Devconnect() returns 0 if the operation was successful or non-zero otherwise.

Caveats	Setting the prescaler to an invalid value will result in a mute condition.

See Also	Soundcmd()

DMAread()

LONG DMAread( sector, count, buf, dev )

LONG sector;

WORD count;

VOIDP buf;

WORD dev;

	DMAread() reads raw sectors from a ACSI or SCSI device.

Opcode	42 (0x2A)

Availability	This call is available as of TOS version 2.00.

Parameters	sector specifies the sector number to begin reading at. count specifies the number of sectors to read. buf is a pointer to the address where incoming data will be stored. dev specifies the device to read from as follows:

		dev	Meaning
		0-7	ACSI devices 0-7
		8-15	SCSI devices 0-7

Binding	move.w dev,-(sp) pea buf move.w count,-(sp) move.l sector,-(sp) move.w #$2A,-(sp) trap #14 lea 14(sp),sp

Return Value	DMAread() returns 0 if the operation was successful or a negative BIOS error code otherwise.

Caveats	SCSI devices will write data until the device exits its data transfer phase. Since this call is not dependent on sector size, you should ensure that the buffer is large enough to hold sectors from devices with large sectors (CD-ROM = 2K, for example).

Comments	ACSI transfers must be done to normal RAM. If you need to read sectors into alternative RAM, use the 64KB pointer found with the '_FRB' cookie as an intermediate transfer point while correctly managing the '_flock' system variable.SCSI transfers on the TT030 do not actually use DMA. Handshaking is used to transfer bytes individually. This means that alternative RAM may be used. The Falcon030 uses DMA for SCSI transfers making transfers to alternative RAM illegal.

See Also	DMAwrite(), Rwabs()

DMAwrite()

LONG DMAwrite( sector, count, buf, dev )

LONG sector;

WORD count;

VOIDP buf;

WORD dev;

	DMAwrite() writes raw sectors to ACSI or SCSI devices.

Opcode	43 (0x2B)

Availability	TOS versions >= 2.00

Parameters	sector is the starting sector number to write data to. count is the number of sectors to write. buf defines the starting address of the data to write. dev is the device number as specified in DMAread().

Binding	move.w dev,-(sp) pea buf move.w count,-(sp) move.l sector,-(sp) move.w #$2B,-(sp) trap #14 lea 14(sp),sp

Return Value	DMAwrite() returns 0 if successful or a negative BIOS error code otherwise.

Comments	ACSI transfers must be done from normal RAM. If you need to read sectors into alternative RAM, use the 64KB pointer found with the '_FRB' cookie as an intermediate transfer point while correctly managing the '_flock' system variable.SCSI transfers do not actually use DMA. Handshaking is used to transfer bytes individually.

See Also	DMAread(), Rwabs()

Dosound()

VOID Dosound( cmdlist )

char *cmdlist;

	Dosound() initializes and starts an interrupt driven sound playback routine using the PSG.

Opcode	32 (0x20)

Availability	All TOS versions.

Parameters	If cmdlist is positive, it will be interpreted as a pointer to a character array containing a sequential list of commands required for the sound playback. Each command is executed in order and has a meaning as follows:

	Command Byte	Meaning
	0x00 - 0x0F	Select a PSG register (the register number is the command byte). The next byte in the list will be loaded into this register. See Appendix I for a detailed listing of registers, musical frequencies, and sound durations.
	0x80	Store the next byte in a temporary register for use by command 0x81.
	0x81	Three bytes follow this command. The first is the PSG register to load with the value in the temporary register (set with command 0x80). The second is a signed value to add to the temporary register until the value in the third byte is met.
	0x82	If a 0 follows this command, this signals the end of processing, otherwise the value indicates the number of 50Hz ticks to wait until the processing of the next command.

	Passing the value DS_INQUIRE (1) for cmdlist will cause the pointer to the current sound buffer to be returned or NULL if no sound is currently playing.

Binding	pea cmdlist move.w #$20,-(sp) trap #14 addq.l #6,sp

Caveats	This routine is driven by interrupts. Do not use an array created on the stack to store the command list that may go out of scope before the sound is complete.This function will cause the OS to crash under MultiTOS versions prior to 1.08 if every running application is not set to 'Supervisor' or 'Global' memory protection.Dosound( DS_INQUIRE ) will cause the OS to crash under MultiTOS versions 1.08 and below.

Dsp_Available()

VOID Dsp_Available( xavail, yavail )

LONG *xavail, *yavail;

	Dsp_Available() returns the amount of free program space in X and Y DSP memory.

Opcode	106 (0x6A)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	Upon return, the longwords pointed to by xavail and yavail will contain the length of memory (in bytes) available for DSP programs and subroutines.

Binding	pea yavail pea xavail move.w #$6A,-(sp) trap #14 lea 10(sp),sp

See Also	Dsp_Reserve()

Dsp_BlkBytes()

VOID Dsp_BlkBytes( data_in, size_in, data_out, size_out )

UBYTE *data_in;

LONG size_in;

UBYTE *data_out;

LONG size_out;

	Dsp_BlkBytes() transfers a block of unsigned character data to the DSP and returns the output from the running program or subroutine.

Opcode	124 (0x7C)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	data_in is a pointer to an unsigned character array which is transferred to the DSP. size_in is the length (in bytes) of data to transfer.data_out is a pointer to the unsigned character array to be filled in from the low byte of the DSP's transfer register. size_out is the length (in bytes) of the output buffer array.

Binding	move.l size_out,-(sp) pea data_out move.l size_in,-(sp) pea data_in move.w #$7C,-(sp) trap #14 lea 18(sp),sp

Caveats	No handshaking is performed with this call. Error sensitive data should be transferred with Dsp_BlkHandShake().

Comments	Bytes are not sign extended before transfer. Also, due to the length of static memory in the DSP, size_in and size_out should not exceed 65536.

See Also	Dsp_BlkWords()

Dsp_BlkHandShake

VOID Dsp_BlkHandShake( data_in, size_in, data_out, size_out )

char *data_in;

LONG size_in;

char *data_out;

LONG size_out;

	Dsp_BlkHandShake() handshakes a block of bytes to the DSP and returns the output generated by the running subroutine or program.

Opcode	97 (0x61)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	data_in is a pointer to data being sent to the DSP. size_in specifies the number of DSP words of data to be transferred. Dsp_GetWordSize() can be used to determine the number of bytes that occur for a DSP word.data_out is a pointer to the buffer to which processed data will be returned from the DSP. size_out indicates the number of DSP words to transfer.

Binding	move.l size_out,-(sp) pea data_out move.l size_in,-(sp) pea data_in move.w #$61,-(sp) trap #14 lea 18(sp),sp

Comments	Dsp_BlkHandshake() is identical to Dsp_DoBlock(), however, this function handshakes each byte to prevent errors in sensitive data.

See Also	Dsp_DoBlock()

Dsp_BlkUnpacked()

VOID Dsp_BlkUnpacked( data_in, size_in, data_out, size_out )

LONG *data_in;

LONG size_in;

LONG *data_out;

LONG size_out;

	Dsp_BlkUnpacked() transfers data to the DSP from a longword array. Data processed by the running subroutine or program is returned.

Opcode	98 (0x62)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	data_in is a pointer to an array of LONGs from which data is transferred to the DSP. As many bytes are transferred from each LONG as there are bytes in a DSP WORD. For example, if Dsp_GetWordSize() returns 3, the lower three bytes of each LONG are transferred into each DSP WORD.size_in represents the number of LONGs in the array to transfer. data_out is a pointer to an array of LONGs size_out in length in which data sent from the DSP is returned.

Binding	move.l size_out,-(sp) pea data_out move.l size_in,-(sp) pea data_in move.w #$62,-(sp) trap #14 lea 18(sp),sp

Caveats	This function only works with DSP's which return 4 or less from Dsp_GetWordSize(). In addition, no handshaking is performed with this call. Data which is sensitive to errors should use Dsp_BlkHandShake().

See Also	Dsp_DoBlock()

Dsp_BlkWords()

VOID Dsp_BlkWords( data_in, size_in, data_out, size_out )

WORD *data_in;

LONG size_in;

WORD *data_out;

LONG size_out;

	Dsp_BlkWords() transfers an array of WORDs to the DSP and returns the output generated by the running subroutine or program.

Opcode	123 (0x7B)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	data_in is a pointer to the WORD array to be transferred to the DSP. size_in is the length (in WORDs) of data to transfer.data_out is a pointer to the WORD array to be filled in during the data output phase of the DSP from the middle and low bytes of the transfer register. size_out is the length (in WORDs) of the buffer for the output array.

Binding	move.l size_out,-(sp) pea data_out move.l size_in,-(sp) pea data_in move.w #$7B,-(sp) trap #14 lea 18(sp),sp

Caveats	No handshaking is performed with this call. Data which is sensitive to errors should use Dsp_BlkHandShake().

Comments	WORDs are sign extended before transfer. Also, due to the length of static memory in the DSP, size_in and size_out should not exceed 32768.

See Also	Dsp_BlkBytes()

Dsp_DoBlock()

VOID Dsp_DoBlock( data_in, size_in, data_out, size_out )

char *data_in;

LONG size_in;

char *data_out;

LONG size_out;

	Dsp_DoBlock() transfers bytewise packed data to the DSP and returns the data processed by the running subroutine or program.

Opcode	96 (0x60)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	data_in is a character array containing data to transfer to the DSP. size_in specifies the number of DSP words to transfer. For example, if Dsp_GetWordSize() returns 3, the first 3 bytes from data_in are stored in the first DSP word, the next 3 bytes are stored in the next DSP word and so on. data_out points to a character array where the output will be stored in a similar manner. size_out represents the size of this array.

Binding	move.l size_out,-(sp) pea data_out move.l size_in,-(sp) pea data_in move.w #$60,-(sp) trap #14 lea 18(sp),sp

Caveats	No handshaking is performed with this call. Data which is sensitive to errors should use Dsp_BlkHandShake().

See Also	Dsp_BlkHandShake()

Dsp_ExecBoot()

VOID Dsp_ExecBoot( codeptr, codesize, ability )

char *codeptr;

LONG codesize;

WORD ability;

	Dsp_ExecBoot() completely resets the DSP and loads a new bootstrap program into the first 512 DSP words of memory.

Opcode	110 (0x6E)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	codeptr points to the beginning of the DSP program data to be transferred. codesize indicates the size (in DSP words) of program data to transfer. ability indicates the bootstrapper's unique ability code.

Binding	move.w ability,-(sp) move.l codesize,-(sp) pea codeptr move.w #$6E,-(sp) trap #14 lea 12(sp),sp

Comments	This call is only designed for special development and testing purposes. Use of this call takes over control of the DSP system. This call is limited to transferring up to 512 DSP words of code.

See Also	Dsp_LoadProg(), Dsp_ExecProg()

Dsp_ExecProg()

VOID Dsp_ExecProg( codeptr, codesize, ability )

char *codeptr;

LONG codesize;

WORD ability;

	Dsp_ExecProg() transfers a DSP program stored in binary format in memory to the DSP and executes it.

Opcode	109 (0x6D)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	codeptr points to the start of the binary program in memory. codesize indicates the number of DSP words to transfer. ability indicates the program's unique ability code.

Binding	move.w ability,-(sp) move.l codesize,-(sp) pea codeptr move.w #$6D,-(sp) trap #14 lea 12(sp),sp

Comments	codesize should not exceed the amount of memory reserved by the Dsp_Reserve() call.

See Also	Dsp_LoadProg(), Dsp_Reserve()

Dsp_FlushSubroutines()

VOID Dsp_FlushSubroutines( VOID )

	Dsp_FlushSubroutines() removes all subroutines from the DSP.

Opcode	115 (0x73)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Binding	move.w #$73,-(sp) trap #14 addq.l #2,sp

Comments	This call should only be used when a program requires more memory than is returned by Dsp_Available().

See Also	Dsp_Available()

Dsp_GetProgAbility()

WORD Dsp_GetProgAbility( VOID )

	Dsp_GetProgAbility() returns the current ability code for the program currently residing in DSP memory.

Opcode	114 (0x72)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Binding	move.w #$72,-(sp) trap #14 addq.l #2,sp

Return Value	Dsp_GetProgAbility() returns the WORD ability code for the current program loaded in the DSP.

Comments	If you know the defined ability code of the program you wish to use, you can use this call to see if the program already exists on the DSP and avoid reloading it.

See Also	Dsp_InqSubrAbility()

Dsp_GetWordSize()

WORD Dsp_GetWordSize( VOID )

	Dsp_GetWordSize() returns the size of a DSP word in the installed Digital Signal Processor.

Opcode	103 (0x67)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Binding	move.w #$67,-(sp) trap #14 addq.l #4,sp

Return Value	Dsp_GetWordSize() returns the number of bytes per DSP word.

Comments	This value is useful with many DSP-related XBIOS calls to provide upward compatibility as the DSP hardware is not guaranteed to remain the same.

Dsp_Hf0()

WORD Dsp_Hf0( flag )

WORD flag;

	Dsp_Hf0() reads/writes to bit #3 of the HSR.

Opcode	119 (0x77)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	flag has three legal values as follows:

	Name	flag	Meaning
	HF_CLEAR	0	Clear bit #3 of the DSP's HSR.
	HF_SET	1	Set bit #3 of the DSP's HSR.
	HF_INQUIRE	-1	Return the current value of bit #3 of the DSP's HSR.

Binding	move.w flag,-(sp) move.w #$77,-(sp) trap #14 addq.l #4,sp

Return Value	If flag is HF_INQUIRE (1), Dsp_Hf0() returns the current state of bit #3 of the HSR register.

See Also	Dsp_Hf1()

Dsp_Hf1()

WORD Dsp_Hf1( flag )

WORD flag;

	Dsp_Hf1() reads/writes to bit #4 of the HSR.

Opcode	120 (0x78)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	flag has three legal values as follows:

	Name	flag	Meaning
	HF_CLEAR	0	Clear bit #4 of the DSP's HSR.
	HF_SET	1	Set bit #4 of the DSP's HSR.
	HF_INQUIRE	-1	Return the current value of bit #4 of the DSP's HSR.

Binding	move.w flag,-(sp) move.w #$78,-(sp) trap #14 addq.l #4,sp

Return Value	If flag is HF_INQUIRE (1), Dsp_Hf1() returns the current state of bit #4 of the HSR register.

See Also	Dsp_Hf0()

Dsp_Hf2()

WORD Dsp_Hf2( VOID )

	Dsp_Hf2() returns the current status of bit #3 of the DSP's HCR.

Opcode	121 (0x79)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Binding	move.w #$79,-(sp) trap #14 addq.l #2,sp

Return Value	Dsp_Hf2() returns the current setting of bit #3 of the HCR register (valid values are 0 or 1).

See Also	Dsp_Hf3()

Dsp_Hf3()

WORD Dsp_Hf3( VOID )

	Dsp_Hf3() returns the current status of bit #4 of the DSP's HCR.

Opcode	122 (0x7A)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Binding	move.w #$7A,-(sp) trap #14 addq.l #2,sp

Return Value	Dsp_Hf3() returns the current setting of bit #4 of the HCR register (valid values are 0 or 1).

See Also	Dsp_Hf2()

Dsp_HStat()

BYTE Dsp_Hstat( VOID )

	Dsp_HStat() returns the value of the DSP's ICR register.

Opcode	125 (0x7D)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Binding	move.w #$7D,-(sp) trap #14 addq.l #2,sp

Return Value	Dsp_Hstat() returns an 8-bit value representing the current state of the DSP's ICR register as follows:

		Name	Bit	Meaning
		ICR_RXDF	0	ISR Receive data register full (RXDF)
		ICR_TXDE	1	ISR Transmit data register empty (TXDE)
		ICR_TRDY	2	ISR Transmitter ready (TRDY)
		ICR_HF2	3	ISR Host flag 2 (HF2)
		ICR_HF3	4	ISR Host flag 3 (HF3)
		-	5	Reserved
		ICR_DMA	6	ISR DMA Status (DMA)
		ICR_HREQ	7	ISR Host Request (HREQ)

Dsp_InqSubrAbility()

WORD Dsp_InqSubrAbility( ability )

WORD ability;

	Dsp_InqSubrAbility() determines if a subroutine with the specified ability code exists in the DSP.

Opcode	117 (0x75)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	ability is the ability code you wish to check.

Binding	move.w ability,-(sp) move.w #$75,-(sp) trap #14 addq.l #2,sp

Return Value	Dsp_InqSubrAbility() returns a handle to the subroutine if found or 0 if not.

See Also	Dsp_RunSubroutine()

Dsp_InStream()

VOID Dsp_InStream( data_in, block_size, num_blocks, blocks_done )

char *data_in;

LONG block_size;

LONG num_blocks;

LONG *blocks_done;

	Dsp_InStream() passes data to the DSP via an interrupt handler.

Opcode	99 (0x63)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	data_in is a pointer to unsigned character data which should be transferred to the DSP. block_size indicates the number of DSP WORDs that will be transferred at each interrupt. num_blocks indicates the number of blocks to transfer.The LONG pointed to by blocks_done will be constantly updated to let the application know the progress of the transfer.

Binding	pea blocks_done move.l num_blocks,-(sp) move.l block_size,-(sp) pea data_in move.w #$63,-(sp) trap #14 lea 18(sp),sp

Caveats	No handshaking is performed with this call. If the data you are transmitting is error sensitive, use Dsp_BlkHandShake().

Comments	This call is suited for transferring small blocks while other blocks are being prepared for transfer. For larger blocks, Dsp_DoBlock() would be more suitable.

See Also	Dsp_BlkHandShake(), Dsp_DoBlock()

Dsp_IOStream()

VOID Dsp_IOStream( data_in, data_out, block_insize, block_outsize, num_blocks, blocks_done )

char *data_in, *data_out;

LONG block_insize, block_outsize, num_blocks;

LONG *blocks_done;

	Dsp_IOStream() uses two interrupt handlers to transmit and receive data from the DSP.

Opcode	101 (0x65)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	data_in is a pointer to a buffer in which each output block is placed. data_out is a pointer to a buffer used to receive each data block from the DSP.block_insize and block_outsize represent the size of the blocks to send and receive, respectively, in DSP WORDs. num_blocks is the total number of blocks to transfer.The LONG pointed at by blocks_done is constantly updated to indicate the number of blocks actually transferred.

Binding	pea blocks_done move.l num_blocks,-(sp) move.l block_outsize,-(sp) move.l block_insize,-(sp) pea data_out pea data_in move.w #$65,-(sp) trap #14 lea 26(sp),sp

Caveats	This call makes the assumption that the DSP will be ready to accept a new block as input every time it finishes sending a block back to the host.

Comments	No handshaking is performed with this call. If your data is error-sensitive, you should use Dsp_BlkHandShake().

See Also	Dsp_InStream(), Dsp_OutStream()

Dsp_LoadProg()

WORD Dsp_LoadProg( file, ability, buf )

char *file;

WORD ability;

char *buf;

	Dsp_LoadProg() loads a '.LOD' file from disk, transmits it to the DSP, and executes it.

Opcode	108 (0x6C)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	file is a pointer to a NULL-terminated string containing a valid GEMDOS file specification. ability is the unique ability code that will be assigned to this program. buf should point to a temporary buffer where the DSP will place the binary code it generates. The minimum size of the buffer is determined by the following formula: 3 * ( #program/data words + (3 * #blocks in program))

Binding	pea buf move.w ability,-(sp) pea file move.w #$6C,-(sp) trap #14 lea 12(sp),sp

Return Value	Dsp_LoadProg() returns a 0 is successful or -1 otherwise.

Comments	Before loading you should determine if a program already exists on the DSP with your chosen ability with Dsp_GetProgAbility().

See Also	Dsp_LoadSubroutine()

Dsp_LoadSubroutine()

WORD Dsp_LoadSubroutine( ptr, size, ability )

char *ptr;

LONG size;

WORD ability;

	Dsp_LoadSubroutine() transmits subroutine code to the DSP.

Opcode	116 (0x74)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	ptr points to a memory buffer which contains DSP binary subroutine code. size is the length of code to transfer (specified in DSP words). ability is the WORD identifier for the unique ability of this subroutine.

Binding	move.w ability,-(sp) move.l size,-(sp) pea ptr move.w #$74,-(sp) trap #14 lea 12(sp),sp

Return Value	Dsp_LoadSubroutine() returns the handle assigned to the subroutine or 0 if an error occurred.

Comments	DSP subroutines have many restrictions and you should see the previous discussion of the DSP for more information.

See Also	Dsp_RunSubroutine(), Dsp_InqSubrAbility()

Dsp_Lock()

WORD Dsp_Lock( VOID )

	Dsp_Lock() locks the use of the DSP to the calling application.

Opcode	104 (0x68)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Binding	move.w #$68,-(sp) trap #14 addq.l #2,sp

Return Value	Dsp_Lock() returns a 0 if successful or -1 if the DSP has been locked by another application.

Comments	Dsp_Lock() should be performed before each use of the DSP to prevent other applications from modifying DSP memory or flushing subroutines. A corresponding Dsp_Unlock() should be issued at the end of each usage. You should limit the amount of time the DSP is locked so other applications may utilize it.

See Also	Dsp_Unlock()

Dsp_LodToBinary()

LONG Dsp_LodToBinary( file, codeptr )

char *file,*codeptr;

	Dsp_LodToBinary() reads a '.LOD' file and converts the ASCII data to binary program code ready to be sent to the DSP via Dsp_ExecProg() or Dsp_ExecBoot().

Opcode	111 (0x6F)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	file is a character pointer to a null-terminated GEMDOS file specification. codeptr should point to a large enough buffer to hold the resulting binary program code.

Binding	pea codeptr pea file move.w #$6F,-(sp) trap #14 lea 10(sp),sp

Return Value	Dsp_LodToBinary() returns the size of the resulting program code in DSP words or a negative error code.

See Also	Dsp_ExecProg(), Dsp_LoadProg()

Dsp_MultBlocks()

VOID Dsp_MultBlocks( numsend, numreceive, sendblks, receiveblks )

LONG numsend, numreceive;

DSPBLOCK *sendblks, *receiveblks;

	Dsp_MultBlocks() transmit and receive multiple blocks of DSP data of varying size.

Opcode	127 (0x7F)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	numsend and numreceive indicate the number of blocks of DSP data to send and receive respectively. sendblks and receiveblks are both pointers to arrays of type DSPBLOCK which contain information for each block. DSPBLOCK is defined as follows: typedef struct { #define BLOCK_LONG 0 #define BLOCK_WORD 1 #define BLOCK_UBYTE 2 /* 0 = LONGs, 1 = WORDs, 2 = UBYTEs / WORD blocktype; / Num elements in block / LONG blocksize; / Start address of block */ VOIDP blockaddr; } DSPBLOCK;

Binding	pea receiveblks pea sendblks move.l numreceive,-(sp) move.l numsend,-(sp) move.w #$7F,-(sp) trap #14 lea 18(sp),sp

Caveats	No handshaking is performed with this call. To transfer blocks with handshaking use Dsp_BlkHandShake().

Dsp_OutStream()

VOID Dsp_OutStream( data_out, block_size, num_blocks, blocks_done )

char *data_out;

LONG block_size;

LONG num_blocks;

LONG *blocks_done;

	Dsp_OutStream() transfers data from the DSP to a user-specified buffer using interrupts.

Opcode	100 (0x64)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	This call transfers data from the DSP to the buffer pointed to by data_out via an interrupt handler. block_size specifies the number of DSP WORDs to be transferred and num_blocks specifies the number of blocks to transfer.The LONG pointed to by blocks_done will be constantly updated by the interrupt handler to indicate the number of blocks successfully transferred. The process is complete when blocks_done is equal to num_blocks.

Binding	pea blocks_done move.l num_blocks,-(sp) move.l block_size,-(sp) pea data_out move.w #$64,-(sp) trap #1 lea 18(sp),sp

See Also	Dsp_DoBlock(), Dsp_MultBlocks(), Dsp_InStream()

Dsp_RemoveInterrupts()

VOID Dsp_RemoveInterrupts( mask )

WORD mask;

	Dsp_RemoveInterrupts() turns off the generation of DSP interrupts.

Opcode	102 (0x66)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	mask is an WORD bit mask indicating which interrupts to turn off composed of one or both of the following values:

		Name	Mask	Meaning
		RTS_OFF	0x01	Disable DSP Ready to Send Interrupts
		RTR_OFF	0x02	Disable DSP Ready to Receive Interrupts

Binding	move.w mask,-(sp) move.w #$66,-(sp) trap #14 addq.l #4,sp

Comments	This call is used to terminate interrupts when an interrupt driven block transfer function does not terminate as expected (this will occur when less than the expected number of blocks is returned) and to shut off interrupts installed by Dsp_SetVectors().

See Also	Dsp_SetVectors()

Dsp_RequestUniqueAbility()

WORD Dsp_RequestUniqueAbility( VOID )

	Dsp_RequestUniqueAbility() generates a random ability code that is currently not in use.

Opcode	113 (0x71)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Binding	move.w #$71,-(sp) trap #14 addq.l #2,sp

Return Value	Dsp_RequestUniqueAbility() returns a unique ability code to assign to a subroutine or program.

Comments	Using this function allows you to call Dsp_InqSubrAbility() and Dsp_GetProgAbility() to determine if the DSP code your application has already loaded is still present (i.e. has not been flushed by another application).

See Also	DspInqSubrAbility(), Dsp_GetProgAbility()

Dsp_Reserve()

WORD Dsp_Reserve( xreserve, yreserve )

LONG xreserve, yreserve;

	Dsp_Reserve() reserves DSP memory for program usage.

Opcode	107 (0x6B)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	xreserve and yreserve specify the amount of memory (in DSP words) to reserve for a DSP program in X and Y memory space respectively. xreserve and yreserve must include all program/data space so that subroutines do not overwrite your reserved area.

Binding	move.l yreserve,-(sp) move.l xreserve,-(sp) move.w #$6B,-(sp) trap #14 lea 10(sp),sp

Return Value	Dsp_Reserve() returns a 0 if the memory was reserved successfully or -1 if not enough DSP memory was available.

Comments	If this call fails you should call Dsp_FlushSubroutines() and then retry it. If it fails a second time, the DSP lacks enough memory space to run your program.

Dsp_RunSubroutine()

WORD Dsp_RunSubroutine( handle )

WORD handle;

	Dsp_RunSubroutine() begins execution of the specified subroutine.

Opcode	118 (0x76)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	handle is the WORD identifier of the DSP subroutine to engage.

Binding	move.w handle,-(sp) move.w #$76,-(sp) trap #14 addq.l #4,sp

Return Value	Dsp_RunSubroutine() returns a 0 if successful or a negative code indicating failure.

See Also	Dsp_LoadSubroutine()

Dsp_SetVectors()

VOID Dsp_SetVectors( receiver, transmitter )

VOID (*receiver)();

LONG (*transmitter)();

	Dsp_SetVectors() sets the location of application interrupt handlers that are called when the DSP is either ready to send or receive data.

Opcode	126 (0x7E)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	receiver is the address of an interrupt handler which is called when the DSP is ready to send a DSP word of data or NULLFUNC ( VOID ()() 0L ) if you do not wish to set this interrupt.Likewise, transmitter* is a pointer to an interrupt handler which is called when the DSP is ready to receive a DSP word of data or NULLFUNC if you do not wish to install a transmitter interrupt.Any function installed to handle transmitter interrupts should return a LONG which has one of the following values:

	Name	transmitter Return Value	Meaning
	DSPSEND_NOTHING	0x00000000	Do not send any data to the DSP.
	DSPSEND_ZERO	0xFF000000	Transmit a DSP word of 0 to the DSP.
	-	Any other	Transmit the low 24 bits to the DSP.

Binding	move.l #transmitter,-(sp) move.l #receiver,-(sp) move.w #$7E,-(sp) trap #14 lea 10(sp),sp

Comments	Use Dsp_RemoveInterrupts() to turn off interrupts set with this call.

See Also	Dsp_RemoveInterrupts()

Dsp_TriggerHC()

VOID Dsp_TriggerHC( vector );

WORD vector;

	Dsp_TriggerHC() causes a host command set aside for DSP programs to execute.

Opcode	112 (0x70)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Parameters	vector specifies the vector to execute.

Binding	move.w vector,-(sp) move.w #$70,-(sp) trap #14 addq.l #4,sp

Caveats	Currently vectors 0x13 and 0x14 are the only vectors available for this purpose. All other vectors are overwritten by the system on program load and are used by the system and subroutines.

Dsp_Unlock()

VOID Dsp_Unlock( VOID )

	Dsp_Unlock() unlocks the sound system from use by a process which locked it previously using Dsp_Lock().

Opcode	105 (0x69)

Availability	This call is only available if the fifth bit of the '_SND' cookie is set.

Binding	move.w #$69,-(sp) trap #14 addq.l #2,sp

See Also	Dsp_Lock()

Dsptristate()

LONG Dsptristate( dspxmit, dsprec )

WORD dspxmit, dsprec;

	Dsptristate() connects or disconnects the DSP from the connection matrix.

Opcode	137 (0x89)

Availability	Available if '_SND' cookie has bits 3 and 4 set.

Parameters	dpsxmit and dsprec specify whether data being transmitted and/or recorded into the DSP passes through the connection matrix. A value of DSP_TRISTATE (0) indicates a 'tristate' condition where data is not fed through the matrix. A value of DSP_ENABLE (1) enables the use of the connection matrix.

Binding	move.w dsprec,-(sp) move.w dspxmit,-(sp) move.w #$89,-(sp) trap #14 addq.l #6,sp

Return Value	Dsptristate() returns 0 if no error occurred or non-zero otherwise.

Comments	This call is used in conjunction with Devconnect() to link the DSP to the internal sound system.

See Also	Devconnect()

EgetPalette()

VOID EgetPalette( start, count, paldata )

WORD start, count;

WORD *paldata;

	EgetPalette() copies the current TT030 color palette data into a specified buffer..

Opcode	85 (0x55)

Availability	This call is available when the high word of the '_VDO' cookie has a value of 2.

Parameters	start gives the index (0-255) of the first color register to copy data into. count specifies the total number of registers to copy. paldata is a pointer to an array where the TT030 palette data will be stored. Each WORD will be formatted as follows:

		Bits 15-12	Bits 11-8	Bits 7-4	Bits 3-0
		Reserved	Red	Green	Blue

Binding	pea paldata move.w count,-(sp) move.w start,-(sp) move.w #$55,-(sp) trap #14 lea 10(sp),sp

Caveats	This call is machine-dependent to the TT030. It is therefore recommended that vq_color() be used in most instances.

Comments	Unlike Setpalette() this call encodes color nibbles from the most signifigant to least signifigant bit (3-2-1-0) as opposed to the compatibilty method of 0-3-2-1.

See Also	Esetpalette(), vq_color()

EgetShift()

WORD EgetShift( VOID )

	EgetShift() returns the current mode of the video shifter.

Opcode	81 (0x51)

Availability	This call is available when the high word of the '_VDO' cookie has a value of 2.

Binding	move.w #$51,-(sp) trap #14 addq.l #2,sp

Return Value	EgetShift() returns a WORD bit array which is divided as follows:

	Mask Name	Bit(s)	Meaning
	ES_BANK	0-3	These bits determine the current color bank being used by the TT (in all modes with less than 256 colors).The macro ColorBank() as defined below will extract the current bank code. #define ColorBank(x) ((x) & ES_BANK)
	-	4-7	Unused
	ES_MODE	8-10	These bits determine the current mode of the TT video shifter as follows: Name Value ST_LOW 0x0000 ST_MED 0x0100 ST_HIGH 0x0200 TT_MED 0x0300 TT_HIGH 0x0600 TT_LOW 0x0700The current shifter mode code can be extracted with the following macro: #define ScreenMode(x) ((x) & ES_MODE)
	-	11	Unused
	ES_GRAY	12	This bit determines if the TT video shifter is currently in grayscale mode. The following macro can be used to extract this information: #define IsGrayMode(x) ((x) & ES_GRAY)
	-	13-14	Unused
	ES_SMEAR	15	If this bit is set, the TT video shifter is currently in smear mode. The following macro can be used to extract this information: #define IsSmearMode(x) ((x) & ES_SMEAR)

See Also	EsetGray(), EsetShift(), EsetSmear(), EsetBank()

EsetBank()

WORD EsetBank( bank )

WORD bank;

	EsetBank() chooses which of 16 banks of color registers is currently active.

Opcode	82 (0x52)

Availability	This call is available when the high word of the '_VDO' cookie has a value of 2.

Parameters	bank specifies the index of the color bank to activate. A value of ESB_INQUIRE (1) does not change anything but still returns the current bank.

Binding	move.w bank,-(sp) move.w #$52,-(sp) trap #14 addq.l #4,sp

Return Value	EsetBank() returns the index of the old blank.

Caveats	This call is machine-dependent to the TT030.

See Also	EgetShift()

EsetColor()

WORD EsetColor( idx, color )

WORD idx, color;

	EsetColor() sets an individual color in the TT030's palette.

Opcode	83 (0x53)

Availability	This call is available when the high word of the '_VDO' cookie has a value of 2.

Parameters	idx specifies the color index to modify (0-255). color is a TT030 format color WORD bit array divided as follows:

		Bits 15-12	Bits 11-8	Bits 7-4	Bits 3-0
		Reserved	Red	Green	Blue

	If color is EC_INQUIRE (1) then the call does not change the register but still returns it value.

Binding	move.w color,-(sp) move.w idx,-(sp) move.w #$53,-(sp) trap #14 addq.l #6,sp

Return Value	EsetColor() returns the old value of the color register.

Caveats	This call is machine-dependent to the TT030. It is therefore recommended that vs_color() be used instead for compatibility.

Comments	Unlike Setpalette() this call encodes color nibbles from the most signifigant to least signifigant bit (3-2-1-0) as opposed to the compatibilty method of 0-3-2-1.

See Also	EsetPalette(), vs_color()

EsetGray()

WORD EsetGray( mode )

WORD mode;

	EsetGray() reads/modifies the TT030's video shifter gray mode bit.

Opcode	86 (0x56)

Availability	This call is available when the high word of the '_VDO' cookie has a value of 2.

Parameters	mode is defined as follows:

	Name	mode	Meaning
	ESG_INQUIRE	-1	Return the gray bit of the video shifter.
	ESG_COLOR	0	Set the video shifter to interpret the lower 16 bits of a palette entry as a TT030 color value (RGB 0-15).
	ESG_GRAY	1	Set the video shifter to interpret the lower 8 bits of a palette entry as a TT030 gray value (0-255)

Binding	move.w mode,-(sp) move.w #$56,-(sp) trap #14 addq.l #4,sp

Return Value	EsetGray() returns the previous value of the video shifter's gray bit.

Caveats	This call is machine-dependent to the TT030.

See Also	EgetShift()

EsetPalette()

VOID EsetPalette( start, count, paldata )

WORD start,count;

WORD *paldata;

	EsetPalette() copies TT030 color WORDs from the specified buffer into the TT030 Color Lookup Table (CLUT).

Opcode	84 (0x54)

Availability	This call is available when the high word of the '_VDO' cookie has a value of 2.

Parameters	start specifies the index of the starting color register to copy color data to. count indicates the number of palette WORDs to copy. paldata is a pointer to an array of palette WORDs to copy.

Binding	pea paldata move.w count,-(sp) move.w start,-(sp) move.w #$54,-(sp) trap #14 lea 10(sp),sp

Caveats	This call is machine-dependent to the TT030. It is therefore recommended that vs_color() be used instead for compatibility.

Comments	For the format of the color WORDs, see EgetPalette().

See Also	EgetPalette(), vq_color()

EsetShift()

WORD EsetShift( mode )

WORD mode;

	EsetShift() reads/modifies the TT030 video shifter.

Opcode	80 (0x50)

Availability	This call is available when the high word of the '_VDO' cookie has a value of 2.

Parameters	mode is a WORD bit array which defines the new setting of the video shifter as follows:

	Name	Bit(s)	Meaning
	-	0-3	These bits determine the current color bank being used by the TT (in all modes with less than 256 colors).
	-	4-7	Unused
	-	8-10	These bits determine the current mode of the TT video shifter as follows: Name Bit Mask ST_LOW 0x0000 ST_MED 0x0100 ST_HIGH 0x0200 TT_MED 0x0300 TT_HIGH 0x0600 TT_LOW 0x0700
	-	11	Unused
	ES_GRAY	12	Setting this bit places the TT video shifter in grayscale mode.
	-	13-14	Unused
	ES_SMEAR	15	Setting this bit places the TT video shifter in smearsmear mode.

Binding	move.w mode,-(sp) move.w #$50,-(sp) trap #14 addq.l #4,sp

Return Value	EsetShift() returns the old mode setting of the video shifter.

Caveats	This call is machine-dependent to the TT030.

See Also	EgetShift(), EsetGray(), EsetSmear(), EsetBank()

EsetSmear()

WORD EsetSmear( mode )

WORD mode;

	EsetSmear() reads/modifies the current state of the video shifter's smear mode bit.

Opcode	87 (0x57)

Availability	This call is available when the high word of the '_VDO' cookie has a value of 2.

Parameters	mode specifies the action of this call as follows:

	Name	mode	Meaning
	ESM_INQUIRE	-1	Return the smear bit of the video shifter.
	ESM_NORMAL	0	Set the video shifter to process video data normally.
	ESM_SMEAR	1	Set the video shifter to repeat the color of the last displayed pixel each time a 0x0000 is read from video memory.

Binding	move.w mode,-(sp) move.w #$57,-(sp) trap #14 addq.l #4,sp

Return Value	EsetSmear() returns the prior setting of the video shifter's smear mode bit.

See Also	Egetshift(), EsetShift()

Flopfmt()

WORD Flopfmt( buf, skew, dev, spt, track, side, intlv, magic, virgin )

VOIDP buf;

WORD *skew;

WORD dev, spt, track, side, intlv;

LONG magic;

WORD virgin;

	Flopfmt() formats a specified track on a floppy disk.

Opcode	10 (0x0A)

Availability	All TOS versions.

Parameters	buf is a pointer to a word-aligned buffer large enough to hold one disk track which is used to build a copy of each sector to write. skew should be NULL for non-interleaved sectors or point to a WORD array containing spt entries which specifies the sector interleave order.dev specifies which floppy drive to format ('A:' = FLOP_DRIVEA (0), 'B:' = FLOP_DRIVEB (1)). spt indicates the number of sectors to format. track indicates which track to format.side indicates the side to format. intlv should be FLOP_NOSKEW (1) for consecutive sectors or FLOP_SKEW (-1) to interleave the sectors based on the array pointed to by skew.magic is a fixed magic number which must be FLOP_MAGIC (0x87654321). virgin is the value to assign to uninitialized sector data (should be FLOP_VIRGIN (0xE5E5)).

Binding	move.w virgin,-(sp) move.l magic,-(sp) move.w intlv,-(sp) move.w side,-(sp) move.w track,-(sp) move.w spt,-(sp) move.w dev,-(sp) pea skew pea buf move.w #$0A,-(sp) trap #14 lea 26(sp),sp

Return Value	Flopfmt() returns 0 if the track was formatted successfully or non-zero otherwise. Also, upon exit, buf will be filled in with a WORD array of sectors that failed formatting terminated by an entry of 0. If no errors occurred then the first WORD of buf will be 0.

Comments	The steps required to a format a floppy disk are as follows:1. Call Flopfmt() to format the disk as desired. 2. Call Protobt() to create a prototype boot sector in memory. 3. Call Flopwr() to write the prototype boot sector to track 0, side 0, sector 1.Interleaved sector formatting is only possible as of TOS 1.2. skew should be set to NULL and intlv should be set to FLOP_NOSKEW under TOS 1.0.Specifying an intlv value of FLOP_SKEW and a skew array equalling { 1, 2, 3, 4, 5, 6, 7, 8, 9 } is the same as specifying an intlv value of FLOP_NOSKEW. To accomplish a 9 sector 2:1 interleave you would use a skew array which looked like: { 1, 6, 2, 7, 3, 8, 4, 9, 5 }.The '_FDC' cookie (if present) contains specific information regarding the installed floppy drives. The lower three bytes of the cookie value contain a three-letter code indicating the manufacturer of the drive (Atari is 0x415443 'ATC'). The high byte determines the capabilities of the highest density floppy drive currently installed as follows:

		Name	Value	Meaning
		FLOPPY_DSDD	0	Standard Density (720K)
		FLOPPY_DSHD	1	High Density (1.44MB)
		FLOPPY_DSED	2	Extra High Density (2.88MB)

	To format a high density diskette, multiple the spt parameter by 2. To format a extra-high density diskette, multiply the spt parameter by 4.This call forces a 'media changed' state on the device which will be returned on the next Mediach() or Rwabs() call.

See Also	Floprate(), Floprd(), Flopwr()

Floprate()

WORD Floprate( dev, rate )

WORD dev, rate;

	Floprate() sets the seek rate of the specified floppy drive.

Opcode	41 (0x29)

Availability	Available on all TOS versions except 1.00.

Parameters	dev indicates the floppy drive whose seek rate you wish to modify ('A:' = FLOP_DRIVEA (0), 'B:' = FLOP_DRIVEB (1)). rate specifies the seek rate as follows:

		Name	rate	Meaning
		FRATE_6	0	Set seek rate to 6ms
		FRATE_12	1	Set seek rate to 12ms
		FRATE_2	2	Set seek rate to 2ms
		FRATE_3	3	Set seek rate to 3ms

	A rate value of FRATE_INQUIRE (1) will inquire the current seek rate without modifying it.

Binding	move.w rate,-(sp) move.w dev,-(sp) move.w #$29,-(sp) trap #14 addq.l #6,sp

Return Value	Floprate() returns the prior seek rate for the specified drive.

Comments	TOS version 1.00 can have its seek rates set by setting the system variable (_seekrate (WORD )0x440 ) to the desired value (as in rate). Note that you can only set the seek rate for both* drives in this manner.

Floprd()

WORD Floprd( buf, rsrvd, dev, sector, track, side, count )

VOIDP buf;

LONG rsrvd;

WORD dev, sector, track, side, count;

	Floprd() reads sectors from a floppy disk.

Opcode	8 (0x08)

Availability	All TOS versions.

Parameters	buf points to a word-aligned buffer where the data to be read will be stored. rsrvd is currently unused and should be 0. dev specifies the floppy drive to read from ('A:' = FLOP_DRIVEA (0), 'B:' = FLOP_DRIVEB (1)). The function reads count physical sectors starting at sector sector, track track, side side.

Binding	move.w count,-(sp) move.w side,-(sp) move.w track,-(sp) move.w sector,-(sp) move.w dev,-(sp) move.l rsrvd,-(sp) pea buf move.w #$08,-(sp) trap #14 lea 20(sp),sp

Return Value	Floprd() returns 0 if the operation was successful or non-zero otherwise.

Caveats	This function reads sectors in physical order (not taking interleave into account). Use Rwabs() to read logical sectors.

See Also	Flopwr(), Flopfmt(), Flopver(), Rwabs()

Flopver()

WORD Flopver( buf, rsrvd, dev, sector, track, side, count )

VOIDP buf;

LONG rsrvd;

WORD dev, sector, track, side, count;

	Flopver() verifies data on a floppy disk with data in memory.

Opcode	19 (0x13)

Availability	All TOS versions.

Parameters	buf is a pointer to a word-aligned buffer to compare the sector against. rsrvd is unused and should be 0. dev specifies the drive to verify ('A:' = FLOP_DRIVEA (0), 'B:' = FLOP_DRIVEB (1)). This function verifies count sectors starting at sector sector, track track, side side.

Binding	move.w count,-(sp) move.w side,-(sp) move.w track,-(sp) move.w sector,-(sp) move.w dev,-(sp) move.l rsrvd,-(sp) pea buf move.w #$13,-(sp) trap #14 lea 20(sp),sp

Return Value	Flopver() returns 0 if all sectors were successfully verified or a non-zero value otherwise.

Caveats	This function only verifies sectors in physical order.

Comments	As with Flopfmt(), upon the return of the function, buf is filled in with a WORD array containing a list of any sectors which failed. The array is terminated with a NULL.

See Also	Flopwr(), Flopfmt()

Flopwr()

WORD Flopwr( buf, rsrvd, dev, sector, track, side, count )

VOIDP buf;

LONG rsrvd;

WORD dev, sector, track, side, count;

	Flopwr() writes sectors to the floppy drive.

Opcode	9 (0x09)

Availability	All TOS versions.

Parameters	buf is a pointer containing data to write. rsrvd is currently unused and should be set to 0. dev specifies the floppy drive to write to ('A:' = 0,'B:' = 1). This function writes count sectors starting at sector sector, track track, side side.

Binding	move.w count,-(sp) move.w side,-(sp) move.w track,-(sp) move.w sector,-(sp) move.w dev,-(sp) move.l rsrvd,-(sp) pea buf move.w #$09,-(sp) trap #14 lea 20(sp),sp

Return Value	Flopwr() returns 0 if the sectors were successfully written or non-zero otherwise.

Caveats	This function writes sectors in physical order only (ignoring interleave). Use Rwabs() to write sectors in logical order.

Comments	If this call is used to write to track 0, sector 1, side 0, the device will enter a 'media might have changed' state indicated upon the next Rwabs() or Mediach() call.

See Also	Floprd(), Flopfmt(), Flopver(),Rwabs()

Getrez()

WORD Getrez( VOID )

	Getrez() returns a machine-dependent code representing the current screen mode/ratio.

Opcode	4 (0x04)

Availability	All TOS versions.

Binding	move.w #$04,-(sp) trap #14 addq.l #2,sp

Return Value	Getrez() returns a value representing the current video display mode. To find the value you will receive back based on current Atari manufactured video hardware, refer to the following chart:

		Colors:Screen Dimension:	2	4	16	256	True Color
		320x200	X	X	0	0	X
		320x240	X	0	0	0	0
		320x480	X	7	7	7	7
		640x200	1	X	X	X	X
		640x400	2	X	X	X	X
		640x480	2	2	2†	2	2
		1280x960	6	X	X	X	X

	† This value varies. TT030 Medium resolution returns a value of 4, however, the Falcon returns a value of 2.

Caveats	This call is extremely machine-dependent. Dependence on this call will make your program incompatible with third-party video boards and future hardware. Use the values returned by v_opnvwk() to determine screen attributes.

Comments	Use of this call in preparing to call v_opnvwk() is acceptable and must be done to specify the correct fonts to load from GDOS.

See Also	VsetMode(), Egetshift(), Setscreen()

Gettime()

LONG Gettime( VOID )

	Gettime() returns the current IKBD time.

Opcode	23 (0x17)

Availability	All TOS versions.

Binding	move.w #$17,-(sp) trap #14 addq.l #2,sp

Return Value	Gettime() returns a LONG bit array packed with the current IKBD time as follows:

		Bits	Meaning
		0-4	Seconds/2 (0-29)
		5-10	Minute (0-59)
		11-15	Hour (0-23)
		16-20	Day (1-31)
		21-24	Month (1-12)
		25-31	Year-1980 (0-127)

	The return value can be represented in a C structure as follows: typedef struct { unsigned year:7; unsigned month:4; unsigned day:5; unsigned hour:5; unsigned minute:6; unsigned second:5; } BIOS_TIME;

See Also	Settime(), Tgettime(), Tgetdate()

Giaccess()

WORD Giaccess( data, register )

WORD data, register;

	Giaccess() reads/sets the registers of the FM sound chip and Port A/B peripherals.

Opcode	28 (0x1C)

Availability	All TOS versions.

Parameters	The lower eight bits of data are written to the register selected by register if the value for register is OR'ed with 0x80 (high bit set). If this bit is not set, data is ignored and the value of the register is returned. register selects the register to read/write to as follows:

	Name	register	Meaning
	PSG_APITCHHIGH PSG_BPITCHHIGH	0 1	Set the pitch of the PSG's channel A to the value in registers 0 and 1. Register 0 contains the lower 8 bits of the frequency and the lower 4 bits of register 1 contain the upper 4 bits of the frequency's 12-bit value.
	PSG_BPITCHLOW PSG_BPITCHHIGH	2 3	Set the pitch of the PSG's channel B to the value in registers 0 and 1. Register 0 contains the lower 8 bits of the frequency and the lower 4 bits of register 1 contain the upper 4 bits of the frequency's 12-bit value.
	PSG_CPITCHLOW PSG_CPITCHHIGH	2 3	Set the pitch of the PSG's channel C to the value in registers 0 and 1. Register 0 contains the lower 8 bits of the frequency and the lower 4 bits of register 1 contain the upper 4 bits of the frequency's 12-bit value.
	PSG_NOISEPITCH	6	The lower five bits of this register set the pitch of white noise. The lower the value, the higher the pitch.
	PSG_MODE	7	This register contains an eight bit map which determines various aspects of sound generation. Setting each bit on causes the following actions:Name Bit Mask Meaning PSG_ENABLEA 0x01 Chnl A tone enable PSG_ENABLEB 0x02 Chnl B tone enable PSG_ENABLEC 0x04 Chnl C tone enablePSG_NOISEA 0x08 Chnl A white noise onPSG_NOISEB 0x10 Chnl B white noise on PSG_NOISEC 0x20 Chnl C white noise onPSG_PRTAOUT 0x40 Port A: 0 = input 1 = output PSG_PRTBOUT 0x80 Port B: 0 - input 1 = output
	PSG_AVOLUME	8	This register controls the volume of channel A. Values from 0-15 are absolute volumes with 0 being the softest and 15 being the loudest. Setting bit 4 causes the PSG to ignore the volume setting and to use the envelope setting in register 13.
	PSG_BVOLUME	9	This register controls the volume of channel B. Values from 0-15 are absolute volumes with 0 being the softest and 15 being the loudest. Setting bit 4 causes the PSG to ignore the volume setting and to use the envelope setting in register 13.
	PSG_CVOLUME	10	This register controls the volume of channel C. Values from 0-15 are absolute volumes with 0 being the softest and 15 being the loudest. Setting bit 4 causes the PSG to ignore the volume setting and to use the envelope setting in register 13.
	PSG_FREQLOW PSG_FREQHIGH	11 12	Register 11 contains the low byte and register 12 contains the high byte of the frequency of the waveform specified in register 13. This value may range from 0 to 65535.
	PSG_ENVELOPE	13	The lower four bits of the register contain a value which defines the envelope wavefrom of the PSG. The best definition of values is obtained through experimentation.
	PSG_PORTA	14	This register accesses Port A of the Yamaha PSG. It is recommended that the functions Ongibit() and Offgibit() be used to access this register.
	PSG_PORTB	15	This register accesses Port B of the Yamaha PSG. This register is currently assigned to the data in/out line of the Centronics Parallel port.

Binding	move.w register,-(sp) move.w data,-(sp) move.w #$1C,-(sp) trap #14 addq.l #6,sp

Return Value	Giaccess() returns the value of the register in the lower eight bits of the word if data was OR'ed with 0x80.

Gpio()

LONG Gpio( mode, data )

WORD mode, data;

	Gpio() reads/writes data over the general purpose pins on the DSP connector.

Opcode	138 (0x8A)

Availability	Available if '_SND' cookie has bit 3 set.

Parameters	mode specifies the meaning of data and the return value as follows:

	Name	mode	Meaning
	GPIO_INQUIRE	0	Return the old value.
	GPIO_READ	1	Read the three general purpose pins and return their state in the lower three bits of the returned value. data is ignored.
	GPIO_WRITE	2	Write the lower three bits of data to the corresponding DSP pins. The return value is 0.

Binding	move.w data,-(sp) move.w mode,-(sp) move.w #$8A,-(sp) trap #14 addq.l #6,sp

Ikbdws()

VOID Ikbdws( len, buf )

WORD len;

CHAR *buf;

	Ikbdws() writes the contents of a buffer to the intelligent keyboard controller.

Opcode	25 (0x19)

Availability	All TOS versions.

Parameters	This function writes len + 1 characters from buffer buf to the IKBD.

Binding	pea buf move.w len,-(sp) move.w #$19,-(sp) trap #14 addq.l #8,sp

Initmous()

VOID Initmous( mode, param, vec )

WORD mode;

VOIDP param;

VOID (*vec)();

	Initmous() determines the method of handling IKBD mouse packets from the system.

Opcode	0 (0x00)

Availability	All TOS versions.

Parameters	mode indicates a IKBD reporting mode and defines the meaning of the other parameters as listed below. hand points to a mouse packet handler which is called when each mouse packet is sent. Register A0 contains the mouse packet address when called.

	Name	mode	Meaning
	IM_DISABLE	0	Disable mouse reporting.
	IM_RELATIVE	1	Enable relative mouse reporting mode. Packets report offsets from the previous mouse position. In this mode, param is a pointer to a structure as follows: struct param { BYTE topmode; BYTE buttons; BYTE xparam; BYTE yparam; }topmode is IM_YBOT (0) to indicate that Y=0 means bottom of the screen. A topmode value of IM_YTOP (1) indicates that Y=0 means the top of the screen.buttons is a bit array which affect the way mouse clicks are handled. A value of IM_KEYS (4) causes mouse buttons to generate keycodes rather than mouse packets. A value of IM_PACKETS (3) causes the absolute mouse position to be reported on each button press.xparam and yparam specify the number of mouse X/Y increments between position report packets.This mode is the default mode of the AES and VDI.
	IM_ABSOLUTE	2	Enable absolute mouse reporting mode. Packets report actual screen positions. In this mode, param is a pointer to a structure as follows: struct param { BYTE topmode; BYTE buttons; BYTE xparam; BYTE yparam; WORD xmax; WORD ymax; WORD xinitial; WORD yinitial; }topmode, buttons, xparam, and yparam are the same as for mode 2.xmax and ymax specify the maximum X and Y positions the mouse should be allowed to move to. xinital and yinitial specify the mouse's initial location.
	-	3	Unused
	IM_KEYCODE	4	Enable mouse keycode mode. Keyboard codes for mouse movements are sent rather than actual mouse packets.param is handled the same as in mode 1.

Binding	pea hand pea param move.w mode,-(sp) clr.w -(sp) trap #14 lea 12(sp),sp

Caveats	Changing the mouse packet handler to anything but relative mode will cause the AES and VDI to stop receiving mouse input.

See Also	Kbdvbase()

Iorec()

IOREC *Iorec( dev )

WORD dev;

	Iorec() returns the address in memory of system data structures relating to the buffering of input data.

Opcode	14 (0x0E)

Availability	All TOS versions.

Parameters	dev specifies the device to return information about as follows:

		Name	dev	Meaning
		IO_SERIAL	0	Currently mapped serial device (see Bconmap() )
		IO_KEYBOARD	1	Keyboard
		IO_MIDI	2	MIDI

Binding	move.w dev,-(sp) move.w #$0E,-(sp) trap #14 addq.l #4,sp

Return Value	Iorec() returns the address of an IOREC array with either one element (Keyboard or MIDI) or two elements (RS-232 - 1st = input, 2nd = output). The IOREC structure is defined as follows: typedef struct { /* start of buffer / char ibuf; /* size of buffer / WORD ibufsize; / head index mark of buffer / WORD ibufhd; / tail index mark of buffer / WORD ibuftl; / low-water mark of buffer / WORD ibuflow; / high-water mark of buffer */ WORD ibufhi; } IOREC;

See Also	Bconmap()

Jdisint()

VOID Jdisint( intno )

WORD intno;

	Jdisint() disables an MFP interrupt.

Opcode	26 (0x1A)

Availability	All TOS versions.

Parameters	intno specifies the interrupt to disable (see Mfpint() for a list).

Binding	move.w intno,-(sp) move.w #$1A,-(sp) trap #14 addq.l #4,sp

See Also	Jenabint(), Mfpint()

Jenabint()

VOID Jenabint( intno )

WORD intno;

	Jenabint() enables an MFP interrupt.

Opcode	27 (0x1B)

Availability	All TOS versions.

Parameters	intno specifies the interrupt to enable (see Mfpint() for a list).

Binding	move.w intno,-(sp) move.w #$1B,-(sp) trap #14 addq.l #4,sp

See Also	Jdsint(), Mfpint()

Kbdvbase()

KBDVECS *Kbdvbase( VOID )

	Kbdvbase() returns a pointer to a system structure containing a 'jump' table to system vector handlers.

Opcode	34 (0x22)

Availability	All TOS versions.

Binding	move.w #$22,-(sp) trap #14 addq.l #2,sp

Return Value	Kbdvbase() returns a pointer to a system structure KBDVECS which is defined as follows: typedef struct { VOID (midivec)( UBYTE data ); / MIDI Input / VOID (vkbderr)( UBYTE data ); /* IKBD Error / VOID (vmiderr)( UBYTE data ); /* MIDI Error / VOID (statvec)(char buf); / IKBD Status / VOID (mousevec)(char buf); / IKBD Mouse / VOID (clockvec)(char buf); / IKBD Clock / VOID (joyvec)(char buf); / IKBD Joystick / VOID (midisys)( VOID ); /* Main MIDI Vector / VOID (ikbdsys)( VOID ); /* Main IKBD Vector / char ikbdstate; / See below / } KBDVECS; midivec* is called with the received data byte in d0. If an overflow error occurred on either ACIA, vkbderr or vmiderr will be called, as appropriate by midisys or ikbdsys with the contents of the ACIA data register in d0.statvec, mousevec, clockvec, and joyvec all are called with the address of the packet in register A0.midisys and ikbdsys are called by the MFP ACIA interrupt handler when a character is ready to be read from either the midi or keyboard ports.ikbdstate is set to the number of bytes remaining to be read by the ikbdsys handler from a multiple-byte status packet.

Comments	If you intercept any of these routines you should either JMP through the old handler or RTS.

See Also	Initmous()

Kbrate()

WORD Kbrate( delay, rate )

WORD delay, rate;

	Kbrate() reads/modifies the keyboard repeat/delay rate.

Opcode	35 (0x23)

Availability	All TOS versions.

Parameters	delay specifies the amount of time (in 50Hz ticks) before a key begins repeating. rate indicates the amount of time between repeats (in 50Hz ticks). A parameter of KB_INQUIRE (1) for either of these values leaves the value unchanged.

Binding	move.w rate,-(sp) move.w delay,-(sp) move.w #$23,-(sp) trap #14 addq.l #6,sp

Return Value	Kbrate() returns a WORD with the low byte being the old value for rate and the high byte being the old value for delay.

Keytbl()

KEYTAB *Keytbl( normal, shift, caps )

char *unshift, *shift, *caps;

	Keytbl() reads/modifies the internal keyboard mapping tables.

Opcode	16 (0x10)

Availability	All TOS versions.

Parameters	normal is a pointer to an array of 128 CHARs which can be indexed by a keyboard scancode to return the correct ASCII value for a given unshifted key. shift and caps point to similar array except their values are only utilized when shift and caps-lock respectively are used. Passing a value of KT_NOCHANGE ((char *)-1) will leave the table unchanged.

Binding	pea caps pea shift pea normal move.w #$10,-(sp) trap #14 lea 14(sp),sp

Return Value	Keytbl() returns a pointer to a KEYTAB structure defined as follows: typedef struct { char unshift; char shift; char *caps; } KEYTAB;The entries in this table each point to the current keyboard lookup table in their category.Entries are indexed with a keyboard scancode to obtain the ASCII value of a key. A value of 0 indicates that no ASCII equivalent exists.

See Also	Bioskeys()

Locksnd()

LONG Locksnd( VOID )

	Locksnd() prevents other applications from simultaneously attempting to use the sound system.

Opcode	128 (0x80)

Availability	Available if the '_SND' cookie has bit 2 set.

Binding	move.w #$80,-(sp) trap #14 addq.l #2,sp

Return Value	Locksnd() returns 1 if the sound system was successfully locked or SNDLOCKED (-129) if the sound system was already locked.

Comments	This call should be used prior to any usage of the 16-bit DMA sound system.

See Also	Unlocksnd()

Logbase()

VOIDP Logbase( VOID )

	Logbase() returns a pointer to the base of the logical screen.

Opcode	3 (0x03)

Availability	All TOS versions.

Binding	move.w #$03,-(sp) trap #14 addq.l #2,sp

Return Value	Logbase() returns a pointer to the base of the logical screen.

Comments	The logical screen should not be confused with the physical screen. The logical screen is the memory area where the VDI does any drawing. The physical screen is the memory area where the video shifter gets its data from. Normally they are the same; however, keeping the addresses separate facilitates screen flipping.

See Also	Physbase()

Metainit()

VOID Metainit( metainfo )

METAINFO *metainfo;

	Metainit() returns information regarding the current version and installed drives of MetaDOS.

Opcode	48 (0x30)

Availability	To test for the availability of MetaDOS the following steps must be taken:1. Fill the METAINFO structure with all zeros. 2. Call Metainit(). 3. If metainfo.version is NULL, MetaDOS is not installed.

Parameters	metainfo is a pointer to a METAINFO structure which is filled in by the call. METAINFO is defined as: typedef struct { /* Bitmap of drives (Bit 0 = A, 1 = B, etc... / ULONG drivemap; / String containing name and version / char version; /* Currently unused */ LONG reserved[2]; } METAINFO;

Binding	pea metainfo move.w #$30,-(sp) trap #14 addq.l #6,sp

Mfpint()

VOID Mfpint( intno, vector )

WORD intno;

VOID (*vector)();

	Mfpint() defines an interrupt handler for an MFP interrupt.

Opcode	13 (0x0D)

Availability	All TOS versions.

Parameters	intno is an index to a vector to replace with vector as follows:

	Name	intno	Vector
	MFP_PARALLEL	0	Parallel port
	MFP_DCD	1	RS-232 Data Carrier Detect
	MFP_CTS	2	RS-232 Clear To Send
	MFP_BITBLT	3	BitBlt Complete
	MFP_TIMERD or MFP_BAUDRATE	4	Timer D (RS-232 baud rate generator)
	MFP_200HZ	5	Timer C (200Hz system clock)
	MFP_ACIA	6	Keyboard/MIDI vector
	MFP_DISK	7	Floppy/Hard disk vector
	MFP_TIMERB or MFP_HBLANK	8	Timer B (Horizontal blank)
	MFP_TERR	9	RS-232 transmit error
	MFP_TBE	10	RS-232 transmit buffer empty
	MFP_RERR	11	RS-232 receive error
	MFP_RBF	12	RS-232 receive buffer full.
	MFP_TIMERA or MFP_DMASOUND	13	Timer A (DMA sound)
	MFP_RING	14	RS-232 ring indicator
	MFP_MONODETECT	15	Mono monitor detect/DMA sound complete

Binding	pea vector move.w intno,-(sp) move.w #$0D,-(sp) trap #14 addq.l #8,sp

Caveats	This call does not return the address of the old handler.The only RS-232 vector that may be set on the Falcon030 with this function is the ring indicator.

Comments	Newly installed interrupts must be enabled with Jenabint().

See Also	Jenabint(), Jdisint()

Midiws()

VOID Midiws( count, buf )

WORD count;

char *buf;

	Midiws() outputs a data buffer to the MIDI port.

Opcode	12 (0x0C)

Availability	All TOS versions.

Parameters	count + 1 characters are written from the buffer pointed to by buf.

Binding	pea buf move.w count,-(sp) move.w #$0C,-(sp) trap #14 addq.l #8,sp

NVMaccess()

WORD NVMaccess( op, start, count, buffer )

WORD op, start, count;

char *buffer;

	NVMaccess() reads/modifies data in non-volatile (battery backed-up) memory.

Opcode	46 (0x2E)

Availability	This function's availability is variable. If it returns 0x2E (its opcode) when called, the function is non-existent and the operation was not carried out.

Parameters	op indicates the operation to perform as follows:

	Name	op	Meaning
	NVM_READ	0	Read count bytes of data starting at offset start and place the data in buffer.
	NVM_WRITE	1	Write count bytes of data from buffer starting at offset start.
	NVM_RESET	2	Resets and clears all data in non-volatile memory.

Binding	pea buffer move.w count,-(sp) move.w start,-(sp) move.w op,-(sp) move.w #$2E,-(sp) trap #14 lea 12(sp),sp

Return Value	NVMaccess() returns 0 if the operation succeeded or a negative error code otherwise.

Caveats	All of the locations are reserved for use by Atari and none are currently documented.

Comments	Currently there is a total of 50 bytes in non-volatile RAM.

Offgibit()

VOID Offgibit( mask )

WORD mask;

	Offgibit() clears individual bits of the sound chip's Port A.

Opcode	29 (0x1D)

Availability	All TOS versions.

Parameters	mask is a bit mask arranged as shown below. For each of the lower eight bits in mask set to 0, that bit will be reset. Other bits (set as 1) will remain unchanged.

		Name	Mask	Meaning
		GI_FLOPPYSIDE	0x01	Floppy side select
		GI_FLOPPYA	0x02	Floppy A select
		GI_FLOPPYB	0x04	Floppy B select
		GI_RTS	0x08	RS-232 Request To Send
		GI_DTR	0x10	RS-232 Data Terminal Ready
		GI_STROBE	0x20	Centronics strobe
		GI_GPO	0x40	General purpose output (On a Falcon030, this bit controls the state of the internal speaker)
		GI_SCCPORT	0x80	On a Mega STe or TT030, calling Ongibit( 0x80 ) will cause SCC channel A to control the Serial 2 port rather than the LAN. To select the LAN, use Offgibit( 0x7F ).

Binding	move.w mask,-(sp) move.w #$1D,-(sp) trap #14 addq.l #4,sp

See Also	Giaccess(), Ongibit()

Ongibit()

VOID Ongibit( mask )

WORD mask;

	Ongibit() sets individual bits of the sound chip's assigned Port A.

Opcode	30 (0x1E)

Availability	All TOS versions.

Parameters	mask is a bit mask arranged as defined in Offgibit(). For each of the lower eight bits in mask set to 1, that bit will be set. Other bits (set as 0) will remain unchanged.

Binding	move.w mask,-(sp) move.w #$1E,-(sp) trap #14 addq.l #4,sp

See Also	Giaccess(), Offgibit()

Physbase()

VOIDP Physbase( VOID )

	Physbase() returns the address of the physical base of screen memory.

Opcode	2 (0x02)

Availability	All TOS versions.

Binding	move.w #$02,-(sp) trap #14 addq.l #2,sp

Return Value	Physbase() returns the physical base address of the screen.

Comments	The physical base address is the memory area where the video shifter reads its data. The logical address is the memory area where the VDI draws. These are normally the same but are addressed individually to enable screen flipping.

See Also	Logbase()

Protobt()

VOID Protobt( buf, serial, type, execflag )

VOIDP buf;

LONG serial;

WORD type, execflag;

	Protobt() creates a prototype floppy boot sector in memory for writing to a floppy drive.

Opcode	18 (0x12)

Availability	All TOS versions.

Parameters	buf is a 512 byte long buffer where the prototyped buffer will be written. If you are creating an executable boot sector, the memory buffer should contain the code you require. serial can be any of the following values:

	Name		serial			Meaning
	SERIAL_NOCHANGE		-1			Don't change the serial number already in memory.
	SERIAL_RANDOM		>0x01000000			Use a random number for the serial number
	-		any other positive number			Set the serial number to serial.

	type defines the type of disk to prototype as follows:

		Name		type			Meaning
		DISK_NOCHANGE		-1			Don't change disk type.
		DISK_SSSD		0			40 Track, Single-Sided (180K)
		DISK_DSSD		1			40 Track, Double-Sided (360K)
		DISK_SSDD		2			80 Track, Single-Sided (360K)
		DISK_DSDD		3			80 Track, Double-Sided (720K)
		DISK_DSHD		4			High Density (1.44MB)
		DISK_DSED		5			Extra-High Density (2.88MB)

	execflag specifies the executable status of the boot sector as follows:

		Name			execflag			Meaning
		EXEC_NOCHANGE			-1			Don't alter executable status
		EXEC_NO			0			Disk is not executable
		EXEC_YES			1			Disk is executable

Binding	move.w execflag,-(sp) move.w type,-(sp) move.l serial,-(sp) pea buf move.w #$12,-(sp) trap #14 lea 14(sp),sp

Caveats	type values of DISK_DSHD and DISK_DSED are only available when the high byte of the '_FDC' cookie has a value of FLOPPY_DSHD (1) and FLOPPY_DSED (2) respectively.

Comments	To create an MS-DOS compatible disk you must set the first three bytes of the prototyped boot sector to 0xE9, 0x00, and 0x4E.

See Also	Flopfmt(), Flopwr()

Prtblk()

WORD Prtblk( blk )

PRTBLK *blk;

	Prtblk() accesses the built-in bitmap/text printing code.

Opcode	36 (0x24)

Availability	All TOS versions.

Parameters	blk is a PRTBLK pointer containing information about the bitmap or text to print. PRTBLK is defined as follows: typedef struct { VOIDP blkptr; /* pointer to screen scanline / UWORD offset; / bit offset of first column / UWORD width; / width of bitmap in bits / UWORD height; / height of bitmap in scanlines / UWORD left; / left print margin (in pixels) / UWORD right; / right print margin (in pixels) / UWORD srcres; / same as Getrez() / UWORD destres; / 0 = draft, 1 = final / UWORD colpal; /* color palette pointer / / * 0 = B/W Atari * 1 = Color Atari * 2 = Daisy Wheel * 3 = B/W Epson / UWORD type; / 0 = parallel, 1 = serial / UWORD port; / halftone mask pointer or NULL to use default / char masks; } PRTBLK;

Binding	pea prtblk move.w #$24,-(sp) trap #14 addq.l #6,sp

Caveats	This call is extremely device dependent. v_bit_image() with GDOS installed should be used instead. Only ST compatible screen resolution bitmaps may be printed with this utility function.

Comments	When printing text, blkptr should point to the text string, width should be the length of the text string, height should be 0, and masks should be NULL. In graphic print mode, masks can be NULL to use the default halftone masks.The system variable _prt_cnt (WORD *)0x4EE should be set to 1 to disable the alt-help key before calling this function. It should be restored to a value of -1 when done.

See Also	Scrdump(), SetPrt()

Puntaes()

VOID Puntaes( VOID )

	Puntaes() discards the AES (if memory-resident) and restarts the system.

Opcode	39 (0x27)

Availability	All TOS versions.

Binding	move.w #$27,-(sp) trap #14 addq.l #2,sp

Return Value	If successful, this function will not return control to the caller.

Caveats	Puntaes() is only valid with disk-loaded AES's.

Comments	Puntaes() discards the AES by freeing any memory it allocated, resetting the system variable os_magic (this variable should contain the magic number 0x87654321, however if reset, the AES will not initialize), and rebooting the system.

Random()

LONG Random( VOID )

	Random() returns a 24 bit random number.

Opcode	17 (0x11)

Availability	All TOS versions.

Binding	move.w #$11,-(sp) trap #14 addq.l #2,sp

Return Value	Random() returns a 24-bit random value in the lower three bytes of the returned LONG.

Caveats	The algorithm used provides an exact 50% occurrence of bit 0.

Rsconf()

ULONG Rsconf( speed, flow, ucr, rsr, tsr, scr )

WORD speed, flow, ucr, rsr, tsr, scr;

	Rsconf() reads/modifies the configuration of the serial device currently mapped to BIOS device #1 (GEMDOS 'aux:').

Opcode	15 (0x0F)

Availability	All TOS versions.

Parameters	speed sets the serial device speed as follows:

	Name			speed		Baud Rate		Name		speed	Baud Rate
	BAUD_19200			0		19200		BAUD_600		8	600
	BAUD_9600			1		9600		BAUD_300		9	300
	BAUD_4800			2		4800		BAUD_200		10	200
	BAUD_3600			3		3600		BAUD_150		11	150
	BAUD_2400			4		2400		BAUD_134		12	134
	BAUD_2000			5		2000		BAUD_110		13	110
	BAUD_1800			6		1800		BAUD_75		14	75
	BAUD_1200			7		1200		BAUD_50		15	50

	If speed is set to BAUD_INQUIRE (-2), the last baud rate set will be returned. flow selects the flow control method as follows:

		Name			flow		Meaning
		FLOW_NONE			0		No flow control
		FLOW_SOFT			1		XON/XOFF flow control (ctrl-s/ctrl-q)
		FLOW_HARD			2		RTS/CTS flow control (hardware)
		FLOW_BOTH			3		Both methods of flow control

	ucr, rsr, and tsr are each status bit arrays governing the serial devices. Each parameter uses only the lower eight bits of the WORD. They are defined as follows:

	Mask		ucr						rsr and tsr
	0x01		Unused						Receiver enable: RS_RECVENABLE
	0x02		Enable odd parity RS_ODDPARITY (0x02) RS_EVENPARITY (0x00)						Sync strip RS_SYNCSTRIP
	0x04		Parity enable RS_PARITYENABLE						Match busy RS_MATCHBUSY
	0x08		Bits 3-4 of the ucr collectively define the start and stop bit configuration as follows:00 = No Start or Stop bits RS_NOSTOP (0x00) 01 = 1 Start bit, 1 Stop bit RS_1STOP (0x08) 10 = 1 Start bit, 1½ Stop bits RS_15STOP (0x10) 11 = 1 Start bit, 2 Stop bits RS_2STOP (0x18)						Break detect RS_BRKDETECT
	0x10		See above.						Frame error RS_FRAMEERR
	0x20		Bits 5 and 6 together define the number of bits per word as follows:00 = 8 bits RS_8BITS (0x00) 01 = 7 bits RS_7BITS (0x20) 10 = 6 bits RS_6BITS (0x40) 11 = 5 bits RS_5BITS (0x60)						Parity error RS_PARITYERR
	0x40		See above.						Overrun error RS_OVERRUNERR
	0x80		CLK/16 RS_CLK16						Buffer full RS_BUFFULL

	scr sets the synchronous character register in which the low byte is used as the character to search for in an underrun error condition.If a RS_INQUIRE (-1) is used for either ucr, rsr, tsr, or scr, then that parameter is read and the register is unmodified.

Binding	move.w scr,-(sp) move.w tsr,-(sp) move.w rsr,-(sp) move.w ucr,-(sp) move.w flow,-(sp) move.w speed,-(sp) move.w #$0F,-(sp) trap #14 lea 14(sp),sp

Return Value	Rsconf() returns the last set baud rate if speed is set to RS_LASTBAUD (2). Otherwise, it returns the old settings in a packed LONG with ucr being in the high byte, down to scr being in the low byte.

Comments	Bits in the ucr, rsr, tsr, and scr should be set atomically. To correctly change a value, read the old value, mask it as appropriate and then write it back.Baud rates higher than 19,200 bps available with SCC-based serial devices may be set by using the appropriate Fcntl() call under MiNT or by directly programming the SCC chip.

Caveats	The baud rate inquiry mode (speed = RS_LASTBAUD) does not work at all on TOS versions less than 1.04. TOS version 1.04 requires the patch program TOS14FX2.PRG (available from Atari Corp.) to allow this mode to function. All other TOS versions support the function normally.

See Also	Bconmap()

Scrdmp()

VOID Scrdmp( VOID )

	Scrdmp() starts the built-in hardware screen dump routine.

Opcode	20 (0x14)

Availability	All TOS versions.

Binding	move.w #$14,-(sp) trap #14 addq.l #2,sp

Caveats	Scrdmp() only dumps ST compatible screen resolutions.

Comments	This routine is extremely device-dependent. You should use the VDI instead.

See Also	Prtblk(), v_hardcopy()

Setbuffer()

LONG Setbuffer( mode, begaddr, endaddr )

WORD mode;

VOIDP begaddr;

VOIDP endaddr;

	Setbuffer() sets the starting and ending addresses of the internal play and record buffers.

Opcode	131 (0x83)

Availability	Available when bit #2 of the '_SND' cookie is set.

Parameters	mode specifies which registers are to be set. A mode value of PLAY (0) sets the play registers, a value of RECORD (1) sets the record registers. begaddr specifies the starting location of the buffer. endaddr specifies the first invalid location for sound data past begaddr.

Binding	pea endaddr pea begaddr move.w mode,-(sp) move.w #$83,-(sp) trap #14 lea 12(sp),sp

Return Value	Setbuffer() returns a 0 if successful or non-zero otherwise.

See Also	Buffoper()

Setcolor()

WORD Setcolor( idx, new )

WORD idx, new;

	Setcolor() sets a ST/TT030 color register.

Opcode	7 (0x07)

Availability	All TOS versions.

Parameters	idx specifies the color register to modify (0-16 on an ST, 0-255 on a STe or TT030). new is a bit array specifying the new color as follows:

		Bits 15-12	Bits 11-8	Bits 7-4	Bits 3-0
		Unused	Red	Green	Blue

	Each color value has its bits packed in an unusual manner to stay compatible between machines. Bits are ordered 0, 3, 2, 1 with 0 being the least signifigant bit. If new is COL_INQUIRE (-1) then the old color is returned.

Binding	move.w new,-(sp) move.w idx,-(sp) move.w #$06,-(sp) trap #14 addq.l #6,sp

Return Value	Setcolor() returns the old value of the color register.

Caveats	This call is extremely device-dependent. vs_color() should be used instead.

Comments	The top bit of each color nibble is unused on the original ST machines.

See Also	VsetRGB(), EsetColor(), Setpalette()

Setinterrupt()

LONG Setinterrupt( mode, cause )

WORD mode, cause;

	Setinterrupt() defines the conditions under which an interrupt is generated by the sound system

Opcode	135 (0x87)

Availability	Available when bit #2 of the '_SND' cookie is set.

Parameters	mode configures interrupts to occur when the end of a buffer is reached. A value of INT_TIMERA (0) for mode sets Timer A, a value of INT_I7 (1) sets the MFP i7 interrupt. cause defines the conditions for the interrupt as follows:

		Name	cause	Meaning
		INT_DISABLE	0	Disable interrupt
		INT_PLAY	1	Interrupt at end of play buffer
		INT_RECORD	2	Interrupt at end of record buffer
		INT_BOTH	3	Interrupt at end of both buffers

Binding	move.w cause,-(sp) move.w mode,-(sp) move.w #$87,-(sp) trap #14 addq.l #6,sp

Return Value	Setinterrupt() returns 0 if no error occurred or non-zero otherwise.

Comments	If either buffer is in repeat mode, these interrupts can be used to double-buffer sounds.

See Also	Buffoper()

Setmode()

LONG Setmode( mode )

WORD mode;

	Setmode() sets the mode of operation for the play and record registers.

Opcode	132 (0x84)

Availability	Available if bit #2 of the '_SND' cookie is set.

Parameters	mode defines the playback and record mode as follows:

		Name	mode	Meaning
		MODE_STEREO8	0	8-bit Stereo Mode
		MODE_STEREO16	1	16-bit Stereo Mode
		MODE_MONO	2	8-bit Mono Mode

Binding	move.w mode,-(sp) move.w #$84,sp trap #14 addq.l #4,sp

Return Value	Setmode() returns 0 if the operation was successful or non-zero otherwise.

Caveats	Recording only works in 16-bit stereo mode.

See Also	Buffoper()

Setmontracks()

LONG Setmontracks( track )

WORD track;

	Setmontracks() defines which playback track is audible through the internal speaker.

Opcode	134 (0x86)

Availability	Available only when bit #2 of the '_SND' cookie is set.

Parameters	track specifies the playback track to monitor (0-3).

Binding	move.w track,-(sp) move.w #$86,-(sp) trap #14 addq.l #4,sp

Return Value	Setmontracks() returns a 0 if the operation was successful or non-zero otherwise.

Setpalette()

VOID Setpalette( palette )

WORD *palette;

	Setpalette() loads the ST color lookup table with a new palette.

Opcode	6 (0x06)

Availability	All TOS versions.

Parameters	palette is a pointer to a WORD array containing 16 color encoded WORDs as defined in Setcolor().

Binding	pea palette move.w #$06,-(sp) trap #14 addq.l #6,sp

Comments	The actual palette data is not copied from the specified array until the next vertical blank interrupt. For this reason, this call should be followed by Vsync() to be sure the array memory is not modified or reallocated prior to the transfer.

See Also	Setcolor(), EsetPalette(), VsetRGB(), vs_color()

Setprt()

WORD Setprt( new )

WORD new;

	Setprt() sets the OS's current printer configuration bits.

Opcode	33 (0x21)

Availability	All TOS versions.

Parameters	new is a WORD bit array defined as follows:

		Mask	When clear	When Set
		0x01	Dot Matrix PRT_DOTMATRIX	Daisy Wheel PRT_DAISY
		0x02	Monochrome PRT_MONO	Color PRT_COLOR
		0x04	Atari Printer PRT_ATARI	Epson Printer PRT_EPSON
		0x08	Draft Mode PRT_DRAFT	Final Mode PRT_FINAL
		0x10	Parallel Port PRT_PARALLEL	Serial Port PRT_SERIAL
		0x20	Continuous Feed PRT_CONTINUOUS	Single Sheet Feed PRT_SINGLE
		-	Unused	Unused

	If new is set to PRT_INQUIRE (1) Setprt() will return the current configuration without modifying the current setup.

Binding	move.w new,-(sp) move.w #$33,-(sp) trap #14 addq.l #4,sp

Return Value	Setprt() returns the prior configuration.

Caveats	This call only affects the internal screen dump code which only operates on ST compatible resolutions.

See Also	Prtblk(), Scrdmp(), v_hardcopy()

Setscreen()

VOID Setscreen( log, phys, mode )

VOIDP log, phys;

WORD mode;

	Setscreen() changes the base addresses and mode of the current screen.

Opcode	5 (0x05)

Availability	All TOS versions.

Parameters	log is the address for the new logical screen base. phys is the new address for the physical screen base. mode defines the screen mode to switch to (same as Getrez()). If any of these three parameters is set to SCR_NOCHANGE (1) then that value will be left unchanged.

Binding	move.w mode,-(sp) pea phys pea log move.w #$5,-(sp) trap #14 lea 12(sp),sp

Caveats	Changing screen modes with this call does not reinitialize the AES. The VDI and VT52 emulator are, however, correctly reinitialized. The AES should not be used after changing screen mode with this call until the old screen mode is restored.

Comments	The Atari ST and Mega ST required that its physical screen memory be on a 256 byte boundary. All other Atari computers only require a WORD boundary.To access the unique video modes of the Falcon030 the call VsetScreen() (which is actually an alternate binding of this call with the same opcode) should be used in place of this call.

See Also	VsetMode(), VsetScreen(), EsetShift()

Settime()

VOID Settime( time )

LONG time;

	Settime() sets a new IKBD date and time.

Opcode	22 (0x16)

Availability	All TOS versions.

Parameters	time is a LONG bit array defined as follows:

		Bits	Meaning
		0-4	Seconds / 2 (0-29)
		5-10	Minute (0-59)
		11-15	Hour (0-23)
		16-20	Day (1-31)
		21-24	Month (1-12)
		25-31	Year - 1980 (0-127)

	The value can be represented in a C structure as follows: typedef struct { unsigned year:7; unsigned month:4; unsigned day:5; unsigned hour:5; unsigned minute:6; unsigned second:5; } BIOS_TIME;

Binding	move.l time,-(sp) move.w #$16,-(sp) trap #14 addq.l #6,sp

Comments	As of TOS 1.02, this function also updates the GEMDOS time.

See Also	Gettime(), Tsettime(), Tsetdate()

Settracks()

LONG Settracks( playtracks, rectracks )

WORD playtracks, rectracks;

	Setttracks() sets the number of recording and playback tracks.

Opcode	133 (0x85)

Availability	Available only when bit #2 of the '_SND' cookie is set.

Parameters	playtracks specifies the number of playback tracks (0-3) and rectracks specifies the number of recording tracks.

Binding	move.w rectracks,-(sp) move.w playtracks,-(sp) move.w #$85,-(sp) trap #14 addq.l #6,sp

Return Value	Settracks() returns 0 if the operation was successful or non-zero otherwise.

Comments	The tracks specified are stereo tracks. When in 8-bit Mono mode, two samples are read at a time.

See Also	Setmode(), Setmontracks()

Sndstatus()

LONG Sndstatus( reset )

WORD reset;

	Sndstatus() can be used to test the error condition of the sound system and to completely reset it.

Opcode	140 (0x8C)

Availability	Available only when bit #2 of the '_SND' cookie is set.

Parameters	reset is a flag indicating whether the sound system should be reset. A value of SND_RESET (1) will reset the sound system.

Binding	move.w reset,-(sp) move.w #$8C,-(sp) trap #14 addq.l #4,sp

Return Value	Sndstatus() returns a LONG bit array indicating the current error status of the sound system defined as follows:

		Bit(s)	Meaning
		0-3	These bits form a value indicating the error condition of the sound system as follows: Name Mask Meaning SND_ERROR 0xF Use to mask error code Name Value Meaning SND_OK 0 No Error SND_BADCONTROL 1 Invalid Control Field SND_BADSYNC 2 Invalid Sync Format SND_BADCLOCK 3 Clock out of range
		4	If this bit is set, left channel clipping has occurred. Use the mask SND_LEFTCLIP (0x10) to isolate this bit.
		5	If this bit is set, right channel clipping has occurred. Use the mask SND_RIGHTCLIP (0x20) to isolate this bit.
		6-31	Unused.

Comments	On reset, the following things happen: DSP is tristated Gain and attentuation are zeroed Old matrix connections are reset ADDERIN is disabled Mode is set to 8-Bit Stereo Play and record tracks are set to 0 Monitor track is set to 0 Interrupts are disabled Buffer operation is disabled

Soundcmd()

LONG Soundcmd( mode, data )

WORD mode, data;

	Soundcmd() sets various configuration parameters in the sound system.

Opcode	130 (0x82)

Availability	Available only when bit #2 of '_SND' cookie is set.

Parameters	mode specifies how data is interpreted as follows:

	Name	mode	Meaning
	LTATTEN	0	Set the left attenuation (increasing attentuation is the same as decreasing volume). data is a bit mask as follows: XXXX XXXX LLLL XXXX'L' specifies a valid value between 0 and 15 used to set the attenuation of the left channel in -1.5db increments. The bits represented by 'X' are reserved and should be 0.
	RATTEN	1	Set the right attentuation. data is a bit mask as follows: XXXX XXXX RRRR XXXX'R' specifies a valid value between 0 and 15 used to set the attenuation of the right channel in -1.5db increments. The bits represented by 'X' are reserved and should be 0.
	LTGAIN	2	Set the left channel gain (boost the input to the ADC). data is a bit mask as follows: XXXX XXXX LLLL XXXX'L' specifies a valid value between 0 and 15 used to set the gain of the left channel in 1.5db increments. The bits represented by 'X' are reserved and should be 0.
	RTGAIN	3	Set the right channel gain (boost the input to the ADC). data is a bit mask as follows: XXXX XXXX RRRR XXXX'R' specifies a valid value between 0 and 15 used to set the gain of the right channel in 1.5Db increments. The bits represented by 'X' are reserved and should be 0.
	ADDERIN	4	Set the 16 bit ADDER to receive its input from the source(s) specified in data. data is a bit mask where each bit indicates a possible souce. Bit 0 represents the ADC (ADDR_ADC). Bit 1 represents the connection matrix (ADDR_MATRIX). Setting either or both of these bits determines the source of the ADDER.
	ADCINPUT	5	Set the inputs of the left and right channels of the ADC. data is a bit mask with bit 0 being the right channel: LEFT_MIC (0x00) or LEFT_PSG (0x02) and bit 1 being the left channel: RIGHT_MIC (0x00) or RIGHT_PSG (0x01).Setting a bit causes that channel to receive its input from the Yamaha PSG. Clearing a bit causes that channel to receive its input from the microphone.
	SETPRESCALE	6	This mode is only valid when Devconnect() is used to set the prescaler to TT030 compatibility mode. In that case, data represents the TT030 compatible prescale value as follows:Name Value Meaning CCLK_6K 0 Divide by 1280 (6.25 MHz) CCLK_12K 1 Divide by 640 (12.5 Mhz) CCLK_25K 2 Divide by 320 (25 MHz) CCLK_50K 3 Divide by 160 (50 MHz)

	Setting data to SND_INQUIRE (-1) with any command will cause that command's current value to be returned and the parameter unchanged.

Binding	move.w data,-(sp) move.w mode,-(sp) move.w #$82,-(sp) trap #14 addq.l #6,sp

Return Value	Soundcmd() returns the prior value of the specified command if data is SND_INQUIRE (-1).Using the SETPRESCALE mode to set a frequency of 6.25 MHz (CCLK_6K) will cause the sound system to mute on a Falcon030 as it does not support this sample rate.

Caveats	On current systems, a bug exists that causes a mode value of LTGAIN to set the gain for both channels.

See Also	Devconnect()

Ssbrk()

VOIDP Ssbrk( len )

WORD len;

	Ssbrk() is designed to reserve memory at the top of RAM prior to the initialization of GEMDOS.

Opcode	1 (0x01)

Availability	All TOS versions.

Parameters	len is a WORD value specifying the number of bytes to reserve at the top of RAM.

Binding	move.w len,-(sp) move.w #$01,-(sp) trap #14 addq.l #4,sp

Return Value	Ssbrk() returns a pointer to the allocated block.

Caveats	Ssbrk() was only used on early development systems. Currently the function is unimplemented and does not do anything.

Supexec()

LONG Supexec( func )

LONG (*func)( VOID );

	Supexec() executes a user-defined function in supervisor mode.

Opcode	38 (0x26)

Availability	All TOS versions.

Parameters	func is the address to a function which will be called in supervisor mode.

Binding	pea func move.w #$26,-(sp) trap #14 addq.l #6,sp

Return Value	Supexec() returns the LONG value returned by the user function.

Caveats	Care must be taken when calling the operating system in supervisor mode. The AES must not be called while in supervisor mode.

See Also	Super()

Unlocksnd()

LONG Unlocksnd( VOID )

	Unlocksnd() unlocks the sound system so that other applications may utilize it.

Opcode	129 (0x81)

Availability	All TOS versions.

Binding	move.w #$81,-(sp) trap #14 addq.l #2,sp

Return Value	Unlocksnd() returns a 0 if the sound system was successfully unlocked or SNDNOTLOCK (-128) if the sound system wasn't locked prior to the call.

See Also	Locksnd()

VgetMonitor()

WORD VgetMonitor( VOID )

	VgetMonitor() returns a value which determines the kind of monitor currently being used. Thsi function mis alson sometimes referred to as mon_type () by some compilers.

Opcode	89 (0x59)

Availability	Available if the '_VDO' cookie has a value of 0x00030000 or greater.

Binding	move.w #$59,-(sp) trap #14 addq.l #2,sp

Return Value	VgetMonitor() returns a value describing the monitor currently connected to the system as follows:

		Name	Return Value	Monitor Type
		MON_MONO	0	ST monochrome monitor
		MON_COLOR	1	ST color monitor
		MON_VGA	2	VGA monitor
		MON_TV	3	Television

VgetRGB()

VOID VgetRGB( index, count, rgb )

WORD index, count;

RGB *rgb;

	VgetRGB() returns palette information as 24-bit RGB data.

Opcode	94 (0x5E)

Availability	Available if the '_VDO' cookie has a value of 0x00030000 or greater.

Parameters	index specifies the beginning color index in the palette to read data from. count specifies the number of palette entries to read. rgb is a pointer to an array of RGBs which will be filled in by the functions. RGB is defined as: typedef struct { BYTE reserved; BYTE red; BYTE green; BYTE blue; } RGB;

Binding	pea rgb move.w count,-(sp) move.w index,-(sp) move.w #$5E,-(sp) trap #14 lea 10(sp),sp

Comments	VgetRGB() is device-dependent in nature and it is therefore recommended that vq_color() be used instead.

See Also	VsetRGB()

VgetSize()

LONG VgetSize( mode )

WORD mode;

	VgetSize() returns the size of a screen mode in bytes.

Opcode	91 (0x5B)

Availability	Available if the '_VDO' cookie has a value of 0x00030000 or greater.

Parameters	mode is a modecode as defined in VsetMode().

Binding	move.w mode,-(sp) move.w #$5B,-(sp) trap #14 addq.l #4,sp

Return Value	VgetSize() returns the size in bytes of a screen mode of type mode.

VsetMask()

VOID VsetMask( ormask, andmask, overlay )

LONG ormask, andmask;

WORD overlay;

	VsetMask() provides access to 'overlay' mode.

Opcode	146 (0x92)

Availability	Available if the '_VDO' cookie has a value of 0x00030000 or greater.

Parameters	When the VDI processes a vs_color() call. It converts the desired color into a hardware palette register. In 16-bit true-color mode, this is a WORD formatted as follows: RRRR RGGG GGXB BBBB The 'X' is the system overlay bit. In 24-bit true color a LONG is formatted as follows: XXXXXXXX RRRRRRRR GGGGGGGG BBBBBBBB VsetMask() sets a logical OR and AND mask which are applied to this register before being stored. The default system value for ormask is 0x00000000 and the default value for andmask is 0xFFFFFFFF.overlay should be OVERLAY_ON (1) to enable overlay mode or OVERLAY_OFF (0) to disable it.

Binding	move.w overlay,-(sp) move.l andmask,-(sp) move.l ormask,-(sp) move.w #$92,-(sp) trap #14 lea 12(sp),sp

Comments	To make colors defined by the VDI transparent in 16-bit true color with overlay mode enabled, use an andmask value of 0xFFFFFFDF and an ormask value of 0x00000000. To make colors visible, use an andmask of 0x00000000 and an ormask of 0x00000020.

VsetMode()

WORD VsetMode( mode )

WORD mode;

	VsetMode() places the video shifter into a specific video mode.

Opcode	88 (0x58)

Availability	Available if the '_VDO' cookie has a value of 0x00030000 or greater.

Parameters	mode is a WORD bit array arranged as follows:

	Name	Bit(s)	Meaning
	BPS1 (0x00) BPS2 (0x01) BPS4 (0x02) BPS8 (0x03) BPS16 (0x04)	0-2	These bits form a value so that 2 ^ X represents the number of bits per pixel.
	COL80 (0x08) COL40 (0x00)	3	80 Column Flag (if set, 80 columns, otherwise 40)
	VGA (0x10) TV (0x00)	4	VGA Flag (if set, VGA mode will be used, otherwise television/monitor mode)
	PAL (0x20) NTSC (0x00)	5	PAL Flag (if set, PAL will be used, otherwise NTSC)
	OVERSCAN (0x40)	6	Overscan Flag (not valid with VGA)
	STMODES (0x80)	7	ST Compatibility Flag
	VERTFLAG (0x100)	8	Vertical Flag (is set, enables interlace mode on a color monitor or double-line mode on a VGA monitor)
	-	9-15	Reserved (set to 0)

	If mode is VM_INQUIRE (-1) then the current mode code is returned without changing the current settings.

Binding	move.w mode,-(sp) move.w #$58,sp trap #14 addq.l #4,sp

Return Value	VsetMode() returns the prior video mode.

Caveats	VsetMode() does not reset the video base address, reserve memory, or reinitialize the VDI. To do this, use VsetScreen().

Comments	Some video modes are not legal. 40 column monoplane modes and 80 column VGA true color modes are not supported.

See Also	VsetScreen(), Setscreen()

VsetRGB()

VOID VsetRGB( index, count, rgb )

WORD index, count;

RGB *rgb;

	VsetRGB() sets palette registers using 24-bit RGB values.

Opcode	93 (0x5D)

Availability	Available if the '_VDO' cookie has a value of 0x00030000 or greater.

Parameters	index specifies the first palette index to modify. count specifies the number of palette entries to modify. rgb is a pointer to an array of RGB elements which will be copied into the palette.

Binding	pea rgb move.w count,-(sp) move.w index,-(sp) move.w #$5D,-(sp) trap #14 lea 10(sp),sp

Comments	This call is device-dependent by nature. It is therefore recommended that vs_color() be used instead.

See Also	VgetRGB(), EsetPalette(), Setpalette(), vs_color()

VsetScreen()

VOID VsetScreen( log, phys, mode, modecode )

VOIDP log, phys;

WORD mode, modecode;

	VsetScreen() changes the base addresses and mode of the current screen.

Opcode	5 (0x05)

Availability	All TOS versions. The ability of this call to utilize the modecode parameter and the memory allocation feature is limited to systems having a '_VDO' cookie with a value of 0x00030000 or greater.

Parameters	log is the address for the new logical screen base. phys is the new address for the physical screen base. If either log or phys is NULL, the XBIOS will allocate a new block of memory large enough for the current screen and reset the parameter accordingly. mode defines the screen mode to switch to (same as Getrez()). Setting mode to SCR_MODECODE (3) will cause modecode to be used to set the graphic mode (see VsetMode() for valid values for this parameter), otherwise modecode is ignored. If any of these three parameters is set to SCR_NOCHANGE (1) then that value will be left unchanged.

Binding	move.w modecode,-(sp) move.w mode,-(sp) pea phys pea log move.w #$05,-(sp) trap #14 lea 14(sp),sp

Caveats	Changing screen modes with this call does not reinitialize the AES. The VDI and VT52 emulator are, however, correctly reinitialized. The AES should not be used after changing screen mode with this call until the old screen mode is restored.

Comments	TOS 1.00 and 1.02 required that its physical screen memory be on a 256 byte boundary. All other Atari computers only require a WORD boundary.This call is actually a revised binding of Setscreen() developed to allow access to the newly available modecode parameter.

See Also	Setscreen(), VsetMode()

VsetSync()

VOID VsetSync( external )

WORD external;

	VsetSync() sets the external video sync mode.

Opcode	90 (0x5A)

Availability	Available if the '_VDO' cookie has a value of 0x00030000 or greater.

Parameters	external is a WORD bit array defined as follows:

		Name	Bit	Meaning
		VCLK_EXTERNAL	0	Use external clock.
		VCLK_EXTVSYNC	1	Use external vertical sync.
		VCLK_EXTHSYNC	2	Use external horizontal sync.
		-	3-15	Reserved (set to 0)

Binding	move.w external,-(sp) move.w #$5A,-(sp) trap #14 addq.l #4,sp

Caveats	This call only works in Falcon video modes, not in compatibility or any four color modes.

Vsync()

VOID Vsync( VOID )

	Vsync() pauses program execution until the next vertical blank interrupt.

Opcode	37 (0x25)

Availability	All TOS versions.

Binding	move.w #$25,-(sp) trap #14 addq.l #2,sp

WavePlay()

WORD WavePlay( flags, rate, sptr, slen )

WORD flags;

LONG rate;

VOIDP sptr;

LONG slen;

	WavePlay() provides a easy method for applications to utilize the DMA sound system on the STe, TT030, and Falcon030 and playback user-defined event sound effects.

Opcode	165 (0xA5)

Availability	Available only when the 'SAM\0' cookie exists.

Parameters	flags is a bit mask consisting of the following options:

		Name		Mask		Meaning
		WP_MONO		0x00		The sound to be played back is monophonic.
		WP_STEREO		0x01		The sound to be played back is in stereo.
		WP_8BIT		0x00		The sound to be played back was sampled at 8-bit resolution.
		WP_16BIT		0x02		The sound to be played back was sampled at 16-bit resolution.
		WP_MACRO		0x100		Play back a user-assigned macro or application global sound effect. This flag is exclusive and modifies the meaning of the other parameters to this call as shown below.

	rate specifies the sample rate in Hertz (for example 49170L to play back at 49170 Hz). If WP_MACRO was specified in flags, then this parameter is ignored and should be set to 0L.sptr is a pointer to the sound sample in memory. If WP_MACRO was specified in flags then this parameter should be a LONG containing either the application cookie specified in the .SAA file or the 'SAM\0' cookie to play an application global.slen is the length of the sample in bytes. If WP_MACRO was specified in flags then slen is the macro or application global index as specified in the .SAA file. Valid application global values are as follows:

	Name		slen		Usage
	AG_FIND		0		Call WavePlay() with this value when the user requests display of the 'Find' dialog box.
	AG_REPLACE		1		Call WavePlay() with this value when the user requests display of the 'Replace' dialog box.
	AG_CUT		2		Call WavePlay() with this value when the user requests a 'Cut' operation.
	AG_COPY		3		Call WavePlay() with this value when the user requests a 'Copy' operation.
	AG_PASTE		4		Call WavePlay() with this value when the user requests a 'Paste' operation.
	AG_DELETE		5		Call WavePlay() with this value when the user requests a 'Delete' operation. This should not be called when the user presses the 'Delete' key.
	AG_HELP		6		Call WavePlay() with this value when the user requests display of application 'Help.' This should not be called when the user presses the 'Help' key.
	AG_PRINT		7		Call WavePlay() with this value when the user requests display of the 'Print' dialog box.
	AG_SAVE		8		Call WavePlay() with this value when the user requests that the current document be saved. This should not be used for any operation that calls the file selector.
	AG_ERROR		9		Call WavePlay() with this value when the application encounters an error not presented to the user in an alert or error dialog (error dialogs may be assigned sounds).
	AG_QUIT		10		Call WavePlay() with this value when the user requests that the application exit. Use this global after the user has confirmed a quit with any dialog box that may have been necessary.

Binding	move.l slen,-(sp) pea sptr move.l rate,-(sp) move.w flags,-(sp) move.w #$A5,-(sp) trap #14 lea 16(sp),sp

Return Value	WavePlay() returns WP_OK (0) if the call was successful, WP_ERROR (-1) if an error occurred, or WP_NOSOUND (1) to indicate that no sound was played (either because the user had not previously assigned a sound to the given macro or SAM was disabled).

Caveats	This function is only available when the System Audio Manager TSR (available from Atari Corp. or SDS) is installed. Extended development information is available online the Atari Developer's roundtable on GEnie.Because of previously misdocumented sample rates, the value for rate must be 33880 to play back a sample at 32880 Hz, 20770 to play back a sample at 19668 Hz, and 16490 to play back a sample at 16390 Hz.

Comments	Even if an application does not install any custom events in a .SAA file, an application must still provide a .SAA file if it wishes to use application globals so that the SAM configuration accessory allows the user to assign those sounds.A macro is commonly used to access the application global sounds available as follows: #define WavePlayMacro(a) WavePlay( WP_MACRO, 0L, SAM_COOKIE, a );

Xbtimer()

VOID Xbtimer( timer, control, data, hand )

WORD timer, control, data;

VOID (*hand)( VOID );

	Xbtimer() sets an interrupt on the 68901 chip.

Opcode	31 (0x1F)

Availability	All TOS versions.

Parameters	timer is a value defining which timer to set as follows:

		Name	Timer	Meaning
		XB_TIMERA	0	Timer A (DMA sound counter)
		XB_TIMERB	1	Timer B (Hblank counter)
		XB_TIMERC	2	Timer C (200Hz system clock)
		XB_TIMERD	3	Timer D (RS-232 baud rate generator)

	control is placed into the control register of the timer. data is placed in the data register of the timer. hand is a pointer to the interrupt handler which is called by the interrupt.

Binding	pea hand move.w data,-(sp) move.w control,-(sp) move.w timer,-(sp) move.w #$1F,-(sp) trap #14 lea 12(sp),sp

See Also	Mfpint(), Jenabint(), Jdisint()

Table of Contents | Index