1 (23)

DSP Gateway Dynamic Loader Daemon (dsp_dld) Specification Revision History

Date Author Revision Description

28.06.2004 Toshihiro Kobayashi 1.0 Document Created

04.10.2004 Toshihiro Kobayashi 1.1 Small Update with DSP Gateway 3.0.1 Release

02.11.2004 Toshihiro Kobayashi 1.2 Small Update

Copyright (c) 2004 Nokia Corporation

2 (23)

1. Introduction ..................................................................................................................... 3

1.1. Scope ...................................................................................................................................... 3 1.2. Requirements .......................................................................................................................... 3

2. Function Definitions................................................................................................... 4 2.1. Mechanism Overview .............................................................................................................. 4 2.2. Boot ......................................................................................................................................... 4 2.3. Task Device Event Detection .................................................................................................. 4 2.4. Dynamic Link ........................................................................................................................... 5 2.5. Dynamic Loading / Unloading.................................................................................................. 5 2.6. Memory Management.............................................................................................................. 5

3. Usage ................................................................................................................................. 6 3.1. Command Line Options........................................................................................................... 6 3.2. Configuration File .................................................................................................................... 6 3.3. Starting the dsp_dld................................................................................................................. 6 3.4. Using a Dynamic Task............................................................................................................. 7 3.5. Terminating the dsp_dld .......................................................................................................... 8

4. Generating The DSP Kernel (TINKERNEL) ............................................. 9 4.1. What is tinkernel? .................................................................................................................... 9 4.2. sysinfo.c................................................................................................................................... 9 4.3. Building the tinkernel Using Code Composer Studio............................................................. 10

4.3.1. Create A New CCS Project ............................................................................................ 10 4.3.2. DSP/BIOS Configuration ................................................................................................ 11 4.3.3. tinkernel-local.cmd ......................................................................................................... 11 4.3.4. Build ............................................................................................................................... 12

5. Generating A DSP Dynamic Task Module .............................................. 16 5.1. DSP Dynamic Module ........................................................................................................... 16 5.2. Task Source .......................................................................................................................... 16 5.3. Task Specific Linker Command............................................................................................. 16 5.4. Helper Object......................................................................................................................... 16 5.5. Building the Module Using Code Composer Studio .............................................................. 17

5.5.1. Create A New CCS Project ............................................................................................ 17 5.5.2. Build ............................................................................................................................... 18

6. Linker Command File............................................................................................. 22 REFERENCES.............................................................................................................................. 23

3 (23)

1. INTRODUCTION

1.1. Scope

This is the specification of DSP Dynamic Loader Daemon (dsp_dld), a core utility program that manages DSP tasks and resources for the DSP Gateway. This describes how to use the dsp_dld, how it works, and how to generate the DSP kernel and the DSP dynamic task modules. 1.2. Requirements

To use the dsp_dld, following system and software are required.

TI OMAP1510/1610/5912/1710 based hardware Linux kernel + omap patch DSP Gateway syslogd (recommended) TI Code Composer Studio

4 (23)

2. FUNCTION DEFINITIONS

2.1. Mechanism Overview

Figure 2-1: DSP Dynamic Loading Mechanism Block Chart

DSP ARM

gateway (tinkernel) gateway pointers to

dsptask structures

task FXN FXN FXN

struct dsptask

task FXN FXN FXN

struct dsptask

API functions

new task FXN FXN FXN

struct dsptask

DSP task module

(*.o)

linker command file (*.cmd)

TASKADD

load

link

register

task add request

application

task I/F

dsp_dld

wake up access

access event

task watch I/F

DSP mem space manager

symbol table

dynamic link

config file

2.2. Boot

When the dsp_dld starts, it performs the following steps. • Boots the DSP up using the DSP Gateway kernel (tinkernel). • Creates DSP task device files in ARM side as the DSP task interfaces to the dynamic tasks. • Initializes the memory space manager according to the base linker command file

(tinkernelcfg.cmd). • Creates the symbol table.

Then, it waits for the DSP task device event. 2.3. Task Device Event Detection

The dsp_dld is watching the task device event through /dev/dsptwch. It can detect open and close event of the DSP task devices. When an open event is detected, the corresponding task module is loaded to the DSP memory and the task is added to the system. When a close event is detected, the corresponding task is removed from the system.

5 (23)

2.4. Dynamic Link

