4.11 DSP programming

On the Falcon, the following routines for programming the DSP-56001 digital signal processor are available:

• Dsp_Available	Obtains amount of free memory.
• Dsp_BlkBytes	Bytewise data transfer.
• Dsp_BlkHandShake	Data transfer with handshake.
• Dsp_BlkUnpacked	Transfer of DSP-words (max. 4 byte long).
• Dsp_BlkWords	Wordwise data transfer.
• Dsp_DoBlock	Data transfer to the DSP.
• Dsp_ExecBoot	Loads bootstrap program for the DSP.
• Dsp_ExecProg	Executes DSP program.
• Dsp_FlushSubroutines	Removes subroutines.
• Dsp_GetProgAbility	Requests identification of a process.
• Dsp_GetWordSize	Obtains size of a DSP-word.
• Dsp_Hf0	Sets or clears bit 3 of the HSR.
• Dsp_Hf1	Sets or clears bit 4 of the HSR.
• Dsp_Hf2	Inquires bit 3 of the HCR.
• Dsp_Hf3	Inquires bit 4 of the HCR.
• Dsp_HStat	Inquires value of the ISR-register.
• Dsp_InqSubrAbility	Inquires subroutine identifier.
• Dsp_InStream	Data transfer to DSP via an interrupt.
• Dsp_IOStream	Data transfer from and to DSP via two interrupts.
• Dsp_LoadProg	Loads and executes DSP-program.
• Dsp_LoadSubroutine	Installs a subroutine.
• Dsp_Lock	Inquires availability of the DSP.
• Dsp_LodToBinary	Converts LOD to Binary format.
• Dsp_MultBlocks	Data transfer from and to DSP.
• Dsp_OutStream	Data transfer from DSP via an interrupt.
• Dsp_RemoveInterrupts	Turns off generation of DSP interrupts.
• Dsp_RequestUniqueAbility	Generates an identifier.
• Dsp_Reserve	Reserves DSP memory for use by a program.
• Dsp_RunSubroutine	Starts execution of a subroutine.
• Dsp_SetVectors	Installs custom transfer routines.
• Dsp_TriggerHC	Executes host command.
• Dsp_Unlock	Releases DSP.

4.11.1 Dsp_Available

Name:	»Dsp_Available« - Inquire amount of free X and Y memory space.
Opcode:	106
Syntax:	void Dsp_Available( int32_t xavailable, int32_t yavailable );
Description:	The function Dsp_Available inquires amount of free X and Y DSP memory. Free memory always starts at the physical address 0. The lowest 64 words are reserved for interrupt vectors.
Return value:	The function does not return a result.
Availability:	The function is available only on computers with the DSP-56001 signal processor
Group:	DSP programming
See also:	Binding Dsp_Lock Dsp_Unlock Dsp_Reserve Dsp_LoadProg Dsp_ExecProg Dsp_ExecBoot

4.11.1.1 Bindings for Dsp_Available

C:	#include <tos.h> void Dsp_Available( int32_t xavailable, int32_t yavailable );
Assembler:	pea yavailable ; Offset 6 pea xavailable ; Offset 2 move.w #106,-(sp) ; Offset 0 trap #14 ; Call XBIOS lea $A(sp),sp ; Correct stack

4.11.2 Dsp_BlkBytes

Name:	»Dsp_BlkBytes« - Bytewise data transfer to the DSP.
Opcode:	124
Syntax:	void Dsp_BlkBytes( void data_in, int32_t size_in, void data_out, int32_t size_out );
Description:	The function copies size_in unsigned bytes from the buffer data_in to the DSP. After all data has been transferred, the procedure waits until the data has been processed. Then size_out 8-bit DSP-words are copied back into the buffer data_out, irrespective of how much data is actually present. If no data is to be sent, one has to set size_in to zero. The same applies for the receipt; in that case size_out is assigned zero. size_in and size_out are limited to 64 kbyte. Data is only exchanged when the DSP process is ready for this.
Return value:	The function does not return a result.
Availability:	The function is available only on computers with the DSP-56001 signal processor
Group:	DSP programming
See also:	Binding Dsp_DoBlock Dsp_BlkUnpacked Dsp_BlkHandShake Dsp_BlkWords Dsp_InStream Dsp_OutStream Dsp_IOStream Dsp_GetWordSize Dsp_MultBlocks

4.11.2.1 Bindings for Dsp_BlkBytes

C:	#include <tos.h> void Dsp_BlkBytes( void data_in, int32_t size_in, void data_out, int32_t size_out );
Assembler:	move.l size_out,-(sp) ; Offset 14 pea data_out ; Offset 10 move.l size_in,-(sp) ; Offset 6 pea data_in ; Offset 2 move.w #124,-(sp) ; Offset 0 trap #14 ; Call XBIOS lea $12(sp),sp ; Correct stack

4.11.3 Dsp_BlkHandShake

