DSPLink API Guide

Learn here what DSPLink is, what it can be used for and how to use it. The complete toolchain is described on the OMAP3 DSP Toolchain page. The installation of a Windows or mixed Windows/Linux toolchain is also described in detail there. The installation for OpenEmbedded builds is described in the DSPLink installation guide.

Introduction

On the OMAP3, aside from the main processor (the ARM Cortex A8), there are three other processing units which can be used optionally. One of them is the TMS320C64x+ DSP.
The Linux operating system runs on the ARM processor just as if it would run on an Intel or AMD on a desktop PC. Analogously we can compile applications to run on the Beagleboard-hosted Linux using an ARM compiler. Some real difficulties arise however if we are ambitious to use the DSP. Naturally we want to use the DSP to support the computations being performed in some Linux application. That means, we want to call the DSP out of our application to do some computationally intensive algorithms, ideally without needing to stop and wait for the result.
Generally this means hardcore harware programming. We, however are in the lucky situation that someone has already done this job and packed the result in a library called DSPLink.

DSPLink is an API for the interprocessor communication across the GPP-DSP boundary. Hence it serves as an abstraction of the physical link connecting GPP and DSP. Alltogether it makes the utilization of the DSP out of a GPP- (Linux-) application less complex, more human-readable and therefore more user-friendly.
To be able to provide its services, DSPLink avails itself of a little real-time operating called BIOS. BIOS stands for Built-In Operating System. It runs on the DSP in its reserved part of RAM and is controlled by DSPLink.

Depending on the supported platform and OS, DSP/BIOS LINK provides a subset of the following services:

  • Basic processor control
  • Shared/syncronized memory pool access multiple processors
  • Notification of user events
  • Mutually exclusive access to shared data structures
  • Linked list based data streaming
  • Data transfer over logical channels
  • Messaging (based on MSGQ module of DSP/BIOS)
  • Ring buffer based data streaming
  • Zero Copy Messaging (physical mechanism)

DSP/BIOS LINK is designed to be scalable at compile time such that only the required conponents and services can be chosen.


DSP/BIOS LINK API

Documentation

Important:


Further reading:



The software architecture of DSP/BIOS LINK is shown in the diagram below:

DSP/BIOS LINK software architecture

Note the strict separation of GPP and DSP sides.

Components on the GPP side

On the GPP side, a specific OS is assumed to be running.

The OS ADAPTION LAYER encapsulates the generic OS services that are required by the other components of DSP/BIOS LINK. This component exports a generic API that insulates the other components from the specifics of an OS. All other components use this API instead of direct OS calls. This makes DSP/BIOS LINK portable across different operating systems.

The LINK DRIVER encapsulates the low-level control operations on the physical link between the GPP and DSP. This module is responsible for controlling the execution of the DSP and data trnsfer using defined protocol across the GPP-DSP boundary.

The PROCESSOR MANAGER maintains book-keeping information for all components. It also allows different boot-loaders to be plugged into the system. It builds exposes the control operations provided by the LINK DRIVER to the user through the API layer.

The DSP/BIOS LINK API is interface for all clients on the GPP side. This is a very thin component and usually doesn't do any more processing than parameter validation. The API layer can be considered as 'skin' on the 'muscle' mass contained in the PROCESSOR MANAGER and LINK DRIVER.

The thin API layer allows easy partition of DSP/BIOS LINK across the user kernel boundary on specific operation systems e.g. Linux. Such partition may not be necessary on other operating systems.

Components on the DSP side

Here, the LINK DRIVER is one of the drivers in DSP/BIOS. This driver specializes in communicating with the GPP over the physical link.

The communication (data/ message transfer) is done using the DSP/BIOS modules- SIO/ GIO/ MSGQ. There are specific DSP/BIOS LINK API on the DSP for the other modules RingIO, MPCS, MPLIST, NOTIFY, POOL.

DSPLink API key components

PROC