The dsp_dld links the dynamic task module with the tinkernel. Section placement is done according to the task-specific linker command, the base linker command and the memory space manager. 2.5. Dynamic Loading / Unloading

The dsp_dld loads the dynamic task to the DSP memory, and issue the TADD ioctl to the DSP Gateway driver. By this ioctl call, the new dsptask structure is added to the system in the DSP side and TCFG exchange between ARM and DSP is done. 2.6. Memory Management

The memory space is managed by the memory space manager in the dsp_dld. This manages section placement at the dynamic link time. Internal structure of the memory space manager is constructed according to the linker command files. External RAM block is mapped / unmapped dynamically according to the linker command files. External memory sections declared in the base linker command is allocated and mapped at the start time, and lasts to the end. On the other hand, ones declared in the task-specific linker command are allocated and linked on demand and are released when the task is unloaded.

6 (23)

3. USAGE

3.1. Command Line Options

dsp_dld [-c configfile] [-b biosfile] [-m cmdfile] [-p]

-c configfile: read configuration (module database) from configfile. default is /etc/dsp/dsp_dld.conf.

-b kernelfile: load kernelfile as the DSP kernel. default is /etc/dsp/tinkernel.out. -m cmdfile: use cmdfile for linker command file. default is /etc/dsp/tinkernelcfg.cmd. -p: work as a normal process, not a daemon.

3.2. Configuration File

A configuration file example is shown in List 3-1.

List 3-1: Configuration File Example # # dsp_dld.conf # # devname taskname pri module cmdfile test1 _task_test1 1 /etc/dsp/modules/task_test1.o test2 _task_test2 1 /etc/dsp/modules/task_test2.o test3 _task_test3 1 /etc/dsp/modules/task_test3.o test4 _task_test4 1 /etc/dsp/modules/task_test4.o test5 _task_test5 1 /etc/dsp/modules/task_test5.o test6 _task_test6 1 /etc/dsp/modules/task_test6.o test7 _task_test7 1 /etc/dsp/modules/task_test7.o hellotimer _task_hellotimer 1 /etc/dsp/modules/hellotimer.o /etc/dsp/modules/hellotimer.cmd

The meaning of each field is shown in Table 3-1.

Table 3-1: Fields in Configuration File

devname Device file name. This is used as the device file name of the dynamic task. for example, if this field is ‘test1’, /dev/dsptask/dest1 will be created as the device file interface to this task.

taskname Symbol name of the dsptask structure. When this module is loaded, dsp_dld looks for this symbol in the module, then add it to the system.

pri Priority. This field is not used in this version. Reserved for the future use. module DSP task module file location. cmdfile Additional linker command file for this module. This field is optional.

3.3. Starting the dsp_dld

