Engineer-to-Engineer Note

Transcription

1 Engineer-to-Engineer Note EE-303 Technicl notes on using Anlog Devices DSPs, processors nd development tools Visit our Web resources nd or e-mil or for technicl support. Using VisulDSP++ Thred-Sfe Librries with Third-Prty RTOS Contributed by Andy Millrd Rev 1 November 10, 2006 Introduction This document describes how to use the thred-sfe C nd C++ librries provided with VisulDSP with n RTOS other thn VDK. This informtion is provided s guide for users who hve firm understnding of multithreded progrmming principles nd the procedures used in their multithreded operting system. Thred-sfe librries re designed to work specificlly with the VDK RTOS, which is the only configurtion supported by Anlog Devices. Overview The C nd C++ librries tht re shipped with VisulDSP re vilble in vrious flvors, severl of which contin functions considered to be sfe for use in multithreded environment. These thred-sfe versions of the librries were developed s requisite for the VDK kernel nd re not intended to be used in conjunction with ny other RTOS. By replcing the VDK functions clled from within the C nd C++ librries with equivlent functions from the lterntive RTOS, dding the relevnt support to the initiliztion objects nd modifying the Linker Description File (.LDF), it is possible to integrte the librries into nother environment. It is ssumed tht users wishing to use n lterntive RTOS will be using initiliztion code provided by the RTOS developer responsible for hep nd stck initiliztion, file I/O, nd other required components. This overrides the behvior of the defult initiliztion code provided with VisulDSP++. A customized.ldf file provided with the RTOS must be used to include these new objects. When using the multithreded C run-time support librry, the ppliction must be linked ginst the multithreded C++ run-time support librry. The C librry requires the use of C++ mutex clss defined in the C++ librry. Copyright 2006, Anlog Devices, Inc. All rights reserved. Anlog Devices ssumes no responsibility for customer product design or the use or ppliction of customers products or for ny infringements of ptents or rights of others which my result from Anlog Devices ssistnce. All trdemrks nd logos re property of their respective holders. Informtion furnished by Anlog Devices pplictions nd development tools engineers is believed to be ccurte nd relible, however no responsibility is ssumed by Anlog Devices regrding technicl ccurcy nd topiclity of the content provided in Anlog Devices Engineer-to-Engineer Notes.

2 Sections of this Document This document contins the following sections. Chnges from VisulDSP to VisulDSP Locking nd Unlocking Criticl Sections in the C nd C++ Librries Thred-Locl Storge Modifying the Linker Description File Initilizing the C nd C++ Librries Chnges from VisulDSP to VisulDSP The underlying implementtion of the thred-sfe librries hs chnged significntly between the VisulDSP nd VisulDSP releses. The previous releses used semphores, nd the new implementtion uses mutex-bsed system. The following functions re no longer clled from the run-time librries tht re thred sfe: CreteSemphore 3VDKFUiN31 DestroySemphore 3VDKF11SemphoreID PendSemphore 3VDKF11SemphoreIDUi PostSemphore 3VDKF11SemphoreID GetThredID 3VDKFv The following functions, which re described lter in this document, were dded in VisulDSP++ 4.5: RMutexInit 3VDKFPQ2_3VDK6RMutexUi RMutexDeInit 3VDKFPQ2_3VDK6RMutex RMutexAcquire 3VDKFPQ2_3VDK6RMutex RMutexRelese 3VDKFPQ2_3VDK6RMutex Locking nd Unlocking Criticl Sections in the C nd C++ Librries The C nd C++ runtime support librries provided with VisulDSP use severl VDK functions for serilized ccess to criticl sections of code, s follows. void PushUnscheduledRegion 3VDKFv (void) This function is clled whenever criticl section is entered. The function ensures tht the scheduler does not ssign control of the process to nother thred while inside criticl section. Clls to PushUnscheduledRegion cn be nested. For detils, refer to VisulDSP Kernel (VDK) User s Guide [1]. Using VisulDSP++ Thred-Sfe Librries with Third-Prty RTOS (EE-303) Pge 2 of 7