The PROC module provides functionality to setup, boot-load, control, and communicate with the processors in the system. The master processor in the system is responsible for all control activities on the slave processors in the system. For example, in an SoC such as Davinci, the ARM processor is the master and the DSP is the slave. The specific services provided by the PROC module are:

  • Setup and destroy the DSP/BIOS LINK driver.
  • Attach to and detach from a specific processor. Every process in the system wishing to communicate with a specific processor must do this to gain access to the processor.
  • Load a DSP executable on the target processor. This executable is present within the GPP file system.
  • Start execution of the DSP executable on the target processor.
  • Stop execution of the target processor
  • Write to and read from DSP memory
  • Get the current state of the PROC component. This indicates the last successful state transition for the DSP. It does not return the actual run-time state of the DSP.
  • Perform platform-specific control activities with the target processor.


POOL

The POOL component provides APIs for configuring shared memory regions across processors.

These buffers are used by other modules from DSP/BIOS Link for providing interprocessor communication functionality.

The specific services provided by this module are:

  • Configure the shared memory region through open & close calls.
  • Allocate and free buffers from the shared memory region.
  • Translate address of a buffer allocated to different address spaces (e.g. GPP to DSP)
  • Synchronize contents of memory as seen by the different CPU cores.

This component is responsible for providing a uniform view of different memory pool implementations, which may be specific to the hardware architecture or OS on which DSP/BIOS™ LINK is ported. This component is based on the POOL interface in DSP/BIOS™.

The DSP/BIOS LINK POOL is not a heap-based pool. It is a fixed-size buffer pool. It requires the specific configuration of number of buffers and sizes as will be used by the application. The exactMatchReq property only allows users the flexibility of configuring an approximate size for each buffer. However, the maximum number of buffers still must be configured.

NOTIFY

This component allows applications to register for notification of events occurring on the remote processor and send event notification to the remote processor.
It allows applications to register a callback function with an associated parameter for events that occur on remote processors.
It enables applications to send specific event notification to remote processors. The applications can also send an optional value with the event.
The NOTIFY component enforces a priority on event notifications. The priority is defined by the event number, with lower event number indicating higher priority. The applications can also un-register their event callback functions at runtime if such event notification is no longer required.

NOTIFY component may be used for messaging/data transfer if:

  • Only 32-bit information needs to be sent between the processors.
  • Prioritization of notifications is required. For example, one low priority event (e.g. 30) can be used for sending buffer pointers. A higher priority event (e.g. 5) can be used to send commands.
  • The notification is to be sent infrequently. If multiple notifications for the same event are sent very quickly in succession, each attempt to send a specific event spins, waiting till the previous event has been read by the other processor. This may result in inefficiency.
  • Multiple clients need to be able to register for the same notification event. When the event notification is received, the same notification with payload is broadcast to all clients registered for that event.


MPLIST

This component provides a doubly-linked circular linked list based transport mechanism between GPP and DSP. On the devices where a shared memory region exists between GPP and DSP, this module implements the linked-list in the shared memory region. In cases where a shared memory region does not exist, the module internally maintains coherence between linked lists on the remote processors.
This component provides APIs to create and delete instance of the MPLIST. Each instance of the MPLIST is identified by a system-wide unique string name. Every client that needs to use an MPLIST must get a handle to the MPLIST by calling an API to open it. A corresponding API to close the MPLIST handle is used when the client no longer needs to use the MPLIST.
The MPLIST component provides APIs to place an element at the end of list, and remove an element from the front of the list. It also allows applications to insert a buffer before an existing element in the list, and remove any specified list element from the list. An API to check if the list is empty is also provided. In addition, APIs are also provided to traverse the list by getting a pointer to the first element in the list and the element after a specified element.

CHNL

This component represents a logical data transfer channel in the application space.
CHNL is responsible for the data transfer across the GPP and DSP. CHNL is an acronym for ‘channel’.
A channel (when referred in context of DSP/BIOS™ LINK) is:

  • A means of transferring data across GPP and DSP.
  • A logical entity mapped over a physical connectivity between the GPP and DSP.
  • Uniquely identified by a number within the range of channels for a specific physical link towards a DSP.
  • Unidirectional. The direction of a channel is decided at run time based on the attributes passed to the corresponding API.

