linux dsp gateway specificationdspgateway.sourceforge.net/pub/3.1/dsp_gateway31_spec.pdf6 (121) 2....

1 (121)

Linux DSP Gateway Specification Rev 3.1

Revision History

Date Author SW Revision

Doc Revision

Description

16.05.2003 Toshihiro Kobayashi

Kiyotaka Takahashi

1.0 - First Release

13.11.2003 Toshihiro Kobayashi 2.0 - Dynamic Loader Support

05.08.2004 Toshihiro Kobayashi - kernel 2.6 Support

20.08.2004 Toshihiro Kobayashi

2.0.1

a Error fix in example instruction

30.08.2004 Toshihiro Kobayashi 3.0 - mmap, interactive ioctl support

dsptask multiple open support

04.10.2004 Toshihiro Kobayashi 3.0.1 - Without-devfs system support

02.11.2004 Toshihiro Kobayashi 3.0.2 - Bug fix (1MB export, proc read entries)

06.12.2004 Toshihiro Kobayashi 3.1 - DSP Gateway Release 3.1

Suspend / resume support

Copyright (c) 2003 - 2004 Nokia Corporation

2 (121)

1.1.1.1. INTRODUCTIONINTRODUCTIONINTRODUCTIONINTRODUCTION................................................................................................................................................................................................................................................................................................................................................................................................................................................................................ 5555 1.1. OVERVIEW................................................................................................................................................. 5 1.2. FEATURES ................................................................................................................................................. 5

2.2.2.2. DSP GATEWAY ARCHITECDSP GATEWAY ARCHITECDSP GATEWAY ARCHITECDSP GATEWAY ARCHITECTURETURETURETURE ............................................................................................................................................................................................................................................................................................ 6666 2.1. MEMORY MAP ........................................................................................................................................... 6

2.1.1. DSP Internal Memories ................................................................................................................... 6 2.1.2. External Memory (SDRAM) ............................................................................................................ 7

2.2. INTER-PROCESSOR COMMUNICATION ........................................................................................................ 9 2.2.1. Mailbox mechanism in OMAP processor ........................................................................................ 9 2.2.2. Communication Buffer..................................................................................................................... 9

2.3. MAILBOX COMMAND PROTOCOL .............................................................................................................. 14 2.3.1. Basic Concepts for the Protocol ..................................................................................................... 14 2.3.2. Bit Definitions for Mailbox Registers............................................................................................ 14 2.3.3. Mailbox Command Definition ....................................................................................................... 14

2.4. MAILBOX COMMAND SEQUENCE.............................................................................................................. 43 2.4.1. Configuration Sequence................................................................................................................. 43 2.4.2. Data Transfer Sequence ................................................................................................................ 44

3.3.3.3. LINUX APILINUX APILINUX APILINUX API........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................ 50505050 3.1. OVERVIEW............................................................................................................................................... 50 3.2. DSP TASK DEVICES ................................................................................................................................ 50

3.2.1. open() .............................................................................................................................................. 51 3.2.2. close().............................................................................................................................................. 52 3.2.3. read() .............................................................................................................................................. 52 3.2.4. write() ............................................................................................................................................. 53 3.2.5. poll(), select() .................................................................................................................................. 54 3.2.6. ioctl()............................................................................................................................................... 54 3.2.7. mmap() ........................................................................................................................................... 54

3.3. DSP CONTROL DEVICE ........................................................................................................................... 55 3.3.1. ioctl()............................................................................................................................................... 55

3.4. DSP MEMORY DEVICE ............................................................................................................................ 57 3.4.1. lseek() ............................................................................................................................................. 58 3.4.2. read() .............................................................................................................................................. 58 3.4.3. write() ............................................................................................................................................. 58 3.4.4. ioctl()............................................................................................................................................... 58

3.5. DSP TASK WATCH DEVICE...................................................................................................................... 59 3.5.1. read() .............................................................................................................................................. 60 3.5.2. poll(), select() .................................................................................................................................. 60 3.5.3. ioctl()............................................................................................................................................... 61

3.6. DSP ERROR DETECTION DEVICE............................................................................................................. 61 3.6.1. read() .............................................................................................................................................. 61 3.6.2. poll(), select() .................................................................................................................................. 62

3.7. DSP PROC FILE I/F ................................................................................................................................. 62 3.7.1. /proc/dsp/cur_users ........................................................................................................................ 62 3.7.2. /proc/dsp/mblog .............................................................................................................................. 62 3.7.3. /proc/dsp/version ............................................................................................................................ 63 3.7.4. /proc/dsp/icrmask ........................................................................................................................... 63 3.7.5. /proc/dsp/mmu................................................................................................................................ 63 3.7.6. /proc/dsp/ipbuf ................................................................................................................................ 63 3.7.7. /proc/dsp/loadinfo ........................................................................................................................... 64 3.7.8. /proc/dsp/task/<taskname>/status................................................................................................. 64

3 (121)

3.7.9. /proc/dsp/task/<taskname>/fifosz .................................................................................................. 64 3.8. HEADER FOR APPLICATIONS.................................................................................................................... 65

4.4.4.4. LINUX DRIVER OVERVIELINUX DRIVER OVERVIELINUX DRIVER OVERVIELINUX DRIVER OVERVIEW AND SYSTEM W AND SYSTEM W AND SYSTEM W AND SYSTEM CONFIGURATIONCONFIGURATIONCONFIGURATIONCONFIGURATION .................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... 66666666

4.1. OVERVIEW............................................................................................................................................... 66 4.2. KERNEL CONFIGURATION........................................................................................................................ 66 4.3. DEVICE FILES.......................................................................................................................................... 67

5.5.5.5. DSP PROGRAMMINGDSP PROGRAMMINGDSP PROGRAMMINGDSP PROGRAMMING .................................................................................................................................................................................................................................................................................................................................................................................................................... 68686868 5.1. OVERVIEW............................................................................................................................................... 68 5.2. DSP TASK PROGRAMMING ...................................................................................................................... 68 5.3. TASK TYPE .............................................................................................................................................. 69

5.3.1. Active Sending / Passive Sending.................................................................................................. 69 5.3.2. Active Receiving / Passive Receiving............................................................................................. 69 5.3.3. Word Sending / Block Sending ...................................................................................................... 70 5.3.4. Word Receiving / Block Receiving ................................................................................................. 70 5.3.5. Global Block Sending / Private Block Sending ............................................................................. 70 5.3.6. Global Block Receiving / Private Block Receiving ........................................................................ 70

5.4. DSPTASK STRUCTURE MEMBERS .............................................................................................................. 71 5.5. TASK API ................................................................................................................................................ 74 5.6. GLOBAL IPBUF ALLOCATION / FREEING RULE....................................................................................... 76 5.7. TIMER QUEUE ......................................................................................................................................... 77 5.8. ENDIANISM.............................................................................................................................................. 77 5.9. SYSTEM PARAMETERS ............................................................................................................................. 78 5.10. EXAMPLE............................................................................................................................................. 78

5.10.1. sysinfo.c .......................................................................................................................................... 78 5.10.2. task_test2.c .................................................................................................................................... 79 5.10.3. Command File for CCS, ‘ex_task.cmd’ .......................................................................................... 80 5.10.4. Compilation using CCS (Code Composer Studio) ......................................................................... 80

6.6.6.6. DSP GATEWAY SYSTEM KDSP GATEWAY SYSTEM KDSP GATEWAY SYSTEM KDSP GATEWAY SYSTEM KERNEL OVERVIEWERNEL OVERVIEWERNEL OVERVIEWERNEL OVERVIEW.................................................................................................................................... 85858585 6.1. OVERVIEW............................................................................................................................................... 85 6.2. DSP/BIOS ENTITIES............................................................................................................................... 85

6.2.1. HWI ................................................................................................................................................ 86 6.2.2. TSK................................................................................................................................................. 86 6.2.3. PRD ................................................................................................................................................ 87

7.7.7.7. DSP PROGRAM EXECUTIODSP PROGRAM EXECUTIODSP PROGRAM EXECUTIODSP PROGRAM EXECUTION ON THE TARGET MACHN ON THE TARGET MACHN ON THE TARGET MACHN ON THE TARGET MACHINEINEINEINE.... 88888888 7.1. FILES TO BE PREPARED ON ARM(LINUX) SIDE......................................................................................... 88 7.2. DSP-ENABLED PROGRAM EXECUTION ...................................................................................................... 88

7.2.1. DSP program loading and starting ............................................................................................... 88 7.2.2. Test Run......................................................................................................................................... 88

REFERENCESREFERENCESREFERENCESREFERENCES................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................ 90909090

APPENDIX A: APPENDIX A: APPENDIX A: APPENDIX A: dspctldspctldspctldspctl UTILITY UTILITY UTILITY UTILITY................................................................................................................................................................................................................................................................................................................................................................................ 91919191 1) START .......................................................................................................................................................... 91 2) STOP............................................................................................................................................................ 92 3) LOAD ........................................................................................................................................................... 93

4 (121)

4) RUN (= UNRESET) / RESET............................................................................................................................ 93 5) SETRSTVECT (FOR DEBUG USE) .................................................................................................................... 93 6) IDLE ............................................................................................................................................................ 93 7) SUSPEND, RESUME ...................................................................................................................................... 93 8) DSPCFG, DSPUNCFG ..................................................................................................................................... 93 9) EXMAP, EXUNMAP........................................................................................................................................ 93 10) MAPFLUSH ............................................................................................................................................... 95 11) FBEXPORT................................................................................................................................................ 96 12) MMUINIT.................................................................................................................................................. 97 13) MMUITACK (FOR DEBUG USE) ................................................................................................................... 97 14) MKDEV, RMDEV (FOR DEBUG USE)............................................................................................................ 97 15) TADD, TDEL (FOR DEBUG USE).................................................................................................................. 97 16) GETVAR, SETVAR...................................................................................................................................... 97 17) REGREAD, REGWRITE (FOR DEBUG USE) ................................................................................................... 97 18) RUNLEVEL ............................................................................................................................................... 98 19) MBSEND (FOR DEBUG USE) ....................................................................................................................... 98

APPENDIX B: DSP TASKAPPENDIX B: DSP TASKAPPENDIX B: DSP TASKAPPENDIX B: DSP TASK EXAMPLES AND MAILBO EXAMPLES AND MAILBO EXAMPLES AND MAILBO EXAMPLES AND MAILBOX X X X COMMAND EXCHANGE COMCOMMAND EXCHANGE COMCOMMAND EXCHANGE COMCOMMAND EXCHANGE COMMENTARYMENTARYMENTARYMENTARY ................................................................................................................................................................................................................................................ 99999999

1) DSP CONFIGURATION.................................................................................................................................. 99 2) TEST1 .........................................................................................................................................................100 3) TEST2 .........................................................................................................................................................102 4) TEST3 .........................................................................................................................................................103 5) TEST4 .........................................................................................................................................................106 6) TEST7 .........................................................................................................................................................109 7) TASK8.........................................................................................................................................................112 8) HELLOTIMER ..............................................................................................................................................118

5 (121)

1. INTRODUCTION

1.1. Overview

The Texas Instruments’ OMAP1510/1610 and their derivatives are dual-core processors, which are composed of an ARM9 general purpose processor (GPP) and TMS320C55x DSP processor along with integrated peripheral controllers for memory, serial, USB, MMC/SD cards and others. Since version 2.6.6, Linux kernel officially supports OMAP devices. DSP Gateway works on this kernel and allows access to the DSP from application program on the GPP. The DSP Gateway consists of two parts, a Linux device driver on the ARM and a DSP-side kernel library, and they communicate with each other. The Linux driver provides conventional Linux device driver interface so the application can use DSP functions through normal system calls such as read() and write(). The DSP kernel library provides multi-task environment and APIs for user tasks, which can be accessed from Linux. This document describes the communication protocol between two processors, APIs for Linux application and DSP tasks, summaries of the Linux driver and the DSP library and an example of the DSP task. Besides, the manual for the DSP control utility and the commentary of the inter-processor communication in the DSP Gateway are attached as appendixes. 1.2. Features

The features of the DSP Gateway are summarized as followings. ♦ Familiar APIs for Linux applications, using conventional Linux device file interfaces. ♦ Multi-task environment for DSP applications. ♦ Minimum copy count for maximum throughput in data exchange between the ARM and the DSP. ♦ Memory extension feature for DSP, i.e. external memory mapping for the DSP space. ♦ /proc file entries for debugging and run-time environment configurations. ♦ Power Management functions for DSP. ♦ Fault-tolerant features for DSP.

6 (121)

2. DSP GATEWAY ARCHITECTURE

2.1. Memory Map

2.1.1. DSP Internal Memories

OMAP1510/1610 and derivatives have three types of internal memory for DSP, DARAM (Dual Access Memory), SARAM (Single Access Memory) and PDROM (Program and Data ROM). DARAM and SARAM are seen in the DSP memory space and also in the MPU memory space. PDROM is not seen in the MPU space and not used in the DSP Gateway. See Table 2-1 and Figure 2-1.

Table 2-1: Mappings of DSP Internal Memories

DSP Byte Address

MPU Physical Address

Linux Virtual Address

size

DARAM 0x000000

| 0x00ffff

0xe0000000 |

0xe000ffff

0xe0000000 |

0xe000ffff 64kB

SARAM 0x010000

| 0x027fff

0xe0010000 |

0xe0027fff

0xe0010000 |

0xe0027fff 96kB

PDROM 0xff8000

| 0xffffff

(not seen in MPU space)

32kB

Figure 2-1: Internal Memories for DSP

0 0 0 0 _ 0 0 0 0

F F F F _ F F F F

0 0 _ 0 0 0 0 D A R A M S A R A M

P D R O M D S P M e m o r y S p a c e

M P U V ir tu a l S p a c e

0 0 0 0 _ 0 0 0 0

F F F F _ F F F F

M P U P h y s ic a l S p a c e

E 0 0 0 _ 0 0 0 0E 0 0 0 _ 0 0 0 0

S A R A M D A R A M

S A R A M D A R A M

E 0 F F _ F F F F E 0 F F _ F F F FF F _ F F F F

D S P s p a c e s h a d o w a re a

As seen in Figure 2-1, 0xe0000000 - 0xe0ffffff in the MPU virtual space is defined as DSP space shadow area. Whole 16MB of the DSP space is shadowed to this area, except the PDROM.

7 (121)

2.1.2. External Memory (SDRAM)

External memory (SDRAM) can also be used from DSP by mapping it to the DSP space through the DSP MMU. Using this feature, DSP application programmer can extend the available memory area for code and data which is confined in 192kB by default. This mapping procedure is handled by the MPU. When the MPU maps a memory block to the DSP space, it also maps to the DSP space shadow area in the MPU virtual space so the offsets in the DSP space and the shadow area become same. (Figure 2-2) With this mapping, address exchanges between DSP space and MPU virtual space can be done with very simple operation.

Figure 2-2: SDRAM mapping for DSP space

00 00 _0 0 00

F FF F_ FF FF

10 00 _0 0 00

S D R A M

0 0 _ 0 0 0 0 D A R A M S A R A M

P D R O M D S P M e m o r y S p a c e

m a p (b y D S P M M U )


0 00 0_ 00 00

F FF F_ FF FF

C0 00 _0 0 00

S D R A M


E 00 0_ 00 00E 00 0_ 00 00

S A R A M D A R A M

S A R A M D A R A M

E 10 0_ 00 00 E 10 0_ 00 00F F _ F F F F

L in u x s tra ig h t m a p p in g a re a

D S P s p a c e s h a d o w a re a m a p

(b y M P U M M U )

Before releasing the DSP from reset, the reset vector at address 0xffff00 should be set so that the DSP program can jump to the start address of the application code. By default, this address is in PDROM area, which cannot be modified by user. In the DSP Gateway driver, a 4k-page of external SDRAM memory is allocated and mapped to the DSP space covering the DSP vector table (i.e. 0xfff000-0xffffff), overriding the PDROM. (Figure 2-3)

8 (121)

Figure 2-3: SDRAM mapping for Reset Vector

0 0 0 0_ 0 00 0

FF F F _F F F F

1 0 0 0_ 0 00 0

S D R A M

0 0 _0 0 0 0 D A R A M S A R A M

D S P M e m o r y S p a c e

m a p (in D S P M M U )


0 00 0 _ 00 0 0

F F F F_ F FF F

C 00 0 _ 00 0 0

S D R A M


E 0 0 0_ 0 00 0E0 0 0 _0 0 0 0

S A R A M D A R A M

S A R A M D A R A M

E1 0 0 _0 0 0 0 E 1 0 0_ 0 00 0F F _ FF F F

D S P s p a c e s h a d o w a re a

m a p (in M P U M M U )

E 0 F F_ F 00 0

9 (121)

2.2. Inter-Processor Communication

2.2.1. Mailbox mechanism in OMAP processor

The ARM-DSP interprocessor communication is implemented as the mechanism called ‘mailbox’ in OMAP. There are three sets of mailbox registers: one for the MPU to send messages and issue an interrupt (INT5) to DSP, the other two for DSP to send messages and issue an interrupt (IRQ10/11) to the MPU. Each set of mailbox registers consists of two 16-bit registers and a 1-bit flag register. The interrupting processor can use one 16-bit register to pass a data word to the interrupted processor and the other 16-bit register to pass a command word. The DSP Gateway uses one mailbox for each direction as shown in Figure 2-4, i.e. one mailbox for DSP to ARM direction is not used. The mailbox protocol used in DSP Gateway is described in 2.3.

Figure 2-4: Mailbox mechanism

DSP ARM

INT5

IRQ10

IRQ11

(not used)

ARM2DSP1 mailbox (command/data/flag)

DSP2ARM1 mailbox (command/data/flag)

DSP2ARM2 mailbox (command/data/flag)

2.2.2. Communication Buffer

It is unrealistic to transfer a large amount of data between two processors with only mailbox registers. Therefore, IPBUF (Inter-Processor Buffer) is introduced for the large block data transfer. The IPBUF can be placed at the DSP internal memories (DARAM and SARAM), or the external SDRAM block which is mapped to the DSP space. There are three types of IPBUFs, Global IPBUF, Private IPBUF and System IPBUF. 2.2.2.1. Global IPBUF

The Global IPBUFs are defined for the block data transfer between ARM and DSP. The Global IPBUF lines are identified with BID (Buffer ID), and all tasks can use them commonly. The maximum line size is 64k words (128k bytes). Each IPBUF line has 6-words header, which contains valid data size, owner task information and sync words. An example of the Global IPBUF structure is shown in Figure 2-5.

10 (121)

Figure 2-5: An example of Global IPBUF structure header(6words) (word address) 0x000100

0x000185 IPBUF0 (128 words)

header(6words) 0x000186

0x00020b IPBUF1 (128 words) header(6words) 0x00020c


