Engineer-to-Engineer Note EE-069 Technicl notes on using Anlog Devices DSPs, processors nd development tools Visit our Web resources http://www.nlog.com/ee-notes nd http://www.nlog.com/processors or e-mil processor.support@nlog.com or processor.tools.support@nlog.com for technicl support. Understnding nd Using Linker Description Files on SHARC Processors Contributed by Mtt Wlsh Rev 2 Jnury 17, 2007 Introduction Often, progrmmer wnts to control where prticulr piece of code or dt resides in SHARC processor s memory spce. For exmple, on ADSP-2106x, ADSP-2116x, nd ADSP-2137x processors, it is possible to execute from externl memory; however, execution is performed t reduced rte. In this cse, the progrm will need to store nd execute frequently used code internlly nd store rrely used code externlly. Regrdless whether you wnt to relocte C function or n ssembly routine, the mechnism is the sme. To mp portions of code or dt to specific memory sections, it is necessry to use the Linker Description File (referred to s the.ldf file). This EE-Note explins the functionlity of the.ldf file nd demonstrtes its fetures through n exmple. The implementtion detils of specific pplictions tht require reltively complex.ldf files (such s the externl code-execution exmple previously mentioned) re beyond the scope of this document. This EE-Note pplies to ll SHARC processors. The first step towrd gining n understnding of the.ldf file is to understnd the mkeup of the files involved in building processor executble (.DXE). Source Files Source files contin code written in C or ssembly. The first step towrd producing n executble is to compile nd/or ssemble these source files. The ssembler outputs files clled object files. (The compiler outputs ssembly files tht re then fed to the ssembler.) The VisulDSP++ ssembler produces object files tht hve.doj extension. Typiclly, Object Files these object files re output to the ~/YourProject/debug directory. Object files produced by the compiler nd ssembler re divided into vrious sections (referred to s object sections). Ech of these objects section holds prticulr type of compiled source code. For exmple, n object section my hold progrm opcodes (48-bits wide) or dt such s vribles (16, 32, or 40 bits wide). Some object sections lso hold informtion not pertinent to this discussion (since the informtion is not importnt to the user, such s debug-informtion, nd so on). Ech object section hs different nme tht is specified in the source code. Depending on whether the source is C or ssembly, different convention is used to specify the object section nme. Copyright 2002-2007, 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.
In n ssembly source, the code nd/or dt is plced below the.section segment_nme. Refer to the following exmple..section /dm seg_dmd.var foo[3];.section /pm seg_pmco r0 = 0x1234; r1 = 0x4567; r2 = r1 + r2; In the exmple bove, the seg_dmd object section would contin the foo rry, nd the three lines of code would be locted in the seg_pmco object section. In C source file, the progrmmer would use the section("segment_nme") directive, for exmple: section("ext_dt") int temp; section("ext_code") void func1(void) int x = 1; void func2(void) int i = 0; When the C file bove is compiled, the code generted from func1 will be stored in its own seprte object section of the of the.doj file nmed ext_code. The temp vrible will reside seprtely in ext_dt. So wht hppens to func2? If n object section nme is not specified, the compiler will use defult nme. In this cse, the object file would hold the code from func2 in n object section for progrm code with defult object section nme of seg_pmco. For the list of defult object section nmes, refer to the VisulDSP++ C/C++ Compiler nd Librry Mnul for SHARC Processors. There re no defult object section nmes for ssembly source files, nd.section/ sttements must be used. The wy tht these object sections nd object section nmes relte to code plcement in memory will be illustrted lter. Executble Files Once the source files hve been ssembled nd/or compiled into their respective object files, the linker combines these object files into one integrted executble, which hs.dxe extension. Similr to object files, n executble is split into different sections. All.DXE files produced by the VisulDSP++ linker dhere to the splitting rules s dictted by the ELF (Executble nd Linking Formt) file stndrd. These sections re referred to s DXE sections, nd hve DXE section nmes. DXE section nmes re completely independent of object section nmes. They exist in different nmespces, which mens tht DXE section nme cn be identicl to n object section nme. (Unfortuntely, in most distributed exmples, this is the cse. Using the sme nme for different items, lthough vlid, is poor progrmming style nd mkes the.ldf file look confusing.) The.DXE file is not loded into the processor, nd it is not burned into n EPROM. A.DXE file contins extr informtion (in ddition to the rw code nd dt from the object files), which is used by down-strem tools such s the loder (to populte n EPROM) nd the debugger (to simulte or emulte processor) in locting code to the processor..ldf Files vs. the Other Files The linker s job is resonbly strightforwrd. Bsed on commnds in the.ldf file, the linker collects the object sections from the object files nd combines them into single executble Understnding nd Using Linker Description Files (LDFs) on SHARC (EE-069) Pge 2 of 7
(.DXE) file using the memory model declred in the.ldf file. Let s look t n exmple.ldf file to understnd how this process works. We will exmine n.ldf file used to link ssembly-only source code. This is the simplest type of.ldf file, becuse C source code must be supported in the.ldf file with dditionl informtion bout the C run-time heder nd other librry informtion. The following section of this document discusses test.ldf (Listing 1). Ech section below includes number tht mtches it to corresponding portion of the.ldf file, identified with [#:] djcent to the.ldf feture being described. [1:] Memory The first thing of interest in the.ldf file is the Memory commnd, which defines the memory model. It informs the linker s to the vilble memory spces nd gives them nmes clled memory spce nmes. It s importnt to understnd tht the memory spce nmes declred here hve bsolutely no reltion to DXE object section nmes. The next notble feture of the.ldf file is used to bind (link) ll of these vrious sections nd nme spces together. [2:] Sections As mentioned, the second nd perhps most importnt piece of the.ldf file is the Sections portion, where the linker does the rel work. Bsed on three rguments to the Sections commnd, the linker tkes object sections s inputs, plces them in DXE section, nd then mps ech DXE section to the specified memory spce. In test.ldf, for exmple, the first line in the Sections commnd tkes the object section nmed seg_rth creted in min.doj, plces it in the DXE section nmed seg_rth, nd mps tht DXE section to the seg_rth memory spce. When the.dxe file creted by the linker is loded into the debugger or mde redy for EPROM vi the loder, ech of these downstrem utilities will know where the different DXE sections reside on-chip. [3:] $OBJECTS nd $COMMAND_LINE_OBJECTS A minor thing to note is tht we hve used $OBJECTS interchngebly with $COMMAND_LINE_OBJECTS. This is becuse the $ symbol in the.ldf file is mcro definition. It works much like #define sttement in C. These mcro definitions, though unnecessry in this exmple, re quite useful when you hve multiple object files. For instnce, there re two options if you wnt to plce ll of the code portions (object sections) of multiple files into the sme memory section. The first wy is to explicitly list ech object file, s follows: seg_pmco INPUT_SECTIONS( min.doj(seg_pmco) config.doj(seg_pmco) dsp.doj(seg_pmco) ) > seg_pmco The second wy is to define mcro (s follows) $OBJECTS = min.doj, config.doj, dsp.doj; nd plce the mcro in the INPUT_SECTIONS portion of the.ldf file s follows: seg_pmco INPUT_SECTIONS( $OBJECTS (seg_pmco) ) > seg_pmco Both of these syntxes re equivlent. They cuse the linker to go through ll of the object files listed, nd if ny object sections nmed seg_pmco re found, it puts them into the sme DXE section (here seg_pmco ), nd then links Understnding nd Using Linker Description Files (LDFs) on SHARC (EE-069) Pge 3 of 7
tht DXE section to the memory spce clled seg_pmco. Ech processor in multiprocessor system would hve its own Processor section (processor p0, p1, nd so on). Ech processor would lso hve its own Sections declrtion. [4:] LINK_AGAINST() The LINK_AGAINST()commnd is used by the linker in multiprocessor sitution. It is used when there is shred memory resource tht holds code nd/or dt. The use of this commnd is beyond the scope of this document, but is discussed in VisulDSP++ Linker nd Utilities Mnul. [5:] OUTPUT() The finl thing of interest in the.ldf file is the OUTPUT() commnd. This specifies the nme of the produced.dxe file. If the $COMMAND_LINE_OUTPUT_FILE mcro is used s n rgument to the OUTPUT() commnd; the linker will nme the.dxe file bsed on the VisulDSP++ project nme. Alterntively, you cn enter the explicit filenme: OUTPUT(myfile.dxe). ARCHITECTURE(ADSP-21368) SEARCH_DIR( $ADI_DSP/213xx/lib ) [3:] $OBJECTS = $COMMAND_LINE_OBJECTS; [1:] MEMORY seg_rth TYPE(PM RAM) START(0x00090000) END(0x000900ff) WIDTH(48) seg_init TYPE(PM RAM) START(0x00090100) END(0x000901ff) WIDTH(48) seg_int_code TYPE(PM RAM) START(0x00090200) END(0x000902CF) WIDTH(48) seg_pmco TYPE(PM RAM) START(0x000902D0) END(0x00093FFF) WIDTH(48) seg_pmd TYPE(PM RAM) START(0x000C0000) END(0x000c1FFF) WIDTH(32) seg_dmd TYPE(DM RAM) START(0x000b8000) END(0x000bbfff) WIDTH(32) seg_stk TYPE(DM RAM) START(0x000bc000) END(0x000bdfff) WIDTH(32) seg_hep TYPE(DM RAM) START(0x000e0000) END(0x000e1fff) WIDTH(32) seg_srm TYPE(DM RAM) START(0x00200000) END(0x0027ffff) WIDTH(8) PROCESSOR p0 [4:] LINK_AGAINST( $COMMAND_LINE_OUTPUT_DIRECTORY\P1.dxe) [5:] OUTPUT($COMMAND_LINE_OUTPUT_DIRECTORY\P0.dxe ) [2:] SECTIONS //.text output section seg_rth INPUT_SECTIONS( $OBJECTS(seg_rth) $LIBRARIES(seg_rth)) > seg_rth seg_init ldf_seginit_spce =. ; INPUT_SECTIONS( $OBJECTS(seg_init) $LIBRARIES(seg_init)) > seg_init seg_int_code INPUT_SECTIONS( $OBJECTS(seg_int_code) $LIBRARIES(seg_int_code)) Understnding nd Using Linker Description Files (LDFs) on SHARC (EE-069) Pge 4 of 7
> seg_int_code seg_pmco INPUT_SECTIONS( $OBJECTS(seg_pmco) $LIBRARIES(seg_pmco)) > seg_pmco seg_pmd INPUT_SECTIONS( $OBJECTS(seg_pmd) $LIBRARIES(seg_pmd)) > seg_pmd.bss ZERO_INIT INPUT_SECTIONS( $OBJECTS(.bss) $LIBRARIES(.bss)) > seg_dmd seg_dmd INPUT_SECTIONS( $OBJECTS(seg_dmd) $LIBRARIES(seg_dmd)) > seg_dmd Stckseg // llocte stck for the ppliction ldf_stck_spce =.; ldf_stck_length = MEMORY_SIZEOF(seg_stk); > seg_stk hep // llocte hep for the ppliction ldf_hep_spce =.; ldf_hep_length = MEMORY_SIZEOF(seg_hep); ldf_hep_end = ldf_hep_spce + ldf_hep_length - 1; > seg_hep seg_srm INPUT_SECTIONS($OBJECTS(seg_srm) $LIBRARIES(seg_srm)) PACKING(5 B0 B0 B0 B4 B0 B0 B0 B0 B3 B0 B0 B0 B0 B2 B0 B0 B0 B0 B1 B0) > seg_srm Listing 1. test.ldf Understnding nd Using Linker Description Files (LDFs) on SHARC (EE-069) Pge 5 of 7
Expert Linker Utility The Expert Linker utility vilble with the ltest VisulDSP++ tools simplifies the process of the.ldf file genertion. The Expert Linker is grphicl tool tht simplifies complex tsks such s memory-mp mnipultion, code nd dt plcement, overly nd shred memory cretion, nd C stck/hep djustment. It enbles new users to tke immedite dvntge of the powerful.ldf formt flexibility by providing visuliztion cpbility. Expert Linker llows users to: Define trget processor s memory mp Plce project s object sections into tht memory mp View how much of the stck or hep hs been used fter running the DSP progrm The.LDF file for the user ppliction cn be creted by selecting the following menu item from VisulDSP++: Tools -> Expert Linker -> Crete LDF Figure 1 shows the.ldf file generted using the Expert Linker. Figure 1. Expert Linker GUI. Use the Expert Linker to drg nd drop the object sections from the input section to the output memory section. After running the ppliction, it shows the mount of the hep memory nd stck memory utilized by the user ppliction. This informtion cn be used to djust the hep nd stck memory size. The unused memory sections cn be used for plcing code or dt, providing efficient use of the processor s memory. For detils on Expert Linker fetures, refer to the VisulDSP++ Linker nd Utilities mnul nd to online Help. The Expert Linker supports.ldf file genertion for both single-processor nd multiprocessor systems. See Using the Expert Linker for Multiprocessor LDFs (EE-202) for detils. Understnding nd Using Linker Description Files (LDFs) on SHARC (EE-069) Pge 6 of 7
Summry This EE-Note discusses the vrious sections nd commnds used in the.ldf file. It provides n overview of the Expert Linker utility in VisulDSP++. It lso explins how code nd dt cn be plced in different memory sections of the user ppliction. The exmple code ssocited with this EE-Note demonstrtes how code cn be locted in specific memory sections either on per-object file bsis or vi the SECTION () directive shown bove. References [1] VisulDSP++ 4.5 Linker nd Utilities Mnul, Revision 2.0, April 2006. Anlog Devices, Inc. [2] VisulDSP++ 4.5 C/C++ Compiler nd Librry Mnul for SHARC Processors, Revision 6.0, April 2006. Anlog Devices, Inc. [3] Using the Expert Linker for Multiprocessor LDFs (EE-202), Revision 2.0, September 2004, Anlog Devices Inc. Document History Revision Rev 2 Jnury 17, 2007 by C. Prbkrn nd Jeynthi Jegdeesn Rev 1 Jnury 5, 2002 by Mtt Wlsh Description Generlized the EE-Note for ll SHARC Processors. Initil Relese. Understnding nd Using Linker Description Files (LDFs) on SHARC (EE-069) Pge 7 of 7