Multiple channels may be multiplexed on single physical link between the GPP and DSP depending upon the characteristics of the link & associated link driver.
The data being transferred on the channel does not cont in any information about the source or destination. The consumer and producer on either side of the processor boundary must establish the data path explicitly.
This component follows the issue-reclaim model for data transfer. As such, it mimics the behavior of issue-reclaim model of the SIO module in DSP/BIOS™.

MSGQ

This component represents queue based messaging. It is an acronym for ‘message queue’. This component is responsible for exchanging short messages of variable length between the GPP and DSP clients3. It is based on the MSGQ module in DSP/BIOS™.
The messages are sent and rceived through message queues.
A reader gets the message from the queue and a writer puts the message on a queue. A message queue can have only one reader and many writers. A task may read from and write to multiple message queues.
The client is responsible for creating the message queue if it expects to receive messages. Before sending the message, it must ‘locate’ the queue where message is destined.

MSGQ component may be used for messaging/data transfer if:

  • Application requires single reader and multiple writers.
  • More than 32-bit information needs to be sent between the processors using application-defined message structures.
  • Variable sized messages are required.
  • Reader and writer operate on the same buffer sizes.
  • Messages need to be sent frequently. In this case, the messages are queued and there is no spin-wait for the previous event to be cleared.
  • The ability to wait when the queue is empty is desired. This is inbuilt within the MSGQ protocol, and no extra application code is required. If MSGQ_get() is called on an empty queue, it waits till a message is received. If NOTIFY is used, the application must register the callback, or wait on a semaphore that is posted by the application’s notification callback function.
  • It is desired to have the ability to move the Message Queue between processors. In this case, the MSGQ_locate() on other processors internally takes care of locating the queue, and the application code sending messages to this queue does not need to change.
  • It is desired to also have DSP-DSP communication. In this case, Message Queue component in DSP/BIOS allows usage of different Message Queue Transport modules independent of DSPLINK to communicate between DSPs.


RING IO

This component provides Ring Buffer based data streaming.
This component allows creation of a ring buffer created within the shared memory.
The reader and writer of the ring buffer can be on different processors.
The RingIO component provides the ability for the writer to acquire empty regions of memory within the data buffer. The contents of the acquired region are committed to memory when the data buffer is released by the writer.
The RingIO component provides the ability for the reader to acquire regions of memory within the data buffer with valid data within them. On releasing the acquired region, the contents of this region are marked as invalid.
Each RingIO instance can have a single reader and a single writer.
The RingIO component also supports APIs for enabling synchronous transfer of attributes with data. End of Stream (EOS), Time Stamps, Stream offset etc. are examples of such attributes and these can be associated with offsets in the ring buffer.

RingIO component may be used for messaging & data transfer if:

  • Single reader and single writer are required.
  • Data, as well as attributes/messages associated with data are to be sent & received.
  • Writer and reader need to execute independently of each other. The size of buffer used by writer may be different from the buffer size needed by reader.
  • The buffer sizes for acquire and release for writer & reader do not need to match. Writer/reader may choose to release lesser buffer size than was acquired, or may choose to acquire more data before releasing any data.
  • Applications have different notification needs. The application can minimize interrupts by choosing the most appropriate type of notification based on watermark.
  • It is desired to have the capability to cancel unused data that was acquired but not released.
  • It is desired to flush the contents of the ring buffer to clear the ring buffer of released data. For example, when ongoing media file play is stopped and new media file is to be streamed and decoded.



Design Possibilities

Static buffer system with minimal control communication with the DSP

Application requirements
  1. Boot-load the DSP
  2. Statically reserve a region of memory to be shared with DSP. The complete system is static.
  3. GPP and DSP may need to infrequently ping each other with some control information.
Suggested Design

Static buffer system with minimal control

  • PROC module is used to boot-load the DSP. The DSP executable is present in the GPP file system.
  • Two regions of memory can be statically reserved (at compile time) through the DSPLINK dynamic configuration file (CFG_<PLATFORM>.c). On DSP-side, a similar configuration needs to be done within TCF file to reserve the memory. One region of memory can be used for GPP→DSP transfers, and the other for DSP→GPP transfers. Since the memory is statically reserved, both GPP and DSP are aware of their start addresses and sizes.
  • NOTIFY module can be used to send 32-bit control messages between the GPP and DSP.