header(6words) 0x000292


The Global IPBUF header contains a word of the valid count information, IPBLINK word, and two sets of a lock word and a sync word each for ARM and DSP (Figure 2-6). For future expansion, note that the data body should be aligned at the long word (4-bytes) boundary in order to transfer long words between ARM and DSP.

Figure 2-6: Global IPBUF structure (detail)

(word offset) 0x00 valid count 0x01 next BID in IPBLINK 0x02 ARM side lock info 0x03 ARM side sync word 0x04 DSP side lock info 0x05 DSP side sync word

header

0x06

0x83

data body (128 words)

data body

The ARM side lock info field indicates to which DSP task ARM has sent the block data using this IPBUF line. The value of 0xfe is reserved as anonimous task and 0xff is the indication that this line is free. In the same way, the DSP side lock info is used by DSP side to indicate which task has sent the block data to ARM using this IPBUF line. The ARM side and DSP side sync words are used to make sure read-after-write operation between the processors. The receiver processor should not read the data from this IPBUF until the sync word indicates that the data write has been completed by the sender processor. Both processors will try to maintain their own buffer line count balanced between as far as possible. The Global IPBUF lines are managed with the IPBLINK. This mechanism is used for the free IPBUF pool in both ARM and DSP, and read buffer link in ARM side. The read buffer link is not equipped in DSP side. See the IPBLINK structure (Figure 2-7) and an example of buffer ownership transition sequence (Figure 2-8).

11 (121)

Figure 2-7: IPBLINK structure

IPBLINK head top = 1 tail = 3 next = 2

IPBUF 1

next = 3

IPBUF 2

next = NULL

IPBUF 3

Figure 2-8: An example of Global IPBUF ownership transition sequence

ARM

2 3

n IPBUF n

(1) initial state free pool

task0

read link

task1 task2

read link

read link

DSP

0 1

free pool

task0 task1 task2

ARM

3

(2) task0 in DSP reserved buffer 0 from the free pool and writes data to it

free pool

task0

read link

task1 task2

read link

read link

DSP

1

free pool

task0 task1 task2

2 0

12 (121)

ARM

3

(3) DSP sends data with buffer 0 to ARM. Buffer 0 is linked to task0 read link.

free pool

task0

read link

task1 task2

read link

read link

DSP

0 1

free pool

task0 task1 task2

2

ARM

3

(4) ARM reads data from buffer 0, besides yielding buffer 2 to DSP

free pool

task0

read link

task1 task2

read link

read link

DSP

0 1

free pool

task0 task1 task2

2

ARM

3

(5) buffer 0 is returned to the free pool

free pool

task0

read link

task1 task2

read link

read link

DSP

0 1

free pool

task0 task1 task2

2

When an IPBUF is sent from one to the other, the receiving processor will yield one buffer ownership to the sending processor in return as (4) above. 2.2.2.2. Private IPBUF

DSP tasks can have their Private IPBUF. The structure is different from Global IPBUF as shown in Figure 2-9. The address of the IPBUF data body can be changed in every data transfer. Only Active Receiving tasks can use the Private IPBUF for data receiving from ARM, since it needs to inform the address of the buffer data body to ARM before ARM sends data to DSP.

13 (121)

Figure 2-9: Private IPBUF structure

(word offset) 0x00 valid count 0x01 sync word 0x02 lower 0x03

data body address upper

header

(address specified

in the header)

data body data body

The sync word field is used to make sure read-after-write operation between the processors. The sending processor sets the TID of this task to this field after writing the data to this IPBUF. The receiver processor should not read the data from this IPBUF until the sync word becomes that TID. After reading, the receiver processor writes 0xff to this field to indicate this buffer is free. After that, the sending processor can use this IPBUF again. The reason why the header and the data body are separated for Private IPBUF is for the situation in which the data needs to be written at the middle of the buffer block, like (Figure 2-10).

Figure 2-10: Valid data at middle of the Private IPBUF

header

buffer block

(data needs to be written here)

address

2.2.2.3. System IPBUF

The system IPBUF is defined for the system data delivery for each direction (ARM to DSP and DSP to ARM). They are used to send extra data along with the Mailbox command. The System IPBUF structure is shown in Figure 2-11.

Figure 2-11: System IPBUF

(word offset) 0x00 sync word 0x01

0x0f

data (15 words)

14 (121)

2.3. Mailbox Command Protocol

2.3.1. Basic Concepts for the Protocol

Followings are essential ideas or concepts to understand the Mailbox protocol in the DSP Gateway. ♦ Tasks in the DSP are identified with TID (Task ID), and Most commands are sent with the TID. ♦ IPBUFs are used for the block data transfer between ARM and DSP. ♦ An IPBUF is owned by either processors. Only the processor which has the ownership of the IPBUF

can access to that IPBUF. When a data transfer with an IPBUF is performed, the ownership of the IPBUF moves to the recipient.

2.3.2. Bit Definitions for Mailbox Registers

Bit definitions of mailbox command and data registers are shown in Figure 2-12 and Figure 2-13. The Q bit (command register bit [15]) is toggled on each command trasnmission, in order to distinguish the command from previous one. This is a workaround operation for potential problem of the mailbox interrupt mechanism – In some situation, two mailbox interrupts are observed on ARM even DSP writes to mailbox registers only once.

Figure 2-12: Mailbox Command Register Bit Definitions 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Q CMD_H CMD_L

Bit Name Description 15 Q sequence number 14:8 CMD_H command primary bits (Defined in 2.3.3) 7:0 CMD_L command option bits

Figure 2-13: Mailbox Data Register Bit Definitions

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 command dependent

2.3.3. Mailbox Command Definition

7-bit mailbox commands are defined as Table 2-2. These commands are sent on CMD_H field (bits [14:8]) in the command register, along with supplemantary information on CMD_L bits and data register.

Table 2-2: Mailbox Command Definition

Command CMD_H CMD_L data register Short Description WDSND 0x10 TID word data to send Word Send WDREQ 0x11 TID - Word Request BKSND 0x20 TID BID Block Send BKREQ 0x21 TID requesting count Block Request BKYLD 0x23 - BID Block Yield BKSNDP 0x24 TID - Block Send Private

15 (121)

BKREQP 0x25 TID - Block Request Private TCTL 0x30 TID ctlcmd / return value Task Control TCTLDATA 0x31 - data Task Control Data WDT 0x50 - notification value Watchdog Timer Notification RUNLEVEL 0x51 RUNLEVEL - DSP Runlevel Switch PM 0x52 PMCMD mask Power Management SUSPEND 0x53 - - Suspend TCFG 0x60 TID configuration data Task Conriguration TADD 0x62 TID - Task Add TDEL 0x63 TID type Task Delete TSTOP 0x65 - - Task Stop DSPCFG 0x70 CFGTYP configuration data System Configuration REGRW 0x72 TYPE address / data Register Read / Write GETVAR 0x74 VARID data Get Variable SETVAR 0x75 VARID data Set Variable ERR 0x78 EID command caused

the error Error Information

DBG 0x79 TID - Debug

16 (121)

2.3.3.1. WDSND

Word Send. The initiating processor sends a 16-bit data on the mailbox data register to the target processor. See 2.4.1.3 for the data transfer sequence. Direction

ARM to DSP yes DSP to ARM yes

Mailbox registers usage

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 0 0 1 0 0 0 0 TID 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register DATA

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x10 command[7:0] TID DSP task ID data[15:0] DATA 1-word sending data

17 (121)

2.3.3.2. WDREQ

Word Request. The initiating processor requests a 16-bit data and the target processor should respond with WDSND command to this request. See 2.4.1.3 for the data transfer sequence. Direction



15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 0 0 1 0 0 0 1 TID 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register don’t care

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x11 command[7:0] TID DSP task ID data[15:0] don’t care

18 (121)

2.3.3.3. BKSND

Block Send. The initiating processor sends a block data to the target processor using the Global IPBUF. With this command the ownership of this IPBUF line moves to the target processor. The valid word count is indicated in the IPBUF header. See 2.4.1.3 for the data transfer sequence. Direction



15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 0 1 0 0 0 0 0 TID 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register BID

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x20 command[7:0] TID DSP task ID data[15:0] BID IPBUF ID

19 (121)

2.3.3.4. BKREQ

Block Request. The initiating processor requests a block data using the Global IPBUF or the Private IPBUF and the target processor should respond with BKSND or BKSNDP command to this request. The word number requested in this command is a suggestion to the target processor. The target processor decides how many words to send according to this information, but it should not be more than requested count. See 2.4.1.3 for the data transfer sequence. Direction



15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 0 1 0 0 0 0 1 TID 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register CNT

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x21 command[7:0] TID DSP task ID data[15:0] CNT requesting word count (suggestion)

20 (121)

2.3.3.5. BKYLD

Block Yield. The initiating processor can yield the ownership of a Global IPBUF line to the target processor with this command. This command may be issued in response to a BKSND command. See 2.4.1.3 for the data transfer sequence. Direction



15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 0 1 0 0 0 1 1 don't care 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register BID

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x23 command[7:0] don't care data[15:0] BID IPBUF ID

21 (121)

2.3.3.6. BKSNDP

Block Send Private. The initiating processor sends a block data to the target processor using the Private IPBUF. The valid word count should be indicated in the IPBUF header. ARM can issue this command only in responce to the BKREQP command from DSP. DSP can isue this command at any time (as long as the Private IPBUF is free). See 2.4.1.3 for the data transfer sequence. Direction





22 (121)

2.3.3.7. BKREQP

Block Request Private. DSP requests a block data using the Private IPBUF and ARM should respond with BKSNDP command to this request. ARM uses BKREQ command even if the corresponding task is Private Sending task, and should not issue this command. DSP should set the requesting word number in the Private IPBUF header before sending this command to ARM. When ARM received this command, it reads the count information in the IPBUF and decides how many words to send regarding this information, but it should not be more than requested count. See 2.4.1.3 for the data transfer sequence. Direction

ARM to DSP no DSP to ARM yes




23 (121)

2.3.3.8. TCTL

Task Control. ARM sends the task control commands to DSP, and DSP sends back the return value to ARM (if necessary). The DSP action to take at receiving this command is task dependent. The definition of the commands are shown below. The user can define TCTL commands in the ranges of 0x8000 – 0x81ff and 0x9000 – 0x91ff. Additionally, the command range of 0x80 – 0xff is also user-defined. but it is kept for the backward compatibility. The user should not define any commands in this range newly. If the TCTL command being sent has an argument, it is sent using the System IPBUF. Direction



15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 0 1 1 0 0 0 0 TID 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register CTLCMD or RETVAL

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x30 command[7:0] TID DSP task ID

CTLCMD (ARM to DSP) control command data[15:0] RETVAL (DSP to ARM) return value

Configuration data structure (on the System IPBUF)

Word Name Description 1 arg1 Argument 1

24 (121)

CTLCMD definition

Code Range Description 0x0000 – 0x007f System Command

0x0000 TINIT Task Initialize 0x0001 TEN Task Enable 0x0002 TDIS Task Disable 0x0003 TCLR Task Clear 0x0004 TKILL Task Kill

0x0005 | 0x007f

Reserved

0x0080 – 0x00ff User-defined (No parameter, No return value) This range is kept for backward compatibility. DO NOT define new commands in this range.

0x0100 - 0x7fff Reserved 0x8000 - 0x80ff User-defined (No parameter, No return value) 0x8100 - 0x81ff User-defined (1 argument, No return value) 0x8200 - 0x8fff Reserved 0x9000 - 0x90ff User-defined (No parameter, have a return value) 0x9100 - 0x91ff User-defined (1 argument, have a return value) 0x9200 - 0xffff Reserved

25 (121)

2.3.3.9. TCTLDATA

Task Control Data. This command is used only in DSP internally. This is additional parameter for the TCTL commands which takes an argument. Direction

ARM to DSP no DSP to ARM no


15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register 0 1 1 0 0 0 1 TID 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register DATA

Bit Name Description command[15] don’t care command[14:8] CMD_H 0x31 command[7:0] don’t care data[15:0] DATA parameter for TCTL

26 (121)

2.3.3.10. WDT

Watchdog Timer notification. When DSP watchdog timer expires, DSP notifies ARM with this command. On receiving this command, the process reading /dev/dspctl/err in Linux is woken up and reads a 1-word notification value sent on the mailbox data register. This value is user-defined. Direction



15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 1 0 1 0 0 0 0 don’t care 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register NVAL

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x50 command[7:0] don’t care data[15:0] NVAL notification value (user-defined)

27 (121)

2.3.3.11. RUNLEVEL

DSP Runlevel Switch. The user can switch the DSP system runlevel. There are three runlevels, USER, SUPER and RECOVERY. The USER runlevel is normal mode, on which all user tasks can run. The SUPER runlevel is the supervisor mode, on which only the super task can run. All user tasks become pending on this runlevel. The RECOVERY runlevel is same as SUPER, except that the DSP sends debug information of the erring task. This mode is used when DSP MMU error is detected on ARM. Direction

ARM to DSP yes DSP to ARM no


15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 1 0 1 0 0 0 1 RUNLEVEL 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register don’t care

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x51 command[7:0] RUNLEVEL Runlevel to switch data[15:0] don’t care

RUNLEVEL description

Name RUNLEVEL Description USER 0x01 Normal mode. SUPER 0x0e Supaervisor mode. No user task can run. RECOVERY 0x10 Recovery mode. DSP sends debug information about the

erring task.

28 (121)

2.3.3.12. PM

Power Management. This command is used to allow or prohibit domains in DSP to stop when DSP enters idle mode. When this command is sent with PMCMD=ENABLE, domains indicated in MASK will be prohibited to stop even if DSP enters idle. On the other hand, when this command is sent with PMCMD=DISABLE, domains indicated in MASK can stop in conjunction with the DSP idle. DSP-side program is expeted to support multiple enabling / disabling. In practice, this command is used to keep awake DMA domain to allow ARM to access to DSP internal memories. Direction

ARM to DSP yes DSP to ARM no


15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 1 0 1 0 0 1 0 PMCMD 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register MASK

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x52 command[7:0] PMCMD Power management command data[15:0] MASK Mask of domain of interest

PMCMD description

Command PMCMD Description DISABLE 0x00 Allow to stop ENABLE 0x01 Prohibit to stop when DSP enters idle

MASK description

MASK bit definition is derived from DSP Idle Configuration Register (ICR).

bit NAME Description 15:6 Reserved 5 EMIF_IDLE_DOMAIN EMIF 4 DPLL_IDLE_DOMAIN DPLL 3 PER_IDLE_DOMAIN peripherals 2 CACHE_IDLE_DOMAIN I-cache 1 DMA_IDLE_DOMAIN DMA controller 0 CPU_IDLE_DOMAIN CPU core and memory

29 (121)

2.3.3.13. SUSPEND

Suspend. ARM requests DSP to suspend with this command. When DSP received this command, it saves register contents to the memory, sets its own reset vector to the pointer of the resume code, then returns SUSPEND response to ARM and hungs up. When ARM receives the SUSPEND response, it can reset DSP. After then, when DSP needs to be resumed, ARM can just release the DSP’s reset so the DSP runs resume code which restores the saved register contents, and gets back to the norma operation. Direction

ARM to DSP yes (request) DSP to ARM yes (resonse)


15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 1 0 1 0 0 1 1 don’t care 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register don’t care

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x53 command[7:0] don’t care data[15:0] don’t care

30 (121)

2.3.3.14. TCFG

Task Configuration Request/Response. ARM requests task configuration information with this command. DSP should respond to the request also by this command, with configuration data in the System Buffer. See 2.4.1.2 for the configuration sequence. Direction






Word Name Description task type information Bit Name Description 15:6 RFU reserved (SBZ) 5 PVDM private buffer for DSP->MPU 4 PVMD private buffer for MPU->DSP 3 BKDM block transfer for DSP -> MPU 2 BKMD block transfer for MPU -> DSP 1 ASND active send

0 ttyp

0 ARCV active receive 1 upper 7 bits 2

ipb_dm lower 16 bits

private IPBUF header address (word address) for DSP->MPU direction

3 upper 7 bits 4

ipb_md lower 16 bits

private IPBUF header address (word address) for MPU->DSP direction

5 upper 7 bits 6

mapstart lower 16 bits

base address of the mmap buffer

7 upper 7 bits 8

maplen lower 16 bits

size of the mmap buffer (in word)

9 upper 7 bits 10

tnm lower 16 bits

address of the task name string

♦ ttyp

Bit definitions of ttyp (task type information) are shown below.

31 (121)

PVDM (bit 5): block transfer using private IPBUF for DSP->MPU 1: This task uses BKSNDP command for DSP -> MPU data transfer. 0: This task uses BKSND or WDSND command for DSP -> MPU data transfer.

PVMD (bit 4): block transfer using private IPBUF for MPU -> DSP 1: This task accepts BKSNDP command for MPU -> DSP data transfer. 0: This task doesn’t accepts BKSNDP command but use BKSND or WDSND command

for MPU -> DSP data transfer.

BKDM (bit 3): block transfer for DSP->MPU 1: This task uses BKSND or BKSNDP command for DSP -> MPU data transfer. 0: This task uses WDSND command for DSP -> MPU data transfer.

BKMD (bit 2): block transfer for MPU -> DSP 1: This task accepts BKSND or BKSNDP command for MPU -> DSP data transfer. 0: This task doesn’t accepts neither BKSND nor BKSNDP command but use WDSND

command for MPU -> DSP data transfer.

AREQ (bit 1): active request 1: This task issues WDREQ/BKREQ command when it needs data from MPU. MPU

should not issue WDSND/BKSND command to this task without receiving WDREQ/BKREQ command from DSP.

0: This task doesn’t issue WDREQ/BKREQ command. MPU can issue WDSND/BKSND command to this task at any time.

ASND (bit 0): active send

1: This task issues WDSND/BKSND command spontaneously and MPU doesn’t need to issue WDREQ/BKREQ command to DSP.

0: This task issues WDSND/BKSND command only in response to the WDREQ/BKREQ command from MPU.

32 (121)

2.3.3.15. TADD

Task Add. ARM requests to add a new dsptask to DSP with this command. In the TADD request from ARM to DSP, the address of the new dsptask is informed to DSP using System IPBUF. Triggered by this command, DSP appends the new dsptask to the system and configure it, then returns TADD response to ARM with the TID of the new dsptask. If this fails on DSP side, is returns TADD responce with TID_ANON (anonymous TID). See 2.4.1.3 for the task add sequence. Direction




Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x62 command[7:0] TID DSP task ID (only for response from DSP to ARM) data[15:0] don’t care

Data structure sent on the System IPBUF

Word Name Description 0 adrh upper 7 bits 1 adrl lower 16 bits

address of dsptask structure to be added. (word address)

33 (121)

2.3.3.16. TDEL