Name:	»DspBlkHandShake« - Data transfer to DSP with handshake.
Opcode:	97
Syntax:	void Dsp_BlkHandShake( int8_t data_in, int32_t size_in, int8_t data_out, int32_t size_out );
Description:	The function copies size_in DSP-words from the buffer data_in to the DSP. After all data has been transferred, the procedure waits until the data has been processed. Then size_out DSP-words are copied back into the buffer data_out, irrespective of how much data is actually present. If no data is to be sent, one has to set size_in to zero. The same applies for the receipt; in that case size_out is assigned zero. size_in and size_out are limited to 64 kbyte. Data is only exchanged when the DSP process is ready for this.
Return value:	The function does not return a result.
Availability:	The function is available only on computers with the DSP-56001 signal processor
Group:	DSP programming
See also:	Binding Dsp_DoBlock Dsp_BlkUnpacked Dsp_BlkWords Dsp_BlkBytes Dsp_InStream Dsp_OutStream Dsp_IOStream Dsp_GetWordSize Dsp_MultBlocks

4.11.3.1 Bindings for Dsp_BlkHandShake

C:	#include <tos.h> void Dsp_BlkHandShake( int8_t data_in, int32_t size_in, int8_t data_out, int32_t size_out );
Assembler:	move.l size_out,-(sp) ; Offset 14 pea data_out ; Offset 10 move.l size_in,-(sp) ; Offset 6 pea data_in ; Offset 2 move.w #97,-(sp) ; Offset 0 trap #14 ; Call XBIOS lea $12(sp),sp ; Correct stack

4.11.4 Dsp_BlkUnpacked

Name:	»Dsp_BlkUnpacked« - Data transfer of DSP-words with a maximum length of 4 bytes (longword array).
Opcode:	98
Syntax:	void Dsp_BlkUnpacked( int32_t data_in, int32_t size_in, int32_t data_out, int32_t size_out );
Description:	This function only works with DSP-words having a maximum length of 4 bytes. The length of the DSP-words can be found with Dsp_GetWordSize. Both data_in and data_out are LONG fields. size_in and size_out refer to the size of the fields in longwords. Depending on the length of the DSP-word, only the lower bytes are transferred to the LONGs. The function copies size_in DSP-words from the buffer data_in to the DSP. After all data has been transferred, the procedure waits until the data has been processed. Then size_out DSP-words are copied back into the buffer data_out, irrespective of how much data is actually present. If no data is to be sent, one has to set size_in to zero. The same applies for the receipt; in that case size_out is assigned zero. size_in and size_out are limited to 64 kbyte. There is no guarantee that the higher-valued bytes of the received LONGs are zero when the DSP-wordlength is less than 4.
Return value:	The function does not return a result.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_DoBlock Dsp_BlkHandShake Dsp_BlkWords Dsp_BlkBytes Dsp_InStream Dsp_OutStream Dsp_IOStream Dsp_GetWordSize Dsp_MultBlocks

4.11.4.1 Bindings for Dsp_BlkUnpacked

C:	#include <tos.h> void Dsp_BlkUnpacked( int32_t data_in, int32_t size_in, int32_t data_out, int32_t size_out );
Assembler:	move.l size_out,-(sp) ; Offset 14 pea data_out ; Offset 10 move.l size_in,-(sp) ; Offset 6 pea data_in ; Offset 2 move.w #98,-(sp) ; Offset 0 trap #14 ; Call XBIOS lea $12(sp),sp ; Correct stack

4.11.5 Dsp_BlkWords

Name:	»Dsp_BlkWords« - Wordwise data transfer of an array of WORDS to the DSP.
Opcode:	123
Syntax:	void Dsp_BlkWords( void data_in, int32_t size_in, void data_out, int32_T size_out );
Description:	The function copies size_in signed 16-bit words from the buffer data_in to the DSP. The words are extended to signed DSP-wordlength before transfer. After all data has been transferred, the procedure waits until the data has been processed. Then size_out 16-bit DSP-words are copied back into the buffer data_out, irrespective of how much data is actually present. If no data is to be sent, one has to set size_in to zero. The same applies for the receipt; in that case size_out is assigned zero. size_in and size_out are limited to 64 kbyte. Data is only exchanged when the DSP process is ready for this.
Return value:	The function does not return a result.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_DoBlock Dsp_BlkUnpacked Dsp_BlkHandShake Dsp_BlkBytes Dsp_InStream Dsp_OutStream Dsp_IOStream Dsp_GetWordSize Dsp_MultBlocks

4.11.5.1 Bindings for Dsp_BlkWords

C:	#include <tos.h> void Dsp_BlkWords( void data_in, int32_t size_in, void data_out, int32_T size_out );
Assembler:	move.l size_out,-(sp) ; Offset 14 pea data_out ; Offset 10 move.l size_in,-(sp) ; Offset 6 pea data_in ; Offset 2 move.w #123,-(sp) ; Offset 0 trap #14 ; Call XBIOS lea $12(sp),sp ; Correct stack