It is strongly recommended to start syslogd before using the dsp_dld. Because the dsp_dld is a daemon, which outputs the messages to the syslog. So without syslogd, you cannot see the messages of the dsp_dld. To start the dsp_dld, put the config file, task modules and linker command files to the proper place -- /etc/dsp/dsp_dld, /etc/dsp/tinkernel.out, /etc/dsp/tinkernelcfg.cmd and /etc/dsp/modules/*, then just type dsp_dld (with options, if any).

List 3-2: Starting dsp_dld

7 (23)

# dsp_dld # -----(kernel messages) mapping external memory for MEMORY segment EXRAM_KERNEL: adr = 0x028000, size =0 setting DSP reset vector to 0x0157ab releasing DSP reset DSP configuration ... omapdsp: found 0 task(s) omapdsp: IPBUF configuration 128 words * 4 lines at 0xe0028000 2 lines are reserved for DSP. succeeded. ----- # cat /var/log/messages Jan 1 00:19:52 dspgw daemon.info dsp_dld: starting. Jan 1 00:19:52 dspgw daemon.info dsp_dld: dsp_dld: event detected. #

3.4. Using a Dynamic Task

From application’s point of view, there is no difference whether you are using dsp_dld or not. When the appication opens the dsptask device, the dynamic task module is linked and loaded automatically. And when closing, the module is unloaded.

List 3-3: Using a Dynamic Task # ./hellotimer 3 time: 1293.57 Hello from DSP! time: 1294.57 Hello from DSP! time: 1295.57 Hello from DSP! # -----(kernel message) omapdsp: task 0: name hellotimer omapdsp: taskdev hellotimer enabled. ht_callback(): task_ht->cnt = 3 ht_callback(): task_ht->cnt = 2 ht_callback(): task_ht->cnt = 1 omapdsp: taskdev hellotimer disabled. ----- # cat /var/log/messages Jan 1 00:21:32 dspgw daemon.info dsp_dld: dsp_dld: event detected. Jan 1 00:21:32 dspgw daemon.info dsp_dld: device hellotimer is requesting. Jan 1 00:21:32 dspgw daemon.info dsp_dld: loading /etc/dsp/modules/hellotimer.o. Jan 1 00:21:32 dspgw daemon.info dsp_dld: mapping external memory for MEMORY segment EXRAM_HELLO: adr = 0x030000, size = 0x1000 Jan 1 00:21:32 dspgw daemon.info dsp_dld: adding _task_hellotimer(@00bc4c) into system. Jan 1 00:21:35 dspgw daemon.info dsp_dld: dsp_dld: event detected. Jan 1 00:21:35 dspgw daemon.info dsp_dld: device hellotimer was closed. Jan 1 00:21:35 dspgw daemon.info dsp_dld: cleaning task hellotimer... Jan 1 00:21:35 dspgw daemon.info dsp_dld: releasing external memory map for MEMORY segment EXRAM_HELLO: adr = 0x030000 Jan 1 00:21:35 dspgw daemon.info dsp_dld: unloading /etc/dsp/modules/hellotimer.o. #

8 (23)

3.5. Terminating the dsp_dld

To terminate the dsp_dld, send a SIGTERM (or other appropriate) signal to the daemon process.

List 3-4: Terminating dsp_dld # killall dsp_dld # cat /var/log/messages Jan 1 00:24:13 dspgw daemon.info dsp_dld: receiving signal 15 Jan 1 00:24:13 dspgw daemon.info dsp_dld: releasing resources for DSP Jan 1 00:24:13 dspgw daemon.info dsp_dld: DSP reset Jan 1 00:24:13 dspgw daemon.info dsp_dld: releasing external memory map for MEMORY segment EXRAM_KERNEL: adr = 0x028000 Jan 1 00:24:13 dspgw daemon.info dsp_dld: exitting. #

9 (23)

4. GENERATING THE DSP KERNEL (TINKERNEL)

4.1. What is tinkernel?

The tinkernel is the minimum DSP-side executable of the DSP Gateway. It means a binary including the DSP Gateway library functions, with no user task. But if needed, the user can include application tasks as static tasks in this kernel. This kernel is loaded and started at the dsp_dld starting time. 4.2. sysinfo.c

The sysinfo.c for the tinkernel is shown in List 4-1. The IPBUF configuration can be modified to fit to your system.

List 4-1: sysinfo.c /* * sysinfo.c */ #include <std.h> #include "tokliBIOS.h" Int _n_task = 0; struct dsptask *task_user[1]; /* dummy. not used. */ /* * ipbuf configuration */ #define IPBUF_SZ 0x80 #define IPBUF_LINES 4 #define IPBUF_KEEP 2 Uns _ipbuf_sz = IPBUF_SZ; Uns _ipbuf_lines = IPBUF_LINES; Uns _ipbuf_keep = IPBUF_KEEP; #pragma DATA_SECTION(_ipbuf_body, "ipbuf") Int _ipbuf_body[(IPBUF_HEADER_SZ + IPBUF_SZ) * IPBUF_LINES];

can be modified to fit to your system

10 (23)

4.3. Building the tinkernel Using Code Composer Studio

4.3.1. Create A New CCS Project

• Project Name --> tinkernel • Project Type --> Executable (out)

Figure 4-1: Creating A New Project (tinkernel)

11 (23)

4.3.2. DSP/BIOS Configuration

We use tokliBIOS.cdb as the base for the DSP/BIOS configuration. Copy tokliBIOS.cdb from tokliBIOS project folder to the tinkernel project folder and rename it to tinkernel.cdb. Then, add it to the project.

MEM – Memory Section Manager / ‘EXRAM_KERNEL’ (Create new one)

• base --> 0x14000 • len --> 0x800 • create a heap in this memory --> no

Figure 4-2: Property of EXRAM_KERNEL

4.3.3. tinkernel-local.cmd

List 4-2 shows a command file using in this project. This includes tinkernelcfg.cmd, which is generated by the DSP/BIOS configuration tool.