Task Delete. ARM requests to delete the dsptask to DSP with this command. Only the tasks which has been added with TADD command can be deleted. Triggered by this command, DSP does away with the dsptask from the system, then returns same command to ARM as the completion notification. See 2.4.1.3 for the task delete sequence. Direction



15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 1 1 0 0 0 1 1 TID 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register TYPE

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x63 command[7:0] TID DSP task ID data[15:0] MODE TDEL mode

TYPE description

Command MODE Description SAFE 0x00 System waits this task to process all commands registered in the

queue before deleting the task object and resources. KILL 0x01 The task object and resources are deleted immediately.

34 (121)

2.3.3.17. TSTOP

Task Stop. This command is used only in DSP internally. Direction

ARM to DSP no DSP to ARM no


15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register 1 1 0 0 1 0 1 don’t care 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register don’t care

Bit Name Description command[15] don’t care command[14:8] CMD_H 0x65 command[7:0] don’t care data[15:0] don’t care

35 (121)

2.3.3.18. DSPCFG

DSP Configuration Request/Response. ARM requests DSP configuration information by this command, with CFGTYP=REQ. DSP should respond to the request also by this command, along with configuration data in the System Buffer. The response from DSP consists of a sequence of several commands, which are identified with CFGTYP. At the last command of the response sequence, L (Last) bit should be asserted. It also means system configuration data in the System Buffer is ready to be read by ARM. If any error occurred in DSP while initialization, it should respond with CFGTYP=ABORT. It means the DSP binary contains fatal error and needs to be revised. In this case ARM should not send mailbox command to DSP anymore. This command also initializes the ownerships of all IPBUFs. At the default state, DSP owns all IPBUFs. DSP can issue BKYLD commands after DSPCFG command sequence, in order to yield some ownerships to ARM side See 2.4.1.1 for the configuration sequence. Direction



15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 1 1 1 0 0 0 0 L CFGTYP 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register CFGDATA

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x70 command[7] L end of configuration data indicator

configuration type Code Command Description 0x00 REQ configuration request 0x28 SYSADRH 0x29 SYSADRL

System IPBUF address (word address)

0x70 PROTREV Mailbox Protocol Revision ID

command[6:0] CFGTYP

0x78 ABORT abort response data[15:0] CFGDATA configuration data

36 (121)

Configuration data structure (on the System Buffer)

Word Name Description 0 task_max maximum task number in DSP. 1 bln Global IPBUF line number. 2 bsz Global IPBUF line size information. It is presented in word count. 3 upper 7 bits 4

badr lower 16 bits

Global IPBUF address. (word address)

5 bkeep line number of Global IPBUF to be kept for DSP. MPU should yield some ownerships for the IPBUF when DSP seems to have less ownerships than the number informed in this command.

6 upper 7 bits 7

sys_da lower 16 bits

The address of the System IPBUF for DSP->ARM. (word address)

8 upper 7 bits 9

sys_ad lower 16 bits

The address of the System IPBUF for ARM->DSP. (word address)

♦ CFGTYP = REQ ARM requests DSP configuration with this command.

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register don’t care

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x70 command[7] L 0 command[6:0] CFGTYP 0x00 data[15:0] don’t care

37 (121)

♦ CFGTYP = SYSADRH ♦ CFGTYP = SYSADRL System IPBUF address information.

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 1 1 1 0 0 0 0 L 0 1 0 1 0 0 * 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register ADR

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x70 command[7] L last data indicator

0x28 SYSADRH: ADR represents upper 7 bits of the System IPBUF address

command[6:0] CFGTYP

0x29 SYSADRL: ADR represents lower 16 bits of the System IPBUF address

data[15:0] ADR address

♦ CFGTYP = PROTREV Mailbox protocol revision information.

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 1 1 1 0 0 0 0 L 1 1 1 0 0 0 0 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register REV

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x70 command[7] L last data indicator command[6:0] CFGTYP 0x70 data[15:0] REV Mailbox protocol revision ID

38 (121)

♦ CFGTYP = ABORT Abort response.

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 1 1 1 0 0 0 0 L 1 1 1 1 0 0 0 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register don’t care

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x70 command[7] L don’t care command[6:0] CFGTYP 0x78 data[15:0] don’t care

39 (121)

2.3.3.19. REGRW

Register Read / Write. This command is used to read or write at specified address in DSP memory or I/O space from ARM. Note that the address greater than 0xffff in memory space is not accessible with this command. See 2.4.2.3 for the read / write sequence. Direction

ARM to DSP yes (read, write) DSP to ARM yes (read data)


15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 1 1 1 0 0 1 0 TYPE 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register A/D

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x72

command type Code Command Description 0x00 MEMR Memory Read 0x01 MEMW Memory Write 0x02 IOR I/O Read 0x03 IOW I/O Write

command[7:0] TYPE

0x04 DATA Data data[15:0] A/D Address or Data

40 (121)

2.3.3.20. GETVAR, SETVAR

Get / Set Variable. This command is used to read or write DSP system variable from ARM. The values of the variable are sent through the System IPBUF. See 2.4.2.5 for get / set sequence. Direction

ARM to DSP yes (GETVAR, SETVAR) DSP to ARM yes (GETVAR data)


15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 1 1 1 0 1 0 * VARID 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register don’t care

Bit Name Description command[15] Q Sequence number

0x74 GETVAR command[14:8] CMD_H 0x75 SETVAR

command[7:0] VARID Variable ID data[15:0] don’t care


Word Name Description 1 : n DATA value(s) of the variable

VARID description

Name VARID Description ICRMASK 0x00 Mask for ICR register when DSP falls in idle mode LOADINFO 0x01 DSP load infomation (only for GETVAR)

41 (121)

2.3.3.21. ERR

Direction


Error Information. When DSP received illegal maibox command, it responds with this command.

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Command Register Q 1 1 1 1 0 0 0 EID 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Data Register E_CMD_H E_TID

Bit Name Description command[15] Q Sequence number command[14:8] CMD_H 0x78 command[7:0] EID error ID data[15:8] E_CMD_H CMD_H which caused this error data[7:0] E_TID TID which caused this error

EID description

Name EID Description BADTID 0x10 TID in the mailbox command is not valid BADTCN 0x11 Received a transaction not allowed BADBID 0x20 BID in the mailbox command is not valid BADCNT 0x21 CNT in the mailbox command is not valid NOTLOCKED 0x22 An IPBUF line which has not been locked by DSP was going to

be released STVBUF 0x23 DSP is starving for the IPBUF BADADR 0x24 Address in the mailbox command is not valid (unused) BADTCTL 0x30 Received unrecognized TCTL command BADPARAM 0x50 Bad parameter in the mailbox command FATAL 0x58 Fatal error. This is used within DSP MMU error recovery

process. NOMEM 0xc0 DSP could not allocate memory resource NORES 0xc1 DSP could not allocate other resources IPBFULL 0xe2 No free Global IPBUF TASKNOTRDY 0xe0 DSP task encountered something not initialized properly TASKBSY 0xe1 Some DSP task resources are busy TASKERR 0xef Other error occurred in the task context BADCFGTYP 0xf0 Received unrecognized CFGTYP in DSPCFG command DEBUG 0xf8 EID for debugging BADSEQ 0xfe Illegal sequence of Q bit in the mailbox command BADCMD 0xff Received unrecognized mailbox command

42 (121)

2.3.3.22. DBG

Debug. DSP sends a debug message using the System IPBUF. ARM doesn’t issue this command. Direction





43 (121)

2.4. Mailbox Command Sequence

Some examples of mailbox command sequence are illustrated in this section. They will help you to understand how the mailbox commands are exchanged between the processors. 2.4.1. Configuration Sequence

2.4.1.1. System Configuration

After DSP program has been loaded, system configuration should be done firstly. The configuration sequence is shown in Figure 2-14.

Figure 2-14: System Configuration Sequence

ARM DSP

DSP issues BKYLD for N times after DSPCFG sequence. Here N is the IPBUF line count that DSP want to give to MPU at initial time.

with configuration data in the System IPBUF

DSPCFG : CFG_PROTREV DSPCFG : CFG_SYSADRH DSPCFG : CFG_SYSADRL with LAST bit asserted

BKYLD

BKYLD

DSPCFG : CFG_REQ

2.4.1.2. Task Configuration

Following the system configuration, all static DSP tasks should be configured. The configuration sequence is shown in Figure 2-15.

Figure 2-15: Task Configuration Sequence

ARM DSP

with task configuration data in the System IPBUF

TCFG (response)

TCFG (request)

44 (121)

2.4.1.3. Task Add / Delete

On-demand task is added to the system with the TADD command. The sequence is shown in Figure 2-16. After the task has been added, it should be configured with TCFG command. See 2.4.1.2.

Figure 2-16: Task Add Sequence

ARM DSP

with task address in the System IPBUF

with TID

(Will be followed by TCFG sequence)

TADD (response)

TADD (request)

On-demand task is deleteed fron the system with the sequence shown in Figure 2-17.

Figure 2-17: Task Delete Sequence

ARM DSP

TDEL (response)

TDEL (request)

2.4.2. Data Transfer Sequence

The Data transfer sequences are different for every task types. Each sequence is shown below. About the task type, see 5.3.

45 (121)

2.4.2.1. ARM to DSP transfer

A word data is sent from ARM to a Passive Word Receiving Task with the sequence shown in Figure 2-18.

Figure 2-18: ARM to DSP Data Transfer Sequence in Passive Word Receiving Task

ARM DSP

WDSND

A word data is sent from ARM to an Active Word Receiving Task with the sequence shown in Figure 2-19.

Figure 2-19: ARM to DSP Data Transfer Sequence in Active Word Receiving Task

ARM DSP

WDSND

WDREQ

A block data is sent from ARM to a Passive Block Receiving Task with the sequence shown in Figure 2-20.

Figure 2-20: ARM to DSP Data Transfer Sequence in Passive Block Receiving Task

ARM DSP

BKYLD (optional)

BKSND

46 (121)

A block data is sent from ARM to an Active Block Receiving Task with the sequence shown in Figure 2-21.

Figure 2-21: ARM to DSP Data Transfer Sequence in Active Block Receiving Task

ARM DSP

BKYLD (optional)

BKSND / BKSNDP

BKREQ / BKREQP

47 (121)

2.4.2.2. DSP to ARM transfer

A word data is sent from a Passive Word Sending Task to ARM with the sequence shown in Figure 2-22.

Figure 2-22: DSP to ARM Data Transfer Sequence in Passive Word Sending Task

ARM DSP

WDSND

WDREQ

A word data is sent from an Active Word Sending Task to ARM with the sequence shown in Figure 2-23.

Figure 2-23: DSP to ARM Data Transfer Sequence in Active Word Sending Task

ARM DSP

WDSND

A block data is sent from an Passive Block Sending Task to ARM with the sequence shown in Figure 2-24.

Figure 2-24: DSP to ARM Data Transfer Sequence in Passive Block Sending Task

ARM DSP

BKREQ

BKSND / BKSNDP

BKYLD (optional)

48 (121)

A block data is sent from an Passive Block Sending Task to ARM with the sequence shown in Figure 2-25.

Figure 2-25: DSP to ARM Data Transfer Sequence in Active Block Sending Task

ARM DSP

BKSND / BKSNDP

BKYLD (optional)

2.4.2.3. TCTL

TCTL sequence is shown in Figure 2-27.

Figure 2-26: TCTL Sequence

ARM DSP with address on

the data register, args in the System

IPBUF (if any).

with return value on the data

register (optional)

TCTL

TCTL

2.4.2.4. REGRW

DSP registers (and any data in memory / IO space) can be read / written with REGRW command. The read sequence is shown in Figure 2-27.

Figure 2-27: DSP Register Read Sequence

ARM DSP with address on

the data register

with read data on the data register

REGRW : MEMR / IOR

REGRW : DATA

49 (121)

The write sequence is shown in Figure 2-28.

Figure 2-28: DSP Register Write Sequence

ARM DSP with address on the

data register, data in the System IPBUF

REGRW : MEMW / IOW

2.4.2.5. GETVAR / SETVAR

The DSP system parameters can be read / written with GETVAR / SETVAR command. The read sequence is shown in Figure 2-29.

Figure 2-29: DSP System Parameter Read Sequence

ARM DSP

with read data on the System IPBUF GETVAR : VARID

GETVAR : VARID

The write sequence is shown in Figure 2-30.

Figure 2-30: DSP System Parameter Write Sequence

ARM DSP

with set data on the System IPBUF

SETVAR : VARID

50 (121)

3. LINUX API 3.1. Overview

Figure 3-1: DSP Gateway Linux APIs

DSP ARM(Linux)

Mailbox

“task1” “task2” “task3”

/dev/dsptask/ task1

/dev/dsptask/ task2

/dev/dsptask/ task3

user app.

dspctl utility

/dev/dspctl/ ctl

/dev/dspctl/ m

em

INT handler

DSP Gateway library

DSP memory

device I/F

DSP control

device I/F

DSP task device I/F

DSP Gateway driver

INT handler

DSP/ BIOS TASK

DSP/ BIOS TASK

DSP/ BIOS TASK

task API

DSP task

watch device I/F

/dev/dspctl/ tw

ch

Dynamic Loader Daemon

/dev/dspctl/ err

DSP error

detection device I/F

Figure 3-1 shows Linux APIs for the DSP Gateway driver. There are five device interfaces regarding the DSP Gateway - DSP task devices, DSP task watch device, DSP control device, DSP error detection device and DSP memory device. In general, user applications which want to utilize a DSP task (like an audio / video codec) need to access only to the DSP task devices. Other device I/Fs are used by special utility programs, i.e. DSP application Dynamic Loader Daemon and dspctl utility. 3.2. DSP Task Devices

The DSP task devices provide interfaces to the DSP tasks for Linux applications. Those device files are created automatically in devfs system, or linked to /dev/dsptask* in non-devfs system. (devfs system)

crw-r--r-- 1 root root 97, 0 Jan 1 0:01 /dev/dsptask/task1 crw-r--r-- 1 root root 97, 1 Jan 1 0:01 /dev/dsptask/task2

(non-devfs system)

lr-xr-xr-x 1 root root 13 Jan 1 0:01 /dev/dsptask/task1 -> /dev/dsptask0 lr-xr-xr-x 1 root root 13 Jan 1 0:01 /dev/dsptask/task2 -> /dev/dsptask1

Reading from and writing to those devices mean receiving and sending data from/to the DSP tasks. There are two types of DSP task, static task and on-demand task. The static tasks are linked with the tokliBIOS kernel statically, and are loaded to DSP memory together. They become available by DSP configuration (i.e. DSPCFG ioctl command to the DSP control device), and stay alive until DSP unconfiguration (i.e. DSPUNCFG ioctl command to the DSP control device). Unlike the static tasks, the on-demand tasks are not linked with the tokliBIOS kernel statically but loaded and linked dynamically. To

51 (121)

use the on-demand tasks, Linux side needs to create the task device file with MKDEV ioctl command to the DSP task watch device (/dev/dspctl/twch), then load the task program object to DSP memory, and issue TADD ioctl command to the DSP task watch device. This series of procedure will be taken care by the DSP Dynamic Loader Daemon. 3.2.1. open()

This driver allows to be opend by two or more processes at same time. In this case, device lock operation might be needed to ensure some exclusive sequence, for instance write then read the result. While one process is locking the dsptask device, all read(), write() and ioctl() calls from other process is blocks until the locking process unlocks the device. Figure 3-2 shows an example of the device lock operation.

Figure 3-2: Example of Device Lock Operation

open()

process1

ioctl(LOCK)

ioctl(UNLOCK)

read()

write()

open()

process2

ioctl(LOCK)

(blocks while process1 is locking the

device)

ioctl(UNLOCK)

read()

write()

close() close()

process1 is locking this device

process2 is locking this device

dsptask device lock status

If this device has been created by MKDEV ioctl (i.e. the DSP task is on-demand type), and the DSP task has not been attached to this device, this open call blocks, and the kernel wakes up the DSP Dynamic Loader Daemon. The daemon loads the corresponding task object and issue TADD ioctl to the DSP control device, then this device gets available and open call is completed.

52 (121)

3.2.2. close()

If this device has been created by MKDEV ioctl (i.e. the DSP task is on-demand type), the kernel wakes up the DSP Dynamic Loader Deamon in order to inform that this task is not in use any more and resources can be released. 3.2.3. read()

Receives data from the DSP task. For a Passive Sending task, ARM sends a request to DSP and waits for the response from DSP. Until the response comes, the read() blocks (Figure 3-3). For an Active Sending task, read() blocks if the driver hasn’t received any data from DSP until any data comes (Figure 3-4). If DSP has already sent some data to ARM, read() can return immediately (Figure 3-5). DSP task can’t detect the presence of the read-waiting process in Linux side, and just send data arbitrary. The Linux application can detect whether the driver has received data from DSP or not with poll() / select() call. This driver receives read data from DSP only when the device is being opened, even from Active Sending tasks. If any data arrived from the task which is not being opened by any applications, the driver simply discards those data. Application programmer should note that the address of the read buffer, specified as the second argument of the read() system call, should be aligned in 2-byte boundary. This function checks it and if not, returns with an error.

Figure 3-3: read( ) call to Passive Sending Task

ARM DSP

call read( )

read( ) returns

blocking

WDREQ/ BKREQ

WDSND/ BKSND

Figure 3-4: read( ) call to Active Sending Task before DSP data send

Figure 3-5: read( ) call to Active Sending Task after DSP data send

ARM DSP

call read( )

read( ) returns

blocking WDSND/ BKSND

ARM DSP

call read( )read( ) returns

WDSND/ BKSND

53 (121)

3.2.4. write()

Sends data to the DSP task. For a Passive Receiving task, write() always sends the data to DSP immediately (Figure 3-6). For an Active Receiving task, write() blocks if the driver hasn’t received any data request from DSP (Figure 3-7). If there is a pending request from DSP, write() can send the data to DSP immediately (Figure 3-8). A DSP task can’t detect the presence of write-waiting processes in Linux side, but just issues data requests arbitrarily. The Linux application can detect whether the driver has pending request from DSP or not with poll() / select() call. Application programmer should note that the address of the write data, specified as the second argument of the write() system call, should be aligned in 2-byte boundary. This function checks it and if not, returns with an error.

Figure 3-6: write( ) call to Passive Receiving Task

ARM DSP

call write( )

write( ) returns

WDSND/ BKSND

♦ Active Receiving Task

Figure 3-7: write( ) call to Active Receiving Task before DSP data request

Figure 3-8: write( ) call to Active Receiving Task after DSP data request

write () before DSP data request

write() after DSP data request

ARM DSP

call write( )

write( ) returns

blocking WDREQ/ BKREQ

WDSND/ BKSND

ARM DSP

call write( )