4.11.6 Dsp_DoBlock

Name:	»Dsp_DoBlock« - Data transfer to the DSP
Opcode:	96
Syntax:	void Dsp_DoBlock( int8_t data_in, int32_t size_in, int8_t data_out, int32_t size_out );
Description:	The function copies size_in DSP-words from the buffer data_in to the DSP. After all data has been transferred, the procedure waits until the data has been processed. Then size_out DSP-words are copied back into the buffer data_out, irrespective of how much data is actually present. If no data is to be sent, one has to set size_in to zero. The same applies for the receipt; in that case size_out is assigned zero. size_in and size_out are limited to 64 kbyte.
Return value:	The function does not return a result.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_BlkHandShake Dsp_BlkUnpacked Dsp_BlkWords Dsp_BlkBytes Dsp_InStream Dsp_OutStream Dsp_IOStream Dsp_GetWordSize Dsp_MultBlocks

4.11.6.1 Bindings for Dsp_DoBlock

C:	#include <tos.h> void Dsp_DoBlock( int8_t data_in, int32_t size_in, int8_t data_out, int32_t size_out );
Assembler:	move.l size_out,-(sp) ; Offset 14 pea data_out ; Offset 10 move.l size_in,-(sp) ; Offset 6 pea data_in ; Offset 2 move.w #96,-(sp) ; Offset 0 trap #14 ; Call XBIOS lea $12(sp),sp ; Correct stack

4.11.7 Dsp_ExecBoot

Name:	»Dsp_ExecBoot« - Load bootstrap program into the DSP.
Opcode:	110
Syntax:	void Dsp_ExecBoot( int8_t *codeptr, int32_t codesize, int16_t ability );
Description:	The function Dsp_ExecBoot loads a bootstrap program into 512 words of the internal DSP memory. Before loading, the DSP is completely reset. The DSP program must be present in a binary format. The parameter codeptr points to the start of the program data. The length of the program is specified by the parameter codesize (in DSP-words). ability identifies the program.
Return value:	The function does not return a result.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_Lock Dsp_Unlock Dsp_Available Dsp_Reserve Dsp_LoadProg Dsp_ExecProg Dsp_LodToBinary

4.11.7.1 Bindings for Dsp_ExecBoot

C:	#include <tos.h> void Dsp_ExecBoot( int8_t *codeptr, int32_t codesize, int16_t ability );
Assembler:	move.w ability,-(sp) ; Offset 10 move.l codesize,-(sp) ; Offset 6 pea codeptr ; Offset 2 move.w #110,-(sp) ; Offset 0 trap #14 ; Call XBIOS lea $C(sp),sp ; Correct stack

4.11.8 Dsp_ExecProg

Name:	»Dsp_ExecProg« - Execute DSP program.
Opcode:	109
Syntax:	void Dsp_ExecProg( int8_t *codeptr, int32_t codesize, int16_t ability );
Description:	The function Dsp_ExecProg transfers a DSP program stored in binary format in memory at the location codeptr and length codesize to the DSP and executes it. Its size may not exceed the memory reserved by Dsp_Reserve. The parameter ability identifies the program.
Return value:	The function does not return a result.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_Lock Dsp_Unlock Dsp_Available Dsp_Reserve Dsp_LoadProg Dsp_ExecBoot Dsp_LodToBinary

4.11.8.1 Bindings for Dsp_ExecProg

C:	#include <tos.h> void Dsp_ExecProg( int8_t *codeptr, int32_t codesize, int16_t ability );
Assembler:	move.w ability,-(sp) ; Offset 10 move.l codesize,-(sp) ; Offset 6 pea codeptr ; Offset 2 move.w #109,-(sp) ; Offset 0 trap #14 ; Call XBIOS lea $C(sp),sp ; Correct stack

4.11.9 Dsp_FlushSubroutines

Name:	»Dsp_FlushSubroutines« - Remove subroutines from the memory of the DSP.
Opcode:	115
Syntax:	void Dsp_FlushSubroutines( void );
Description:	The function Dsp_FlushSubroutines removes all subroutines from the DSP's memory, and so increases the amount of available free memory.
Return value:	The function does not return a result.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_LoadSubroutine Dsp_InqSubrAbility Dsp_RunSubroutine

4.11.9.1 Bindings for Dsp_FlushSubroutines

C:	#include <tos.h> void Dsp_FlushSubroutines( void );
Assembler:	move.w #115,-(sp) ; Offset 0 trap #14 ; Call XBIOS addq.l #2,sp ; Correct stack

4.11.10 Dsp_GetProgAbility

Name:	»Dsp_GetProgAbility« - Request identification of a process.
Opcode:	114
Syntax:	int16_t Dsp_GetProgAbility( void );
Description:	The function Dsp_GetProgAbility assigns an identifier to a DSP process, with which one can check whether the code belonging to the process is already present in the DSP.
Return value:	The function returns the identifier valid for the process.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_RequestUniqueAbility

