Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-FileDSP MC 56001
DSP Macro Assembler
Chips & Chips

                                   The DSP


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.

DSP Memory

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:



DSP Word Size

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.

DSP Subroutines

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_InqSubrAbility() call.

Here is a sample of how to load a DSP subroutine with a non-unique
ability code:

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

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().

Sending Data to the DSP

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.

DSP State

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().

DSP Debugging

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.