write ( ) returns

WDREQ/ BKREQ

WDSND/ BKSND

54 (121)

3.2.5. poll(), select()

Sees if you can do non-blocking read/write for the DSP task. These calls have a meaning only for the input check for Active Sending tasks or output check for Active Receiving tasks. When poll() or select() are used for the input check for a Passive Sending task or the output check for a Passive Receiving task, it will always be set and returns immediately. 3.2.6. ioctl()

Basiaclly, ioctl() commands are forwarded to the DSP task as TCTL mailbox commands (See 2.3.3.8. for TCTL command). The user can define ioctl/TCTL commands in the range of 0x8000 – 0x81ff and 0x9000 – 91ff. Additionally, the command range of 0x80 – 0xff is also user defind, but it is kept for backward compatibility. The user should not define any commands in this range newly. Ioctl commands above 0x10000 are not related to TCTL.

Table 3-1: DSP Task Device ioctl( ) Commands

ioctl command Description 0x0000 -0x007f Issues TCTL to the DSP task. (commands are reserved for system)

0x0000 Reserved. 0x0001 TEN Issues TCTL:TEN to DSP. 0x0002 TDIS Issues TCTL:TDIS to DSP. 0x0003 Reserved. 0x0004 Reserved.

others Reserved. 0x0080 - 0x00ff Issues TCTL to the DSP task. (no parameter, no return value)

This range is kept for backward compatibility. DO NOT define new commands in this range.

0x0100 – 0x7fff Reserved. 0x8000 – 0x80ff Issues TCTL to the DSP task. (no parameter, no return value) 0x8100 – 0x81ff Issues TCTL to the DSP task. (1 parameter, no return value) 0x8200 – 0x8fff Reserved. 0x9000 – 0x90ff Issues TCTL to the DSP task. (no parameter, have a return value) 0x9100 – 0x91ff Issues TCTL to the DSP task. (1 parameter, have a return value) 0x9200 – 0xffff Reserved.

0x10000 - Commands in this range are not related to TCTL. 0x10000 BFLUSH Flushes receive buffer. 0x10001 SETBSZ Changes receive buffer size.

Same thing can be done by writing to /proc/dsp/task/<taskname>/fifosz.

0x10002 LOCK Acquire device lock. 0x10003 UNLOCK Release device lock. 0x10004 GETNAME Acquire device name.

others Reserved. 3.2.7. mmap()

Shares the memory block exported from the DSP task.

55 (121)

This is valid only for the DSP task which has mmap_info structure (see 5.4). After mmapping, the application can access to the task memory block (which starts from mmap_info.start) directly. It should be noted that the data path using mmap() is totally independent from read() or write(). It means that the data obtained by read() and copied from the mmapped buffer will be different. The data synchronization between ARM and DSP can be carried out with read() and write(). For example, after ARM application writes data to the mmapped buffer, it writes the information of the written data – i.e. offset address in the shared buffer and data size. An example is shown in List 3-1 and List 3-2.

List 3-1: mmap example – ARM side List 3-2: mmap example – DSP side unsigned long cmdbuf[2]; addr = mmap(NULL, maplen, PROT_READ | PROT_WRITE, MAP_SHARED, dsp_fd, 0)); memcpy(addr, userdata, wordsize); cmdbuf[0] = 0; // offset cmdbuf[1] = wordsize; // length write(dsp_fd, cmdbuf, 8);

static struct mmap_info mmap_info = { shmem, // start 0x1000 // length }; Uns mm_rcv_bksnd(struct dsptask *task, Uns bid, Uns cnt) { Uns *adr; Uns *ipbp = ipbuf_d[bid] off = ((LgUns)ipbp[1] << 16) | ipbp[0]; len = ((LgUns)ipbp[3] << 16) | ipbp[2]; unuse_ipbuf(task, bid); adr = shmem + off; /*

* handle data at adr... */ }

3.3. DSP Control Device

The DSP control device provides DSP control API for Linux. Linux applications can control DSP reset, read DSP configuration, and perform other various controls through this device. In devfs system, the device file /dev/dspctl/ctl will be created automatically. Otherwise, the user need to create the device file with ‘mknod /dev/dspctl/ctl c 96 0’.

crw-r--r-- 1 root root 96, 0 Jan 1 0:00 /dev/dspctl/ctl 3.3.1. ioctl()

Following ioctl commands are defined. ♦ RESET ♦ RUN

Resets DSP or releases the reset.

56 (121)

♦ SETRSTVECT

Sets specified address for the DSP reset vector.

♦ IDLE

Lets DSP in the idle state by executing short program in DSP. That program includes an IDLE instruction folloing ICR register set. The loading value for the ICR register is generated according to the icrmask value and can be controlled through SETVAR ioctl or /proc/dsp/icrmask proc device.

♦ MPUI_WORDSWAP_ON ♦ MPUI_WORDSWAP_OFF

Turns on / off the wordswap in MPUI block. It affects the accesses to DARAM/SARAM from ARM.

♦ MPUI_BYTESWAP_ON ♦ MPUI_BYTESWAP_OFF

Turns on / off the byteswap in MPUI block. It affects the accesses to DARAM/SARAM from ARM.

♦ DSPCFG

Obtains DSP system/task information and creates the DSP task device files. (The devices created by this ioctl command are static tasks.)

♦ DSPUNCFG

Deletes the DSP task device files and kernel internal structures regarding those tasks.

♦ TASKCNT

Obtains the number of static dsp tasks.

♦ REGMEMR ♦ REGMEMW ♦ REGIOR ♦ REGIOW

Read from / writes to DSP memory or I/O space by issuing REGRW mailbox command to DSP. This command takes an argument, the pointer of struct omapdsp_reginfo.

struct omapdsp_reginfo { unsigned short adr; unsigned short val[5]; }

adr Address in question val Value: user should set when write, result will be here when read

♦ GETVAR ♦ SETVAR

Get or set DSP system variable by issuing GETVAR / SETVAR mailbox command to DSP. This command takes an argument, the pointer of struct omapdsp_varinfo.

struct omapdsp_varinfo { unsigned char varid; unsigned short val; }

57 (121)

varid ID of the system variable (see 2.3.3.20). val Value: user should set when write, result will be here when read

♦ RUNLEVEL

Switches DSP system runlevel by issueing RUNLEVEL mailbox command to DSP. See 2.3.3.11 for more detail about RUNLEVEL mailbox command.

♦ SUSPEND ♦ RESUME

SUSPEND sends SUSPEND mailbox command to DSP and waits for the SUSPEND response. After that, resets DSP. RESUME releases DSP reset. (almost same with RUN ioctl)

♦ MBSEND (for debug use)

Sends mailbox command to the DSP manually. This command takes an argument, the pointer of struct omapdsp_mailbox_cmd.

3.4. DSP Memory Device

The DSP memory device provides the access to the DSP memory space for the DSP program loader in Linux side. In devfs system, the device file /dev/dspctl/mem will be created automatically. Otherwise, the user need to create the device file with ‘mknod /dev/dspctl/mem c 96 1’.

crw-r--r-- 1 root root 96, 1 Jan 1 0:00 /dev/dspctl/mem The DSP program loader loads the DSP binary image to the DSP internal memories (i.e. DARAM and SARAM) through this device. Moreover, the user can extend the usable DSP memory range by mapping external SDRAM block to the DSP memory space using ioctl commands to this device. After mapping, the DSP application loader can access to the extended memory as well.

Figure 3-9: External Memory Mapping for DSP Space 00_0000

01_0000DARAM SARAM

02_8000

DSP MEMORY SPACE FF_FFFF

The extended memory area

58 (121)

3.4.1. lseek()

Seeks in the DSP external memory space. 3.4.2. read()

Reads data from the DSP external memory space. This can be used for the debug purpose. 3.4.3. write()

Writes data to the DSP external memory space. 3.4.4. ioctl()

Following ioctl commands are defined. They are used to maintain DSP memory mapping through the DSP MMU. ♦ MMUINIT (for debug use)

Initializes DSP MMU unit. Usually it is done automatically.

♦ EXMAP

Allocates the buffer and maps it to the DSP memory space by registering an entry in DSP MMU TLB and also to Linux virtual space by setting page table entry. Programmer can extend available memory for DSP (Figure 3-10). This buffers can be accessed through the DSP exmem device driver. This command takes an argument, the pointer of struct omapdsp_mapinfo.

struct omapdsp_mapinfo { unsigned long dspadr; unsigned long size; }

adr Address to which the allocated buffer will be mapped in the DSP space val Required size

Figure 3-10: DSP Memory Expansion with EXMAP ioctl

00_0000

01_0000DARAM SARAM

02_8000


00_0000

01_0000DARAM SARAM

02_8000

FF_FFFF

dspadrsize

59 (121)

♦ EXUNMAP

Releases one buffer allocated by EXMAP ioctl and flushes corresponding mappings in the DSP MMU TLB and Linux page table. This command takes an argument, the DSP address which has been set to dspadr entry in struct omapdsp_mapinfo at the EXMAP ioctl.

♦ EXMAP_FLUSH

Releases all buffers allocated by EXMAP ioctl and flushes corresponding mappings in the DSP MMU TLB and Linux page table. It doesn’t flushes the mapping for interrupt vectors.

Figure 3-11: Clear of External Memory Mapping from DSP space with EXMAP_FLUSH ioctl 00_0000

01_0000DARAM SARAM

02_8000


00_0000

01_0000DARAM SARAM

02_8000

FF_FFFF

Areas mapped by EXMAP ioctl

♦ FBEXPORT

Maps the framebuffer to the DSP memory space and to corresponding Linux virtual space. By doing this, DSP can access to frame buffer directly, without sending back the image data to ARM. This can help to increase the performance of image decoders. This command takes an argument, the pointer of the dspadr variable. The application sets a hint address on this variable, then the DSP Gateway driver returns actual mapped address on it.

♦ MMUITACK

When the application (DSP Dynamic Loader daemon etc.) has detected the DSP MMU error, it issues this ioctl in order to acknowledge the error and switch the DSP to the RECOVERY runlevel.

3.5. DSP Task Watch Device

The DSP Task Watch device provides functionalities needed for the DSP Dynamic Loader Daemon. In devfs system, the device file /dev/dspctl/twch will be created automatically. Otherwise, the user need to create the device file with ‘mknod /dev/dspctl/twch c 96 2’.

crw-r--r-- 1 root root 96, 2 Jan 1 0:00 /dev/dspctl/twch The daemon can obtain the information which task is in use, not in use or requesting to be loaded and started. It adds and deletes on-demand DSP tasks, creates and removes DSP task device files for those tasks through the ioctl() commands for this device.

60 (121)

3.5.1. read()

Reads status of DSP task devices. The read data is byte-stream and each 4 bytes represents one device status (Table 3-2). The data by each read() call always starts from the status of minor number 0 device. For example, if you read 10 * 4 bytes from DSP Task Watch device, you get statuses of minor number 0 to 9 devices.

Table 3-2: Fields in the Data read from DSP Task Watch Device

Byte Description [0:3] open status of task device of minor number 0 [4:7] open status of task device of minor number 1 [8:11] open status of task device of minor number 2 : :

The meanings of open status value are shown in Table 3-3.

Table 3-3: Value Definition of the Data read from DSP Task Watch Device

Status Name Value Description

NOTASK 0x00000001 DSP task is not attached to this device. Initial state for on-demand task.

ATTACHED 0x00000002 DSP task is attached to this device. Static tasks are always in this state.

GARBAGE 0x00000004 Garbage. The DSP task is killed and the device is waiting to be closed by all application processes.

ADDREQ 0x00000100 An application process has opened this on-demand device and the DSP task has not been added yet. When the Dynamic Loader Daemon observes this state, it should load the dynamic task object to the DSP memory and issue TADD ioctl to the Task Watch device.

DELREQ 0x00000200 All application processes have closed this on-demand device and the DSP task has not been deleted yet. When the Dynamic Loader Daemon observes this tate, it should issue TDEL ioctl to the Task Watch device.

KILLREQ 0x00000400 Someone has issued TKILL ioctl to the Task Watch device and waiting for the DSP response.

ADDFAIL 0x00001000 TADD ioctl has failed. Waiting for the open() function which has caused this TADD process to be finished.

The open status values correspond to the static tasks are always seen as ATTACHED. The read() call will block if no task has changed their open status since previous read(), until any status changes occur. If the user process should not block, it should call poll() or select() before calling read(). 3.5.2. poll(), select()

Sees if the user process can do non-blocking read for the DSP Task Watch device.

61 (121)

3.5.3. ioctl()

Following ioctl commands are defined for on-demand DSP task creation and removal. ♦ MKDEV ♦ RMDEV

Creates / removes a DSP task device file. It will become the stub device for the on-demand task added by TADD ioctl in future.

♦ TADD

Adds on-demand task by issuing TADD mailbox command to DSP. The new task will be attached to the task device of same name with this DSP task. The corresponding task device should be created beforehand by MKDEV ioctl. This command takes an argument, the pointer of struct omapdsp_taddinfo.

struct omapdsp_taddinfo { unsigned long minor; unsigned long taskadr; }

minor minor device number of the task device. taskadr address of the dsptask structure of newly adding task.

♦ TDEL

Detaches the on-demand task from the task device and disable that task in DSP side by issuing TDEL:SAFE mailbox command. The task device remains until being deleted explicitly by RMDEV ioctl.

♦ TKILL

Detaches the on-demand task from the task device and disable that task in DSP side by issuing TDEL:KILL mailbox command. TDEL:KILL command will not wait for the DSP task to finish all commands registered its queue, unlike TDEL:SAFE command. The task device remains until being deleted explicitly by RMDEV ioctl.

3.6. DSP Error Detection Device

The DSP Error Detection device is used to detect error from DSP, such as watchdog timer expiration and DSP MMU error interrupt. In devfs system, the device file /dev/dspctl/err will be created automatically. Otherwise, the user need to create the device file with ‘mknod /dev/dspctl/err c 96 3’.

crw-r--r-- 1 root root 96, 3 Jan 1 0:00 /dev/dspctl/err 3.6.1. read()

Reads a 32-bit error code. The read() call blocks until any of DSP errors listed in Table 3-4 occurs. Table 3-4: Error Code

Bit name Short Description 31:2 reserved 1 MMU MMU fault

62 (121)

0 WDT WDT expiration ♦ MMU

Received a DSP MMU interrupt.

♦ WDT

DSP watchdog timer has been expired.

3.6.2. poll(), select()

Sees if any errors are detected and read() can be done without blocking. 3.7. DSP Proc File I/F

Several proc file I/Fs are created for status checks, parameter chacks and changes. 3.7.1. /proc/dsp/cur_users

Read-only entry. This shows the PID of processes which are opening any of the DSP device files. List 3-3: /proc/dsp/cur_uses example /root # cat /proc/dsp/cur_users 35

3.7.2. /proc/dsp/mblog

Read-only entry. This shows the log of mailbox command exchanges. It will be helpful for debugging.

List 3-4: /proc/dsp/mblog example /root # cat /proc/dsp/mblog log count:86 / ARM->DSP:43, DSP->ARM:43 ARM->DSP ARM<-DSP jiffies cmd data cmd data 0000173d 3004 0000 TCTL:task 4 0000173e e005 0000 TCFG:task 5 0000173e e005 0000 TCFG:task 5 0000173f 3005 0000 TCTL:task 5 00001740 e006 0000 TCFG:task 6 : 00001f56 2001 0001 BKSND:task 1 00001f56 2300 0005 BKYLD 00001fba f901 0000 DBG 00001fba 2001 0002 BKSND:task 1 00001fba 2300 0006 BKYLD

63 (121)

3.7.3. /proc/dsp/version

Read entry. This shows DSP Gateway driver version.

List 3-5: /proc/dsp/version example /root # cat /proc/dsp/version 3.1

3.7.4. /proc/dsp/icrmask

Read and write entry. This is the mask value of ICR register in DSP. This value affects when DSP falls in idle mode.

List 3-6: /proc/dsp/icrmask example /root # cat /proc/dsp/icrmask 003f (hex) /root # echo 0 > /proc/dsp/icrmask /root # cat /proc/dsp/icrmask 0000 (hex)

3.7.5. /proc/dsp/mmu

Read entry. This shows DSP MMU TLB status.

List 3-7: /proc/dsp/mmu example /root # cat /proc/dsp/mmu p: preserved, v: valid ety cam_va ram_pa sz ap 00: p v 0xfff000 0x10e21000 4KB FA 01: v 0x100000 0x10d00000 1MB FA lock base = 2 victim = 2 02: 0x600000 0x2a78ec00 1MB NA 03: 0x600000 0xacf4c400 1MB RO 04: 0x900000 0x926d8400 1MB NA 05: 0xa00000 0x8ec74c00 1MB RO : 30: 0xa00000 0x32794c00 1MB NA 31: 0x500000 0x44c76800 1MB NA

3.7.6. /proc/dsp/ipbuf

Read entry. This shows Global IPBUF status.

List 3-8: /proc/dsp/ipbuf example /root # cat /proc/dsp/ipbuf ipbuf[0]: adr = 0xe0100000 DSPtask[1]->Linux (already read and now free for Linux) ipbuf[1]: adr = 0xe010c00c

64 (121)

DSPtask[1]->Linux (already read and now free for Linux) ipbuf[2]: adr = 0xe0118018 Linux->DSPtask[254] (already read and now free for DSP) ipbuf[3]: adr = 0xe0124024 Linux->DSPtask[254] (already read and now free for DSP) ipbuf[4]: adr = 0xe0130030 Linux->DSPtask[254] (already read and now free for DSP) ipbuf[5]: adr = 0xe013c03c Linux->DSPtask[254] (already read and now free for DSP) ipbuf[6]: adr = 0xe0148048 DSPtask[1]->Linux (already read and now free for Linux) ipbuf[7]: adr = 0xe0154054 DSPtask[1]->Linux (already read and now free for Linux) Free IPBUF link: 6 7 0 1 IPBFULL error count: 0

3.7.7. /proc/dsp/loadinfo

Read entry. This shows DSP load infomation.

List 3-9: /proc/dsp/loadinfo example /root # cat /proc/dsp/loadinfo DSP load info: 10ms average = 0.13% 1sec average = 0.13% busiest 10ms = 0.34% 1min average = 0.13% busiest 1s = 0.13%

3.7.8. /proc/dsp/task/<taskname>/status

Read entry. This shows DSP task status.

List 3-10: /proc/dsp/task/<taskname>/status example /root # cat /proc/dsp/task/hellotimer/status device name: hellotimer openstat CLOSE attached task: hellotimer cfgstat DONE tid 1 ttyp 0x000a (active global block send, passive word receive) rcvfifo->buf 0xc0e10000 rcvfifo->sz 49152 rcvfifo->cnt 0 rcvfifo->wp 0 wsz 2 delayed list top NULL tail NULL private IPBUF for read 0x00000000 private IPBUF for write 0x00000000