4.11.10.1 Bindings for Dsp_GetProgAbility

C:	#include <tos.h> int16_t Dsp_GetProgAbility( void );
Assembler:	move.w #114,-(sp) ; Offset 0 trap #14 ; Call XBIOS addq.l #2,sp ; Correct stack

4.11.11 Dsp_GetWordSize

Name:	»Dsp_GetWordSize« - Obtain the size of a DSP-word.
Opcode:	103
Syntax:	int16_t Dsp_GetWordSize( void );
Description:	The function Dsp_GetWordSize obtains the length, in bytes, of a DSP-word. This function is required to dimension the buffers for data transfer adequately.
Return value:	The function returns the size of a DSP-word.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_DoBlock Dsp_BlkUnpacked Dsp_BlkHandShake Dsp_BlkWords Dsp_BlkBytes Dsp_InStream Dsp_IOStream Dsp_OutStream Dsp_MultBlocks

4.11.11.1 Bindings for Dsp_GetWordSize

C:	#include <tos.h> int16_t Dsp_GetWordSize( void );
Assembler:	move.w #103,-(sp) ; Offset 0 trap #14 ; Call XBIOS addq.l #2,sp ; Correct stack

4.11.12 Dsp_Hf0

Name:

»Dsp_Hf0« - Set or clear bit 3 of the HSR.

Opcode:

119

Syntax:

int16_t Dsp_Hf0( int16_t flag );

Description:

The function Dsp_Hf0 obtains or resp. sets the value of bit 3 of the HSR register. The parameter flag has the following meaning:

flag	Meaning
0	Clear bit 3 of the HSR
1	Set bit 3 of the HSR
-1	Leave bit 3 of the HSR unchanged

Return value:

The function returns the value of bit 3 of the HSR.

Availability:

The function is available only on computers with the DSP-56001 signal processor.

Group:

DSP programming

4.11.12.1 Bindings for Dsp_Hf0

C:	#include <tos.h> int16_t Dsp_Hf0( int16_t flag );
Assembler:	move.w flag,-(sp) ; Offset 2 move.w #119,-(sp) ; Offset 0 trap #14 ; Call XBIOS addq.l #4,sp ; Correct stack

4.11.13 Dsp_Hf1

Name:

»Dsp_Hf1« - Set or clear bit 4 of the HSR.

Opcode:

120

Syntax:

int16_t Dsp_Hf1( int16_t flag );

Description:

The function Dsp_Hf1 obtains or resp. sets the value of bit 4 of the HSR register. The parameter flag has the following meaning:

flag	Meaning
0	Clear bit 4 of the HSR
1	Set bit 4 of the HSR
-1	Leave bit 4 of the HSR unchanged

Return value:

The function returns the value of bit 4 of the HSR.

Availability:

The function is available only on computers with the DSP-56001 signal processor.

Group:

DSP programming

4.11.13.1 Bindings for Dsp_Hf1

C:	#include <tos.h> int16_t Dsp_Hf1( int16_t flag );
Assembler:	move.w flag,-(sp) ; Offset 2 move.w #120,-(sp) ; Offset 0 trap #14 ; Call XBIOS addq.l #4,sp ; Correct stack

4.11.14 Dsp_Hf2

Name:	»Dsp_Hf2« - Inquire status of bit 3 of the HCR.
Opcode:	121
Syntax:	int16_t Dsp_Hf2( void );
Description:	The function Dsp_Hf2 inquires the current status of bit 3 of the HCR register.
Return value:	The function returns the value of bit 3 of the HCR.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_Hf0 Dsp_Hf1 Dsp_Hf3 Dsp_HStat

4.11.14.1 Bindings for Dsp_Hf2

C:	#include <tos.h> int16_t Dsp_Hf2( void );
Assembler:	move.w #121,-(sp) ; Offset 0 trap #14 ; Call XBIOS addq.l #2,sp ; Correct stack

4.11.15 Dsp_Hf3

Name:	»Dsp_Hf3« - Inquire status of bit 4 of the HCR.
Opcode:	122
Syntax:	int16_t Dsp_Hf3( void );
Description:	The function Dsp_Hf3 inquires the current status of bit 4 of the HCR register.
Return value:	The function returns the value of bit 4 of the HCR.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_Hf0 Dsp_Hf1 Dsp_Hf2 Dsp_HStat

4.11.15.1 Bindings for Dsp_Hf3

C:	#include <tos.h> int16_t Dsp_Hf3( void );
Assembler:	move.w #122,-(sp) ; Offset 0 trap #14 ; Call XBIOS addq.l #2,sp ; Correct stack

4.11.16 Dsp_HStat

Name:	»Dsp_HStat« - Inquire value of the ISR register
Opcode:	125
Syntax:	int8_t Dsp_HStat( void );
Description:	The function Dsp_HStat inquires the value of the ISR register. This way one can check whether data can be received or sent to the ISR register.
Return value:	The function returns the value of the ISR register.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_Hf0 Dsp_Hf1 Dsp_Hf2 Dsp_Hf3