3 void PopUnscheduledRegion 3VDKFv (void) This function is clled when leving criticl section. Function clls cn be nested. For detils, refer to VisulDSP Kernel (VDK) User s Guide [1]. void RMutexInit 3VDKFPQ2_3VDK6RMutexUi(void* mutex, unsigned int size) This function constructs mutex of size size. In clls from the thred-sfe runtime librries, the size is 5*sizeof(int). In the thred-sfe librries, the memory pointed to by mutex is llocted by cll to mlloc() before the pointer is pssed to this function. void RMutexDeInit 3VDKFPQ2_3VDK6RMutex(void* mutex) This function destructs the mutex for the given mutex pointer. The memory llocted for the mutex is not freed by the cll to this routine nd must be done independently. void RMutexAcquire 3VDKFPQ2_3VDK6RMutex(void* mutex) This function cquires the mutex pointed to by mutex. void RMutexRelese 3VDKFPQ2_3VDK6RMutex(void* mutex) This function releses the mutex pointed to by mutex. The suggested pproch for replcing these functions is to crete them with the sme nmes tht will cll the pproprite functions in the lterntive RTOS. Note tht the VDK mutex is implemented s recursive mutex, i.e., one for which nested cquisitions by the sme thred re legl nd sfe. The mutex implementtion keeps trck of both its current owner (if there is one) nd the count of nested cquisitions by tht thred. The mutex is not relesed until the count flls to zero. The VDK locking mechnisms tht re clled from the C nd C++ librries concern themselves with disbling the scheduler only. They do not disble interrupts. This is left to the developers discretion when clling these functions. The C nd C++ librries re designed to be thred-sfe only nd re not re-entrnt. As consequence, interrupt service routines should not cll ny C or C++ librry functions s they my cuse the librry to perform in n undefined fshion. More informtion on clling librry functions from n ISR cn be found in the VisulDSP C/C++ Compiler nd Librry Mnul [2] [3] [4]. It is possible to replce these clls with clls to functions tht disble the scheduler nd disble interrupts. This pproch is not recommended s the librry my be ttempting to generte its own interrupt. Using VisulDSP++ Thred-Sfe Librries with Third-Prty RTOS (EE-303) Pge 3 of 7

4 Thred-Locl Storge The C librry supports nd uses thred-locl storge to preserve dt between function clls for four sets of dt: errno The vlue of errno is thred-specific. Ech thred uses thred-locl storge to preserve the vlue of errno. strtok() The strtok() function uses thred-locl storge to preserve internl pointers between clls to the function. rnd() The rnd() function uses thred-locl storge to llow progrm to define seed vlue on per-thred bsis. time() nd sctime() The sctime() function nd the time() fmily of functions use thred-locl storge to llow clls to these functions on per-thred bsis. The routines detiled bove rely on three functions in the VDK. Functions with identicl functionlity re vilble in most RTOS. bool AllocteThredSlotEx 3VDKFPiPFPv_v(int *, void (*clenupfunc)(void *)) This function lloctes new thred storge slot if one hs not lredy been ssigned. The VDK function hs severl return vlues. Refer to the VDK API in the VisulDSP Kernel (VDK) User s Guide [1] so tht the lterntive function cn emulte the behvior of AllocteThredSlotsEx. void *GetThredSlotVlue 3VDKFi (int) This function returns pointer to tht thred s loclly stored dt. Refer to the VDK API in the VisulDSP Kernel (VDK) User s Guide [1] for informtion on GetThredSlotVlue. bool SetThredSlotVlue 3VDKFiPv (int, void *) This function stores the dt pointed to in the threds re of the slot. Refer to the VDK API in the VisulDSP Kernel (VDK) User s Guide [1] for informtion on SetThredSlotVlue. Using VisulDSP++ Thred-Sfe Librries with Third-Prty RTOS (EE-303) Pge 4 of 7

5 Modifying the Linker Description File The Linker Description File (.LDF) used by VDK differs from the stndrd.ldf file becuse it links the user's progrm using the thred-sfe version of the C nd C++ librries by defult. The defult.ldf file does not contin support for multithreded librries. Users wishing to use n lterntive RTOS must copy the stndrd.ldf file nd modify it to link with the correct versions of the librries. The multithreded librries for Blckfin nd SHARC contin n mt extension in the librry nme; for exmple, the ADSP-BF532 C librry is nmed libc532mt.dlb with the ADSP C librry nmed libcmt.dlb. The multithreded librries for TigerSHARC contin n _mt extension in their nme; for exmple, the ADSP-TS201 C librry is nmed libc_ts201_mt.dlb. Initilizing the C nd C++ Librries The following sections describe the res of the supplied initiliztion code tht must be modified to llow use of the C nd C++ librries. It is ssumed tht the source code for the initiliztion code used by the RTOS will be vilble. Severl sections of the defult initiliztion code must be replicted in the initiliztion code of the RTOS to ensure tht the C nd C++ librries will function s expected. Detils on these sections follow for ech of the Blckfin, SHARC, nd TigerSHARC processor trgets. Blckfin Strt-Up Code The strt-up code in VisulDSP\Blckfin\lib\src\libc\bsiccrt.s supports severl configurtion options. The Blckfin instlltion includes numerous pre-ssembled combintions. The defult.ldf file selects the crt*.doj file to link with, bsed on user-specified defines nd ccblkfn options. FIOCRT The FIOCRT mcro is true when we wish to use file I/O inside progrm. Enbling this define ensures tht the _init_devtb routine is clled to initilize your I/O method. CPLUSCRT The C++ ctorloop routine must be clled. This routine ensures tht C++ objects re creted nd destroyed correctly. It lso initilizes behind-the-scenes grbge collection. The ctor_tble vrible should lso be declred in similr mnner to the declrtion t the bottom of the defult bsiccrt.s file. FP/SP Initiliztion The initiliztion code should ensure tht the FP nd SP registers re set to sensible vlues. It would be expected thn n lterntive RTOS initiliztion routine would provide this s defult. Using VisulDSP++ Thred-Sfe Librries with Third-Prty RTOS (EE-303) Pge 5 of 7