3.7.9. /proc/dsp/task/<taskname>/fifosz

Read and write entry. This is the receive buffer size of this task in the Linux driver.

65 (121)

List 3-11: /proc/dsp/task/<taskname>/fifosz example /root # cat /proc/dsp/task/hellotimer/fifosz 49152 /root # echo 4096 > /proc/dsp/task/hellotimer/fifosz /root # cat /proc/dsp/task/hellotimer/fifosz 4096

3.8. Header for Applications

Followings are defined in include/asm-arm/arch-omap/dsp.h. If applications need to refer to those values, this header should be included. ♦ ioctl commands for each device I/F ♦ structure for specific ioctls (omapdsp_reginfo, omapdsp_mapinfo, etc.) ♦ value definitions of task device open status ♦ mailbox commands

66 (121)

4. LINUX DRIVER OVERVIEW AND SYSTEM CONFIGURATION

4.1. Overview

The DSP Gateway driver has five device I/Fs (task device I/Fs, task watch device I/F, control device I/F, error detection device I/F and memory device I/F) and two interrupt handlers (Mailbox and DSP MMU), as shown in Figure 4-1.

Figure 4-1: DSP Gateway Driver Block Chart

DSP

ARM(Linux)

DSP memory device I/F

DSP control device I/F

DSP task device I/Fs

Mailbox interrupt handler

DSP task watch device

I/F

Mailbox

open( ) release( )

read( ) write( ) poll( ) ioctl( )

read( ) poll( ) ioctl( )

open( ) release( )

ioctl( )

open( ) llseek( ) read( ) write( ) ioctl( )

WDSND WDREQ BKSND BKREQ

BKSNDP BKREQP

TCFG

WDT

TADD TDEL

DSPCFG REGRW GETVAR SETVAR

DSP MMU

DSP MMU interrupt handler

DSP error detection device I/F read( ) poll( )

BKYLD ERR DBG

4.2. Kernel Configuration

In order to use the DSP Gateway, you should follow the kernel configuration guideline as below.

67 (121)

♦ Enable “System Type ---> TI OMAP Implementations ---> OMAP DSP Driver (DSP Gateway)” (can be a kernel module)

♦ “Mailbox Command Verbose LOG” is optional, but it will help for debugging. ♦ Enable “DSP Task Multiopen Capability” if you want. ♦ Enable “Framebuffer export to DSP” if you want to access framebuffer from DSP.

Figure 4-2: Kernel Configuration Menu

4.3. Device Files

If you don’t use devfs, you need to add following device files in your file system. Contorl devices

crw------- 1 root root 96, 0 Jan 1 0:00 /dev/dspctl/ctl crw-r----- 1 root root 96, 1 Jan 1 0:00 /dev/dspctl/mem crw-r----- 1 root root 96, 2 Jan 1 0:00 /dev/dspctl/twch cr--r----- 1 root root 96, 3 Jan 1 0:00 /dev/dspctl/err

Task devices (as many as you need, but no more than 254)

crw-rw-rw- 1 root root 97, 0 Jan 1 0:00 /dev/dsptask0 crw-rw-rw- 1 root root 97, 1 Jan 1 0:00 /dev/dsptask1 crw-rw-rw- 1 root root 97, 2 Jan 1 0:00 /dev/dsptask2 crw-rw-rw- 1 root root 97, 3 Jan 1 0:00 /dev/dsptask3 crw-rw-rw- 1 root root 97, 4 Jan 1 0:00 /dev/dsptask4 :

Task device directory

drw-rw-rw- 1 root root 4096 Jan 1 0:00 /dev/dsptask/

68 (121)

5. DSP PROGRAMMING 5.1. Overview

Figure 5-1: DSP Software Block Chart

DSP

ARM(Linux)

Mailbox

“task1”

“task2” “task3”

/dev/dsptask /task1

user application

INT handler DSP system kernel (tokliBIOS)

DSP Gateway Driver

DSP/BIOS TSK (user task)



task API

rcv_snd( ) function

queue

DSP/BIOS TSK (supertask)

rcv_req( ) function

rcv_tctl( ) function

Figure 5-1 shows the DSP Software Block Chart. When a Linux user application accesses to the DSP task device, /dev/dsptask/task1 for example, the driver generates a Mailbox command to DSP. In DSP side, the system kernel -- called tokliBIOS -- receives the Mailbox command and registers it into the queue of the corresponding DSP/BIOS TSK. The DSP/BIOS TSK processes the commands in the queue by calling corresponding task function, which is a member of the task1 in this case. This task function is the program which DSP application programmer should implement. The task functions can send back Mailbox commands to ARM by calling task API functions in the tokliBIOS. 5.2. DSP Task Programming

DSP programmer should implement following functions and data defined in the dsptask structure for each task. Details of those members of the structure are described in 5.4. How to update your DSP Gateway 3.0 DSP task to 3.1 is instructed in [2]. struct dsptask { Uns tid; String name; Uns ttyp; Uns (*rcv_snd)(); // (*rcv_wdsnd)(struct dsptask *task, Uns data); // (*rcv_bksnd)(struct dsptask *task, Uns bid, Uns cnt); // (*rcv_bksndp)(struct dsptask *task, Uns cnt); Uns (*rcv_req)(); // (*rcv_wdreq)(struct dsptask *task);

69 (121)

// (*rcv_bkreq)(struct dsptask *task, Uns cnt); Uns (*rcv_tctl)(); // (*rcv_tctl)(struct dsptask *task, Uns ctlcmd, Uns *ret, Uns arg); struct TSK_Attrs *tsk_attrs; struct mmap_info *mmap_info; Void *udata; };

The maximum number of the DSP task is 126 (TID 0x00–0xfd), leaving 0xfe and 0xff for the special purposes for the IPBUF owner information. Note that this dsptask object should be placed in ‘dspgw_task’ section using ‘#pragma DATA_SECTION()’ directive. See List 5-1 for a dsptask instance.

List 5-1: dsptask instance #pragma DATA_SECTION(task1, “dspgw_task”) struct dsptask task1 = { TID_MAGIC, /* tid */ “test1”, /* name */ MBCMD_TTYP_WDDM | MBCMD_TTYP_WDMD | MBCMD_TTYP_PSND | MBCMD_TTYP_PRCV, /* ttyp */ rcv_wdsnd, /* rcv_snd */ rcv_wdreq, /* rcv_req */ rcv_tctl, /* rcv_tctl */ NULL, /* tsk_attrs */ NULL, /* mmap_info */ NULL /* udata */ }

5.3. Task Type

The DSP task type defines how the task performs the data transmission with ARM. it is defined with a combination of the following options. 5.3.1. Active Sending / Passive Sending

♦ Active Sending task

This task sends WDSND / BKSND / BKSNDP commands spontaneously, without receiving WDREQ/BKREQ/BKREQP command from ARM. If this task received WDREQ / BKREQ / BKREQP command, it returns ERR:BADTCN command.

♦ Passive Sending task

This task sends WDSND / BKSND / BKSNDP commands only in response to the WDREQ / BKREQ / BKREQP command from ARM.

5.3.2. Active Receiving / Passive Receiving

♦ Active Receiving task

This task issues WDREQ / BKREQ / BKREQP commands to ARM when it needs data. ARM should not send WDSND / BKSND / BKSNDP command to this task unless receiving a request.

70 (121)

♦ Passive Receiving task

This task never issues WDREQ / BKREQ commands to ARM. ARM can send WDSND / BKSND command at any time. Passive Receiving with Private IPBUF is not allowed.

5.3.3. Word Sending / Block Sending

♦ Word Sending task

This task uses WDSND command and never uses BKSND / BKSNDP command to send data to ARM.

♦ Block Sending task

This task uses BKSND / BKSNDP command and never uses WDSND to send data to ARM.

5.3.4. Word Receiving / Block Receiving

♦ Word Receiving task

This task accepts WDSND command to receive data from ARM. If this task received BKSND / BKSNDP command, it returns ERR:BADTCN command to ARM.

♦ Block Receiving task

This task accepts BKSND / BKSNDP command to receive data from ARM. If this task received WDSND command, it returns ERR:BADTCN command to ARM.

5.3.5. Global Block Sending / Private Block Sending

This option is applied only for Block Sending task. ♦ Global Block Sending task

This task uses BKSND command and never uses BKSNDP command to send data to ARM.

♦ Private Block Sending task

This task uses BKSNDP command and never uses BKSND to send data to ARM.

5.3.6. Global Block Receiving / Private Block Receiving

This option is applied only for Block Receiving task. ♦ Global Block Receiving task

This task accepts BKSND command to receive data from ARM. If this task received BKSNDP command, it returns ERR:BADTCN command to ARM.

71 (121)

♦ Private Block Receiving task

This task accepts BKSNDP command to receive data from ARM. If this task received BKSND command, it returns ERR:BADTCN command to ARM.

5.4. Dsptask structure members

The following instructs how to implement the dsptask structure members. Uns tid

Task ID. The initial value should be TID_MAGIC. The tokliBIOS kernel sets the Task ID of this task to this variable at the initialization. User can refer this value but should not change.

String name

Task name string. This should be a null-terminated string and the maximum length is 16 (including the null character).

Uns ttyp

Task type flags. See 2.3.3.11 for the bit definitions. Uns (*rcv_snd)()

This function defines the task action when it received WDSND (Word Receiving task), BKSND (Global Block Receiving task) or BKSNDP (Private Block Receiving task) command. The number of the arguments varies with the received command. ♦ For WDSND

Uns (*rcv_snd)(struct dsptask *task, Uns data)

The task is the pointer for dsptask structure of this task. The data is the received word data.

♦ For BKSND Uns (*rcv_snd)(struct dsptask *task, Uns bid, Uns cnt)

The task is the pointer for dsptask structure of this task. The bid is the received BID. The cnt is the valid data count. It can be assumed that the received bid and cnt are valid and the programmer doesn’t need to check for the validity in this function.

♦ For BKSNDP Uns (*rcv_snd)(struct dsptask *task, Uns cnt)

The task is the pointer for dsptask structure of this task. The cnt is the valid data count.

This function should return zero on normal completion, but if an error occurred, it should return EID which will be reported to ARM with ERR command. When DSP received BKSND command for the Block Receiving task from ARM, the targeted task becomes the owner of the IPBUF line used in this block transfer. This task is responsible for the lock control of the IPBUF. It can release or reuse for next BKSND to ARM. If it is not needed anymore, it should be released with unuse_ipbuf() API function.

72 (121)

Uns (*rcv_req)()

This function defines the task action when it received WDREQ or BKREQ command. The number of the arguments varies with the received command. ♦ For WDREQ

Uns (*rcv_req)(struct dsptask *task)

The task is the pointer for dsptask structure of this task.

♦ For BKREQ Uns (*rcv_req)(struct dsptask *task, Uns cnt)

The task is the pointer for dsptask structure of this task. The cnt is the valid data count. It can be assumed that the received cnt is valid and the programmer doesn’t need to check for the validity in this function.

This function should return zero on normal completion, but if an error occurred, it should return EID which will be reported to ARM with ERR command. This function pointer can be NULL for Active Sending task since it never receives WDREQ or BKREQ command.

Uns (*rcv_tctl)()

This function defines the task action when it received TCTL command. See 2.3.3.8 for TCTL command. The strict prototype of this function should be Uns (*rcv_tctl)(struct dsptask *task, Uns ctlcmd, Uns *ret, Uns arg);

But for backward compatibility, Uns (*rcv_tctl)(struct dsptask *task, Uns ctlcmd);

is still valid. The task is the pointer for dsptask structure of this task. The ctlcmd is the value of the mailbox data register with the received TCTL command. Table 5-1 shows the ctlcmd definition. The user can define TCTL commands in the range of ‘User-defined’.

Table 5-1: ctlcmd definition

Code Range Description 0x0000 – 0x007f System Command

0x0000 TINIT Task Initialize 0x0001 TEN Task Enable 0x0002 TDIS Task Disable 0x0003 TCLR Task Clear 0x0004 TKILL Task Kill

0x0004 | 0x007f

Reserved

0x0080 – 0x00ff User-defined (No parameter, No return value) This range is kept for backward compatibility. DO NOT define new commands in this range.

0x0100 - 0x7fff Reserved 0x8000 - 0x80ff User-defined (No parameter, No return value)

73 (121)

0x8100 - 0x81ff User-defined (1 parameter, No return value) 0x8200 - 0x8fff Reserved 0x9000 - 0x90ff User-defined (No parameter, have return value) 0x9100 - 0x91ff User-defined (1 parameter, have return value) 0x9200 - 0xffff Reserved

The ret is the value to be sent back to ARM as the return value for the ioctl. It is used only in the ctlcmds which have return value (i.e. 0x9000 – 0x90ff and 0x9100 – 0x91ff). The arg is the parameter sent from ARM as the argument for the ioctl. It can be used only in the ctlcmds which have parameter (i.e. 0x8100 – 0x81ff and 0x9100 – 0x91ff). This function should return zero on normal completion, but if an error occurred, it should return EID which will be reported to ARM with ERR command. it should return MBCMD_EID_BADTCTL for ctlcmds not defined for this task. List 5-2 shows an example of the rcv_tctl() implementation. If the tokliBIOS receives that value from this function, it performs default action for the ctlcmd. TINIT ctlcmd is called at the task initialization. TCLR ctlcmd is called before the task is deleted by TDEL:SAFE mailbox command. (This occurs only if it is an on-demand task) TKILL ctlcmd is called before the task is killed by TDEL:KILL mailbox command. (This occurs only if it is an on-demand task)

List 5-2: rcv_tctl( ) implementation example Uns t1_rcv_tctl(struct dsptask *task, Uns ctlcmd, Uns *ret, Uns arg) { switch(ctlcmd) { case USER_DEFINED_TCTL_COMMAND: /* * user program here. */ return 0; default: return MBCMD_EID_BADTCTL; } }

This function pointer can be NULL if there is nothing to do specifically for this task.

struct TSK_Attrs *tsk_attrs

This structure is defined in <tsk.h> for DSP/BIOS. The programmer can specify the DSP/BIOS TSK property, priority, stack size and others for this task by setting up the members of this structure. This structure is passed to the TSK_create() call in the tokliBIOS kernel. This structure pointer can be NULL if the default value is OK for this task. typedef struct TSK_Attrs { Int property; /* task priority */ Ptr stack; /* stack supplied */ Uns stacksize; /* size of stack */ Uns sysstacksize; /* size of system stack */ Int stackseg; /* segment to allocate stack from */ Ptr environ; /* environment pointer */ String name; /* printable name */ Bool exitflag; /* FALSE for server tasks */ } TSK_Attrs;

Default values of the members of this structure defined in the tokliBIOS library are followings.

74 (121)

property = DSPTASK_DEFAULT_PRIORITY (=2) stack = NULL; stacksize = DSPTASK_DEFAULT_STACKSIZE (=512) sysstacksize = DSPTASK_DEFAULT_SYSSTACKESIZE (=256) stackseg = MEM->MALLOCSEG environ = NULL name = (name in the dsptask structure) exitflag = TRUE

struct mmap_info *mmap_info

This is pointer for the mmap information. By setting this structure, mmap() for this task in Linux application is enabled. Note that the buffer block for mmap must be placed in SDRAM. mmap() doesn’t support the shared memory in DARAM or SARAM.

struct mmap_info { Void *start; LgUns length; };

start Start address of the buffer block to share with ARM. This needs to be aligned with 2k words boundary.

length Buffer block length. This needs to be multiple of 2k words. Void *udata

This pointer is for user data. The user can use this for the data used throughout the task. The tokliBIOS kernel never touches this pointer nor pointed data.

5.5. Task API

The DSP task programmer can use following task API functions / data in the task functions. In addition to these APIs, DSP/BIOS API functions (TSK_create() for example) can be used. The task functions, rcv_snd(), rcv_req() and rcv_tctl() are called in the DSP/BIOS TSK context and there are no limitations to use DSP/BIOS APIs in them. extern Uns *ipbuf_d[]; extern Uns get_free_ipbuf(struct dsptask *task); extern Void unuse_ipbuf(struct dsptask *task, Uns bid); extern Void register_tq_1s(struct dsptask *task, Uns (*f)(struct dsptask *task)); extern Void unregister_tq_1s(struct dsptask *task, Int id); extern Void wdsnd(struct dsptask *task, Uns data); extern Void bksnd(struct dsptask *task, Uns bid, Uns cnt); extern Void bksndp(struct dsptask *task, Void *data, Uns cnt); extern Void wdreq(struct dsptask *task); extern Void bkreq(struct dsptask *task, Uns cnt); extern Void bkreqp(struct dsptask *task, Void *data, Uns cnt); extern Void cmderr(struct dsptask *task, Uns eid); extern void dbg(struct dsptask *task, Char *fmt, ...);

75 (121)

Uns *ipbuf_d[]

Global IPBUF data pointer. The task can access data field of the Global IPBUF by ipbuf_d[bid]. It should access only to the Global IPBUF line which was received from ARM with BKSND command or obtained with get_free_ipbuf() API function. When the task is releasing its own IPBUF line, it should use unuse_ipbuf() API function.

Uns get_free_ipbuf(struct dsptask *task)

The task can allocate an IPBUF line for BKSND command with this API function. The task is the dsptask structure pointer of this task. If this function succeeded, returns the BID. If it failed, returns MBCMD_BID_NULL (0xffff).

Void unuse_ipbuf(struct dsptask *task, Uns bid)

The task can release its own IPBUF line with this API function. The task is the dsptask structure pointer of this task and the bid is the BID to be released. If there are enough free IPBUF lines in DSP side, this causes BKYLD command to ARM.

Void *register_tq_1s(struct dsptask *task, Uns (*f)(struct dsptask *task))

The task can register the function to be processed to the 1-sec Timer Queue (See 5.6). The task is the dsptask structure pointer of this task and the f is the function to be registered. If this function succeeded, returns the id value of the queue entry. If it failed, returns MEM_ILLEGAL.

Void unregister_tq_1s(struct dsptask *task, Void *id)

The task can unregister the function specified with the id from the 1-sec Timer Queue. The task is the dsptask structure pointer of this task.

Void wdsnd(struct dsptask *task, Uns data)

The task can issue a WDSND command with this API function. The task is the dsptask structure pointer of this task and the data is the word data to be sent.

Void bksnd(struct dsptask *task, Uns bid, Uns cnt)

The task can issue a BKSND command with this API function. The task is the dsptask structure pointer of this task, the bid is the BID used in this transaction and the cnt is the word count to be sent.

Void bksndp(struct dsptask *task, Void *data, Uns cnt)

The task can issue a BKSNDP command with this API function. The task is the dsptask structure pointer of this task, the data is the address of the data to be sent and the cnt is the word count to be sent.

Void wdreq(struct dsptask *task)

The task can issue a WDREQ command with this API function. The task is the dsptask structure pointer of this task.

Void bkreq(struct dsptask *task, Uns cnt)

The task can issue a BKREQ command with this API function. The task is the dsptask structure pointer of this task and the cnt is the word count to be requested.

76 (121)

Void bkreqp(struct dsptask *task, Void *data, Uns data)

The task can issue a BKREQP command with this API function. The task is the dsptask structure pointer of this task, the data is the address of the data buffer prepared for following BKSNDP transaction and the cnt is the word count to be requested.

Void cmderr(struct dsptask *task, Uns eid)

The task can issue a ERR command with this API function. The task is the dsptask structure pointer of this task and the eid is the error ID of the error cause. Note that if any error occurred in the task functions, rcv_snd(), rcv_req() and rcv_tctl(), the application doesn’t need to send ERR command using this API function but just return EID. The tokliBIOS kernel takes care of sending ERR command when those function returns non-zero value. This API is used in the user’s TSK context.

Void dbg(struct dsptask *task, Char *fmt, ...)

The task can issue a DBG command with this API function. The task is the dsptask structure pointer of this task and the fmt is the print format as used in printf-like functions. The maximum length of the message is 256, including the last null character. If the formatted string exceeds 256 words, It will be truncated.

5.6. Global IPBUF Allocation / Freeing Rule

The Global IPBUF owner transition is shown in Figure 5-2. Figure 5-2: Global IPBUF Owner Transition

DSP ARM(Linux)

Owned by task

Free IPBUF Pool

Owned by task

Free IPBUF Pool

BKSND

BKYLD

get_free_ipbuf() unuse_ipbuf()

BKSND

BKYLD

user space

kernel space

user task

tokliBIOS

get_free_ipbuf() unuse_ipbuf()

copied by read() system call

copied by write() system call

As shown above, DSP task application takes part in the IPBUF owner transition. If the DSP application handles it wrong, it will break this ecosystem. So the DSP application programmer should take care of it. When the Linux application calls write() system call, ARM sends BKSND command to DSP, then the rcv_snd() function in the DSP user task is called. From this point, this task owns the IPBUF line sent with BKSND command until it releases the line with unuse_ipbuf() API or sends back it to ARM with bksnd() API.

77 (121)

5.7. Timer Queue

The Timer Queue is link-listed. All registered functions are executed at every 1 second. The function is registered to the Timer Quene with register_tq_1s() API and deleted with unregister_tq_1s() API. 5.8. Endianism

The endianism is little bit tricky issue in the OMAP platform, since ARM and DSP works upon different endianism strategies. The DSP Gateway is designed so that the application programmer can handle word (16-bit) structured data in same manner in both processors. For example:

There is short buf16[4] in Linux, and let’s assume values shown in List 5-3. List 5-3: Value of 16-bit data array from ARM view buf16[0] = 0x0123 buf16[1] = 0x4567 buf16[2] = 0x89ab buf16[3] = 0xcdef

And do write(fd, buf16, 4*sizeof(short))

then it is seen in DSP, ipbuf_d[bid] as a copy of buf16.

List 5-4: Value of 16-bit data array from DSP view ipbuf_d[bid][0] = 0x0123 ipbuf_d[bid][1] = 0x4567 ipbuf_d[bid][2] = 0x89ab ipbuf_d[bid][3] = 0xcdef

This is the principle concept of the data transfer in the DSP Gateway. But 32-bit data cannot handled in this way. The upper 16-bit and the lower 16-bit are swapped between ARM and DSP. For example:

There is long buf32[2] in Linux, and let’s assume values shown in List 5-5. List 5-5: Value of 32-bit data array from ARM view buf32[0] = 0x01234567 buf32[1] = 0x89abcdef

And do write(fd, buf32, 2*sizeof(long))

Then it is seen in DSP word-swapped values, if you just cast the ipbuf_d as 32-bit data like shown in List 5-6.

List 5-6: Value of 32-bit data array from DSP view *(LgUns*)&ipbuf_d[bid][0] = 0x45670123 *(LgUns*)&ipbuf_d[bid][2] = 0xcdef89ab

To fix this situation, the received data need to be performed word-swap operation as shown in List 5-7.

List 5-7: word-swap operation LgUns d32[2];

78 (121)

d32[0] = ((LgUns)ipbuf_d[bid][1] << 16) | ipbuf_d[bid][0]; d32[1] = ((LgUns)ipbuf_d[bid][3] << 16) | ipbuf_d[bid][2];

Then you can see as List 5-8. List 5-8: corrected 32-bit data d32[0] = 0x01234567 d32[1] = 0x89abcdef

Or if the IPBUF is placed at DARAM or SARAM space, it can be accessed in word-swapped style by accessing as long word type at odd address as shown in List 5-9, but this is not recommended since it cannot be applied for external memory, and may spoil the portability of your code.

List 5-9: 32-bit data with odd-address access *(LgUns*)&ipbuf_d[bid][1] = 0x01234567 *(LgUns*)&ipbuf_d[bid][3] = 0x89abcdef

5.9. System Parameters

User should declare following global variables in the application to define system parameters.

Uns _ipbuf_sz Uns _ipbuf_lines

These values define the Global IPBUF configuration. the _ipbuf_sz is the line size, and the _ipbuf_lines is the number of the lines.

Int _ipbuf_body[]

This is the Global IPBUF instance. The size of this buffer should be (IPBUF_HEADER_SZ + _ipbuf_sz) * _ipbuf_lines. (IPBUF_HEADER_SZ is defined in the library header.)

5.10. Example

This section describes an example of the DSP application and how to compile it as a static task. If you are willing to generate a dynamic task, skip this section and refer to [3]. 5.10.1. sysinfo.c

System parameters are defined here.

List 5-10: sysinfo.c example /* * sysinfo.c */ #include <std.h> #include "tokliBIOS.h" /* * ipbuf configuration */

79 (121)

#define IPBUF_SZ 0x80 #define IPBUF_LINES 4 Uns _ipbuf_sz = IPBUF_SZ; Uns _ipbuf_lines = IPBUF_LINES; #pragma DATA_SECTION(_ipbuf_body, "ipbuf") Int _ipbuf_body[(IPBUF_HEADER_SZ + IPBUF_SZ) * IPBUF_LINES];

5.10.2. task_test2.c

A DSP task example. The bkdata[] is set as the udata in the struct dsptask and it is accessed throughout this task.

List 5-11: DSP task example /* * task_test2.c * DSP task example */ #include <std.h> #include "mailbox.h" #include "tokliBIOS.h" static Uns t2_rcv_bksnd(struct dsptask *task, Uns bid, Uns cnt) { memcpy(task->udata, ipbuf_d[bid], cnt); unuse_ipbuf(task, bid); return 0; } static Uns t2_rcv_bkreq(struct dsptask *task, Uns cnt) { Uns bid; bid = get_free_ipbuf(task); if (bid == MBCMD_BID_NULL) return MBCMD_EID_STVBUF; memcpy(ipbuf_d[bid], task->udata, cnt); bksnd(task, bid, cnt); return 0; } static Uns bkdata[128]; #pragma DATA_SECTION(task_test2, “dspgw_task”) struct dsptask task_test2 = { TID_MAGIC, /* tid */ "test2", /* name */ MBCMD_TTYP_GBDM | MBCMD_TTYP_GBMD | MBCMD_TTYP_BKDM | MBCMD_TTYP_BKMD | MBCMD_TTYP_PSND | MBCMD_TTYP_PRCV, /* ttyp: passive block snd, passive block rcv */ t2_rcv_bksnd, /* rcv_snd */ t2_rcv_bkreq, /* rcv_req */ NULL, /* rcv_tctl */ NULL, /* tsk_attrs */ NULL, /* mmap_info */

80 (121)

bkdata /* udata */ };

