Each of the sixteen color registers is bitmapped into a WORD as follows (The first row indicates color, the second is bit significance):
xxxx xRRR xGGG xBBB xxxx x321 x321 x321
The STe series expanded the color depth to four bits instead of three which expanded the number of available colors from 512 to 4096. This changed the layout of these color WORDs as follows:
xxxx RRRR GGGG BBBB xxxx 1432 1432 1432
This odd bit layout allowed for backward compatibility to the
ST series.
The TT030 supports an expanded palette of 256 entries in 16 banks
containing any of 4096 colors. The first bank of colors is still
supported by Setcolor() and Setpalette(), however
to access the additional 240 colors, 4 additional palette support
calls were added.
Esetpalette(), Egetpalette(), and Esetcolor()
provide access to these colors in a similar manner to Setpalette()
and Setcolor(). Esetbank() switches between the
16 available banks of colors in color modes that support less
than 16 colors. You should note that the TT030 color calls returned
the color WORDs to normal bit ordering as follows:
When using the TT's special gray mode, the lower eight bits of
each hardware register is used as a gray value from 0-255.
The Falcon030 computer gives up the TT030 calls in favor of a
more portable method of setting the hardware palette (ST calls
will remain as compatible as possible). VsetRGB() and VgetRGB()
set color palette entries based on 24-bit true color values. The
XBIOS will scale these values as appropriate for the screen
mode.
Vsync() halts all further processing by the application
until a vertical blank interrupt occurs. This interrupt signals
that the video display gun has reached the bottom of the display
and is returning to the top. At this time, a brief period occurs
where updates to the screen will not be immediately apparent to
the user. This time is usually used to present flicker-free animation
and redraws.
VsetSync() is used to enable external hardware video synchronization
for devices such as GENLOCK's. Both the vertical and horizontal
syncronizations may be set independent of each other with this
call.
VsetMask() provides easy access to the Falcon030's overlay
mode. This call allows you to specify bits which will be added
or removed to future color definitions created with the VDI
call vs_color(). When a GENLOCK hardware device is connected,
pixels with their overlay bit cleared will be replaceable by the
device with external video.
XBIOS sound system calls are only present as of the Falcon030
computer (though their presence should always be verified by the
'_SND' cookie). If you want to program digitized audio that plays
on an STe, TT, and Falcon030, see Chapter 5: Hardware.
The Falcon030 sound system consists of four stereo 16-bit DMA
playback and record channels, an onboard ADC (microphone jack),
DAC (speaker and headphone jack), connection matrix, and digital
signal processor.
When your application uses the sound system you should first lock
it with Locksnd(). This ensures that other system processes
don't try to access the sound system simultaneously. Unlocksnd()
should be used as soon as the sound system is free.
Each of four possible source devices can be connected to any or
all of the four possible destination devices using the connection
matrix as follows:
The external input and output are accessible with a specially
designed hardware device connected to the DSP connector.
The sound system call Devconnect() connects sound system
components together. You must specify the source device, destination
device(s), source clock, prescaler setting, and handshaking protocol.
The source clock can be set to either of two internal clocks (25.175
MHz and 32 MHz) or an external clock. The internal DMA sound routines
are only compatible with the 25.175 MHz clock. Other clock sources
are used in conjunction with external hardware devices.
The prescaler sets the actual sample playback and recording rate.
A value of 0 will cause the sound system to use a STe/ TT030 compatible
prescaler for outputting sound recorded at STe/TT030 frequencies.
One STe/TT030 frequency, 6.258 kHz, is not supported on the Falcon030.
You can set the STe/TT030 prescaler with the Soundcmd()
call. Using values other than 0 will set the Falcon030 prescaler
as documented under the Devconnect() call.
The last parameter you must pass to Devconnect() specifies
whether to enable or disable hardware handshaking. Enabling handshaking
will produce data that is 100% error free but will result in a
variable transfer rate which may negatively affect digital sound.
Handshaking is generally only enabled when the data being transferred
must be transferred without errors (usually compressed audio or
video data).
To record or playback an audio sample, use Setbuffer()
to identify the location and length of your playback/recording
buffer. Also, any Devconnect(), Setmode(), and Soundcmd()
calls should be made prior to starting your playback/recording
to set the sound hardware to the proper frequency and mode.
The Falcon030 only supports the recording of 16-bit stereo
audio. To generate 8-bit samples you must scale the values in
the buffer from WORDs to BYTEs after recording.
When processing either recording or playback through the DSP,
the command Dsptristate() must be used to connect the DSP
to the matrix.
You may use the function Setinterrupt(), as desired, to
cause a MFP or Timer A interrupt at the end of every frame. This
is most useful when you are playing or recording in repeat mode
and you wish to use multiple buffers.
Buffptr() may be used to determine the current playback
or record buffer pointer as sounds are being played/recorded.
Setmontracks() is used to define which track which will
be output over the computer speaker/headphones. Settracks()
controls which tracks will be used to record/playback data.
The function Soundcmd() has four modes which allow the
setting and interrogation of the current levels of attenuation
and gain. Gain affects input levels. The higher the value for
gain, the louder the microphone input will be. Attenuation affects
output levels. The higher the attenuation setting, the softer
sounds will be output from the computer speaker/headphone jack.
Sndstatus() can be used to tell if a source clock rate
was correctly set or if hardware clipping has occurred on either
channel.
Gpio() is used to communicate data over the three general
purpose pins of the DSP connector.
The Falcon030 comes standard with a Motorola 56001 digital signal
processor (DSP). Digital signal processors are useful for many
different purposes such as audio/video compression, filtering,
encryption, modulation, and math functions.
The DSP is able to support both programs and subroutines. Both
must be written in 56001 assembly language (or a language which
outputs 56001 object code). A full treatment of 56001 assembly
language is beyond the scope of this document. Consult the DSP56000/56001
Digital Signal Processor's User Manual published by Motorola,
Inc. for more information.
The DSP is capable of having many subroutines resident in memory,
however, only one program may be loaded at any time.
When using the DSP you should call Dsp_Lock() to prevent
other processes from modifying your setup and to ensure that you
do not modify the work of other processes. Call Dsp_Unlock()
when done (the DSP's MR and IPR registers should have been returned
to their original state) to release the DSP semaphore.
The Falcon030's DSP contains 96K bytes of RAM for system programs,
user programs, and subroutines. The DSP uses three distinct address
spaces, X, Y, and P. Program memory (P) overlaps both X and Y
memory spaces. Because of this, DSP programs should be careful
when referencing memory. The following is a memory map of the
DSP:
The 56001 uses a 24-bit WORD. Future Atari computers may
use different DSP's with different WORD sizes. Use the
Dsp_GetWordSize() call prior to using the DSP to determine
the proper DSP WORD size.
Subroutines are usually short programs (no longer than 1024 DSP
WORDs) which transform incoming data. Each subroutine must
be written to be fully relocatable. When writing subroutines,
start instructions at location $0. All addresses in the subroutine
must be relocatable based on the original PC of $0 in order to
function. An alternative to this is to include a stub program
at the start of your subroutine that performs a relocation based
upon the start address assigned by the XBIOS (which is
available in X:HRX at subroutine start).
Subroutines should store initialized data within its program space.
The memory area from $3f00-$3fff is reserved for use as the BSS
of subroutines. Subroutines must not rely on the BSS's data to
remain constant between subroutine calls.
Each subroutine must be assigned a unique ability code either
by using one predefined by Atari (none have been published yet)
or by using the Dsp_RequestUniqueAbility() call. Since
subroutines are only flushed from the DSP when necessary, an application
may be able to use an existing subroutine with the same ability
left by another application by using the Dsp_InqrSubrAbility()
call.
Here is a sample of how to load a DSP subroutine with a non-unique
ability code:
Only one DSP program may be resident in memory at once. Prior
to loading a DSP program you should ensure enough memory is available
for your program by calling Dsp_Available(). If not enough
memory is available, you may have to flush resident subroutines
to free enough memory.
After you have found that enough memory is available, you must
reserve it with Dsp_Reserve(). This memory will be reserved
until the next Dsp_Reserve() call so you should ensure
that you have called Dsp_Lock() to block other processes
from writing over your program.
Programs can be stored in either binary or ASCII ('.LOD') format.
The function Dsp_LodToBinary() can be used to convert this
data. DSP programs in binary form load much faster than those
in the '.LOD' format.
Dsp_LoadProg() is used to execute programs stored on disk
in the '.LOD' format. Dsp_ExecProg() is used to execute
programs stored in memory in binary format.
As with subroutines, programs are assigned a unique ability code
that can be determined with Dsp_GetProgAbility().
Several functions transfer data to and from DSP programs and subroutines
as follows:
Dsp_DoBlock()
Dsp_BlkHandshake()
Dsp_BlkUnpacked()
Dsp_BlkWords()
Dsp_BlkBytes()
Dsp_MultBlocks()
Dsp_InStream()
Dsp_OutStream()
You should read the description of each in the function reference
and decide which is best suited for your needs.
Dsp_SetVectors() installs special purpose routines that
are called when the DSP sends an interrupt indicating it is ready
to send or receive data. Dsp_RemoveInterrupts() removes
these routines from the vector table in memory.
The HFx bits of the HSR register can be read atomically with the
four calls Dsp_Hf0(), Dsp_Hf1(), Dsp_Hf2(),
and Dsp_Hf3(). The current value of the ISR register may
be read with Dsp_Hstat().
DSP programs may also define special host commands at DSP vectors
$13 and $14 to be triggered by the command DSP_TriggerHC().
When full control over the DSP is necessary (such is the case
for specialized debuggers), the command Dsp_ExecBoot()
can be used to download up to 512 DSP WORDs of bootstrap
code. The DSP will be reset before this happens. This call should
only be used by advanced applications as it will cause other DSP
functions to stop working unless those functions are properly
supported.
The XBIOS call Supexec() provides access to a special
mode of the 680x0 processor called supervisor mode. Normal programs
always execute in user mode. Programs operating in user mode,
however, have less memory access privileges than those operating
in supervisor mode.
Some special instructions of the 680x0 may only be executed in
supervisor mode. In addition, any memory reads or writes to locations
$0-$7FF or memory-mapped I/O must be made in supervisor mode.
To use Supexec(), simply pass it the address of a function
to be called. When writing the function in 'C', you should be
careful to define the function in a way that is safe for your
compiler (see your compiler documentation for details).
While in supervisor mode, the AES should never be called.
One special XBIOS opcode, Metainit() was reserved
for a TOS extension called MetaDOS. MetaDOS
was designed to supplement the OS to allow for more than 16 drives
and to provide the extra support needed for CD-ROM drives. MetaDOS
is no longer officially supported by Atari because of the increased
functionality of MultiTOS.
MultiTOS allows the use of all 26 drive letters as well
as providing loadable device drivers and file systems. See Chapter
2: GEMDOS for more information.
The XBIOS has several functions that provide extended control
over the keyboard and mouse. These functions should be used with
care, however, as the keyboard and mouse are 'global' devices
shared by other processes.
Initmous() is used to change the way the keyboard controller
reports mouse movements to the system. Changing this mode will
cause the AES and VDI to be unable to recognize
mouse input.
Keytbl() allows you to read and manipulate the tables which
translate IKBD scan codes into ASCII codes. This is essential
when you want your application to run on Atari machines with foreign
keyboards. Use Keytbl() to return a pointer to the internal
table structure and then convert keycodes into ASCII by looking
codes up in the appropriate table.
TOS versions 5.0 and greater support the loading of external
keyboard tables when the '_AKP' cookie is present. In this case,
if a file called 'KEYTBL.TBL' is found in the '\MULTITOS' directory
of the boot drive, it will be loaded upon bootup to provide keyboard
mapping changes. The format of the file is as follows:
Advanced Video
The Falcon030 Sound System
The Connection Matrix
Recording/Playing Digital Audio
Configuring Levels
Other Calls
The DSP
DSP Memory
DSP Word Size
DSP Subroutines
if(!DSP_Lock())
{
ability = DSP_RequestUniqueAbility();
handle = DSP_LoadSubroutine( subptr, length, ability );
if(!handle)
{
DSP_FlushSubroutines();
handle = DSP_LoadSubroutine( subptr, length, ability );
if(!handle)
error("Unable to load DSP subroutine");
}
if(handle)
{
if(!Dsp_RunSubroutine( handle ))
DSP_DoBlock( data_in, size_in, data_out, size_out);
else
error("Unable to run DSP subroutine!");
}
}
DSP Programs
Sending Data to the DSP
DSP State
DSP Debugging
User/Supervisor Mode
MetaDOS
Keyboard and Mouse Control
Loadable XBIOS Keyboard Tables