ANALOG DEVICES EE-303 Service Manual

Engineer-to-Engineer Note EE-303

r

a

Technical notes on using Analog Devices DSPs, processors and development tools

Visit our Web resources http://www.analog.com/ee-notes and http://www.analog.com/processors o
e-mail [e-mail] or [e-mail] for technical support.

Using VisualDSP++® Thread-Safe Libraries with a Third-Party RTOS

Contributed by Andy Millard Rev 1 – November 10, 2006

Introduction

This document describes how to use the thread-safe C and C++ libraries provided with VisualDSP++®

4.5 with an RTOS other than VDK. This information is provided as a guide for users who have a firm
understanding of multithreaded programming principles and the procedures used in their multithreaded
operating system.

Thread-safe libraries are designed to work specifically with the VDK RTOS, which is the only

L

Overview

configuration supported by Analog Devices.

The C and C++ libraries that are shipped with VisualDSP++ 4.5 are available in various flavors, several of
which contain functions considered to be safe for use in a multithreaded environment. These thread-safe
versions of the libraries were developed as a requisite for the VDK kernel and are not intended to be used
in conjunction with any other RTOS. By replacing the VDK functions called from within the C and C++
libraries with equivalent functions from the alternative RTOS, adding the relevant support to the
initialization objects and modifying the Linker Description File (.LDF), it is possible to integrate the
libraries into another environment.

It is assumed that users wishing to use an alternative RTOS will be using initialization code provided by
the RTOS developer responsible for heap and stack initialization, file I/O, and other required components.
This overrides the behavior of the default initialization code provided with VisualDSP++. A customized

.LDF file provided with the RTOS must be used to include these new objects.

When using the multithreaded C run-time support library, the application must be linked against the
multithreaded C++ run-time support library. The C library requires the use of a C++ mutex class defined
in the C++ library.

Copyright 2006, Analog Devices, Inc. All rights reserved. Analog Devices assumes no responsibility for customer product design or the use or application of
customers’ products or for any infringements of patents or rights of others which may result from Analog Devices assistance. All trademarks and logos are property
of their respective holders. Information furnished by Analog Devices applications and development tools engineers is believed to be accurate and reliable, however
no responsibility is assumed by Analog Devices regarding technical accuracy and topicality of the content provided in Analog Devices Engineer-to-Engineer Notes.

Sections of this Document

a

This document contains the following sections.

 Changes from VisualDSP++ 4.0 to VisualDSP++ 4.5
 Locking and Unlocking Critical Sections in the C and C++ Libraries
 Thread-Local Storage
 Modifying the Linker Description File
 Initializing the C and C++ Libraries

Changes from VisualDSP++ 4.0 to VisualDSP++ 4.5

The underlying implementation of the thread-safe libraries has changed significantly between the
VisualDSP++ 4.0 and VisualDSP++
implementation uses a mutex-based system.

The following functions are no longer called from the run-time libraries that are thread safe:

 CreateSemaphore__3VDKFUiN31
 DestroySemaphore__3VDKF11SemaphoreID
 PendSemaphore__3VDKF11SemaphoreIDUi
 PostSemaphore__3VDKF11SemaphoreID
 GetThreadID__3VDKFv

4.5 releases. The previous releases used semaphores, and the new

The following functions, which are described later in this document, were added in VisualDSP++ 4.5:

 RMutexInit__3VDKFPQ2_3VDK6RMutexUi
 RMutexDeInit__3VDKFPQ2_3VDK6RMutex
 RMutexAcquire__3VDKFPQ2_3VDK6RMutex
 RMutexRelease__3VDKFPQ2_3VDK6RMutex

Locking and Unlocking Critical Sections in the C and C++ Libraries

The C and C++ runtime support libraries provided with VisualDSP++ 4.5 use several VDK functions for
serialized access to critical sections of code, as follows.

void PushUnscheduledRegion__3VDKFv (void)

This function is called whenever a critical section is entered. The function ensures that the scheduler does
not assign control of the process to another thread while inside a critical section. Calls to

PushUnscheduledRegion can be nested. For details, refer to VisualDSP++ 4.5 Kernel (VDK) User’s

[1]

Guide

.

Using VisualDSP++® Thread-Safe Libraries with a Third-Party RTOS (EE-303) Page 2 of 7

void PopUnscheduledRegion__3VDKFv (void)

a

This function is called when leaving a critical section. Function calls can be nested. For details, refer to

VisualDSP++ 4.5 Kernel (VDK) User’s Guide

void RMutexInit__3VDKFPQ2_3VDK6RMutexUi(void* mutex, unsigned int size)

This function constructs a mutex of size size. In calls from the thread-safe runtime libraries, the size is

5*sizeof(int). In the thread-safe libraries, the memory pointed to by mutex is allocated by a call to
malloc() before the pointer is passed to this function.

void RMutexDeInit__3VDKFPQ2_3VDK6RMutex(void* mutex)

This function destructs the mutex for the given mutex pointer. The memory allocated for the mutex is not
freed by the call to this routine and must be done independently.

void RMutexAcquire__3VDKFPQ2_3VDK6RMutex(void* mutex)

This function acquires the mutex pointed to by mutex.

void RMutexRelease__3VDKFPQ2_3VDK6RMutex(void* mutex)

This function releases the mutex pointed to by mutex.

[1]

.

The suggested approach for replacing these functions is to create them with the same names that will call
the appropriate functions in the alternative RTOS.

Note that the VDK mutex is implemented as a recursive mutex, i.e., one for which nested acquisitions by
the same thread are legal and safe.

The mutex implementation keeps track of both its current owner (if there is one) and the count of nested
acquisitions by that thread. The mutex is not released until the count falls to zero.

The VDK locking mechanisms that are called from the C and C++ libraries concern themselves with
disabling the scheduler only. They do not disable interrupts. This is left to the developers’ discretion when
calling these functions.

The C and C++ libraries are designed to be thread-safe only and are not re-entrant. As a consequence,
interrupt service routines should not call any C or C++ library functions as they may cause the library to
perform in an undefined fashion. More information on calling library functions from an ISR can be found
in the VisualDSP++ 4.5 C/C++ Compiler and Library Manual

It is possible to replace these calls with calls to functions that disable the scheduler and disable interrupts.
This approach is not recommended as the library may be attempting to generate its own interrupt.

[2] [3] [4]

.

Using VisualDSP++® Thread-Safe Libraries with a Third-Party RTOS (EE-303) Page 3 of 7