5.10.3. Command File for CCS, ‘ex_task.cmd’

The ‘ipbuf’ section is kept in DARAM. All other sections are placed according to the tokliBIOScfg.cmd and tokliBIOS.cmd. Note: IPBUF should not cross the 64k-word boundary.

List 5-12: linker command file example -l ..¥tokliBIOS¥tokliBIOScfg.cmd -l ..¥tokliBIOS¥tokliBIOS.cmd SECTIONS { ipbuf: {} > DARAM }

5.10.4. Compilation using CCS (Code Composer Studio)

The compilation procedure is as followings. ♦ Create a new project (ex_task.pjt).

81 (121)

♦ Select large memory model for this project in order for IPBUF to be accessed from anywhere in the memory space. (Dialog below is shown by selecting “Project” -> “Build Options...”)

Figure 5-3: Build Options – Compiler / Advanced options

82 (121)

♦ Specify include directory where the ‘tokliBIOS.h’ and ‘mailbox.h’ are located.

Figure 5-4: Build Options – Compiler / Preprocessor options

83 (121)

♦ Select ‘Load-time Initialization’ for Autoinit model option. (This is not a requirement, but recommended for the size reduction of output binary)

Figure 5-5: Build Options – Linker / Basic options

85 (121)

6. DSP GATEWAY SYSTEM KERNEL OVERVIEW

6.1. Overview

Figure 6-1: DSP Gateway system kernel Block Chart

DSP “task1”

“task2” “task3”

Mailbox interrupt handler

DSP system kernel (tokliBIOS)


task API

MBQ

DSP/BIOS TSK (supertask)

Mailbox

Mailbox

Timer1 QueueMBQ

BKSND BKREQ BKSND

REGRW f1 f2

TIMER1

rcv_snd( ) function

rcv_req( ) function

rcv_tctl( ) function

timer callback function: f1



DSP/BIOS TSK (idle task)

DSP/BIOS PRD (PRD1: 1s timer)

Figure 6-1 shows the block chart of the DSP Gateway system kernel in DSP side. The programmer can build a DSP application by preparing task functions (see 5.4) and linking with the DSP Gateway system kernel library, ‘tokliBIOS.lib’. How to generate it is instructed by [1]. 6.2. DSP/BIOS Entities

The system kernel is developed upon TI’s DSP/BIOS. In this section, HWI, TSK and PRD entities used in the system kernel are summarized.

86 (121)

6.2.1. HWI

Mailbox and Watchdog Timer interrupts are used. 6.2.1.1. Mailbox Interupt

The Mailbox Interrupt is the mechanism for the inter-processor communication between ARM and DSP. The mailbox interrupt handler is invoked when this interrupt occurs. It reads the mailbox registeres, interprets the mailbox command then adds the command to the mailbox queue in appropriate user task or the supertask. 6.2.1.2. Watchdog Timer Interrupt

The fault tolerance function in the tokliBIOS kernel is implemented using the watchdog timer. The watchdog timer can be configured in two ways, the watchdog mode and the timer mode. In this library, the watchdog timer is used in the timer mode. In this mode the interrupt handler is invoked when the watchdog timer expires. The interrupt handler reports this situation to ARM with WDT mailbox command, then it is observed through /dev/dspctl/err device. The expiration of the watchdog timer means that the idle task has not executed at all for about 20 seconds, because of a bug in the user task. 6.2.2. TSK

User tasks are executed in TSK contexts, along with two TSKs for system (supertask and idle task) and two PRD functions. 6.2.2.1. User Tasks

The user task is executed in TSK context. The priority of the TSK can be set in the range of 2 to 14. Each user task has a mailbox queue (MBQ), to which the received mailbox commands are registered. The TSK executes the commands in the queue sequentially, calling corresponding task functions in the dsptask structure of the user task. In this way, order between two mailbox commands directed one task is retained. The latter command never processed before the former command is completed. 6.2.2.2. Supertask

The supertask is the TSK for system. The priority of the supertask is 15, higher than any user tasks. The spuertask has a mailbox queue (MBQ) as well, to which the received mailbox commands are registered. The supertask executes commands for system (i.e. BKYLD, DSPCFG, REGRW, GETVAR, SETVAR, TADD and TDEL). 6.2.2.3. Sleep Task

The Sleep task is the TSK which is executed when all other TSKs have nothing to do. The priority of the idle task is 1, lower than any user tasks. The idle task issues IDLE instruction to reduce power consumption, after setting the ICR register. The loading value for ICR register can be controlled from Linux through /dev/dspctl device or /proc/dsp/icrmask proc file.

87 (121)

6.2.3. PRD

Following two PRD entities are used. 6.2.3.1. PRD0

PRD0 is invoked at every 10ms. This calls TSK_yield() to initiate task switch between TSKs. 6.2.3.2. PRD1

PRD1 is invoked at every 1s. In this context, all functions registered in the 1-sec Timer Queue are executed.

88 (121)

7. DSP PROGRAM EXECUTION ON THE TARGET MACHINE

An example execution of a DSP-enabled program and utility are shown in this chapter. 7.1. Files to be prepared on ARM(Linux) side

Following files should be prepared on ARM(Linux) side for this example.

Table 7-1: Files to be prepared on the target machine

File Description /sbin/dspctl DSP control utility / program loader (See Appendix A) /root/ex_task.out DSP program binary /root/initial1.txt Initialization text for demo (256 bytes)

7.2. DSP-enabled program execution

7.2.1. DSP program loading and starting

List 7-1: DSP program loading and starting /root # dspctl start ex_task.out setting DSP idle loading ex_task.out... .vers : adr = 0x000000, size= 112 ... ignored. .sysstack : adr = 0x000200, size= 512 ... initialized. .clk : adr = 0x000400, size= 8 .prd : adr = 0x000408, size= 48 .swi : adr = 0x000438, size= 80 : .gblinit : adr = 0x015aea, size= 74 ... initialized. .sysinit : adr = 0x015b34, size= 204 ... initialized. .hwi_vec : adr = 0x000100, size= 256 ... initialized. ipbuf : adr = 0x015c54, size= 1072 dbgbuf : adr = 0x016084, size= 512 setting DSP reset vector to 0x001fc0 releasing DSP reset DSP configuration ... succeeded.

7.2.2. Test Run

List 7-2: DSP program test running

(See the contents of initial1.txt) /root # cat initial1.txt This is initial text for test2! This is initial text for test2! This is initial text for test2! This is initial text for test2! This is initial text for test2!

89 (121)

This is initial text for test2! This is initial text for test2! This is initial text for test2! (Send data to DSP task2) /root # cp initial1.txt /dev/dsptask/test2 (Receive data from DSP task2) /root # dd if=/dev/dsptask/test2 bz=256 count=1 This is initial text for test2! This is initial text for test2! This is initial text for test2! This is initial text for test2! This is initial text for test2! This is initial text for test2! This is initial text for test2! This is initial text for test2!

90 (121)

REFERENCES • [1] Generating tokliBIOS.lib for DSP Gateway 3.1

• [2] Updating Application for DSP Gateway 3.1, Nokia

• [3] DSP Gateway Dynamic Loader Daemon (dsp_dld) Specification rev 1.3, Nokia

91 (121)

APPENDIX A: dspctl UTILITY dspctl is the DSP control utility program for the DSP Gateway. The user can load DSP program, control DSP reset, perform DSP configuration and map external memory for DSP with this utility. In addition, it is possible to send mailbox commands to DSP for the debug purpose. Usage:

dspctl <command> [options...] commands are:

start <cofffile> stop load <cofffile> run (= unreset) reset setrstvect <addr> idle suspend resume dspcfg dspuncfg exmap <dspadr> <request size> exunmap <dspadr> mapflush fbexport <dspadr> mmuinit mmuitack mkdev <devname> rmdev <devname> tadd <minor> <addr> tdel <minor> getvar <varid> setvar <varid> <data> regread [-io] <adr> regwrite [-io] <adr> <val> runlevel <user|super> mbsend <cmd> <data>

1) start

Before using DSP task applications, the user needs to load the DSP application program to the DSP memory, release the DSP reset, and configure the DSP system by obtaining information from DSP application. These steps are done by ‘load’, ‘unreset’ and ‘dspcfg’ commands of dspctl respectively, and the ‘start’ command performs all of them. In the dspcfg phase, DSP task devices are created and after that the DSP tasks are ready to use from Linux processes. <Note about DSP idling>: In loading step, the driver brings the DSP into idle mode, by issueing IDLE instruction in DSP. Before that, the ICR register (Idle Control Register) in DSP is set according to the ICRMASK system variable. It affects DSP peripherals, such as McBSPs, MCSIs. If you are using these

92 (121)

peripherals (ex. audio through McBSP), set the ICRMASK variable to proper value before issueing ‘start’ command. This note is applied for ‘load’ and ‘idle’ command as well.

List A-1: dspctl start /root # dspctl start test2.out setting DSP idle loading test2.out... .vers : adr = 0x000000, size= 120 ... ignored. .sysstack : adr = 0x000100, size= 512 ... initialized. .clk : adr = 0x000300, size= 8 ... initialized. .prd : adr = 0x000308, size= 48 ... initialized. .swi : adr = 0x000338, size= 80 ... initialized. : .trcdata : adr = 0x015836, size= 6 ... initialized. .hwi_vec : adr = 0xffff00, size= 256 ... initialized. ipbuf : adr = 0x01583c, size= 1072 ... initialized. dbgbuf : adr = 0x015c6c, size= 512 ... initialized. .cinit : adr = 0x010000, size= 3118 ... .bss variables are ¥ initialized. setting DSP reset vector to 0x015765 releasing DSP reset DSP configuration ... succeeded. (kernel message) omapdsp: found 1 task(s) omapdsp: task 0 was attached to /dev/dsptask/test2. omapdsp: IPBUF configuration 128 words * 4 lines at 0xe001583c (See dsp devices) # ls -l /dev/dsptask dr-xr-xr-x 2 root root 97 Jan 0 01:07 test2

2) stop

After using DSP tasks, the user needs to clear the allocated resources and remove the created device files for the DSP system, then stop (reset) the DSP. These steps are done by ‘dspuncfg’ and ‘reset’ commands of dspctl respectively, and the ‘stop’ command performs all of them.

List A-2: dspctl stop /root # dspctl stop releasing resources for DSP DSP reset (kernel message) omapdsp: /dev/dsptask/test2 was deleted.

93 (121)

3) load

This command loads the DSP application binary (*.out file) to the DSP memory. This step is included in ‘start’ command, and usually the user doesn’t need to use this command, except in case that user want to do ‘load’, ‘unreset’ and ‘dspcfg’ step-by-step. In this command, the driver brings the DSP into idle mode. See also <Note about DSP idling> in 1) start, in this appendix. 4) run (= unreset) / reset

The run command releases the reset of DSP. The reset command resets DSP. These procedures are included in ‘start’ and ‘stop’ command respectively, and in normal case the user doesn’t need to use these commands. 5) setrstvect (for debug use)

