Home XBIOSXBIOS Printer functionsPrinter functions Hatari DHS XBIOS extensionHatari DHS XBIOS extension

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.

See also: Interface programming

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
 
See also: Binding   Dsp_Hf1   Dsp_Hf2   Dsp_Hf3   Dsp_HStat
 

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
 
See also: Binding   Dsp_Hf0   Dsp_Hf2   Dsp_Hf3   Dsp_HStat
 

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

C: #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

C: #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

C: #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

C: #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
 
See also: Binding   Dsp_InStream   Dsp_OutStream   Dsp_IOStream   Dsp_SetVectors
 

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

Home XBIOSXBIOS Printer functionsPrinter functions Hatari DHS XBIOS extensionHatari DHS XBIOS extension