6 SHARC Strt-Up Code The strt-up code s source code is in one of the following files, depending on the trget rchitecture: VisulDSP\21k\lib\src\crt_src\020_hdr.sm VisulDSP\21k\lib\src\crt_src\06x_hdr.sm VisulDSP\211xx\lib\src\crt_src\16x_hdr.sm VisulDSP\212xx\lib\src\crt_src\26x_hdr.sm VisulDSP\213xx\lib\src\crt_src\36x_hdr.sm The SHARC instlltion includes numerous pre-ssembled combintions. When using the defult.ldf file, the.ldf file selects the *hdr*.doj file to link with, bsed on user-specified defines nd cc21k options. By defult, severl vrints of pre-built strt-up code re included in the relese. By convention, the file nmes of the pre-built strt-up modules tht tht support C++ contin cpp, nd the thred-sfe versions contin _mt in their nmes. cplusplus Define The _lib_cll_ctors routine will be included when this mcro is defined. This routine ensures tht C++ objects re creted nd destroyed correctly. This routine is clled when the cplusplus define is set when ssembling the *hdr*.sm. The ctors vrible should lso be declred; this vrible should be defined within the.ldf file nd should point to the strt of the seg_ctdm section. TigerSHARC Strt-Up Code The strt-up code s source code is in the ssembly source file tht cn be found in the following loction: VisulDSP\TS\lib\src\crt_src\ts_hdr.sm. The TigerSHARC instlltion includes numerous pressembled combintions. When using the defult.ldf file, the.ldf file selects the ts_hdr*.doj file to link with, bsed on user-specified defines nd ccts options. By defult, severl vrints of pre-built strt-up code re included in the relese. By convention, file nmes for the pre-built strt-up modules tht support C++ contin cpp, thred-sfe versions contin _mt in their nmes, nd byte-ddressing mode strt-up files contin _b in their nmes. It is ssumed tht users will hve the source code for the initiliztion code tht is used by the RTOS. The following sections of code from the defult initiliztion code must be replicted in the initiliztion code of the RTOS to ensure tht the C nd C++ librries will function s expected. _CPLUSPLUS Define The C++ routine ctorloop must be clled to ensure tht C++ objects re creted nd destroyed correctly. This routine is clled when the _CPLUSPLUS define is set while ssembling ts_hdr.sm. This routine will lso initilize the hep nd the I/O librry, so these must be initilized before use. The ctor_tble vrible should lso be declred in mnner similr to the declrtion t the bottom of the defult ts_hdr.sm file. Using VisulDSP++ Thred-Sfe Librries with Third-Prty RTOS (EE-303) Pge 6 of 7

7 vdkminmrker The C vrible vdkminmrker is declred within VDK to notify the run-time librries s to when the ppliction enters multithreded stte. vdkminmrker is declred s: int vdkminmrker = 0; The vrible is ssigned vlue of 1 immeditely before the progrm invokes the highest-priority boot thred. Until the vrible is set to vlue of 1, no VDK locking functions re clled by the run-time librries. This is implemented to void clling thred-specific functions from non-threded code. For use with ny RTOS other thn VDK, this vrible should be declred with n initil vlue of zero nd set to one just before the progrm invokes the user boot thred. This pplies to Blckfin, SHARC, nd TigerSHARC processors. References [1] VisulDSP Kernel (VDK) User s Guide. Rev 2.0, April Anlog Devices, Inc. [2] VisulDSP C/C++ Compiler nd Librry Mnul for Blckfin Processors. Rev 4.0 April Anlog Devices, Inc. [3] VisulDSP C/C++ Compiler nd Librry Mnul for SHARC Processors. Rev 6.0 April Anlog Devices, Inc. [4] VisulDSP C/C++ Compiler nd Librry Mnul for TigerSHARC Processors. Rev 3.0 April Anlog Devices, Inc. Document History Revision Rev 1 November 10, 2006 by Andy Millrd Description Initil Relese Using VisulDSP++ Thred-Sfe Librries with Third-Prty RTOS (EE-303) Pge 7 of 7