This command sets the reset vector to jump to specified address at releasing the reset. Usually this step is automatically done in ‘load’ command. When the user wants to do it manually, use this command. 6) idle

This command brings DSP into idle mode. See also <Note about DSP idling> in 1) start, in this appendix. 7) suspend, resume

The suspend command brings DSP to reset, after DSP runs suspend code. The resume command resumes DSP to the previous state, as before suspending. 8) dspcfg, dspuncfg

These commands configure / unconfigure the DSP system. These steps are included in ‘start’ or ‘stop’ command, and usually the user doesn’t need to use these commands. 9) exmap, exunmap

‘exmap’ allocates a buffer and maps it to DSP memory space. The user can extend the DSP memory with this command. ‘exunmap’ releases the buffer which has been allocated with ‘exmap’ command.

List A-3: dspctl exmap / exunmap

(See default status of TLB) /root # cat /proc/dsp/mmu p: preserved, v: valid ety cam_va ram_pa sz ap 00: p v 0xfff000 0x10d73000 4KB FA lock base = 1 victim = 1 01: 0x100000 0x10c00000 1MB FA 02: 0x000000 0x36069400 1MB NA

94 (121)

03: 0xd00000 0xa8506400 1MB NA

:

29: 0x400000 0xf71d1400 1MB NA 30: 0xa00000 0x32794c00 1MB NA 31: 0x500000 0x44c76800 1MB NA (Map 64kB at 0x03_0000 in DSP memory space) /root # dspctl exmap 30000 10000 mapping external memory for DSP: dspadr = 0x030000, size = 0x10000 65536 bytes mapped. (See status of TLB) /root # cat /proc/dsp/mmu p: preserved, v: valid ety cam_va ram_pa sz ap 00: p v 0xfff000 0x10d73000 4KB FA 01: v 0x030000 0x10f60000 64KB FA lock base = 2 victim = 2 02: 0x000000 0x36069400 1MB NA 03: 0xd00000 0xa8506400 1MB NA

:

29: 0x400000 0xf71d1400 1MB NA 30: 0xa00000 0x32794c00 1MB NA 31: 0x500000 0x44c76800 1MB NA (Unmap the memory mapped above) /root # dspctl exunmap 30000 releasing external memory map for DSP: dspadr = 0x030000 65536 bytes unmapped. (See status of TLB) /root # cat /proc/dsp/mmu p: preserved, v: valid ety cam_va ram_pa sz ap 00: p v 0xfff000 0x10d73000 4KB FA lock base = 1 victim = 1 01: 0x000000 0x10f60000 1MB FA 02: 0x000000 0x36069400 1MB NA 03: 0xd00000 0xa8506400 1MB NA

:

29: 0x400000 0xf71d1400 1MB NA 30: 0xa00000 0x32794c00 1MB NA 31: 0x500000 0x44c76800 1MB NA

95 (121)

10) mapflush

This command releases all buffers which has been allocated with ‘exmap’ command or mapped to the DSP space with ‘fbexport’ command.

List A-4: dspctl mapflush

(See status of TLB) /root # cat /proc/dsp/mmu p: preserved, v: valid ety cam_va ram_pa sz ap 00: p v 0xfff000 0x10d73000 4KB FA 01: v 0x030000 0x10f60000 64KB FA 02: v 0x040000 0x10d60000 64KB FA 03: v 0x050000 0x10bd0000 64KB FA lock base = 4 victim = 4 04: 0x000000 0x9e1f9800 1MB NA 05: 0x000000 0x1c7da800 1MB FA

:

29: 0x400000 0xf71d1400 1MB NA 30: 0xa00000 0x32794c00 1MB NA 31: 0x500000 0x44c76800 1MB NA (Flush the DSP TLB) /root # dspctl mapflush DSP TLB has been flushed. (See status of TLB) /root # dspctl mapflush flush DSP TLB. # cat /proc/dsp/mmu p: preserved, v: valid ety cam_va ram_pa sz ap 00: p v 0xfff000 0x10d73000 4KB FA lock base = 1 victim = 1 01: 0x000000 0x10f60000 1MB FA 02: 0x000000 0x10d60000 1MB FA 03: 0x000000 0x10bd0000 1MB FA 04: 0x000000 0x9e1f9800 1MB NA 05: 0x000000 0x1c7da800 1MB FA

:

29: 0x400000 0xf71d1400 1MB NA 30: 0xa00000 0x32794c00 1MB NA 31: 0x500000 0x44c76800 1MB NA

96 (121)

11) fbexport

This command exports the frame buffer used in ARM side to the DSP memory space. After exported, DSP can write raw image data to the frame buffer directly. Note that you can specify the dspadr option for this command but it is a ‘hint’ address for mapping. The actual address can be different from the hint, because the driver tries to align the offset between the physical address and the dsp address as far as possible.

List A-5: dspctl fbexport

(See default status of TLB) /root # cat /proc/dsp/mmu p: preserved, v: valid ety cam_va ram_pa sz ap 00: p v 0xfff000 0x10d73000 4KB FA lock base = 1 victim = 1 01: 0x100000 0x10c00000 1MB FA 02: 0x000000 0x36069400 1MB NA 03: 0xd00000 0xa8506400 1MB NA

:

29: 0x400000 0xf71d1400 1MB NA 30: 0xa00000 0x32794c00 1MB NA 31: 0x500000 0x44c76800 1MB NA (Export framebuffer to DSP space) /root # dspctl fbexport 100000 mapping frame buffer to DSP space: dspadr hint = 0x100000 dspadr actual = 0x101000 258048(0x3f000)bytes mapped. (See status of TLB) /root # cat /proc/dsp/mmu p: preserved, v: valid ety cam_va ram_pa sz ap 00: p v 0xfff000 0x10d73000 4KB FA 01: v 0x100000 0x11300000 1MB FA lock base = 2 victim = 2 02: 0x000000 0x10d60000 1MB FA 03: 0x000000 0x10bd0000 1MB FA

:

29: 0xc00000 0xd505ec00 1MB FA 30: 0xf00000 0x1649f000 1MB NA 31: 0x400000 0x045aac00 1MB NA

97 (121)

12) mmuinit

This command initializes the DSP MMU. 13) mmuitack (for debug use)

This command sends the acknowledge toward the DSP MMU interupt after setting the DSP runlevel to RECOVERY. By doing this, you might get some info from DSP who caused the MMU fault, where, etc... but plase note that they are not guaranteed to be correct. 14) mkdev, rmdev (for debug use)

These commands creates / removes a device file for DSP on-demand task. These are usually done by the dynamic loader daemon and the user doesn’t need to do them manually. 15) tadd, tdel (for debug use)

These commands adds / deletes the DSP on-demand task to the device file. These are usually done by the dynamic loader daemon and the user doesn’t need to do them manually. 16) getvar, setvar

The user can read / write the system variables in DSP. See 2.3.3.20 for the variable definitions. 17) regread, regwrite (for debug use)

The user can read / write the data in DSP memory / IO space with these commands. It can cause fatal error for the system. Use with care.

List A-6: dspctl regread / regwrite

(Read TIMER1 LOAD VALUE) /root # dspctl regread -io 2803 DSP register read: adr=IO:0x2803, val=0xea5f (Test the timer: See the interval is 1 second) /root # ./hellotimer 5 ht_callback(): task_ht->cnt = 5 time: 4800.04 Hello from DSP! ht_callback(): task_ht->cnt = 4 time: 4801.04 Hello from DSP! ht_callback(): task_ht->cnt = 3 time: 4802.04 Hello from DSP! ht_callback(): task_ht->cnt = 2 time: 4803.04 Hello from DSP! ht_callback(): task_ht->cnt = 1 time: 4804.04 Hello from DSP! (Change TIMER1 LOAD VALUE)

98 (121)

/root # dspctl regwrite -io 2803 752f DSP register write: adr=IO:0x2803, val=0x752f /root # dspctl regread -io 2803 DSP register read: adr=IO:0x2803, val=0x752f (Test the timer again: See the interval became 0.5 second) /root # ./hellotimer 5 ht_callback(): task_ht->cnt = 5 time: 4838.27 Hello from DSP! ht_callback(): task_ht->cnt = 4 time: 4838.77 Hello from DSP! ht_callback(): task_ht->cnt = 3 time: 4839.27 Hello from DSP! ht_callback(): task_ht->cnt = 2 time: 4839.77 Hello from DSP! ht_callback(): task_ht->cnt = 1 time: 4840.27 Hello from DSP!

18) runlevel

The user can set the DSP runlevel with this command. 19) mbsend (for debug use)

The user can send mailbox command manually with this command.

99 (121)

APPENDIX B: DSP TASK EXAMPLES AND MAILBOX COMMAND EXCHANGE COMMENTARY 1) DSP configuration

List B-1: Mailbox command exchange in DSP configuration phase /root # dspctl start test2.out setting DSP idle loading test2.out... .vers : adr = 0x000000, size= 120 ... ignored. .sysstack : adr = 0x000100, size= 512 ... initialized. .clk : adr = 0x000300, size= 8 ... initialized. .prd : adr = 0x000308, size= 48 ... initialized. .swi : adr = 0x000338, size= 80 ... initialized. : .trcdata : adr = 0x015836, size= 6 ... initialized. .hwi_vec : adr = 0xffff00, size= 256 ... initialized. ipbuf : adr = 0x01583c, size= 1072 ... initialized. dbgbuf : adr = 0x015c6c, size= 512 ... initialized. .cinit : adr = 0x010000, size= 3118 ... .bss variables ¥ are initialized. setting DSP reset vector to 0x015765

releasing DSP reset DSP configuration ... succeeded.

(mailbox commands) M->D, DSPCFG:CFG_REQ

(kernel message) omapdsp: found 1 task(s)

D->M, DSPCFG:CFG_PROTREV D->M, DSPCFG:CFG_SYSADRH D->M, DSPCFG:CFG_SYSADRL D->M, BKYLD D->M, BKYLD

omapdsp: task 0 was attached to /dev/dsptask/test2.

M->D, TCFG(TID=0) D->M, TCFG(TID=0)

omapdsp: IPBUF configuration 128 words * 4 lines at 0xe001583c

/root #

100 (121)

2) test1

Task Name: “test1” Task Type: passive word sending / passive word receiving This task remembers sent data from ARM up to 64 words and returns it when requested.

DSP Source Code List B-2: DSP task example: test1

/* * task_test1.c */ #include <std.h> #include "mailbox.h" #include "tokliBIOS.h" struct t1_udata { Int wdwptr, wdrptr; Uns wddata[64]; }; static Uns t1_rcv_wdsnd(struct dsptask *task, Uns data) { struct t1_udata *udata = task->udata; udata->wddata[udata->wdwptr] = data; if (udata->wdwptr < 64) udata->wdwptr++; return 0; } static Uns t1_rcv_wdreq(struct dsptask *task) { struct t1_udata *udata = task->udata; if (udata->wdwptr == 0) return 0; wdsnd(task, udata->wddata[udata->wdrptr++]); if (udata->wdrptr == udata->wdwptr) udata->wdrptr = 0; return 0; } static Uns t1_rcv_tctl(struct dsptask *task, Uns ctlcmd, Uns *ret, Uns arg) { struct t1_udata *udata = task->udata; switch (ctlcmd) { case MBCMD_TCTL_TINIT: udata->wdwptr = 0; udata->wdrptr = 0; return 0; default: return MBCMD_EID_BADTCTL; } } static struct t1_udata udata;

101 (121)

#pragma DATA_SECTION(task_test1, “dspgw_task”) struct dsptask task_test1 = { TID_MAGIC, /* tid */ "test1", /* name */ MBCMD_TTYP_WDDM | MBCMD_TTYP_WDMD | MBCMD_TTYP_PSND | MBCMD_TTYP_PRCV, /* ttyp: passive word snd, passive word rcv */ t1_rcv_wdsnd, /* rcv_snd */ t1_rcv_wdreq, /* rcv_req */ t1_rcv_tctl, /* rcv_tctl */ NULL, /* tsk_attrs */ NULL, /* mmap_info */ &udata /* udata */ };

Task Execution List B-3: Mailbox command exchange in task1

(mailbox commands) /root # echo acyo1 > /dev/dsptask/test1 /root #

M->D, WDSND M->D, WDSND M->D, WDSND

/root # cat /dev/dsptask/test1 acyo1 acyo1 acyo1 acyo1 acyo1 : (^C) (We get the written data continuously because cat continues to read)

M->D, WDREQ D->M, WDSND M->D, WDREQ D->M, WDSND M->D, WDREQ D->M, WDSND M->D, WDREQ D->M, WDSND :

/root #

102 (121)

3) test2

Task Name: “test2” Task Type: passive block sending / passive block receiving This task remembers one sent block data from ARM and returns it when requested

DSP Source Code See 5.10.2.


(mailbox commands) /root # cat initial1.txt This is initial text for test2!

/root # cp initial1.txt /dev/dsptask/test2 /root #

M->D, BKSND(BID=2) D->M, BKYLD(BID=0)

/root # # dd if=/dev/dsptask/test2 bs=32 count=1 This is initial text for test2!

M->D, BKREQ(CNT=16) D->M, BKSND(BID=1) M->D, BKYLD(BID=3)

/root #

103 (121)

4) test3

Task Name: “test3” Task Type: active word sending passive word receiving This task receives 1-word data, which is the iteration count and sends word data readable for ARM, for iteration count times actively.


/* * task_test3.c */ #include <std.h> #include "mailbox.h" #include "tokliBIOS.h" static Uns t3_rcv_wdsnd(struct dsptask *task, Uns data) { Int i; Uns wd; for (i = 0, wd = 0x0a40; i < data; i++, wd++) { wdsnd(task, wd); } return 0; } #pragma DATA_SECTION(task_test3, “dspgw_task”) struct dsptask task_test3 = { TID_MAGIC, /* tid */ "test3", /* name */ MBCMD_TTYP_WDDM | MBCMD_TTYP_WDMD | MBCMD_TTYP_ASND | MBCMD_TTYP_PRCV, /* ttyp: active word snd, passive word rcv */ t3_rcv_wdsnd, /* rcv_snd */ NULL, /* rcv_req */ NULL, /* rcv_tctl */ NULL, /* tsk_attrs */ NULL, /* mmap_info */ NULL /* udata */ };

Linux Frontent Program List B-6: Frontend program for test3

/* * test3.c */ #include <stdio.h> #include <stdlib.h> #include <unistd.h> #include <fcntl.h> #define BUFSZ 256 void usage(char *cmd) {

104 (121)

fprintf(stderr, "%s <repeat_count>¥n", cmd); } int main(int argc, char **argv) { int fd; unsigned short repeat; char buf[BUFSZ]; char *devfn = "/dev/dsptask/test3"; if (argc != 2) { usage(argv[0]); return 1; } repeat = atoi(argv[1]); fd = open(devfn, O_RDWR); if (fd < 0) { fprintf(stderr, "cannot open %s¥n", devfn); return 1; } write(fd, &repeat, 2); for (;;) { int cnt; cnt = read(fd, buf, BUFSZ); if (cnt < 0) { perror("read failed"); break; } write(1, buf, cnt); } close(fd); return 0; }


(mailbox commands) /root # ./test3 5 @ A B C D (^c)

M->D, WDSND D->M, WDSND D->M, WDSND D->M, WDSND D->M, WDSND D->M, WDSND

/root # ./test3 20 D E F G : P Q R S (^c)

M->D, WDSND D->M, WDSND : (20 times) D->M, WDSND

105 (121)

(We have got 20 words from DSP but we have only 32 bytes (16 words) buffer in the driver, and first 4 words have been lost) /root #

106 (121)

5) test4

Task Name: “test4” Task Type: active block sending / passive word receiving This task receives 1-word data, which is the iteration count and sends block data readable for ARM, for iteration count times actively.


/* * task_test4.c */ #include <std.h> #include "mailbox.h" #include "tokliBIOS.h" static Void busywait(Uns cnt) { Uns i; for (i = 0; i < cnt; i++) {} } static Uns t4_rcv_wdsnd(struct dsptask *task, Uns data) { Uns bid; Int ipbuf_trycnt = 0; Int i, j, k; Uns *p; for (i = 0; i < data; i++) { ipbuf_trycnt = 0; for (;;) { bid = get_free_ipbuf(task); if (bid != MBCMD_BID_NULL) break; if (++ipbuf_trycnt >= 100) return MBCMD_EID_STVBUF; busywait(100); } p = ipbuf_d[bid]; for(j = 0; j < 4; j++) { for(k = 0; k < 30; k++) { *(p++) = 0x4141 + 0x0101 * j; } *(p++) = 0x0a00 | (0x30 + (i&0x07)); } bksnd(task, bid, 124); } return 0; } #pragma DATA_SECTION(task_test4, “dspgw_task”) struct dsptask task_test4 = { TID_MAGIC, /* tid */ "test4", /* name */ MBCMD_TTYP_GBDM | MBCMD_TTYP_BKDM | MBCMD_TTYP_WDMD | MBCMD_TTYP_ASND | MBCMD_TTYP_PRCV, /* ttyp: active block snd, passive word rcv */

107 (121)

t4_rcv_wdsnd, /* rcv_snd */ NULL, /* rcv_req */ NULL, /* rcv_tctl */ NULL, /* tsk_attrs */ NULL, /* mmap_info */ NULL /* udata */ };

Linux Frontent Program List B-9: Frontent program for test4

/* * test4.c */ #include <stdio.h> #include <stdlib.h> #include <unistd.h> #include <fcntl.h> #define DEFAULT_BUFSZ 1024 void usage(char *cmd) { fprintf(stderr, "%s <repeat_count> [buffer size]¥n", cmd); } int main(int argc, char **argv) { int fd; unsigned short repeat; size_t bufsz = DEFAULT_BUFSZ; char *buf; char *devfn = "/dev/dsptask/test4"; if ((argc != 2) && (argc != 3)) { usage(argv[0]); return 1; } repeat = atoi(argv[1]); if (argc == 3) { bufsz = atoi(argv[2]); if (bufsz == 0) { fprintf(stderr, "invalid buffer size (%d)¥n", bufsz); } } buf = malloc(bufsz); fd = open(devfn, O_RDWR); if (fd < 0) { fprintf(stderr, "cannot open %s¥n", devfn); return 1; } printf("reading with %d bytes buffer...¥n", bufsz); write(fd, &repeat, 2); for (;;) { int cnt; cnt = read(fd, buf, bufsz); if(cnt < 0) { perror("read failed"); break; }

108 (121)

write(1, buf, cnt); } close(fd); free(buf); return 0; }