4.11.16.1 Bindings for Dsp_HStat

C:	#include <tos.h> int8_t Dsp_HStat( void );
Assembler:	move.w #125,-(sp) ; Offset 0 trap #14 ; Call XBIOS addq.l #2,sp ; Correct stack

4.11.17 Dsp_InqSubrAbility

Name:	»Dsp_InqSubrAbility« - Inquire subroutine identifier
Opcode:	117
Syntax:	int16_t Dsp_InqSubrAbility( int16_t ability );
Description:	The function Dsp_InqSubrAbility inquires the identifier of the subroutine with the functionality abilitiy.
Return value:	The function returns the identifier of the subroutine. A return value of 0 means that the corresponding subroutine is not present in DSP memory; in that case the subroutine has to be installed with Dsp_LoadSubroutine.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_RunSubroutine Dsp_FlushSubroutines Dsp_LoadSubroutine

4.11.17.1 Bindings for Dsp_InqSubrAbility

C:	#include <tos.h> int16_t Dsp_InqSubrAbility( int16_t ability );
Assembler:	move.w ability,-(sp) ; Offset 2 move.w #117,-(sp) ; Offset 0 trap #14 ; Call XBIOS addq.l #4,sp ; Correct stack

4.11.18 Dsp_InStream

Name:	»Dsp_InStream« - Data transfer to the DSP via an interrupt handler
Opcode:	99
Syntax:	void Dsp_InStream( int8_t data_in, int32_t block_size, int32_t num_blocks, int32_t blocks_done );
Description:	The function copies via a DSP interrupt handler num_blocks data blocks with a size of block_size DSP-words from the buffer data_in to the DSP. For each interrupt one block will be transferred, irrespective of whether the DSP is ready to receive or not. At the same time the counter blocks_done, which keeps track of the number of blocks transferred, will be incremented. As the data is transferred via an interrupt, the procedure does not have to wait. Via blocks_done the program can then determine whether the transfer has been completed.
Return value:	The function does not return a result.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_DoBlock Dsp_BlkUnpacked Dsp_BlkHandShake Dsp_BlkWords Dsp_BlkBytes Dsp_OutStream Dsp_IOStream Dsp_GetWordSize Dsp_SetVectors Dsp_RemoveInterrupts Dsp_MultBlocks

4.11.18.1 Bindings for Dsp_InStream

#include <tos.h>

void Dsp_InStream( int8_t *data_in, int32_t block_size, int32_t num_blocks, int32_t *blocks_done );

Assembler:

pea       blocks_done       ; Offset 14
move.l    num_blocks,-(sp)  ; Offset 10
move.l    block_size,-(sp)  ; Offset  6
pea       data_in           ; Offset  2
move.w    #99,-(sp)         ; Offset  0
trap      #14               ; Call XBIOS
lea       $12(sp),sp        ; Correct stack

4.11.19 Dsp_IOStream

Name:	»Dsp_IOStream« - Data transfer from and to DSP via two interrupts
Opcode:	101
Syntax:	void Dsp_IOStream( int8_t data_in, int8_t data_out, int32_t block_insize, int32_t block_outsize, int32_t num_blocks, int32_t *blocks_done );
Description:	The function sends and receives simultaneously via DSP interrupt handling num_blocks data blocks with a size of block_insize or block_outsize DSP-words from/to the DSP. The sent data is taken from the buffer data_in, the received data is stored in the buffer data_out. For each interrupt one block is sent and one received (except for the first and last interrupt). At the same time the counter blocks_done, which keeps track of the number of blocks transferred, will be incremented. As the data is transferred via an interrupt, the function does not have to wait. Via blocks_done the program can then determine whether the transfer has been completed.
Return value:	The function does not return a result.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_DoBlock Dsp_BlkUnpacked Dsp_BlkHandShake Dsp_BlkWords Dsp_BlkBytes Dsp_InStream Dsp_OutStream Dsp_GetWordSize Dsp_SetVectors Dsp_RemoveInterrupts Dsp_MultBlocks

4.11.19.1 Bindings for Dsp_IOStream

#include <tos.h>

void Dsp_IOStream( int8_t *data_in, int8_t *data_out, int32_t block_insize, int32_t block_outsize, int32_t num_blocks, int32_t *blocks_done );

Assembler:

pea       blocks_done          ; Offset 22
move.l    num_blocks,-(sp)     ; Offset 18
move.l    block_outsize,-(sp)  ; Offset 14
move.l    block_insize,-(sp)   ; Offset 10
pea       data_out             ; Offset  6
pea       data_in              ; Offset  2
move.w    #101,-(sp)           ; Offset  0
trap      #14                  ; Call XBIOS
lea       $1A(sp),sp           ; Correct stack