FIXME For what kind of application is this design useful?
FIXME Step-by-step HowTo or generic library
FIXME Example code

DSP/BIOS LINK components used
  • PROC
  • NOTIFY





Dynamic buffer system with minimal control communication with the DSP

Application Requirements
  1. Boot-load the DSP
  2. Be able to dynamically allocate and free regions of memory to be shared with DSP. For example, this may be needed if same DSP executable is to be used with different GPP applications having different buffer size requirements.
  3. Buffer requirements for each application are limited. For example, each application just needs to allocate one or two buffers during setup phase, and after this, the same buffers are used directly by GPP and DSP.
  4. GPP and DSP may need to infrequently ping each other with some control information.
Suggested Design

Dynamic buffer system with minimal control

  • PROC module is used to boot-load the DSP. The DSP executable is present in the GPP file system.
  • A POOL is opened with a configuration of the sizes of buffers to be shared between the GPP and DSP.
  • Buffers are allocated from the POOL as required by the GPP or DSP during setup phase of the application.
  • If allocated on GPP, the buffer address received from POOL_alloc can be translated to DSP address space to get the corresponding DSP address of the same buffer using POOL_translateAddr.
  • NOTIFY module can be used to send the 32-bit buffer addresses (or other 32-bit control information) between the GPP and DSP.
  • If the buffer is allocated on DSP-side, the DSP address received on the GPP can be translated using POOL_translateAddr.
  • The buffers are now used by GPP and DSP for sending/receiving data. NOTIFY module can be used to inform the processors when data is available/freed in the buffers.
  • If both GPP and DSP may have to simultaneously access the pool buffers, and mutually exclusive access is to be provided to the buffers, the MPCS module can be optionally used to protect access to the buffers.

FIXME For what kind of application is this design useful?
FIXME Step-by-step HowTo or generic library
FIXME Example code

DSP/BIOS LINK Components used
  • PROC
  • NOTIFY
  • POOL
  • MPCS (optional)




Multiple buffers to be sent between GPP and DSP

Application requirements
  1. Boot-load the DSP
  2. Be able to dynamically allocate and free regions of memory to be shared with DSP.
  3. Multiple buffers are required by each application. The buffers may be allocated and freed at run-time. The buffers need to be sent between GPP and DSP during execution phase.
Suggested Design

Multiple buffers to be sent between GPP and DSP

  • PROC module is used to boot-load the DSP. The DSP executable is present in the GPP file system.
  • A POOL is opened with a configuration of the sizes of buffers to be shared between the GPP and DSP.
  • Buffers are allocated from the POOL as required by the GPP or DSP.
  • If allocated on GPP, the buffer addresses received from POOL_alloc can be translated to DSP address space to get the corresponding DSP addresses of the same buffers using POOL_translateAddr.
  • If the buffers are to be sent infrequently, the NOTIFY module can be used to send the 32-bit buffer addresses (or other 32-bit control information) between the GPP and DSP. If one processor may need to send multiple buffers to the other processor in one shot, either MSGQ or MPLIST module can be used. If additional information (e.g. buffer attributes) is required to be associated with the data buffer, a message structure can be defined that has these attributes, and MSGQ or MPLIST component can be used to send the message to the other processor.
  • If the buffers are allocated on DSP-side, the DSP addresses received on the GPP can be translated using POOL_translateAddr.

FIXME For what kind of application is this design useful?
FIXME Step-by-step HowTo or generic library
FIXME Example code

DSP/BIOS LINK Components used
  • PROC
  • NOTIFY / MSGQ / MPLIST
  • POOL


Generic Program Flow

FIXME this is only a draft!

  • Initialize DSP (set memory map, start DSP/BIOS, Codec Engine, whatever)
  • Load DSP executable (our algorithm) into DSP memory space
  • Application main loop:
    • Execute ARM-routine (e.g. grab image from camera)
    • Load input buffer to DSP memory
    • Run DSP executable
      • In the meantime do some independent calculation (let's bother the GPU a bit)
    • Read back DSP output buffer
    • Execute ARM-routine (write results to file e.g.)
    • Iterate main loop

@USER@

Project

Related Sites

Micro Air Vehicles

2009-2011 System

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 3.0 Unported