(mailbox commands) /root # ./test4 2 AAAAAAAAAAAAAAAAAAAAAAA...AAAAAAAAAAAAAAA0 BBBBBBBBBBBBBBBBBBBBBBB...BBBBBBBBBBBBBBB0 CCCCCCCCCCCCCCCCCCCCCCC...CCCCCCCCCCCCCCC0 DDDDDDDDDDDDDDDDDDDDDDD...DDDDDDDDDDDDDDD0 AAAAAAAAAAAAAAAAAAAAAAA...AAAAAAAAAAAAAAA1 BBBBBBBBBBBBBBBBBBBBBBB...BBBBBBBBBBBBBBB1 CCCCCCCCCCCCCCCCCCCCCCC...CCCCCCCCCCCCCCC1 DDDDDDDDDDDDDDDDDDDDDDD...DDDDDDDDDDDDDDD1 (^c)

M->D, WDSND D->M, BKSND(BID=0) M->D, BKYLD(BID=2) D->M, BKSND(BID=1) M->D, BKYLD(BID=3)

/root #

109 (121)

6) test7

Task Name: “test7” Task Type: active private block sending / active private block receiving An example of Private IPBUF. This task requests 16-word data using private IPBUF. The received data is sent back to ARM also using private IPBUF with no modification.


/* * task_test7.c */ #include <std.h> #include "mailbox.h" #include "tokliBIOS.h" #define T7_BUF_SZ 0x10 struct t7_udata { Int *rbuf; Int *wbuf; }; static Uns t7_rcv_bksnd(struct dsptask *task, Uns cnt) { struct t7_udata *udata = task->udata; if (cnt > T7_BUF_SZ) return MBCMD_EID_BADCNT; memcpy(udata->wbuf, udata->rbuf, cnt); bksndp(task, udata->wbuf, cnt); /* echo back */ bkreqp(task, udata->rbuf, T7_BUF_SZ); return 0; } static Uns t7_rcv_tctl(struct dsptask *task, Uns ctlcmd, Uns *ret, Uns arg) { struct t7_udata *udata = task->udata; switch (ctlcmd) { case MBCMD_TCTL_TINIT: memset(udata->rbuf, 0xbeef, T7_BUF_SZ); memset(udata->wbuf, 0xdead, T7_BUF_SZ); bkreqp(task, udata->rbuf, T7_BUF_SZ); return 0; default: return MBCMD_EID_BADTCTL; } } #pragma DATA_SECTION(t7_rbuf_data, "ipbuf"); #pragma DATA_SECTION(t7_wbuf_data, "ipbuf"); static Int t7_rbuf_data[T7_BUF_SZ]; static Int t7_wbuf_data[T7_BUF_SZ]; static struct t7_udata udata = { t7_rbuf_data, t7_wbuf_data }; #pragma DATA_SECTION(task_test7, “dspgw_task”)

110 (121)

struct dsptask task_test7 = { TID_MAGIC, /* tid */ "test7", /* name */ MBCMD_TTYP_PVDM | MBCMD_TTYP_PVMD | MBCMD_TTYP_BKDM | MBCMD_TTYP_BKMD | MBCMD_TTYP_ASND | MBCMD_TTYP_ARCV, /* ttyp: active block snd, active block rcv */ t7_rcv_bksnd, /* rcv_snd */ NULL, /* rcv_req */ t7_rcv_tctl, /* rcv_tctl */ NULL, /* tsk_attrs */ NULL, /* mmap_info */ &udata /* udata */ };


/* * test7.c */ #include <stdio.h> #include <stdlib.h> #include <unistd.h> #include <fcntl.h> #include <asm/arch/omapdsp.h> #define BUFSZ 50 void usage(char *cmd) { fprintf(stderr, "%s <repeat_count>¥n", cmd); } int main(int argc, char **argv) { int fd; char buf[BUFSZ]; int cnt1, cnt2; char *wdata = "aaaaabbbbbcccccdddddeeeeefffffggggghhhhhiiiiijjjjj"; char *devfn = "/dev/dsptask/test7"; fd = open(devfn, O_RDWR); if (fd < 0) { fprintf(stderr, "cannot open %s¥n", devfn); return 1; } cnt1 = write(fd, wdata, BUFSZ); if (cnt1 < 0) { perror("write failed"); return 1; } fprintf(stderr, "%d bytes written¥n", cnt1); cnt2 = read(fd, buf, BUFSZ); if (cnt2 < 0) { perror("read failed"); return 1; } fprintf(stderr, "%d bytes read¥n", cnt2); write(1, buf, cnt2); putchar('¥n'); close(fd);

111 (121)

return 0; }

List B-13: Mailbox command exchange in task7 (mailbox commands) D->M, BKREQP /root # ./test7 32 bytes written 32 bytes read aaaaabbbbbcccccdddddeeeeefffffgg

M->D, BKSNDP D->M, BKSNDP D->M, BKREQP

/root #

112 (121)

7) task8

Task Name: “test8a”, “test8b”, “task8c” Task Type: active block sending / passive word receiving DSP/BIOS switching TSK example. These tasks receive 1-word data, which is the iteration count and go into busy loop in which these task sends the greeting string for iteration count times. We can observe the TSK switching by DSP/BIOS. The task8c has higher priority than other two tasks, and it occupies the DSP without yielding to other tasks until it exits from the busy loop.


/* * task_test8.c */ #include <std.h> #include <sem.h> #include <tsk.h> #include "mailbox.h" #include "tokliBIOS.h" #define T8A_STR "Hello from task8a! * ¥n" #define T8B_STR "Hello from task8b! * ¥n" #define T8C_STR "Hello from task8c! * ¥n" #define T8A_INT 520000L #define T8B_INT 200000L #define T8C_INT 200000L struct t8_udata { char *s; LgUns interval; }; static Void busywait(LgUns cnt) { LgUns i; for (i = 0; i < cnt; i++) {} } static Int strcpy16to8(Char *d, Char *s) { Int cnt = 0; for (; *s; s++, d++) { *d = *s; *d |= *++s << 8; cnt++; if (!*s) return cnt; } *d = '¥0'; return cnt; } static Uns t8_rcv_wdsnd(struct dsptask *task, Uns data) { struct t8_udata *udata = task->udata; LgUns interval = udata->interval; Uns bid; Int cnt, i;

113 (121)

for (i = 0; i < data; i++) { busywait(interval); bid = get_free_ipbuf(task); if (bid == MBCMD_BID_NULL) return MBCMD_EID_STVBUF; cnt = strcpy16to8((Char *)ipbuf_d[bid], udata->s); bksnd(task, bid, cnt); } return 0; } /* * task 8a: normal priority */ static struct t8_udata udata_a = { T8A_STR, T8A_INT }; #pragma DATA_SECTION(task_test8a, “dspgw_task”) struct dsptask task_test8a = { TID_MAGIC, /* tid */ "test8a", /* name */ MBCMD_TTYP_GBDM | MBCMD_TTYP_BKDM | MBCMD_TTYP_WDMD | MBCMD_TTYP_ASND | MBCMD_TTYP_PRCV, /* ttyp: active block snd, passive word rcv */ t8_rcv_wdsnd, /* rcv_snd */ NULL, /* rcv_req */ NULL, /* rcv_tctl */ NULL, /* tsk_attrs */ NULL, /* mmap_info */ &udata_a /* udata */ }; /* * task 8b: normal priority */ static struct t8_udata udata_b = { T8B_STR, T8B_INT }; #pragma DATA_SECTION(task_test8b, “dspgw_task”) struct dsptask task_test8b = { TID_MAGIC, /* tid */ "test8b", /* name */ MBCMD_TTYP_GBDM | MBCMD_TTYP_BKDM | MBCMD_TTYP_WDMD | MBCMD_TTYP_ASND | MBCMD_TTYP_PRCV, /* ttyp: active block snd, passive word rcv */ t8_rcv_wdsnd, /* rcv_snd */ NULL, /* rcv_req */ NULL, /* rcv_tctl */ NULL, /* tsk_attrs */ NULL, /* mmap_info */ &udata_b /* udata */ }; /* * task 8c: high priority */ static struct TSK_Attrs attr_c = { DSPTASK_DEFAULT_PRIORITY+1, /* priority */ NULL, /* stack */ DSPTASK_DEFAULT_STACKSIZE, /* stacksize */ DSPTASK_DEFAULT_SYSSTACKSIZE, /* sysstacksize */ 0, /* stackseg: can't be overridden */

114 (121)

NULL, /* environ */ NULL, /* name: can't be overridden */ TRUE /* exitflag */ }; static struct t8_udata udata_c = { T8C_STR, T8C_INT }; #pragma DATA_SECTION(task_test8c, “dspgw_task”) struct dsptask task_test8c = { TID_MAGIC, /* tid */ "test8c", /* name */ MBCMD_TTYP_GBDM | MBCMD_TTYP_BKDM | MBCMD_TTYP_WDMD | MBCMD_TTYP_ASND | MBCMD_TTYP_PRCV, /* ttyp: active block snd, passive word rcv */ t8_rcv_wdsnd, /* rcv_snd */ NULL, /* rcv_req */ NULL, /* rcv_tctl */ &attr_c, /* tsk_attrs */ NULL, /* mmap_info */ &udata_c /* udata */ };


/* * test8.c */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <unistd.h> #include <fcntl.h> #include <sys/time.h> #define BUFSZ 256 void usage(char *cmd) { fprintf(stderr, "%s <repeat_count>¥n", cmd); } int dif_str(char *s, struct timeval *tm1, struct timeval *tm2) { int scnt; int timdiff; if (tm2->tv_sec || tm2->tv_usec) { /* non-zero */ timdiff = (tm1->tv_sec - tm2->tv_sec) * 100 + (tm1->tv_usec - tm2->tv_usec) / 10000; scnt = sprintf(s, "time : %ld.%02ld (+%2d.%02d) ", tm1->tv_sec, tm1->tv_usec / 10000, timdiff / 100, timdiff % 100); } else { scnt = sprintf(s, "time : %ld.%02ld ", tm1->tv_sec, tm1->tv_usec / 10000); } return scnt; } int main(int argc, char **argv) { int fd1, fd2, fd3;

115 (121)

unsigned short repeat; char *devfn1 = "/dev/dsptask/test8a"; char *devfn2 = "/dev/dsptask/test8b"; char *devfn3 = "/dev/dsptask/test8c"; fd_set fdset; struct timeval tm1a, tm2a, tm1b, tm2b, tm1c, tm2c; if (argc != 2) { usage(argv[0]); return 1; } repeat = atoi(argv[1]); fd1 = open(devfn1, O_RDWR); if (fd1 < 0) { fprintf(stderr, "cannot open %s¥n", devfn1); return 1; } fd2 = open(devfn2, O_RDWR); if (fd2 < 0) { fprintf(stderr, "cannot open %s¥n", devfn2); return 1; } fd3 = open(devfn3, O_RDWR); if (fd3 < 0) { fprintf(stderr, "cannot open %s¥n", devfn3); return 1; } memset(&tm2a, 0, sizeof(struct timeval)); memset(&tm2b, 0, sizeof(struct timeval)); memset(&tm2c, 0, sizeof(struct timeval)); FD_ZERO(&fdset); FD_SET(fd1, &fdset); FD_SET(fd2, &fdset); FD_SET(fd3, &fdset); write(fd1, &repeat, 2); write(fd2, &repeat, 2); write(fd3, &repeat, 2); for (;;) { fd_set testfds; int result, cnt; char buf[BUFSZ]; char s[64]; int scnt; testfds = fdset; result = select(fd3+1, &testfds, (fd_set *)0, (fd_set *)0, NULL); if (result < 0) { perror("select failed"); break; } if (FD_ISSET(fd1, &testfds)) { cnt = read(fd1, buf, BUFSZ); if (cnt < 0) { perror("read failed"); break; }

116 (121)

gettimeofday(&tm1a, NULL); scnt = dif_str(s, &tm1a, &tm2a); write(1, s, scnt); write(1, buf, cnt); memcpy(&tm2a, &tm1a, sizeof(struct timeval)); } if (FD_ISSET(fd2, &testfds)) { cnt = read(fd2, buf, BUFSZ); if (cnt < 0) { perror("read failed"); break; } gettimeofday(&tm1b, NULL); scnt = dif_str(s, &tm1b, &tm2b); write(1, s, scnt); write(1, buf, cnt); memcpy(&tm2b, &tm1b, sizeof(struct timeval)); } if (FD_ISSET(fd3, &testfds)) { cnt = read(fd3, buf, BUFSZ); if (cnt < 0) { perror("read failed"); break; } gettimeofday(&tm1c, NULL); scnt = dif_str(s, &tm1c, &tm2c); write(1, s, scnt); write(1, buf, cnt); memcpy(&tm2c, &tm1c, sizeof(struct timeval)); } } close(fd1); close(fd2); close(fd3); return 0; }


(mailbox commands) /root # ./test8 10 M->D, WDSND (task8a)

M->D, WDSND (task8b) M->D, WDSND (task8c)

time : 214.11 Hello from task8c! * D->M, BKSND(BID=0) M->D, BKYLD(BID=2)

time : 214.13 (+ 0.02) Hello from task8c! * D->M, BKSND(BID=1) M->D, BKYLD(BID=3)

time : 214.16 (+ 0.03) Hello from task8c! * D->M, BKSND(BID=2) M->D, BKYLD(BID=0)

time : 214.19 (+ 0.03) Hello from task8c! *

D->M, BKSND(BID=3) M->D, BKYLD(BID=1)





time : 214.27 (+ 0.03) Hello from task8c! * D->M, BKSND(BID=2)

117 (121)

M->D, BKYLD(BID=0) time : 214.29 (+ 0.02) Hello from task8c! *






time : 214.40 Hello from task8b! *


time : 214.45 (+ 0.05) Hello from task8b! *


time : 214.48 Hello from task8a! *








time : 214.62 (+ 0.14) Hello from task8a! *




















time : 215.09 (+ 0.07) Hello from task8a! * D->M, BKSND(BID=2) M->D, BKYLD(BID=0)




(^c) /root #

118 (121)

8) hellotimer

Task Name: “hellotimer” Task Type: active block sending / passive word receiving The Timer1 Queue sample. This task receives 1-word data, which is the iteration count and sends the string “Hello from DSP!¥n” for iteration count times by the timer1 interval (1 second).

DSP Source Code List B-17: DSP task example: hellotimer

/* * hellotimer.c */ #include <std.h> #include <sys.h> #include <mem.h> #include "mailbox.h" #include "tokliBIOS.h" struct ht_udata { Int cnt; Void *t1q_id; }; static Int strcpy16to8(Char *d, Char *s) { Int cnt = 0; for (; *s; s++, d++) { *d = *s; *d |= *++s << 8; cnt++; if (!*s) return cnt; } *d = '¥0'; return cnt; } static Uns ht_callback(struct dsptask *task) { struct ht_udata *udata = task->udata; Uns bid; Int cnt; dbg(task, "ht_callback(): udata->cnt = %d¥n", udata->cnt); bid = get_free_ipbuf(task); if (bid == MBCMD_BID_NULL) return MBCMD_EID_STVBUF; cnt = strcpy16to8((Char *)ipbuf_d[bid], "Hello from DSP!¥n"); bksnd(task, bid, cnt); if (--udata->cnt == 0) unregister_tq_1s(task, udata->t1q_id); return 0; } static Uns ht_rcv_wdsnd(struct dsptask *task, Uns data) { struct ht_udata *udata = task->udata; void *qid;

119 (121)

udata->cnt = data; qid = register_tq_1s(task, ht_callback); if (qid == MEM_ILLEGAL) return MBCMD_EID_NORES; udata->t1q_id = qid; return 0; } static struct ht_udata udata; #pragma DATA_SECTION(task_hellotimer, “dspgw_task”) struct dsptask task_hellotimer = { TID_MAGIC, /* tid */ "hellotimer", /* name */ MBCMD_TTYP_GBDM | MBCMD_TTYP_BKDM | MBCMD_TTYP_WDMD | MBCMD_TTYP_ASND | MBCMD_TTYP_PRCV, /* ttyp: active block snd, passive word rcv */ ht_rcv_wdsnd, /* rcv_snd */ NULL, /* rcv_req */ NULL, /* rcv_tctl */ NULL, /* tsk_attrs */ NULL, /* mmap_info */ &udata /* udata */ }

Linux Frontent Program List B-18: Frontent program for hellotimer

/* * hellotimer.c */ #include <stdio.h> #include <stdlib.h> #include <unistd.h> #include <fcntl.h> #include <sys/time.h> #undef DEBUG_PARTIAL_READ #ifdef DEBUG_PARTIAL_READ #define BUFSZ 6 #else #define BUFSZ 256 #endif void usage(char *cmd) { fprintf(stderr, "%s <repeat_count>¥n", cmd); } int main(int argc, char **argv) { int fd; unsigned short repeat; #ifndef DEBUG_PARTIAL_READ unsigned short i; #endif char *devfn = "/dev/dsptask/hellotimer";

120 (121)

if (argc != 2) { usage(argv[0]); return 1; } repeat = atoi(argv[1]); fd = open(devfn, O_RDWR); if (fd < 0) { fprintf(stderr, "cannot open %s¥n", devfn); return 1; } write(fd, &repeat, 2); #ifdef DEBUG_PARTIAL_READ for (;;) { #else for (i = 0; i < repeat; i++) { #endif int cnt; char buf[BUFSZ]; struct timeval tm; char s[64]; int scnt; char lf = '¥n'; cnt = read(fd, buf, BUFSZ); if (cnt < 0) { perror("read failed"); break; } gettimeofday(&tm, NULL); scnt = sprintf(s, "time: %ld.%02ld ", tm.tv_sec, tm.tv_usec/10000); write(1, s, scnt); write(1, buf, cnt); write(1, &lf, 1); #ifdef DEBUG_PARTIAL_READ { int j; for (j = 0; j < 20; j++) { usleep(1000); } } #endif } close(fd); return 0; }

Task Execution List B-19: Mailbox command exchange in hellotimer

(mailbox commands) /root # ./hellotimer 5 ht_callback(): task_ht->cnt = 5 time: 54.46 Hello from DSP! ht_callback(): task_ht->cnt = 4 time: 55.46 Hello from DSP! ht_callback(): task_ht->cnt = 3 time: 56.46 Hello from DSP!

M->D, WDSND D->M, BKSND(BID=0) M->D, BKYLD(BID=2) D->M, BKSND(BID=1) M->D, BKYLD(BID=3) D->M, BKSND(BID=2) M->D, BKYLD(BID=0)

121 (121)

ht_callback(): task_ht->cnt = 2 time: 57.46 Hello from DSP! ht_callback(): task_ht->cnt = 1 time: 58.46 Hello from DSP!

D->M, BKSND(BID=3) M->D, BKYLD(BID=1) D->M, BKSND(BID=0) M->D, BKYLD(BID=2)

/root #

linux dsp gateway specificationdspgateway.sourceforge.net/pub/3.1/dsp_gateway31_spec.pdf6 (121) 2....

Documents