4.11.20 Dsp_LoadProg

Name:	»Dsp_LoadProg« - Load and execute DSP program
Opcode:	108
Syntax:	int16_t Dsp_LoadProg( int8_t file, int16_t ability, int8_t buffer );
Description:	The function Dsp_LoadProg loads the DSP program with the name file from disk. The program must be in the .LOD format and must not exceed the memory space reserved by Dsp_Reserve. The parameter ability identifies the program. buffer points to a memory block where the DSP can place the binary code it generates for the time being. The size of the memory block can be calculated with the formula: DSP-wordsize * ( Number of program and data words in the LOD file + ( DSP-wordsize * Number of blocks in the .LOD file )) After this the program will be executed.
Return value:	The function returns the value 0 if successful, or -1 in case of error.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_Lock Dsp_Unlock Dsp_Available Dsp_Reserve Dsp_ExecProg Dsp_ExecBoot Dsp_LodToBinary

4.11.20.1 Bindings for Dsp_LoadProg

C:	#include <tos.h> int16_t Dsp_LoadProg( int8_t file, int16_t ability, int8_t buffer );
Assembler:	pea buffer ; Offset 8 move.w ability,-(sp) ; Offset 6 pea file ; Offset 2 move.w #108,-(sp) ; Offset 0 trap #14 ; Call XBIOS lea $C(sp),sp ; Correct stack

4.11.21 Dsp_LoadSubroutine

Name:	»Dsp_LoadSubroutine« - Install a subroutine in memory of the DSP
Opcode:	116
Syntax:	int16_t Dsp_LoadSubroutine( int8_t *codeptr, int32_t codesize, int16_t ability );
Description:	The function Dsp_LoadSubroutine installs the DSP binary subroutine from the buffer codeptr in the DSP's memory. The subroutine has a size of codesize DSP- words and has the identifier ability. The subroutine remains resident in DSP memory until there is no more room for new subroutines and it is displaced, or the function Dsp_FlushSubroutines is called.
Return value:	The function returns 0 in case of error. A positive value denotes the handle assigned to the subroutine, which may be called with Dsp_RunSubroutine.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_RunSubroutine Dsp_FlushSubroutines Dsp_InqSubrAbility

4.11.21.1 Bindings for Dsp_LoadSubroutine

C:	#include <tos.h> int16_t Dsp_LoadSubroutine( int8_t *codeptr, int32_t codesize, int16_t ability );
Assembler:	move.w ability,-(sp) ; Offset 10 move.l codesize,-(sp) ; Offset 6 pea codeptr ; Offset 2 move.w #116,-(sp) ; Offset 0 trap #14 ; Call XBIOS lea $C(sp),sp ; Correct stack

4.11.22 Dsp_Lock

Name:	»Dsp_Lock« - Inquire availability of the DSP
Opcode:	104
Syntax:	int16_t Dsp_Lock( void );
Description:	The function Dsp_Lock inquires whether the DSP is available for calling applications and has not been blocked by something else.
Return value:	The function returns the value -1 if the DSP is being used already by another process. A return value of 0 on the other hand signifies the availability of the DSP and blocks this simultaneously for others, until a call of Dsp_Unlock is received.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_Unlock Dsp_Available Dsp_Reserve Dsp_LoadProg Dsp_ExecProg Dsp_ExecBoot

4.11.22.1 Bindings for Dsp_Lock

C:	#include <tos.h> int16_t Dsp_Lock( void );
Assembler:	move.w #104,-(sp) ; Offset 0 trap #14 ; Call XBIOS addq.l #2,sp ; Correct stack

4.11.23 Dsp_LodToBinary

Name:	»Dsp_LodToBinary« - Conversion of a file from the LOD to the binary format
Opcode:	111
Syntax:	int32_t Dsp_LodToBinary( int8_t file, int8_t codeptr );
Description:	The function Dsp_LodToBinary converts the (ASCII) contents of the .LOD file with the name file to a binary format. The DSP program created in this way is stored at the address codeptr. This block of memory must be dimensioned large enough to take it. After this the program can be executed with Dsp_ExecProg or Dsp_ExecBoot.
Return value:	The function returns the size of the resulting program in DSP-words if successful, or a negative value in case of error.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_Lock Dsp_Unlock Dsp_Available Dsp_Reserve Dsp_LoadProg Dsp_ExecBoot Dsp_ExecProg

4.11.23.1 Bindings for Dsp_LodToBinary

C:	#include <tos.h> int32_t Dsp_LodToBinary( int8_t file, int8_t codeptr );
Assembler:	pea codeptr ; Offset 6 pea file ; Offset 2 move.w #111,-(sp) ; Offset 0 trap #14 ; Call XBIOS lea $A(sp),sp ; Correct stack

4.11.24 Dsp_MultBlocks