List 4-2: tinkernel-local.cmd -l tinkernelcfg.cmd SECTIONS { ipbuf: align = 0x1000 {} > EXRAM_KERNEL }

set to fit your IPBUF settings

12 (23)

4.3.4. Build

Build Options – Compiler / Advanced

• select Large memory model (-ml)

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

13 (23)

Build Options – Compiler / Preprocessor

• Include Search Path (-i) --> ..¥tokliBIOS (directory where the ‘tokliBIOS.h’ and ‘mailbox.h’ are located)

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

14 (23)

Build Options – Linker / Basic

• Autoinit Model --> Load-time Initialization (-cr) (This is not a requirement, but recommended for the size reduction of output binary)

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

15 (23)

♦ Add following files to this project. sysinfo.c tinkernel-local.cmd tokliBIOS.lib

Figure 4-6: Project Files

♦ Build. After building the project, we have tinkernel.out in Debug (or Release) folder. This is the tinkernel binary.

16 (23)

5. GENERATING A DSP DYNAMIC TASK MODULE

5.1. DSP Dynamic Module

The DSP dynamic module is a module unit which is linked dynamically with the tinkernel and loaded to the DSP memory on-demand. 5.2. Task Source

We use hellotimer application for a dynamic module example here. Please see [1] for source code. 5.3. Task Specific Linker Command

You can prepare a specific linker command for the task module. In this example, we use a linker command ‘hellotimer.cmd’ shown in List 5-1.

List 5-1: hellotimer.cmd MEMORY { EXRAM_HELLO: origin = 0x30000, len = 0x1000 } SECTIONS { .text {} > EXRAM_HELLO }

5.4. Helper Object

To generate a dynamic task module, you need to link the helper object dyntask_helper.obj (the source is dyntask_helper.s) with your module.

List 5-2: dyntask_helper.s ;; disable RTDX .include rtdx.h55 RTDX_USERTDX .set 0 .global RTDX_USERTDX RTDX_config

17 (23)

5.5. Building the Module Using Code Composer Studio

5.5.1. Create A New CCS Project

• Project Name --> mod_hellotimer • Project Type --> Executable (out)

Figure 5-1: Creating A New Project (mod_hellotimer)

18 (23)

5.5.2. Build

Build Options – Compiler / Advanced

• select Large memory model (-ml)

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

19 (23)

Build Options – Compiler / Preprocessor

• Include Search Path (-i) --> ..¥tokliBIOS (directory where the ‘tokliBIOS.h’ and ‘mailbox.h’ are located)

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

20 (23)

Build Options – Linker / Basic

• Output Module --> Relocatable Non-Executable (-r) • Output Filename (-o) --> .¥Debug¥hellotimer.o • Map Filename (-m) --> .¥Debug¥hellotimer.map • Autoinit Model --> Load-time Initialization (-cr)

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

21 (23)

♦ Add following files to this project. hellotimer.c hellotimer.cmd (optional) dyntask_helper.s

Figure 5-5: Project Files

♦ Build. When building this project, we will see a warning message as Figure 5-6, but we can ignore it.

Figure 5-6: Warning Message at Building

After building the project, we have hellotimer.o in Debug (or Release) folder. This is the DSP dynamic task module.

22 (23)

6. LINKER COMMAND FILE

In the dsp_dld, the linker command file for the TMS320C55x is used ([3]). Though the command file generated by the Code Composer Studio can be used as is, only the MEMORY directive and SECTIONS directive are recognized by the dsp_dld. If you specify MEMORY sections at external memory range, the dsp_dld allocates RAM pages for those memory sections (See 2.6). But if the MEMORY section name is ‘FRAMEBUFFER’, it is regarded as the frame buffer shadow section for the DSP. In this case, the dsp_dld doesn’t allocate new pages for that section, but maps the frame buffer to the specified address. The len field is ignored and actual frame buffer size is used.

List 6-1: Linker Command File Example MEMORY { EXRAM_TASK1: origin = 0x30000, len = 0x10000 FRAMEBUFFER: origin = 0x40000, len = 0x10000

} SECTIONS { large_buf {} > EXRAM_TASK1 }

regarded as the frame buffer shadow

23 (23)

REFERENCES

• [1] Linux DSP Gateway Specification Rev 3.0.2, Nokia

• [2] Generating tokliBIOS.lib for DSP Gateway 3.0, Nokia

• [3] SPRU280: TMS320C55x Assembly Language Tools User’s Guide, Texas Instruments