Name:	»Dsp_MultBlocks« - Data transfer of multiple blocks from and to the DSP
Opcode:	127
Syntax:	void Dsp_MultBlocks( int32_t numsend, int32_t numreceive, DSPBLOCK sendblocks, DSPBLOCK receiveblocks );
Description:	The function Dsp_MultBlocks sends and receives multiple blocks of DSP data of varying size from and to the DSP. numsend is the number of blocks to be sent and numreceive the number to be received. sendblocks and receiveblocks are pointers to arrays that describe the buffers and blocks.
Return value:	The function does not return a result.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_DoBlock Dsp_BlkUnpacked Dsp_BlkHandShake Dsp_BlkWords Dsp_InStream Dsp_OutStream Dsp_IOStream Dsp_GetWordSize Dsp_BlkBytes

4.11.24.1 Bindings for Dsp_MultBlocks

#include <tos.h>

void Dsp_MultBlocks( int32_t numsend, int32_t numreceive, DSPBLOCK *sendblocks, DSPBLOCK *receiveblocks );

Assembler:

pea       receiveblocks     ; Offset 14
pea       sendblocks        ; Offset 10
move.l    numreceive,-(sp)  ; Offset  6
move.l    numsend,-(sp)     ; Offset  2
move.w    #127,-(sp)        ; Offset  0
trap      #14               ; Call XBIOS
lea       $12(sp),sp        ; Correct stack

4.11.25 Dsp_OutStream

Name:	»Dsp_OutStream« - Data transfer from DSP via an interrupt handler to a given buffer
Opcode:	100
Syntax:	void Dsp_OutStream( int8_t data_out, int32_t block_size, int32_t num_blocks, int32_t blocks_done );
Description:	The function copies via a DSP interrupt handler num_blocks data blocks with a size of block_size DSP-words from the DSP into the buffer data_out. For each interrupt one block will be transferred. At the same time the counter blocks_done, which keeps track of the number of blocks transferred, will be incremen- ted. As the data is transferred via an interrupt, the function does not have to wait. Via blocks_done the program can then determine whether the transfer has been completed.
Return value:	The function does not return a result.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_DoBlock Dsp_BlkUnpacked Dsp_BlkHandShake Dsp_BlkWords Dsp_BlkBytes Dsp_InStream Dsp_IOStream Dsp_GetWordSize Dsp_SetVectors Dsp_RemoveInterrupts Dsp_MultBlocks

4.11.25.1 Bindings for Dsp_OutStream

#include <tos.h>

void Dsp_OutStream( int8_t *data_out, int32_t block_size, int32_t num_blocks, int32_t *blocks_done );

Assembler:

pea       blocks_done       ; Offset 14
move.l    num_blocks,-(sp)  ; Offset 10
move.l    block_size,-(sp)  ; Offset  6
pea       data_out          ; Offset  2
move.w    #100,-(sp)        ; Offset  0
trap      #14               ; Call XBIOS
lea       $12(sp),sp        ; Correct stack

4.11.26 Dsp_RemoveInterrupts

Name:

»Dsp_RemoveInterrupts« - Turn off generation of DSP interrupts

Opcode:

102

Syntax:

void Dsp_RemoveInterrupts( int16_t mask );

Description:

The function Dsp_RemoveInterrupts turns off the generation of DSP interrupts. The parameter mask determines which interrupts are affected:

mask	Meaning
1	No interrupts for sending data through the DSP
2	No interrupts for receiving data through the DSP
3	No interrupts for sending or receiving data through the DSP.

The function also removes routines that were installed with Dsp_SetVectors.

Return value:

The function does not return a result.

Availability:

The function is available only on computers with the DSP-56001 signal processor.

Group:

DSP programming

4.11.26.1 Bindings for Dsp_RemoveInterrupts

C:	#include <tos.h> void Dsp_RemoveInterrupts( int16_t mask );
Assembler:	move.w mask,-(sp) ; Offset 2 move.w #102,-(sp) ; Offset 0 trap #14 ; Call XBIOS addq.l #4,sp ; Correct stack

4.11.27 Dsp_RequestUniqueAbility

Name:	»Dsp_RequestUniqueAbility« - Generate an identifier for a process
Opcode:	113
Syntax:	int16_t Dsp_RequestUniqueAbility( void );
Description:	The function Dsp_RequestUniqueAbility assigns to a DSP process a random unique identifier (also called ability code) which is valid for the run-time of the system. With it one can determine whether the program code belonging to the process is already resident in the DSP.
Return value:	The function returns the created identifier/ability code.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_GetProgAbility

4.11.27.1 Bindings for Dsp_RequestUniqueAbility

C:	#include <tos.h> int16_t Dsp_RequestUniqueAbility( void );
Assembler:	move.w #113,-(sp) ; Offset 0 trap #14 ; Call XBIOS addq.l #2,sp ; Correct stack

4.11.28 Dsp_Reserve

Name:	»Dsp_Reserve« - Reserve DSP memory for use by a program
Opcode:	107
Syntax:	int16_t Dsp_Reserve( int32_t xreserve, int32_t yreserve );
Description:	The function Dsp_Reserve reserves xreserve words of X-memory and yreserve words of Y-memory space. The memory request must include all program and data space, and may not exceed the amount of available memory. This function is necessary to prevent DSP processes being overwritten by DSP subroutines. The reservation remains active up to the next call of Dsp_Reserve.
Return value:	The function returns the value 0 if memory reservation was successful, or -1 if not enough DSP memory was available (or some other error).
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_Lock Dsp_Unlock Dsp_Available Dsp_LoadProg Dsp_ExecProg Dsp_ExecBoot

4.11.28.1 Bindings for Dsp_Reserve

C:	#include <tos.h> int16_t Dsp_Reserve( int32_t xreserve, int32_t yreserve );
Assembler:	move.l yreserve,-(sp) ; Offset 6 move.l xreserve,-(sp) ; Offset 2 move.w #107,-(sp) ; Offset 0 trap #14 ; Call XBIOS lea $A(sp),sp ; Correct stack

4.11.29 Dsp_RunSubroutine

Name:	»DspRunSubroutine« - Start execution of a subroutine
Opcode:	118
Syntax:	int16_t Dsp_RunSubroutine( int16_t handle );
Description:	The function Dsp_RunSubroutine starts execution of a program with the identifier handle. The identifier for a subroutine can be found by using Dsp_InqSubrAbility or Dsp_LoadSubroutine.
Return value:	The function returns the value 0 if successful, or a negative number in case of failure.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_InqSubrAbility Dsp_FlushSubroutines Dsp_LoadSubroutine

4.11.29.1 Bindings for Dsp_RunSubroutine

C:	#include <tos.h> int16_t Dsp_RunSubroutine( int16_t handle );
Assembler:	move.w handle,-(sp) ; Offset 2 move.w #118,-(sp) ; Offset 0 trap #14 ; Call XBIOS addq.l #4,sp ; Correct stack

4.11.30 Dsp_SetVectors

Name:	»Dsp_SetVectors« - Installation of a custom transfer routine
Opcode:	126
Syntax:	void Dsp_SetVectors( void (receiver)(), int32_t (transmitter)() );
Description:	The function Dsp_SetVectors installs routines that are called when the DSP wants to transfer data via interrupt handlers. receiver is a pointer to a routine that is called after the DSP has sent data, and transmitter a pointer to a routine that is called before the DSP receives data. The reception routine receiver is passed a LONG that was sent by the DSP as a parameter on the stack. The sender routine transmitter passes a LONG to the DSP in register D0. This must be non-zero so that it (or rather the lowest three bytes) are transferred to the DSP. Both routines are terminated by the assembler command RTS. If a 0 is passed for receiver or transmitter, then the corresponding interrupt will be blocked. To remove a routine, one has to call Dsp_RemoveInterrupts.
Return value:	The function does not return a result.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_InStream Dsp_OutStream Dsp_IOStream Dsp_RemoveInterrupts

4.11.30.1 Bindings for Dsp_SetVectors

C:	#include <tos.h> void Dsp_SetVectors( void (receiver)(), int32_t (transmitter)() );
Assembler:	pea transmitter ; Offset 6 pea receiver ; Offset 2 move.w #126,-(sp) ; Offset 0 trap #14 ; Call XBIOS lea $A(sp),sp ; Correct stack

4.11.31 Dsp_TriggerHC

Name:	»Dsp_TriggerHC« - Execute host command set aside for DSP programs
Opcode:	112
Syntax:	void Dsp_TriggerHC( int16_t vector );
Description:	The function Dsp_TriggerHC executes vector vector. Only the two vectors $13 and $14 are available for free use by DSP programs.
Return value:	The function does not return a result.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding

4.11.31.1 Bindings for Dsp_TriggerHC

C:	#include <tos.h> void Dsp_TriggerHC( int16_t vector );
Assembler:	move.w vector,-(sp) ; Offset 2 move.w #112,-(sp) ; Offset 0 trap #14 ; Call XBIOS addq.l #4,sp ; Correct stack

4.11.32 Dsp_Unlock

Name:	»Dsp_Unlock« - Release DSP for other processes
Opcode:	105
Syntax:	void Dsp_Unlock( void );
Description:	The function Dsp_Unlock releases the DSP for other processes.
Return value:	The function does not return a result.
Availability:	The function is available only on computers with the DSP-56001 signal processor.
Group:	DSP programming
See also:	Binding Dsp_Lock Dsp_Available Dsp_Reserve Dsp_LoadProg Dsp_ExecProg Dsp_ExecBoot

4.11.32.1 Bindings for Dsp_Unlock

C:	#include <tos.h> void Dsp_Unlock( void );
Assembler:	move.w #105,-(sp) ; Offset 0 trap #14 ; Call XBIOS addq.l #2,sp ; Correct stack

XBIOS

Printer functions

Hatari DHS XBIOS extension