lA8 LmbeddedWorkbench

Lo
ALolllc 1rueS1uulC
mlgraLlon gulde

CopyrlghL



ll | a g e


CC?8lCP1 nC1lCL
CopyrlghL 2010-2011 ALolllc A8. All rlghLs reserved. no parL of Lhls documenL may be reproduced
or dlsLrlbuLed wlLhouL Lhe prlor wrlLLen consenL of ALolllc A8. 1he sofLware producL descrlbed ln Lhls
documenL ls furnlshed under a llcense and may only be used or copled accordlng Lo Lhe Lerms of
such a llcense.
18AuLMA8k
ALolllc and !"#$$%& ()*+,(-./0 and Lhe ALolllc logoLype are Lrademarks or reglsLered Lrademarks
owned by ALolllc. LCLlSL` ls a reglsLered Lrademark of Lhe Lcllpse foundaLlon. lA8 SysLems and lA8
LmbeddedWorkbench are reglsLered Lrademarks of lA8 SysLems. All oLher producL names are
Lrademarks or reglsLered Lrademarks of Lhelr respecLlve owners.
ulSCLAlML8
1he lnformaLlon ln Lhls documenL ls sub[ecL Lo change wlLhouL noLlce and does noL represenL a
commlLmenL of ALolllc A8. 1he lnformaLlon conLalned ln Lhls documenL ls assumed Lo be accuraLe,
buL ALolllc assumes no responslblllLy for any errors or omlsslons. ln no evenL shall ALolllc A8, lLs
employees, lLs conLracLors, or Lhe auLhors of Lhls documenL be llable for any Lype of damage, losses,
cosLs, charges, clalms, demands, clalm for losL proflLs, fees, or expenses of any naLure or klnd.
uCCuMLn1 luLn1lllCA1lCn
ASW-lAMC !anuary 2011
8LvlSlCn
llrsL verslon CcLober 2010
Second verslon !anuary 2011





Ato|||c A8
Sclence ark
C[uLerlgaLan 9
SL- 333 18 !nkplng
Sweden
+46 (0) 36 19 60 30
www.ato|||c.com


LlsL of ConLenLs



lll | a g e

Contents
Introduct|on............................................................................. 1
Who Should 8ead 1hls Culde ..................................................................... 1
uocumenL ConvenLlons .............................................................................. 1
1ypographlc ConvenLlons ........................................................................... 2
SLC1ICN 1: M|grat|on Dec|s|ons ............................................... 1
Why mlgraLe? ............................................................................................. 2
When Lo MlgraLe? ...................................................................................... 3
WhaL Lo mlgraLe and Lhe lmpllcaLlons of mlgraLlon?................................. 4
ro[ecL and bulld conLrol ................................................................................... 4
lnfrasLrucLure and work-flow ............................................................................ 4
AppllcaLlon source and flrmware ...................................................................... 4
1hlrd parLy C/S and llbrarles ............................................................................. 3
8e-valldaLlon ..................................................................................................... 3
Pow can mlgraLlon be made easler? .......................................................... 7
AuLomaLed ro[ecL creaLlon .............................................................................. 7
CMSlS - CorLex MlcroconLroller SofLware lnLerface SLandard ........................ 7
MlgraLlon of Legacy llrmware .......................................................................... 8
A8l Compllance ................................................................................................. 8
SLC1ICN 2: Start|ng the M|grat|on w|th Ato|||c 1rueS1UDIC1 . 10
8efore you sLarL ........................................................................................ 11
Workspaces & pro[ecLs ................................................................................... 11
CreaLlng a new pro[ecL ............................................................................. 13
Conflgurlng Lhe pro[ecL ............................................................................ 17
8ulldlng Lhe pro[ecL .................................................................................. 21
8ulld ................................................................................................................ 21
8ebulld all ........................................................................................................ 21
lmporLlng Source llles .............................................................................. 23

LlsL of conLenLs



lv | a g e

uslng flles ln an exLernal locaLlon ................................................................... 23
uslng dlrecLorles ln an exLernal locaLlon ........................................................ 24
SLC1ICN 3: M|grat|ng Source I||es ......................................... 27
C/C++ Source changes .............................................................................. 28
1he re-processor ........................................................................................... 28
Language exLenslons ....................................................................................... 30
lnllne assembler ............................................................................... 31
lnllne funcLlons ................................................................................ 31
8AM based funcLlons ....................................................................... 31
lnLerrupL and excepLlon funcLlons ................................................... 32
nesLed lnLerrupL funcLlons .............................................................. 32
non-reLurnlng funcLlons .................................................................. 32
A8M speclflc funcLlons................................................................... 33
Weak funcLlons/daLa ....................................................................... 33
8ooL funcLlons and unreferenced daLa ............................................ 33
acked uaLa ..................................................................................... 34
AllgnmenL of daLa ............................................................................ 34
Lndlan seLLlng of daLa ...................................................................... 34
non-lnlLlallsed daLa .......................................................................... 33
LocaLlon conLrol of daLa ................................................................... 33
8ullL-ln funcLlons ............................................................................................. 33
Assembler source changes ....................................................................... 36
SLarLup code ............................................................................................. 38
SLC1ICN 4: Deta||ed ro[ect 8u||d Contro| ............................. 40
MlgraLlng 8ulld flles .................................................................................. 41
Compller seLup and conLrol ...................................................................... 42
CpLlmlzaLlon .................................................................................................... 42
lmplemenLaLlon Speclflc CpLlons .................................................................... 43
Llnk managemenL ..................................................................................... 48

LlsL of conLenLs



v | a g e

Llnker ScrlpL/Command llles .......................................................................... 48
Llbrary managemenL ................................................................................ 31
SLandard Llbrarles ........................................................................................... 31
Llbrary CreaLlon and ManagemenL ................................................................. 33
MlgraLlng 3rd arLy flles ........................................................................... 33
vendor supplled porLs ..................................................................................... 33
Source level porLlng ........................................................................................ 33
8lnary level porLlng ......................................................................................... 33
CreaLlng a blnary lnLerface .............................................................................. 36
luncLlon call/reLurn ......................................................................... 36
use Lhe compller Lo creaLe an lnLerface for you ............................. 37

LlsL of llgures



lv | a g e

llgures
No tab|e of f|gures entr|es found.

LlsL of 1ables



v | a g e

1ables
1able 1 - lA8 LmbeddedWorkbench Speclflc redeflned Symbols ............ 29
1able 2 - Cross-assembler dlfferences ......................................................... 37
1able 3 - SLarLup Code symbols.................................................................... 39
1able 4 - Compller opLlon cross-reference .................................................. 47
1able 3 - SLandard Llbrarles ......................................................................... 33


lnLroducLlon



1 | a g e

IN1kCDUC1ICN
Welcome Lo Lhe !"#$$%& ()*+,(-./01 MlgraLlon Culde. 1he purpose of Lhls
documenL ls Lo help you Lo mlgraLe an lA8 LmbeddedWorkbench pro[ecL Lo
!"#$$%& ()*+,(-./01.

WPC SPCuLu 8LAu 1PlS CuluL
1hls documenL ls prlmarlly lnLended for embedded sysLems developers and pro[ecL
managers who wanL Lo undersLand Lhe process of mlgraLlng a pro[ecL (exlsLlng or new)
from uslng Lhe lA8 LmbeddedWorkbench C/C++ compller Lo !"#$$%& ()*+,(-./01 for Lhe
A8M processors.

uCCuMLn1 CCnvLn1lCnS
1he LexL ln Lhls documenL ls formaLLed Lo ease undersLandlng and provlde clear and
sLrucLured lnformaLlon on Lhe Loplcs covered


lnLroducLlon



2 | a g e

1?CC8APlC CCnvLn1lCnS
1hls documenL has Lhe followlng Lypographlc convenLlons:
Sty|e Use
Computer keyboard commands or Source code.
8o|d names of menus, menu commands, buLLons and dlalog
boxes LhaL appear on screen.
!"#$!% A cross reference ln Lhls user gulde or Lo anoLher gulde.
!"#$$%& ()*+,"*2%#1
ALolllc company producLs.


ldenLlfles lnsLrucLlons speclflc Lo Lhe graphlcal user
lnLerface.

ldenLlfles lnsLrucLlons speclflc Lo Lhe command llne
lnLerface.

ldenLlfles help Llps and programmlng hlnLs.

ldenLlfles a cauLlon.
1able 1 - 1ypographlcal convenLlons

lnLroducLlon



1 | a g e



SLC1ICN 1: MIGkA1ICN DLCISICNS
1hls documenL has been creaLed Lo enable developmenL Leams Lo undersLand Lhe
need for, Lhe mechanlsms, and Lhe lmpllcaLlons of mlgraLlng from one developmenL
Loolchaln Lo anoLher for a glven processor or processor famlly.
1he example used LhroughouL Lhe process ls for mlgraLlon from Lhe lA8 SysLems
developmenL Loolchaln Lo Lhe !"#$$%& ()*+,(-./01 luL for A8M processors. Powever
Lhe prlnclples wlll remaln consLanL across processor famllles and developmenL Lool
vendors.
1he reader should refer Lo Lhe Cnu C/C++ compller documenLaLlon avallable wlLh
!"#$$%& ()*+,(-./01 for deLalled documenLaLlon on Lhe usage and exLenslons
supporLed by Lhe compller Loolchaln.
ln addlLlon, Lhe AppllcaLlon 8lnary lnLerface (A8l) documenL ls avallable dlrecLly from
A8M LLd. aL Lhe followlng locaLlon: www.arm.com. llnally, Lhe user should cross-
reference Lhls lnformaLlon wlLh LhaL provlded by Lhelr currenL compller vendor (lA8
SysLems ln Lhls example).
1hls secLlon covers Lhe hlgh-level quesLlons whlch need Lo be addressed before
embarklng on a pro[ecL mlgraLlon:
Why mlgraLe?
When Lo mlgraLe?
WhaL Lo mlgraLe and Lhe lmpllcaLlons of mlgraLlon?
Pow can mlgraLlon be made easler?


MlgraLlon declslons



2 | a g e

Wn MIGkA1L?
MlgraLlon Lo a new developmenL Loolchaln has Lo be drlven by need, Lhe need for beLLer
performance (of Lhe embedded code), Lhe need for sLandards compllance, Lhe need for a
beLLer developmenL workflow uslng hlgher funcLlonallLy and more lnLegraLed
developmenL envlronmenLs and/or Lhe need for a beLLer supporL model from Lhe Lools
vendor.
1he cholce may be largely drlven by englneerlng or commerclal concerns, buL ldeally
should provlde beneflLs ln boLh areas. As an example, Lhe beneflLs of Lhe !"#$$%&
()*+,(-./01 luL over lLs compeLlLors could be summarlzed as:
Cost: 1he !"#$$%& ()*+,(-./01 producL ls parLly based on open-source
componenLs LhaL have been exLended Lo maLch and surpass Lhe feaLure-seL ln
mosL oLher commerclal offerlngs. 8y reuslng some open-source componenLs, Lhe
producL can be offered aL a subsLanLlally lower prlce Lhan many oLher vendors.
erformance: 1he Cnu C/C++ compller provldes a world class compller
developmenL Loolchaln, enhanced and malnLalned by Lhousands of developers
and many companles worldwlde. ln recenL years, lL has become Lhe de-facLo
sLandard Loolchaln for compller research, furLher enhanclng lLs capablllLles ln
Lerms of opLlmlzaLlon and processor supporL.
Standards: 1he Cnu C/C++ compller supporLs C and C++ developmenL wlLh full
supporL for boLh languages along wlLh runLlme llbrarles for boLh 'bare-meLal'
(where Lhe runLlme sysLem runs dlrecLly on Lhe processor) or Llnux user-mode
(where Lhe runLlme sysLem lnLeracLs wlLh Lhe Llnux kernel vla sysLem calls).
Workf|ow: 1he !"#$$%& ()*+,(-./01 luL provldes a modern and hlghly lnLegraLed
developmenL envlronmenL whlch dlrecLly supporLs Lhe use of advanced workflow
Lools such as verslon conLrol, bug Lracklng, code revlew, code analysls and
dlsLrlbuLed Lask-based developmenL, along wlLh Lallored conLrol for pro[ecL and
bulld conLrol and a fully lnLegraLed debugger.
Support Mode|: 1he !"#$$%& ()*+,(-./01 luL comes ln a varleLy of packages
enabllng cusLomers Lo selecL Lhe feaLures/prlce model besL sulLed Lo Lhelr
developmenL needs. As Lhe underlylng compller Loolchaln ls based on Lhe Cnu
C/C++ compller, Lhere ls no worry abouL a 'proprleLary' Loolchaln becomlng ouL of
daLe, or unavallable. 1he same goes for Lhe !"#$$%& ()*+,(-./01 luL, as lL ls
based on Lhe open Lcllpse framework.


MlgraLlon declslons



3 | a g e

WnLN 1C MIGkA1L?
Cnce Lhe declslon has been made Lo mlgraLe Lo a new Loolchaln, Lhe mlgraLlon has Lo be
planned accordlng Lo Lhe needs of Lhe organlzaLlon. 1yplcally Lhere are Lhree scenarlos for
mlgraLlon:
AL Lhe sLarL of a new pro[ecL
arallel Lo a runnlng pro[ecL
ln a falllng pro[ecL Lo brlng lL back on llne
erhaps Lhe slmplesL Llme Lo perform mlgraLlon ls aL Lhe sLarL of a new pro[ecL as Lhe
efforL can be facLored lnLo Lhe pro[ecL plan, wlLh resources and Llme belng allocaLed
before Lhe pro[ecL has sLarLed.
Powever, provlded LhaL Lhe efforL can be reasonably assessed, and Lhe beneflL from
mlgraLlng can be measured (ln performance, developmenL Llme, cosL or oLher Lerms),
Lhere ls no reason why mlgraLlon can'L happen whlle a pro[ecL ls ln progress.
LlLher resources can be allocaLed Lo do mlgraLlon seLup Lasks whlle Lhe resL of Lhe Leam
geLs on wlLh oLher areas of developmenL, or Lhe whole Leam can focus on Lhe mlgraLlon Lo
enable a rapld LranslLlon.
Where companles are uslng verslon conLrol sysLems, lL makes sense Lo 'branch' Lhe
exlsLlng pro[ecL Lo allow for mlgraLlon changes Lo be conLalned ln one developmenL flow,
allowlng any oLher code changes on Lhe orlglnal code base Lo be merged ln as requlred
laLer. ln facL, as Lhe !"#$$%& ()*+,(-./01 luL fully supporLs verslon conLrol sysLem
lnLegraLlon, lL faclllLaLes Lhls mode of operaLlon.

MlgraLlon declslons



4 | a g e

WnA1 1C MIGkA1L AND 1nL IMLICA1ICNS
CI MIGkA1ICN?
1he !"#$$%& ()*+,(-./01 luL provldes a wealLh of faclllLles on Lop of Lhe baslc necesslLles
such as Lhe compller Loolchaln, debugger and edlLor. lL ls enLlrely posslble Lo phase Lhe
mlgraLlon, Laklng advanLage of cerLaln feaLures of Lhe luL when approprlaLe. 1he key
areas Lo conslder are descrlbed below.
1he remalnder of Lhe documenL wlll examlne some of Lhe maln lssues ralsed.

kCILC1 AND 8UILD CCN1kCL
1he !"#$$%& ()*+,(-./01 luL provldes Lhe ablllLy Lo auLo-generaLe pro[ecLs for Lhe
supporLed embedded processors. 1hese auLo-generaLed pro[ecLs provlde a framework ln
Lerms of descrlblng Lhe source flles and llbrarles LhaL make up Lhe pro[ecL, and also
provlde a way Lo generaLe Lhe scrlpLs Lo auLomaLe Lhe bulld process.

INIkAS1kUC1UkL AND WCkk-ILCW
1he !"#$$%& ()*+,(-./01 luL provldes a compleLe pro[ecL and bulld lnfrasLrucLure for Lhe
Cnu compller Loolchaln, Lo lnclude Cul level supporL for conflgurlng LargeL (processor)
speclflc opLlons.
lL wlll auLo-generaLe bulld scrlpLs and llnker command flles whlch may be conLrolled
enLlrely Lhrough Lhe Cul, or edlLed by Lhe user. 1hls ls however noL mandaLory, and so
cusLomers mlgraLlng legacy pro[ecLs whlch have make flles already may wlsh Lo conLlnue
Lo use Lhem.
1he luL provldes a mechanlsm Lo swlLch Lo make flle use, and even provldes a make flle
edlLor. Slmllarly, lf verslon conLrol and/or bug Lracklng sysLems are belng used as
lndependenL appllcaLlons, Lhere ls no requlremenL Lo swlLch Lo uslng Lhem vla Lhe luL.
use of such Lools lnLegraLed wlLhln Lhe luL can be phased lnLo Lhe pro[ecL as requlred.

ALICA1ICN SCUkCL AND IIkMWAkL
1he ma[orlLy of appllcaLlon code ls usually wrlLLen ln a hlgh level language (C or C++), ln
facL uslng common compller exLenslons such as supporL for lnLerrupL servlce rouLlnes ln C,
and lL ls posslble Lo wrlLe nearly all of an appllcaLlon wlLhouL uslng assembler.

MlgraLlon declslons



3 | a g e

Lven assembler modules can be converLed relaLlvely slmply as mosL cross-assemblers
supporL slmllar funcLlonallLy, dlfferlng only sllghLly ln synLax (for example Lhe way LhaL
some addresslng modes are lndlcaLed, or LhaL macros and oLher hlgh level feaLures are
lmplemenLed), a slmple search and replace or perhaps wrlLlng a flle Lo map one symbol Lo
anoLher may sufflce.

1nIkD Ak1 C]S AND LI8kAkILS
ldeally, lL should be posslble Lo geL a porLed and supporLed verslon of your Lhlrd parLy CS
and/or llbrary for Lhe new Cnu compller Loolchaln. Make flles and bulld conLrol can Lhen
relaLlvely slmply be seLup ln Lhe luL.
AlLernaLlvely, some vendors sell source llcenses, wlLh Lhe CS/llbrary belng provlded ln a
porLable hlgh level language. ln LhaL case, Lhe work ls slmllar Lo LhaL whlch was already
underLaken when orlglnally buylng Lhe llcense - l.e. conflguraLlon, bulld and LesL. 1he flnal
posslblllLy ls LhaL Lhe CS/llbrary ls only avallable ln a blnary form, and no porL for Lhe Cnu
compller Loolchaln ls avallable.
lL ls sLlll feaslble Lo use a blnary llbrary as you are noL changlng Lhe underlylng processor
belng used, and for A8M archlLecLures Lhere ls a 'sLandard' AppllcaLlon 8lnary lnLerface
(A8l) deflned by A8M whlch mosL compllers LargeLlng A8M processors lmplemenL.
?ou may be forLunaLe and dlscover LhaL Lhe llbrarles you wlsh Lo llnk lnLo your new porLed
appllcaLlon wlll llnk and work wlLhouL lssue, however careful checklng of how Lhe Lwo
compller lmplemenLaLlons dlffer ln Lhelr A8l compllance may be requlred. ln Lhe case of
Lhere belng some dlfference, lL ls enLlrely posslble Lo wrlLe an A8l compllance wrapper (ln
assembler) whlch ensures LhaL Lhe LranslLlon from Cnu funcLlons Lo legacy code works
correcLly.


kL-VALIDA1ICN
Cne of Lhe ma[or Lasks of mlgraLlon ls re-valldaLlon. 1hls ls of course requlred, regardless
of wheLher any code changes have been performed or noL. 1he acL of movlng from one
compller Lo anoLher wlll mean LhaL sllghLly dlfferenL code wlll be generaLed, as no Lwo
compllers (or even verslons of a slngle compller) wlll generaLe Lhe same code, as each wlll
opLlmlze ln a dlfferenL way.
lL should be remembered LhaL Lhose pre-complled blnarles may have
dependencles on 'sLandard' llbrarles such as Lhe sLandard C llbrary, and on
compller speclflc llbrarles such as lnLrlnslc funcLlons whlch are lmpllclLly
referenced accordlng Lo Lhe code.
8eplaclng Lhe sLandard llbrarles wlLh Lhose provlded by Lhe Cnu Loolchaln
should presenL no problem, buL Lhe naLure of Lhe lnLrlnslc llbrarles may mean
LhaL you have Lo lnclude Lhem ln your flnal blnary ln order Lo make lL work.


MlgraLlon declslons



6 | a g e

lor new pro[ecLs, Lhe efforLs of consLrucLlng new LesLs should noL be any greaLer Lhan wlLh
Lhe legacy Lools, for exlsLlng pro[ecLs, Lhe LesLlng lnfrasLrucLure may also requlre porLlng
(dependlng on your appllcaLlon and sysLem), whlch wlll need Lo be facLored lnLo Lhe
overall mlgraLlon plan.

MlgraLlon declslons



7 | a g e

nCW CAN MIGkA1ICN 8L MADL LASILk?
llrsLly, Lhe assumpLlon ln Lhls documenL ls LhaL Lhe mlgraLlon does noL enLall swlLchlng
processor archlLecLures, and mosL probably LhaL lL ls based on Lhe same chlp vendor and
producL famlly.
ln Lhls case Lhere ls no addlLlonal learnlng curve regardlng Lhe processor, Lhe perlpherals
and lnLerfaces - l.e. Lhe sysLem deslgn problem has already been solved. ln such a case
Lhe Lask ls reduced Lo mlgraLlon of pro[ecL and bulld conLrol, appllcaLlon source flles and
flrmware.

AU1CMA1LD kCILC1 CkLA1ICN
1he !"#$$%& ()*+,(-./01 luL supporLs auLomaLed, wlzard-based pro[ecL generaLlon, whlch
allows rapld creaLlon of Lhe pro[ecL and bulld level conLrol requlred for any pro[ecL.
arL of Lhe pro[ecL generaLlon allows Lhe user Lo selecL Lhe devlce belng used (l.e. vendor
and chlp famlly), and wlll Lhen auLo-generaLe flrmware code compllanL Lo Lhe
processor/chlp vendor's flrmware llbrary Lo supporL Lhe devlce.


CMSIS - CCk1Lk MICkCCCN1kCLLLk SCI1WAkL
IN1LkIACL S1ANDAkD
A sLandard flrmware llbrary lnfrasLrucLure has been creaLed by A8M LLd. along wlLh
semlconducLor and Loolchaln vendors. 1he '()"*+ ,!%)(%(-")($$*) .(/"0#)* 1-"*)/#%*
."#-2#)2 (CMSlS) deflnes a hardware absLracLlon layer whlch ls avallable as a flrmware
llbrary coded Lo supporL compllaLlon by a number of compllers, lncludlng Lhe Cnu C/C++
compller and Lhe lA8 LmbeddedWorkbench C/C++ compller. ueLalls can be found on Lhe
A8M webslLe www.arm.com.
1he flrmware generaLed by Lhe !"#$$%& ()*+,(-./01 luL for Lhe A8M CorLex serles of
processors lncludes all low-level devlce conLrol vla Lhe CMSlS flrmware llbrary (lncludlng
sLarLup, lnLerrupL and excepLlon handlers) along wlLh chlp vendor supplled perlpheral
devlce drlvers.
As Lhe flrmware llbrary complles Lo a sLandard, and has been wrlLLen Lo supporL boLh Lhe
Cnu and lA8 LmbeddedWorkbench compllers (by uslng condlLlonal compllaLlon), users
lL ls recommended Lo use Lhe !"#$$%& ()*+,(-./01 pro[ecL generaLlon code,
wheLher a fully lnLegraLed bulld, or a makeflle based bulld ls belng used, as lL
greaLly slmpllfles Lhe creaLlon of a new pro[ecL and can be used as a
framework Lo compare Lo exlsLlng pro[ecLs and Lo pasLe legacy flles lnLo
where needed.


MlgraLlon declslons



8 | a g e

should flnd LhaL Lhey have a famlllar AppllcaLlon rogrammlng lnLerface (Al) Lo code
agalnsL, whlch reduces Lhe porLlng exerclse Lo one of Lunlng Lhe bulld conLrol and porLlng
appllcaLlon source flles.

MIGkA1ICN CI LLGAC IIkMWAkL
Lven when Lhe legacy pro[ecL has noL made use of Lhe chlp vendor's flrmware llbrary, Lhe
developer sLlll has opLlons on how Lo proceed:
1. 1he legacy flrmware can be porLed Lo Lhe Cnu C/C++ compller (lf a porL ls noL
already avallable).
2. lor A8M CorLex processors, Lhe legacy flrmware llbrary can be replaced wlLhln
Lhe mlgraLlon pro[ecL, by Lhe CMSlS flrmware llbrary, provldlng a hlgh quallLy and
porLable hardware absLracLlon layer whlch ls supporLed and easlly porLable.
1he lnlLlal lnvesLmenL ln flrmware porLlng may be slgnlflcanL, as flrmware ls by lLs naLure
aL Lhe closesL level Lo Lhe underlylng hardware. 1hls lmplles LhaL compller exLenslons have
been used Lo dlrecLly lnLeracL wlLh Lhe underlylng processor and perlpherals Lo generaLe
speclal funcLlons (lnLerrupLs), conLrol placemenL of daLa and code, conLrol processor mode
and lnlLlallzaLlon (uslng lnLrlnslc funcLlons) and conLrol memory mapped hardware devlces.


A8I CCMLIANCL
1he AppllcaLlon 8lnary lnLerface (A8l) deflnes lmplemenLaLlon speclflc deLalls of how a
glven Loolchaln supporLs a processor famlly. 1he A8l ls usually owned and malnLalned by
Lhe processor vendor or on Lhelr behalf by a nomlnaLed Lhlrd parLy.
A8M LLd. provlde and malnLaln a serles of A8l documenLs whlch cover all aspecLs requlred
for bulldlng code for Lhe A8M archlLecLures on varlous plaLforms (bare-meLal, Llnux and
moblle based). 1he A8l documenLaLlon seL can be downloaded from Lhe A8M webslLe aL
www.arm.com.
1hls documenL descrlbes mlgraLlon lssues relaLed Lo bare-meLal appllcaLlons, and
Lherefore only requlres an undersLandlng of a subseL of Lhe A8l documenLaLlon.

knowledge of Lhe A8l ls noL requlred lf mlgraLlon aL a C/C++ source level only
ls Lo be performed. 1he A8l deflnes Lhe low-level lnformaLlon requlred for
wrlLlng assembler funcLlons whlch are callable from C/C++, and requlred by
Loolchaln developers Lo enable lnLeroperablllLy beLween Loolchalns.
Where lL ls noL feaslble Lo use Lhe CMSlS flrmware llbrary, lL may be prudenL
Lo revlew Lhe code Lo undersLand how Lhe varlous hardware and compller
speclflc conLrol ls achleved.


MlgraLlon declslons



9 | a g e

1he A8l ls Lherefore lmporLanL aL Lwo levels:
Assembler Lo C/C++ lnLerface level (procedure call, reLurn and sLack frame
deflnlLlon)
Cb[ecL code formaL and manlpulaLlon
1he lA8 LmbeddedWorkbench and Cnu Loolchalns boLh supporL Lhe rocedure Call
SLandard for Lhe A8M archlLecLure (AACS), whlch means LhaL users can assume LhaL
funcLlons wrlLLen ln assembler for lA8 LmbeddedWorkbench based pro[ecLs can be
slmply mlgraLed Lo Cnu based pro[ecLs.
AL Lhe source level no changes wlll be requlred Lo change Lhe calllng/reLurn mechanlsm.
Powever changes may be requlred Lo conform Lo Lhe lnsLrucLlon synLax deflned by Lhe
Cnu cross-assembler.
AlLernaLlvely, A8l compllance means LhaL assembler source flles whlch have been cross-
assembled lnLo relocaLable ob[ecL flles uslng Lhe lA8 LmbeddedWorkbench Loolchaln (buL
noL yeL llnked), may be llnked wlLh flles bullL wlLh Lhe CCC Loolchaln successfully. 1hls ls
because boLh Loolchalns supporL Lhe same ob[ecL flle formaLs and relocaLlon Lypes.

SLarLlng mlgraLlon



10 | a g e



SLC1ICN 2: S1Ak1ING 1nL MIGkA1ICN
WI1n A1CLLIC 1kULS1UDIC3
1he slmplesL way Lo sLarL your mlgraLlon pro[ecL ls Lo use Lhe !"#$$%& ()*+,(-./0 Lo
generaLe a compleLe skeleLon pro[ecL for you, lncludlng all requlred bulld conLrol flles
(llnker scrlpLs and make flles lf requlred).
Cnce Lhls has been creaLed, Lhe exlsLlng source flles can be added lnLo Lhe pro[ecL, and
Lhe bulld conLrol flles ad[usLed as necessary.
1hls secLlon descrlbes Lhe process of creaLlng a skeleLon pro[ecL, lmporLlng source flles,
and performlng slmple pro[ecL conflguraLlon and bulld.
8efore you sLarL
CreaLlng a new pro[ecL
Conflgurlng Lhe pro[ecL
8ulldlng Lhe pro[ecL
lmporLlng source flles


SLarLlng mlgraLlon



11 | a g e

8LICkL CU S1Ak1
!"#$$%& ()*+,(-./01 ls bullL uslng Lhe LCLlSL` framework, and Lhus lnherlLs some
characLerlsLlcs LhaL may be unfamlllar Lo new users. 1he followlng secLlons ouLllne
lmporLanL lnformaLlon Lo users wlLhouL prevlous experlence wlLh LCLlSL`.
WCkkSACLS & kCILC1S
As !"#$$%& ()*+,(-./01 ls bullL uslng Lhe LCLlSL` framework, lL lnherlLs lLs pro[ecL and
workspace model. 1he baslc concepL ls ouLllned here:
A workspace conLalns pro[ecLs. 1echnlcally, a workspace ls a dlrecLory conLalnlng
pro[ecL dlrecLorles.
A pro[ecL conLalns flles. 1echnlcally, a pro[ecL ls a dlrecLory conLalnlng flles (LhaL
may be organlzed ln sub-dlrecLorles).
ro[ecL dlrecLorles cannoL be locaLed ouLslde a workspace dlrecLory, and pro[ecL
flles can generally noL be locaLed ouLslde lLs pro[ecL dlrecLory. ro[ecLs can
conLaln flles LhaL are locaLed ouLslde Lhe pro[ecL dlrecLory uslng llnks Lo flles and
dlrecLorles locaLed anywhere.
1here can be many workspaces on your compuLer aL varlous locaLlons ln Lhe flle
sysLem, and every workspace can conLaln many pro[ecLs.
Cnly one workspace can be acLlve aL Lhe same Llme, buL you can swlLch Lo
anoLher workspace aL any Llme.
?ou can access all pro[ecLs ln Lhe acLlve workspace aL Lhe same Llme, buL you
cannoL access pro[ecLs LhaL are locaLed ln a dlfferenL workspace.
SwlLchlng workspace ls a very qulck way of shlfLlng work from one seL of pro[ecLs
Lo anoLher seL of pro[ecLs.
ln pracLlce, Lhls creaLes a very sLrucLured hlerarchy of workspaces wlLh pro[ecLs LhaL
conLalns flles.

SLarLlng mlgraLlon



12 | a g e





ALolllc 1rueS1uulC
Workspace 1
(C:\!oe\Workspace)

ro[ecL A
ro[ecL 8
. . .


Workspace 2
(C:\CusLomer1)

ro[ecL C
ro[ecL u
. . .


Workspace 3
(x:\newro[ecLs)

ro[ecL L
ro[ecL l
. . .


CurrenLly lnacLlve
workspace
CurrenLly acLlve
workspace
CurrenLly lnacLlve
workspace
llgure 1 - Workspaces and pro[ecLs

SLarLlng mlgraLlon



13 | a g e

CkLA1ING A NLW kCILC1
!"#$$%& ()*+,(-./01 supporLs boLh managed and unmanaged pro[ecLs. Managed pro[ecLs
are compleLely handled by Lhe luL and can be conflgured uslng Cul seLLlngs, whereas
unmanaged pro[ecLs requlre a makeflle LhaL has Lo be malnLalned manually.
1o creaLe a new managed mode C pro[ecL, perform Lhe followlng sLeps:
1. SelecL Lhe I||e, New, C ro[ect menu command Lo sLarL Lhe !"#$$%& ()*+,(-./01
pro[ecL wlzard.

llgure 2 - SLarLlng Lhe pro[ecL wlzard
2. 1he C ro[ect conf|gurat|on page ls dlsplayed.

llgure 3 - C pro[ecL

SLarLlng mlgraLlon



14 | a g e

3. LnLer a ro[ect name (such as Myro[ecL") and selecL your embedded LargeL as
Lhe ro[ect type, and Ato|||c AkM 1oo|s as Lhe 1oo|cha|n. 1hen cllck Lhe Next
buLLon Lo dlsplay Lhe 1rueS1UDIC 8u||d Sett|ngs page.


llgure 4 - 1rueS1uulC 8ulld SeLLlngs

SLarLlng mlgraLlon



13 | a g e

4. ln Lhe 1rueS1UDIC 8u||d Sett|ngs page, conflgure Lhe hardware seLLlngs
accordlng Lo your LvaluaLlon board or cusLom board deslgn. lease noLe LhaL
your evaluaLlon board may have hardware swlLches for conflguraLlon of 8AM or
lLASP mode. 1hls seLLlng musL be Lhe same ln boLh Lhe pro[ecL wlzard and on
Lhe board. llnally, cllck Lhe Next buLLon Lo dlsplay Lhe 1rueS1UDIC Debug
Sett|ngs page.

llgure 3 - 1rueS1uulC uebug SeLLlngs
3. SelecL Lhe !1AC probe you use. Cllck Lhe Next buLLon Lo dlsplay Lhe Se|ect
Conf|gurat|ons page.

llgure 6 - SelecL ConflguraLlons

SLarLlng mlgraLlon



16 | a g e

6. ln Lhe Se|ect Conf|gurat|ons page, cllck on Lhe I|n|sh buLLon Lo generaLe a new C
pro[ecL.
7. A new managed mode C pro[ecL ls now creaLed. !"#$$%& ()*+,(-./01 generaLes
LargeL speclflc sample flles ln Lhe pro[ecL folder Lo slmpllfy developmenL.
8. Lxpand Lhe pro[ecL folder (such as Myro[ecL" ln Lhe example above) and Lhe
src folder ln Lhe ro[ect Lxp|orer docklng vlew.

llgure 7 - ro[ecL Lxplorer vlew

SLarLlng mlgraLlon



17 | a g e

CCNIIGUkING 1nL kCILC1
Managed mode pro[ecLs can be conflgured uslng dlalog boxes (unmanaged mode pro[ecLs
requlre a manually malnLalned makeflle). 1o conflgure a managed mode pro[ecL, perform
Lhe followlng sLeps:
1. SelecL Lhe ro[ect, ropert|es menu command.

llgure 8 - ro[ecL properLles menu command
2. 1he pro[ecL ropert|es dlalog box ls dlsplayed.

llgure 9 - ro[ecL properLles dlalog box

SLarLlng mlgraLlon



18 | a g e

3. Lxpand Lhe C]C++ 8u||d lLem ln Lhe Lree ln Lhe lefL column. 1hen selecL Lhe
Sett|ngs lLem Lo dlsplay Lhe bulld Sett|ngs panel.

llgure 10 - ro[ecL properLles dlalog box

SLarLlng mlgraLlon



19 | a g e

4. SelecL panels as deslred and conflgure Lhe command llne Lool opLlons uslng Lhe
Cul conLrols. Advanced users may wanL Lo enLer command llne opLlons
manually, and Lhls can be done ln Lhe M|sce||aneous panel for any Lool.

llgure 11 - ro[ecL properLles dlalog box

SLarLlng mlgraLlon



20 | a g e

3. Some pro[ecL seLLlngs are relevanL for boLh managed mode pro[ecLs and
unmanaged mode pro[ecLs. lor lnsLance Lhe selecLed mlcroconLroller or
evaluaLlon board may affecL boLh Lhe opLlons Lo Lhe compller durlng a managed
mode bulld and also how addlLlonal 1rueS1uulC componenLs, for lnsLance Lhe
Sl8-vlewer and debugger, wlll behave.
6. ro[ecL seLLlngs relevanL for boLh managed mode pro[ecLs and unmanaged mode
pro[ecLs are collecLed under Lhe 1arget Sett|ngs lLem.

llgure 12 - ro[ecL properLles dlalog box
7. When Lhe conflguraLlon ls compleLed, cllck Lhe Ck buLLon Lo accepL Lhe new
seLLlngs.

SLarLlng mlgraLlon



21 | a g e

8UILDING 1nL kCILC1
8y defaulL, !"#$$%& ()*+,(-./01 bullds Lhe pro[ecL auLomaLlcally whenever any flle ln Lhe
bulld dependency ls updaLed. 1hls feaLure can be Loggled uslng Lhe ro[ect, 8u||d
Automat|ca||y menu command. As auLomaLlc bulldlng ls swlLched on by defaulL, new
pro[ecLs creaLed by Lhe pro[ecL wlzard are bullL auLomaLlcally when Lhe pro[ecLs are
creaLed.

llgure 13 - 8ulld auLomaLlcally menu command

8UILD
1o manually Lrlgger a bulld, cllck on Lhe 8u||d Loolbar buLLon. Cnly Lhe flles LhaL need Lo be
recomplled wlll be rebullL.

llgure 14 - 8ulld Loolbar buLLon

kL8UILD ALL
1o force a rebulld all", perform Lhe followlng sLeps:
1. Cpen Lhe Conso|e vlew by cllcklng on lLs Lab LlLle. 1hls wlll ensure you can see Lhe
bulld process.

llgure 13 - 8ulld console

SLarLlng mlgraLlon



22 | a g e

2. SelecL Lhe ro[ect, C|ean. menu command. 1hls wlll deleLe Lhe ob[ecL flles and
appllcaLlon blnary flle from Lhe lasL rebulld and Lhus Lrlgger a compleLe rebulld of
Lhe pro[ecL (lf auLomaLlc bulld mode ls sLlll swlLched on).

llgure 16 - Clean pro[ecL
3. A dlalog box wlLh some opLlons ls dlsplayed. Cllck on Lhe Ck buLLon wlLhouL any
changes.

llgure 17 - Clean pro[ecL dlalog box
4. lf 8u||d automat|ca||y ls enabled, a rebulld ls sLarLed and Lhe assembler, compller
and llnker ouLpuL ls dlsplayed ln Lhe Conso|e vlew. lf lL ls noL, Lrlgger a bulld from
Lhe ro[ect menu or Lhe 8u||d Loolbar buLLon. A bulld ls Lhen sLarLed and Lhe
bulld ouLpuL ls dlsplayed ln Lhe Conso|e vlew.

llgure 18 - 8ulld console

SLarLlng mlgraLlon



23 | a g e

IMCk1ING SCUkCL IILLS
lmporLlng Lhe source flles from Lhe old luL lnLo !"#$$%& ()*+,(-./01 ls generally very
slmple. lL ls only a maLLer of copylng Lhe flles lnLo Lhe !"#$$%& ()*+,(-./01 pro[ecL source
dlrecLory.
lf you wanL Lo lnclude speclflc source code flles (or enLlre dlrecLorles conLalnlng many
source code flles) LhaL you wlsh Lo keep ln an exLernal locaLlon (l.e. ln a locaLlon oLher Lhan
ln Lhe pro[ecL dlrecLory Lree), Lhls can be faclllLaLed wlLh llnks Lo Lhe exLernal flle or
dlrecLory.

USING IILLS IN AN Lk1LkNAL LCCA1ICN
1o make Lhe pro[ecL complle flles locaLed ouLslde of Lhe pro[ecL dlrecLory, you need Lo
creaLe a llnk Lo lL ln Lhe pro[ecL. 1hls ls done by performlng Lhe followlng sLeps:
1. 8lghL-cllck on Lhe source dlrecLory ln Lhe ro[ect Lxp|orer vlew. SelecL Lhe New,
I||e menu command:

llgure 19 - CreaLlng a llnk Lo an exLernal flle

SLarLlng mlgraLlon



24 | a g e

2. Cllck on Lhe Advanced buLLon and selecL Lhe L|nk to f||e |n the f||e system
checkbox:

llgure 20 - CreaLlng a llnk Lo an exLernal flle
3. Cllck Lhe 8rowse buLLon and polnL ouL Lhe exLernal flle you wanL Lo complle as
parL of Lhe pro[ecL. A llnk Lo Lhe flle wlll be creaLed ln Lhe pro[ecL flle Lree, and
Lhe selecLed flle wlll be complled as parL of a pro[ecL bulld, even Lhough Lhe flle ls
noL physlcally sLored ln Lhe pro[ecL dlrecLory.

USING DIkLC1CkILS IN AN Lk1LkNAL LCCA1ICN
1o make Lhe pro[ecL complle many flles locaLed ln a dlrecLory ouLslde of Lhe pro[ecL
dlrecLory, you need Lo creaLe a llnk Lo lL ln Lhe pro[ecL. 1hls ls done by performlng Lhe
followlng sLeps:

SLarLlng mlgraLlon



23 | a g e

1. 8lghL-cllck on Lhe source dlrecLory ln Lhe ro[ect Lxp|orer vlew. SelecL Lhe New,
Io|der menu command:

llgure 21 - CreaLlng a llnk Lo an exLernal folder
2. Cllck on Lhe Advanced buLLon and selecL Lhe L|nk to fo|der |n the f||e system
checkbox:

llgure 22 - CreaLlng a llnk Lo an exLernal folder
3. Cllck Lhe 8rowse buLLon and polnL ouL Lhe exLernal folder you wanL Lo complle as
parL of Lhe pro[ecL. A llnk Lo Lhe folder wlll be creaLed ln Lhe pro[ecL flle Lree, and

SLarLlng mlgraLlon



26 | a g e

Lhe flles ln Lhe selecLed folder wlll be complled as parL of a pro[ecL bulld, even
Lhough Lhe flles are noL physlcally sLored ln Lhe pro[ecL dlrecLory.





27 | a g e




SLC1ICN 3: MIGkA1ING SCUkCL IILLS
Changes may be requlred Lo your source flles ln order for Lhem Lo be accepLed by Lhe
Cnu compller Loolchaln. 1hese changes can be due Lo a number of facLors as deLalled
ln Lhls secLlon:
C/C++ source level changes
Assembler source changes
SLarLup code



MlgraLlng source flles



28 | a g e

C]C++ SCUkCL CnANGLS
uependenL on your currenL lmplemenLaLlon of source code flles, you may or may noL need
Lo make modlflcaLlons Lo your source code flles.



1nL kL-kCCLSSCk
1he pre-processor runs before Lhe compller and ls used Lo do LexLual lnserLlon of header
flles, and deflnlLlons along wlLh macro expanslon. All C/C++ compller Loolchalns supporL
sLandard pre-processor dlrecLlves, buL also all compllers lmplemenL compller speclflc
deflnlLlons whlch allow you Lo wrlLe source flles whlch can be condlLlonally complled
accordlng Lo Lhe compller ln use.
1he recommended guldellnes are LhaL all errors should be LreaLed as such,
and serlous revlew of Lhe code should be underLaken Lo undersLand why Lhe
compller ls generaLlng an error. lL ls posslble LhaL lncorrecL code elLher '[usL
worked' before, or was never acLually exerclsed, so Lhe bug wenL unnoLlced.
Warnlngs are a maLLer of LasLe. Some companles requlre LhaL all appllcaLlons
complle wlLhouL warnlngs, buL lL ls llkely LhaL due Lo Lhe complexlLy of Lhe
code, Lhls ls noL achlevable.
lnsLead, lL ls worLh revlewlng all warnlngs, and where Lhe warnlngs do noL
represenL anyLhlng LhaL you can or are wllllng Lo flx, Lhey may be dlsabled
uslng one of Lhe many command llne opLlons.
lor example, your code may use a deprecaLed llbrary funcLlon. 1hls may be
lnLenLlonal and Lherefore you do noL wlsh your bulld logs Lo be polluLed wlLh
such messages. !udlclous use of command llne opLlons Lo reduce warnlngs
should mean LhaL any warnlngs whlch are generaLed can be easlly caughL,
revlewed and dealL wlLh approprlaLely.

8efore conslderlng any compller exLenslons, lL ls worLh noLlng LhaL Lhe level of
'compllance' Lo Lhe C and C++ sLandards varles beLween all compllers.
1he Cnu compller Loolchaln can clalm a hlgh level of sLandards compllance,
so Lhe chances of your legacy code uslng some feaLure of C or C++ whlch lL
doesn'L supporL ls remoLe.
1he Cnu compller documenLs supplled wlLh !"#$$%& ()*+,(-./01 deLall all
aspecLs of compllance, and are worLh checklng lf you are ln any doubL.
Much more llkely ls Lhe dlfferenL behavlour of Lhe compllers ln Lerms of
warnlngs and errors. ?ou may flnd code LhaL was complllng uslng Lhe lA8
Lools wlLh no errors, and perhaps few or no warnlngs, suddenly generaLes
many warnlngs, and even errors.
A loL of work as gone lnLo Lhe Cnu compller ln recenL years Lo lmprove Lhe
error and warnlng checks, whlch means LhaL lL may be qulLe a loL sLrlcLer Lhan
you have experlenced uslng lA8.


MlgraLlng source flles



29 | a g e

1hls allows code sharlng and ls Lyplcally employed ln wrlLlng llbrarles, operaLlng sysLems
and cross-plaLform sofLware. 1herefore lL ls lmporLanL Lo undersLand Lhe compller speclflc
pre-processor dlrecLlves and symbols for each compller Lo enable you Lo mlgraLe your
source cleanly.
Some compller exLenslons are also expressed uslng pre-processor dlrecLlves known as
'pragmas'. 1hese are however covered ln Lhe nexL secLlon whlch looks aL C and C++
language exLenslons.
Lach compller wlll have lLs own seL of compller speclflc symbols whlch may be used Lo
wrlLe code LhaL ls only complled by a speclflc Loolchaln, or even verslon of a Loolchaln. 1he
Cnu C/C++ compller documenLaLlon can be referenced Lo undersLand Lhe symbols
provlded, or alLernaLlvely Lhe pre-processor cpp can be run dlrecLly ln order Lo dlsplay Lhe
symbols for Lhe speclflc archlLecLure as below:
gcc -E -dM test.c

1he compller speclflc predeflned symbols for lA8 LmbeddedWorkbench are llsLed below
along wlLh Lhe equlvalenL/counLerparL symbols for Lhe Cnu compller (CCC).
noLe LhaL Lhe asLerlsk '*' values show where Lhere are mulLlple varlanLs of a symbol.
IAk Symbo| GCC Symbo| Comment
__8ulLu_nuM8L8__ __CnuC__,
__CnuC_MlnC8__,
__CnuC__A1CPLLvLL__
CCC provldes lndlvldual symbols for each level of Lhe
bulld number x.?.Z
__CC8L__ __A8M_A8CP_*__ ArchlLecLure varlanL belng bullL for
__A8Mvl__ __vl_l__ vl usage
__Cu_MCuL__ __1PuM8_ln1L8WC8k__
__Lhumb__
WheLher runnlng ln A8M, Lhumb or lnLerwork mode.
__embedded_cplusplus n/A CCC does noL have a slngle swlLch Lo resLrlcL supporL
of C++ feaLures. lnsLead lndlvldual feaLures (e.g.
811l) can be conLrolled uslng Lhe command llne.
__lA8_S?S1LMS_lCC__ __CnuC__ used Lo check Lhe compller Loolchaln ln use.
__lCC_A8M__ __arm__ Symbol denoLlng bulldlng for A8M
__Ll11LL_LnulAn__ __lLLL_Ll11LL_LnulAn,
__lLLL_8lC_LnulAn
Lndlan seLLlng for compllaLlon
__vL8__ __vL8SlCn__ SLrlng represenLaLlon of compller verslon x.y.z"
__1lu__ n/A 1argeL ldenLlfler, may be formed uslng oLher Cnu
symbols.
1able 1 - lA8 LmbeddedWorkbench Speclflc redeflned Symbols
Cenerally Lhe pre-deflned pre-processor symbols are used Lo conLrol compllaLlon of code
LhaL has been speclflcally wrlLLen for compllaLlon for more Lhan one pro[ecL, archlLecLure
or Loolchaln. ln such cases Lhe user can slmply selecL Lhe Cnu equlvalenL from Lhe Lable.

MlgraLlng source flles



30 | a g e

1he slmplesL way Lo deLermlne Lhe symbol(s) requlred ls Lo complle a LesL flle wlLh Lhe
requlred swlLches, buL Lo only run Lhe pre-processor, wlLh Lhe -dM seLLlng.
lor example:
gcc -E -dM -mthumb test.c

Wlll show Lhe __thumb__ symbol , whereas
gcc -E -dM test.c

wlll show Lhe __arm__ symbol (whlch ls Lhe defaulL).

LANGUAGL Lk1LNSICNS
All C/C++ compllers provlde language exLenslons Lo allow programmers Lo be more
producLlve, and Lo allow flne conLrol over Lhe code generaLlon process. Language
exLenslons can be classlfled ln Lhe followlng way:
Cenerlc exLenslons, noL LargeLed Lo any archlLecLure, buL provldlng some feaLure
seen Lo be mlsslng ln Lhe language (e.g. lnllne funcLlons ln C, macros LhaL can
reLurn values).
LxLenslons deslgned Lo allow Lhe programmer Lo conLrol Lhe placemenL of code
and/or daLa (e.g. deflnlLlon of Lhe ownlng secLlon).
LxLenslons Lo provlde speclal 'aLLrlbuLes' Lo funcLlons or daLa Lo change Lhe way
Lhey are LreaLed by Lhe compller (e.g. lnLerrupL handler funcLlons, packed
sLrucLures).
LxLenslons Lo provlde access Lo low level programmlng (ln llne assembler and
lnLrlnslc funcLlons).
1he exLenslons can be lmplemenLed as one or more of Lhe followlng:
keywords: very commonly used feaLures (such as lnllne funcLlons, or lnllne
assembler) warranL a keyword Lo enable clear code Lo be wrlLLen. 1he number of
exLended keywords ls usually resLrlcLed Lo llmlL 'namespace polluLlon'.
Attr|butes seL vla a slngle __aLLrlbuLe__ keyword: 1hls mechanlsm allows any
number of aLLrlbuLes Lo be applled Lo Lhe deflnlLlon of a daLa ob[ecL or funcLlon
uslng a slngle exLended keyword. 1hls ls Lhe recommended approach for uslng
Lhe Cnu C/C++ compller.
#pragma d|rect|ves: 1hese look llke pre-processor dlrecLlves, and have
lmplemenLaLlon speclflc behavlor. 1hey have Lhe advanLage of noL requlrlng any
new keywords Lo supporL exLended feaLures, buL suffer from Lhe facL LhaL Lhey
cannoL be used ln macros (llke oLher dlrecLlves), and usually Loggle a feaLure

MlgraLlng source flles



31 | a g e

on/off for Lhe resL of Lhe flle, or unLll anoLher #pragma dlrecLlve ls used Lo change
Lhe behavlor.
1he Cnu Compller Loolchaln provldes a large number of language exLenslons, allowlng for
generaLlon of powerful and hlghly LargeLed code. 1hls documenL does noL cover all Cnu
exLenslons, buL raLher examlnes Lhe exLenslon provlded by Lhe lA8 LmbeddedWorkbench
Loolchaln, and dlscusses how Lhey may be supporLed ln a flle Lo be complled uslng Lhe
Cnu Loolchaln.
lnLlnL ASSLM8LL8
IAk GCC
keyword: __asm __asm
ragma:
Syntax: __asm(<assembler>) __asm(<assembler>)
Comment: CCC supporLs a superseL of Lhe lA8 LmbeddedWorkbench funcLlonallLy. Allowlng for C level varlables Lo be
accessed from Lhe assembler. Advanced lnllne assembly ls beyond Lhe scope of Lhls documenL. lease see
Lhe Cnu compller manual for deLalls. noLe LhaL Cnu uses Lhe seml-colon characLer Lo dellmlL lnsLrucLlons,
whllsL Lhe lA8 LmbeddedWorkbench Loolchaln uses Lhe newllne characLer '\n'.

lnLlnL lunC1lCnS
IAk GCC
keyword: inline inline
ragma: inline inline
Syntax: #pragma inline
void foo (void)
{.}
inline void foo2 (void)
{...}
inline void foo2 (void)
{...}
Comment: CCC supporLs only Lhe keyword. 1he pragma exLenslon ls seen Lo be unnecessary, parLlcularly wlLh C99
supporL for lnllne funcLlons.

8AM 8ASLu lunC1lCnS
IAk GCC
keyword: __ramfunc __attribute__((section(NAME)))
ragma:
Syntax: __ramfunc void foo (void)
{...}
void foo (void)__attribute__ ((section
("RAMFNS")))
{...}
Comment: CCC does noL dlrecLly supporL 8AM funcLlons whlch are copled from 8CM Lo 8AM aL sLarLup. Powever Lhls

MlgraLlng source flles



32 | a g e

uses Lhe same mechanlsm as lnlLlallzed daLa, and so can be achleved by creaLlng a secLlon Lo conLaln 8AM
funcLlons (8AMlnS" ln Lhe example), and modlfylng Lhe sLarLup code and llnker scrlpL accordlngly.

ln1L88u1 Anu LxCL1lCn lunC1lCnS
IAk GCC
keyword: __swi
__fiq
__irq
__attribute__((interrupt(SWI)))
__attribute__((interrupt(FIQ)))
__attribute__((interrupt(IRQ)))
ragma: swi_number=NN
Syntax: __irq void foo (void)
{...}
void foo (void)__attribute__
((interrupt("IRQ")))
{...}
Comment: 1he lA8 LmbeddedWorkbench #pragma swl_number=n" ls requlred ln addlLlon Lo Lhe __swl keyword Lo
deflne Lhe SWl number used.

nLS1Lu ln1L88u1 lunC1lCnS
IAk GCC
keyword: __nested __attribute__((nesting))
ragma:
Syntax: __nested __irq
void foo (void)
{...}
void foo (void)__attribute__ ((nesting))
{...}
Comment: 1he Lagged funcLlon ls marked as non-reLurnlng.

nCn-8L1u8nlnC lunC1lCnS
IAk GCC
keyword: __noreturn __attribute__((noreturn))
ragma:
Syntax: __noreturn void foo (void)
{...}
void foo (void)__attribute__ ((noreturn))
{...}
Comment: 1he Lagged funcLlon ls marked as non-reLurnlng.



MlgraLlng source flles



33 | a g e

A8M SLClllC lunC1lCnS
IAk GCC
keyword: __arm
__thumb
__interwork
__attribute__((short_call))
__attribute__((long_call))
ragma: long_calls
Syntax: __arm void foo (void)
{...}

Comment: 1he command llne opLlons can be used Lo enable any of Lhe above aL a module level. no feaLure ls dlrecLly
added Lo supporL conLrol aL an lndlvldual funcLlon level ln CCC currenLly. Powever Lhe |ong_ca|| and
short_ca|| aLLrlbuLes can be used Lo achleve calllng Lo/from Lhumb funcLlons from code locaLed far away ln
Lhe address map.
WLAk lunC1lCnS/uA1A
IAk GCC
keyword: __weak __attribute__((weak))

ragma: weak Weak
Syntax: __weak int i;
__weak void foo (void)
{...}
int i __attribute__((weak));
void foo (void) __attribute__((weak))
{...}
Comment: 1he funcLlon/varlable ls deflned as weak, so wlll be overrldden aL llnk Llme by any non-weak funcLlon wlLh
Lhe same name. lf no non-weak funcLlon ls deflned, lL wlll be lncluded ln Lhe llnked lmage.

8CC1 lunC1lCnS Anu un8LlL8LnCLu uA1A
IAk GCC
keyword: __root __attribute__((used))

ragma: required
Syntax: #pragma required=i
int i;
__root void foo (void)
{...}
int i __attribute__((used));
void foo (void) __attribute__((used))
{...}
Comment: lA8 LmbeddedWorkbench uses Lwo separaLe mechanlsms Lo force Lhe lncluslon of unreferenced
code/daLa aL llnk Llme, CCC uses a slngle aLLrlbuLe.


MlgraLlng source flles



34 | a g e

ACkLu uA1A
IAk GCC
keyword: __packed __attribute__((packed))
ragma: pack Pack
Syntax: #pragma pack(4)
struct tag1
{
char a;
int b;
} mystruct1;
#pragma pack()

__packed struct tag1
{
char a;
int b;
} mystruct1;
#pragma pack(4)
struct tag
{
char a;
int b;
} mystruct;
#pragma pack()

struct tag1
{
char a;
int b __attribute__ ((packed));
} mystruct1;
Comment: CCC supporLs exLenslon uslng Lhe '__aLLrlbuLe__' keyword, and allows packlng on lndlvldual elemenLs of a
sLrucLure.

ALlCnMLn1 Cl uA1A
IAk GCC
keyword: __attribute__((aligned(N)))

ragma: data_alignment
Syntax: #pragma data_alignment(8)
int i;

int i __attribute__((aligned(8)));

Comment: 1he lA8 LmbeddedWorkbench Loolchaln only supporLs a #pragma, whereas CCC supporLs an __aLLrlbuLe__

LnulAn SL11lnC Cl uA1A
IAk GCC
keyword: __big_endian
__little_endian

ragma:
Syntax: __big_endian int i;



Comment: 1he Cnu Loolchaln only supporLs deflnlng Lhe endlan seLLlng aL a module level.


MlgraLlng source flles



33 | a g e

nCn-lnl1lALlSLu uA1A
IAk GCC
keyword: __no_init __attribute__((section(no_init)))
ragma:
Syntax: __no_init int i;

int i __attribute__((section(no_init)));

Comment: 1he varlable wlll noL be lnlLlallzed aL sLarLup as lL ls placed ln a separaLe secLlon. use Lhe Cnu secLlon
aLLrlbuLe Lo achleve Lhe same Lhlng.

LCCA1lCn CCn18CL Cl uA1A
IAk GCC
keyword: @ __attribute__((section(NAME)))
ragma: location
Syntax: #pragma location i=0x0100
int i;
__no_init int j @ 0x0104;

#define i (*(int *)0x0100)

Comment: 1he Cnu Loolchaln only supporLs deflnlng Lhe locaLlon of varlables aL a secLlon level. use Lhe secLlon
aLLrlbuLe Lo conLrol Lhe llnk locaLlon of a varlable. 1he #deflne shown would also produce Lhe same
funcLlonallLy.

8UIL1-IN IUNC1ICNS
ln addlLlon Lo bullL-ln funcLlons Lo access processor lnsLrucLlons, Lhe lA8
LmbeddedWorkbench compller supporLs access Lo Lhe sLarL address of any named
secLlon uslng Lhe below funcLlons.
void * __section_begin(char const * section)
void * __section_end (char const * section)
size_t * __section_size (char const * section)

1hese convenlence funcLlons are noL supporLed by CCC, Lhough Lhe user can slmply
deLermlne Lhe values by deflnlng llnk-Llme symbols aL Lhe sLarL and end of Lhe secLlons of
lnLeresL wlLhln Lhe llnker command flle. 1he symbols can Lhen be used Lo deLermlne Lhe
sLarL, end and slze of any secLlon.

MlgraLlng source flles



36 | a g e

ASSLM8LLk SCUkCL CnANGLS
AlLhough Lhe underlylng lnsLrucLlons and Lhe addresslng modes supporLed by Lhem
remalns consLanL ln a developmenL Lools mlgraLlon pro[ecL, Lhe one non-sLandardlzed parL
of Lhe Loolchaln ls Lhe synLax supporLed by Lhe cross-assembler.
AL Lhe lowesL level, cross-assemblers slmply provlde supporL for creaLlng appllcaLlon code
by dlrecLly speclfylng whlch lnsLrucLlons geL execuLed. ln order Lo make Lhe programmer's
Lask slmpler, cross-assemblers offer addlLlonal 'producLlvlLy' feaLures whlch lnclude:
SupporL for symbols and labels for symbollc addresslng
SupporL for pre-processlng Lo allow for condlLlonal cross-assembly and for Lhe use
of deflnlLlons and macros
SupporL for exLernal flle lncluslon Lo allow for common deflnlLlons Lo be shared
SupporL for arlLhmeLlc expresslons and sLrlngs
SupporL for some hlgh-level language feaLures (e.g. sLrucLures)
unforLunaLely, some cross-assemblers do noL only dlffer ln Lhe 'value added' feaLures, buL
also ln Lhe characLers used for descrlblng lnsLrucLlons (for example Lhe symbols used Lo
dlfferenLlaLe beLween dlfferenL addresslng modes, or Lo deflne numerlc consLanLs).
1hls klnd of varlance beLween Loolchalns ls slmply resolved by uslng a slmple mapplng
scheme.

1he Lable below summarlzes Lhe key dlfferences beLween Lhe Lwo Loolchalns ln assembler
synLax. noLe LhaL Lhere are Loo many dlrecLlves Lo llsL, ln many cases Lhere ls a dlrecL
equlvalenL, buL Lhe user's manual should be consulLed Lo check.

1he Cnu Loolchaln supporLs a dlrecLlve Lo force Lhe lnsLrucLlon synLax Lo be
Lhe same as deflned by Lhe A8M lnsLrucLlon SeL reference. 1he lA8 Loolchaln
ls also compllanL, whlch greaLly slmpllfles porLlng. 1o enable Lhe compllance
add Lhe followlng llne Lo your source flle:

.syntax unified

1hls ensures LhaL Lhe lnsLrucLlons and reglsLers used ln Lhe source flle wlll be
conslsLenL wlLh any oLher Loolchaln compllanL Lo Lhe A8M lnsLrucLlon SeL
reference.

MlgraLlng source flles



37 | a g e


Area GNU IAk
ulrecLlve namlng .<name> <nAML>
MulLlllne commenL /* . */ /* . */
Slngle llne commenL # or [ // or ,
SLaLemenL dellmlLer , or newllne newllne only
8lnary ConsLanLs 0bnnn or 08nnn b'nnn or nnnb
CcLal ConsLanLs 0nnn q'nnn or nnnq
ueclmal ConsLanLs nnn nnn or d'nnn
Pexadeclmal consLanLs 0xnnn 0knnn 0nnnh or 0xnnn or h'nnn
1able 2 - Cross-assembler dlfferences


MlgraLlng source flles



38 | a g e

S1Ak1U CCDL
Cn reseL/power-up, sLarLup code should be execuLed Lo lnlLlallze Lhe runLlme sysLem (C
and/or C++). 1hls lncludes lnlLlallzaLlon of Lhe sLack, heap and daLa secLlons, along wlLh Lhe
execuLlon of global consLrucLors for C++ appllcaLlons. 1hls funcLlonallLy ls auLomaLlcally
supporLed by Lhe sLandard C runLlme provlded wlLh every Loolchaln.
A vecLor Lable should be seL up Lo connecL reseL, excepLlon and lnLerrupL Lable
enLrles Lo Lhe respecLlve handlers.
CLher processor speclflc lnlLlallzaLlon should be performed (e.g. clock and
memory subsysLem lnlLlallzaLlon).
lor Lhe ma[orlLy of sysLems only Lhe hardware speclflc code may need Lo be modlfled,
Lhere ls usually a funcLlon whlch ls called as parL of Lhe sysLem sLarLup code, before Lhe
maln funcLlon whlch may be used Lo do Lhlngs such as seLup clocks, LLs and memory
conLrollers.
1he hardware speclflc funcLlon (SysLemlnlL ln Lhe case of Lhe CCC Lools for A8M
processors) ls wrlLLen ln C, and supplled as a source module whlch can be modlfled
accordlng Lo need.
1he lnLerrupL vecLor Lable and lnLerrupL handlers are also lncluded ln Lhe sLarLup code. lor
Lhe Cnu Loolchaln, Lhe vecLor Lable wlll be populaLed wlLh llnks Lo a defaulL lnLerrupL
handler unless Lhe user lncludes a funcLlon of Lhe same name ln Lhelr source code - Lhls ls
posslble due Lo Lhe use of weak symbols.
A weak symbol (and Lhe daLa or funcLlon assoclaLed wlLh lL) wlll be lncluded ln Lhe flnal
execuLable flle unless anoLher symbol of Lhe same name ls lncluded ln Lhe llnk - when Lhe
non-weak symbol ls dlscovered by Lhe llnker, Lhe weak symbol ls dlscarded. 1hls
mechanlsm allows defaulL behavlor Lo be deflned ln low-level code wlLh overrlde code
exlsLlng ln Lhe user's hlgh level source flles.
1he Lable below summarlzes Lhe funcLlons and symbols used by Lhe lA8
LmbeddedWorkbench and Lhe Cnu Loolchalns for sLarLup code.


MlgraLlng source flles



39 | a g e


roperty GNU IAk
SLarLup flle startup_xxx_cl.s
(e.g.
startup_stm32f10x_cl.s)
cstartup_M.s

LnLry olnL ResetHandler __iar_program_start
Pardware lnlLlallsaLlon SystemInit __low_level_init
lnLerrupL Servlce rouLlnes xxHandler
(e.g. USART2_IRQHandler)
xxHandler
uefaulL l8C Pandler Default_Handler Infinite loop for each
xxHandler
1op of SLack _estack sfe(CSTACK)
8oLLom of Peap _end sfb(HEAP)
SLarL of 8SS _sbss
Lnd of 8SS _ebss
SLarL of lnlL values for uaLa _sidata
SLarL of uaLa _sdata
Lnd of uaLa _edata
1able 3 - SLarLup Code symbols



noLe Lhe lA8 Loolchaln uses speclal dlrecLlves (sfb,sfe) Lo deLermlne Lhe
sLarL/end of secLlons.

lnLroducLlon



40 | a g e




SLC1ICN 4: DL1AILLD kCILC1 8UILD
CCN1kCL
Pavlng deLermlned Lhe source level changes requlred Lo make your appllcaLlon bulld ln
Lhe deslred manner wlLh Lhe new compller, you may flnd LhaL Lhe defaulL compller
seLLlngs don'L generaLe a worklng sysLem, or perhaps generaLe a sysLem LhaL doesn'L
maLch your performance or slze requlremenLs.
AL Lhls sLage knowledge of Lhe underlylng Lools ls lmporLanL, as lL allows you Lo Lake
Lhe besL posslble advanLage of Lhe feaLures and funcLlonallLy offered.
1he placemenL of code and daLa on your LargeL are ofLen of crlLlcal lmporLance. Llnker
scrlpL flles offer Lhe ablllLy Lo conLrol Lhe placemenL of all parLs of your appllcaLlon, buL
are compller Loolchaln speclflc. 1herefore aL some polnL lL may become necessary Lo
edlL a llnker scrlpL flle.
ln addlLlon, ln more compllcaLed mlgraLlons, you may need Lo mlgraLe blnary flles,
and/or llbrarles. 1hls requlres undersLandlng of how llbrarles are consLrucLed.
1hls secLlon covers Lhe above Loplcs ln deLall, allowlng Lhe flnal conLrol and
cusLomlzaLlon of your mlgraLed pro[ecL.

8ulld conLrol



41 | a g e

MIGkA1ING 8UILD IILLS






1he gcc program ls ln facL a wrapper around Lhe underlylng Lools (pre-
processor, C and C++ compllers and llnker). 1hls means LhaL unless expllclLly
lnsLrucLed Lo do oLherwlse, lL wlll aLLempL Lo creaLe an execuLable blnary from
Lhe provlded lnpuL flles, selecLlng Lhe correcL compllaLlon englne and
performlng llnkage uslng a defaulL llnker conLrol scrlpL.
ln mosL embedded appllcaLlons Lhe user requlres Lo have preclse conLrol over
Lhe locaLlon of code and daLa, so a Lwo-sLage complle and llnk process ls
requlred. 1hus Lhe compller and cross-assembler are used Lo generaLe
relocaLable ob[ecL flles, and Lhe llnker ls used Lo comblne Lhe selecLed
relocaLable ob[ecL flles lnLo a slngle 'resolved' execuLable flle. 1hls ls shown
below.


CCC
cpp
cc1
g++
gas
ld
re-processor
C Compller
C++ Compller
Cross-assembler
Llnker

8ulld conLrol



42 | a g e

CCMILLk SL1U AND CCN1kCL
1he Cnu C and C++ compllers offer a huge range of opLlons allowlng Lhe user Lo Lallor Lhe
compller accordlng Lo Lhe LargeL archlLecLure, Lhe requlred level of opLlmlzaLlon, Lhe use of
language exLenslons and/or Lhe generaLlon of warnlngs and errors.
1hls documenL does noL cover every opLlon ln deLall, users should refer Lo Lhe CCC
manual. 1he opLlons dlscussed here are Lhose requlred Lo perform a baslc compllaLlon ln
addlLlon Lo Lhose dlrecLly assoclaLed wlLh Lhe underlylng LargeL.
Slmple compllaLlon of a C flle can be achleved uslng Lhe below command llne
gcc -c myfile.c -o myfile.o

1hls resulLs ln a relocaLable ob[ecL flle belng creaLed (deflned by uslng Lhe '-c' opLlon) from
Lhe compllaLlon of myf||e.c wlLh Lhe resulLlng flle belng called myf||e.o.
uebugglng lnformaLlon (uwarf2 formaL) can be generaLed by uslng Lhe '-g' swlLch
gcc -c myfile.c -g -o myfile.o

SecLlon 3.9 of Lhe CCC manual deLalls Lhe addlLlonal conLrol over Lhe generaLlon of
debugglng lnformaLlon.
C1IMI2A1ICN
CpLlmlzaLlon can be selecLed by uslng one of Lhe 'collecLlon' opLlmlzaLlon swlLches -C1,
-C2, -C3 or -Cs whlch correspond Lo lncreaslng levels of opLlmlzaLlon for performance ln
Lhe case of Lhe numerlc opLlons, or opLlmlzaLlon for code slze ln Lhe case of -Cs. 1he
opLlon -C0 ls Lhe defaulL whlch ensures LhaL Lhe code generaLed can be debugged and
mlnlmlzes compllaLlon Llme.


lL should be noLed LhaL Lhese opLlons represenL a collecLlon of sub-opLlons
whlch conLrol lndlvldual opLlmlzaLlon passes of Lhe compller.
1he user may add addlLlonal sub-opLlons Lo Lhe command llne Lo flne Lune Lhe
opLlmlzaLlon performed. 1he lndlvldual opLlmlzaLlon conLrols are deLalled ln
Lhe CCC manual and are usually preflxed by '-f''.
lor example '-fomlL-frame-polnLer' ls commonly used ln producLlon code as
frame polnLers are useful for debugglng, buL may noL oLherwlse be requlred.
1he hlgher opLlmlzaLlon levels wlll LargeL performance over code slze, whlch
can resulL ln lnllnlng of code and loop unrolllng. Where Lhe code slze lncrease
needs Lo be LlghLly conLrolled addlLlonal command llne swlLches are avallable
Lo conLrol Lhe amounL of lnllnlng and unrolllng. An example command llne
uslng such swlLches ls glven below.
gcc -c myfile.c -O3 -fomit-frame-pointer -finline-
limit=16 -o myfile.o


8ulld conLrol



43 | a g e

ueLalls of Lhe opLlmlzaLlon seLLlngs avallable can be found ln secLlon 3.10 of Lhe CCC
manual.
IMLLMLN1A1ICN SLCIIIC C1ICNS
1here are a large number of opLlons Lo conLrol Lhe Cnu compller Loolchaln, whlch allow
for flne gralned conLrol of all aspecLs of Lhe bulld process. Many of whlch are used Lo flne-
Lune opLlmlzaLlon, or provlde more lnformaLlon Lo oLher Lools, or Lhe user.
Powever parLlcular noLlce should be Laken of any opLlons whlch enable, dlsable or
oLherwlse alLer Lhe way ln whlch Lhe compller generaLes code for source LhaL complles Lo
Lhe C or C++ language sLandard - Lhls 'LransparenL' behavlor can cause problems wlLh
mlgraLlon of code LhaL elLher assumed a dlfferenL behavlor, or when llnked agalnsL
llbrarles LhaL were bullL wlLh non-compaLlble opLlons.
1he areas whlch should be double checked lnclude:
Slze of sLandard Lypes (lnLegers, floaLs, wlde characLers)
uefaulL slgned or unslgned for 'char'
Slze of enumeraLed Lypes
SLrucLure packlng
8lL-fleld layouL
1he documenLaLlon for boLh compllers should be checked Lo deLermlne any confllcLs ln
defaulL behavlor, along wlLh Lhe bulld flles for Lhe orlglnal pro[ecL Lo check lf any speclflc
conLrols have been applled Lo modlfy Lhe defaulL behavlor.
A summary of Lhe command llne opLlons provlded by Lhe lA8 LmbeddedWorkbench
Loolchaln wlLh exacL or slmllar CCC opLlons ls provlded below. Where Lhe CCC opLlon
shown lncludes an asLerlsk '*' Lhls lmplles LhaL more Lhan one opLlon are avallable Lo
provlde flne gralned conLrol.


8ulld conLrol



44 | a g e


IAk Cpt|on GNU Cpt|on GCC manua|
Sect|on
Comment

8ulld conLrol



43 | a g e

IAk Cpt|on GNU Cpt|on GCC manua|
Sect|on
Comment
-aapcs -mabl=aapcs 3.17.2 Speclfles Lhe calllng convenLlon
--aeabl -mabl=aapcs 3.17.2 Lnables ALA8l-compllanL code generaLlon
--allgn_sp_on_lrq n/A 1he SLack ls allgned by defaulL.
--arm (defaulL behavlour) n/A SeLs Lhe defaulL funcLlon mode Lo A8M
--char_ls_slgned -fslgned-char 3.17.2 1reaLs char as slgned
--cpu -mcpu
-mLune
-march
3.17.2 Speclfles a processor varlanL
--cpu_mode --mLhumb
--mLhumb-lnLerwork
3.17.2 SelecLs Lhe defaulL mode for funcLlons
-u -u 3.11 ueflne preprocessor symbol
--debug -g* 3.9 CeneraLe debug lnformaLlon
--dependencles -M* 3.11 LlsLs flle dependencles
--dlag_error n/A 3.7 ulagnosLlc (compller debug and analysls)
lnformaLlon can be conLrolled uslng Lhe CCC
opLlons -d*. 1hls allows very flne gralned
conLrol.
--dlag_remark n/A
--dlag_suppress n/A
--dlag_warnlng n/A
--dlagnosLlcs_Lables n/A
--dlscard_unused_publlcs --dlscard-all
--dlscard-locals
2.1
Lu manual
ulscards unused publlc symbols (lA8
LmbeddedWorkbench), CCC allows conLrol
over varlous Lypes of symbols Lo dlscard.
--dllb_conflg n/A ueLermlnes Lhe llbrary conflguraLlon flle
-e -sLd=gnu90
-sLd=gnu99
-sLd=gnu++98
3.4 Lnables language exLenslons based on C90,
C99 and C++98 respecLlvely.
--ec++,--eec++ -fno-* 3.3 ulsable cerLaln feaLures of C++
--
enable_hardware_workaroun
d
n/A Lnables a speclflc hardware workaround
--enable_mulLlbyLes n/A Lnables supporL for mulLlbyLe characLers ln
source flles. uefaulL behavlour of CCC.
--endlan -mllLLle-endlan
-mblg-endlan
3.17.2 Speclfles Lhe byLe order of Lhe generaLed
code and daLa
--enum_ls_lnL -fshorL-enums 3.18 Speclfy Lhe slze of an enumeraLed Lype
--error_llmlL n/A Speclfles Lhe allowed number of errors before
compllaLlon sLops
-f n/A LxLends Lhe command llne

8ulld conLrol



46 | a g e

IAk Cpt|on GNU Cpt|on GCC manua|
Sect|on
Comment
--fpu -mfloaL-abl
-mfpu
3.17.2 SelecLs Lhe Lype of floaLlng-polnL unlL
--header_conLexL -M* 3.11 LlsLs all referred source flles and header flles
-l -l 3.11 Speclfles lnclude flle paLh
--lnLerwork -mLhumb-lnLerwork 3.17.2 CeneraLes lnLerworklng code
-l (ob[dump) -S 8lnuLlls manual CreaLes a llsL flle (flle musL have been bullL
wlLh debug)
--legacy n/A CeneraLes ob[ecL code llnkable wlLh older Lool
chalns
--mfc -fwhole-program 3.1 Whole program opLlmlsaLlon
--mlgraLlon_preprocessor...
_exLenslons
n/A 1hls ls an lnLer-lA8 compller mlgraLlon opLlon.
--mlsrac1998 , --mlsrac_ n/A Mlsra ls noL supporLed by CCC
--no_clusLerlng n/A LocallLy of access ls enabled by defaulL ln CCC
along wlLh supporL for proflle based
opLlmlsaLlon.
--no_code_moLlon -fno-sched-lnLerblock 3.1 CCC has a number of schedullng opLlons.
--no_consL_allgn n/A
--no_cse -fno-gcse 3.1 ulsables common sub-expresslon ellmlnaLlon
--no_fragmenLs -fno-reorder-funcLlons 3.1 ulsables secLlon fragmenL handllng
--no_guard_calls n/A ulsables guard calls for sLaLlc lnlLlallzers
--no_lnllne -fno-lnllne 3.1 ulsables funcLlon lnllnlng
--no_paLh_ln_flle_macros n/A 8emoves Lhe paLh from Lhe symbols __llLL__
and __8ASL_llLL__
--no_schedullng -fno-schedule-lnsns 3.1 ulsables Lhe lnsLrucLlon scheduler
--no_Lbaa -fno-sLrlcL-allaslng 3.1 ulsables Lype-based allas analysls
--no_Lypedefs_ln_dlagnosLlcs n/A ulsables Lhe use of Lypedef names ln
dlagnosLlcs
--no_unallgned_access -fno-allgn-* 3.1 Avolds unallgned accesses
--no_unroll -fno-unroll-loops 3.1 ulsables loop unrolllng
--no_warnlngs -w 3.8 ulsables all warnlngs
--no_wrap_dlagnosLlcs -fmessage-lengLh 3.7 ulsables wrapplng of dlagnosLlc messages
-C* -C* 3.1 SeLs Lhe opLlmlzaLlon level
-o -o 3.2 SeLs Lhe ouLpuL flle name
--only_sLdouL n/A uses sLandard ouLpuL only - Lhls can be
achleved by Lhe shell used Lo lnvoke Lhe

8ulld conLrol



47 | a g e

IAk Cpt|on GNU Cpt|on GCC manua|
Sect|on
Comment
compller.
--ouLpuL -o 3.2 SeLs Lhe ob[ecL fllename
--predef_macros -L -dM 3.11 LlsLs Lhe predeflned symbols
--prelnclude -lnclude 3.11 lncludes an lnclude flle before readlng Lhe
source flle
--preprocess -L 3.11 CeneraLes preprocessor ouLpuL
--publlc_equ --def-sym 2.1
Lu manual
ueflnes a global named assembler label
-r -g* 3.9 CeneraLes debug lnformaLlon
--remarks n/A Lnables remarks
--requlre_proLoLypes -Wmlsslng-proLoLype 3.8 verlfles LhaL funcLlons are declared before
Lhey are deflned
--secLlon --unlque 2.1
Lu manual
Changes a secLlon name
--separaLe_clusLer_for...
_lnlLlallzed_varlables
n/A SeparaLes lnlLlallzed and non-lnlLlallzed
varlables
--sllenL n/A SeLs sllenL operaLlon
--sLrlcL_ansl -ansl
-pedanLlc
3.4 & 3.8 Checks for sLrlcL compllance wlLh lSC/AnSl C
--Lhumb -mLhumb 3.17.2 SeLs defaulL funcLlon mode Lo 1humb
--
use_unlx_dlrecLory_separaLor
s
n/A uses / as dlrecLory separaLor ln paLhs. 1hls ls
Lhe defaulL behavlour ln CCC.
--warnlngs_affecL_exlL_code n/A Warnlngs affecLs exlL code. 1hls ls Lhe defaulL
behavlour ln CCC
--warnlngs_are_errors -Werror 3.8 Warnlngs are LreaLed as errors
1able 4 - Compller opLlon cross-reference

8ulld conLrol



48 | a g e

LINk MANAGLMLN1
All modern compller Loolchalns lnclude a llnker whlch ls used Lo comblne Lhe ouLpuL of Lhe
compller, Lhe cross-assembler and any llbrarles lnLo an execuLable flle. 1he llnker
Lherefore can have 3 Lypes of lnpuL:
8equlred appllcaLlon relocaLable ob[ecL flles
Llbrary flles used Lo provlde llbrary modules requlred by Lhe appllcaLlon
A llnker conLrol flle
1hls secLlon examlnes Lhe llnker conLrol flle usage and formaL, buL before golng lnLo deLall
lL's worLh undersLandlng how Lhe llnker may be lnvoked. As Lhe CCC wrapper appllcaLlon
supporLs auLomaLlc lnvocaLlon of Lhe correcL underlylng Lool, lL ls posslble Lo run Lhe llnker
dlrecLly, or lndlrecLly.
gcc myfile.o -lc -o myfile.elf !4 *56!7#$*-" "(
ld myfile.o -lc -o myfile.elf
8oLh of Lhe above commands wlll Lake Lhe relocaLable ob[ecL flle myf||e.o, llnk lL wlLh Lhe
sLandard C llbrary flle ||bc.a and produce an execuLable (LLl) formaL flle called myf||e.e|f.
1he '-lc' opLlon uses a shorLhand noLaLlon where '-l' Lells Lhe llnker Lo llnk a llbrary whlch lL
wlll flnd uslng defaulL search paLhs, Lhe envlronmenL or oLher command llne hlnLs, and Lhe
'c' sufflx wlll be expanded Lo '||bc.a' or '||bc.so' (sLaLlc and dynamlc llbrarles respecLlvely).
Many embedded sysLems wlll noL be runnlng wlLh a porL of Llnux, so only sLaLlc llbrarles
are avallable.
lL ls posslble Lo perform compllaLlon and llnkage aL Lhe same Llme, uslng Lhe below
command llne:
gcc myfile.c -lc -o myfile.elf
1he only problem wlLh uslng Lhe CCC wrapper appllcaLlon ls LhaL Lhere are slLuaLlons
where slmllar opLlons are avallable for Lhe compller and Lhe llnker. Where Lhere ls a need
Lo speclfy a llnker opLlon, whlle sLlll uslng CCC, Lhose commands may be preflxed by Lhe -
Wl swlLch as below
gcc myfile.o -lc -Wl,--entry=ResetHandler -o myfile.elf
A separaLe manual ls provlded whlch deLalls how Lhe llnker ls used, called |d.pdf ln Lhe
ALolllc dlsLrlbuLlon.

LINkLk SCkI1]CCMMAND IILLS
Llnker scrlpL flles are used Lo conLrol whaL geLs llnked, where lL geLs placed ln memory and
Lo deflne any symbols whlch may be used Lo lnlLlallze Lhe sysLem on sLarLup.

8ulld conLrol



49 | a g e

MosL modern llnkers provlde slmllar funcLlonallLy Lo one-anoLher, so ln mlgraLlon, Lhe
maln Lask ls Lo undersLand how Lo converL Lhe synLax of one llnker command formaL Lo
LhaL of Lhe oLher.
Some pro[ecLs never requlre changlng Lhe defaulL behavlor of Lhe llnker away from LhaL
elLher provlded by Lhe compller Loolchaln, or more llkely by Lhe luL whlch creaLed Lhe
pro[ecL.
When sLarLlng a mlgraLlon lL ls sLrongly recommended Lo use Lhe !"#$$%& ()*+,(-./01 luL
Lo creaLe a pro[ecL along wlLh Lhe assoclaLed bulld flles whlch may Lhen be Lallored
accordlng Lo need.
1he wlzard provlded by Lhe luL wlll allow Lhe user Lo selecL Lhe LargeL processor and even
developmenL board, whlch wlll greaLly slmpllfy Lhe process. lL should also be remembered
LhaL all embedded sysLems have Lhe same baslc requlremenLs:
Cn reseL/power-up, sLarLup code should be execuLed Lo lnlLlallze Lhe runLlme sysLem
(C and or C++), Lhls lncludes lnlLlallzaLlon of Lhe sLack, heap and daLa secLlons, along
wlLh Lhe execuLlon of global consLrucLors for C++ appllcaLlons. 1hls funcLlonallLy ls
auLomaLlcally supporLed by Lhe sLandard C runLlme provlded wlLh every Loolchaln.
A vecLor Lable should be seL up Lo connecL reseL, excepLlon and lnLerrupL Lable enLrles
Lo Lhe respecLlve handlers.
CLher processor speclflc lnlLlallzaLlon should be performed (e.g. clock and memory
subsysLem lnlLlallzaLlon).
1he Cnu llnker Lu supporLs a hlgh-level command synLax Lo enable placemenL of code and
daLa. An exLracL of example flle ls provlded below along wlLh explanaLory commenLs Lo
hlghllghL Lhe maln feaLures.
noLe LhaL Lhe '.' dlrecLlve deflnes Lhe currenL locaLlon polnLer.


8ulld conLrol



30 | a g e

ENTRY(Reset_Handler) ueflne Lhe enLry polnL of Lhe appllcaLlon as
'8eseLPandler'
_estack = 0x20010000;
_Min_Heap_Size = 0;
_Min_Stack_Size = 0x200;
ueflne symbols wlLh consLanL values
MEMORY
{
FLASH (rx) : ORIGIN = 0x08000000, LENGTH =
256K

RAM (xrw) : ORIGIN = 0x20000000, LENGTH = 64K

MEMORY_B1 (rx) : ORIGIN = 0x60000000, LENGTH =
0K
}
ueflne memory reglons:
'lLASP' wlLh read / execuLe permlsslons,
slze 236k8, sLarL address 0x8000000
'8AM' wlLh read / wrlLe / execuLe
permlsslons, slze 64k8, sLarL address
0x20000000
'MLMC8?_81' wlLh read/execuLe
permlsslons, slze 0k8, sLarL address
0x60000000
SECTIONS
{
SLarL allocaLlon of secLlons Lo memory
.isr_vector :
{
. = ALIGN(4);
KEEP(*(.isr_vector))
. = ALIGN(4);
} >FLASH
AllocaLe Lhe '.lsr_vecLor' secLlon Lo lLASP. 4-byLe
allgnmenL ls malnLalned Lo ensure correcL
placemenL.
.sidata = .;

.data : AT ( _sidata )
{
. = ALIGN(4);
_sdata = .;
*(.data)
*(.data*)
. = ALIGN(4);
_edata = .;
} >RAM
ueflne Lhe symbol '.s|data' Lo be aL Lhe currenL
locaLlon ln memory ([usL afLer Lhe vecLor Lable).
uslng Lhe'A1' dlrecLlve, place Lhe contents of Lhe
.daLa* secLlons aL Lhe addres speclfled by .sldaLa,
buL llnk references Lo Lhe daLa as lf lL exlsLs ln Lhe
8AM secLlon. 1hls allows for lnlLlal values Lo be
placed ln non-volaLllve memory, and copled aL
sLarLup lnLo Lhe runLlme memory lmage.
Symbols _sdata and _edata are deflned for Lhe
sLarL and end addresses of Lhe collecLlon of '.daLa'
secLlons. 1hus lnlLlallsaLlon coples from .s|data Lo
_sdata.
PROVIDE ( end = _ebss );
PROVIDE ( _end = _ebss );
rovlde Lhe symbols end and _end only lf Lhey are
referenced, buL noL deflned anywhere ln Lhe
lncluded flles (Lo ensure a llnker symbol clash
doesn'L occur)
._user_heap_stack :
{
. = ALIGN(4);
. = . + _Min_Heap_Size;
. = . + _Min_Stack_Size;
. = ALIGN(4);
} >RAM
AllocaLe an area ln Lhe 8AM memory whlch ls aL
leasL as blg as Lhe mlnlmum heap and sLack slzes
deflned earller ln Lhe flle.
} CompleLe Lhe secLlon allocaLlon

8ulld conLrol



31 | a g e

LI8kAk MANAGLMLN1
Llbrarles are collecLlons of relocaLable ob[ecL flles LhaL are commonly used by appllcaLlons.
1he collecLlon, or archlve, may be used by Lhe llnker Lo resolve (l.e. flnd a maLch for) a
funcLlon or daLa lLem whlch has been referenced by Lhe user's appllcaLlon code.
Lvery compller shlps wlLh a number of llbrarles such as Lhe sLandard C llbrary, Lhe C
maLhemaLlcs llbrary, Lhe C++ runLlme llbrary eLc. Such 'sysLem' llbrarles usually lnclude
defaulL sLarLup code and lnLrlnslc llbrarles whlch lmplemenL Lhe low-level funcLlonallLy
requlred Lo make an appllcaLlon work.
SLarLup code ensures LhaL Lhe processor ls lnlLlallzed correcLly on reseL and LhaL Lhe
runLlme envlronmenL ls seL up correcLly (global varlables geL Lhelr correcL values, Lhe heap
ls lnlLlallzed eLc).
lnLrlnslc llbrarles lmplemenL low level operaLlons whlch Lhe compller requlres Lo supporL
hlgh level language Lypes and feaLures, whlch are noL easlly lmplemenLed uslng one or a
small number of assembler lnsLrucLlons. Lxamples of lnLrlnslc funcLlons may lnclude 64-blL
arlLhmeLlc on 32-blL machlnes, floaLlng polnL operaLlons on machlnes wlLh no floaLlng
polnL unlL and funcLlon prolog/epllog code used when opLlmlzlng for slze.
Lach relocaLable module conLalned wlLhln a llbrary wlll only be lncluded ln Lhe generaLed
execuLable flle lf one or more of Lhe symbols lL exporLs (whlch correspond Lo funcLlons or
daLa lLems) ls referenced, elLher dlrecLly from appllcaLlon code, or lndlrecLly from anoLher
llbrary whlch lLself was dlrecLly referenced. 1hls enables Lhe generaLed execuLable flle Lo
only lnclude Lhe requlred funcLlons and daLa, raLher Lhan always lncludlng Lhe compleLe C
or C++ runLlme.
1here are Lwo Lypes of llbrary, sLaLlc and dynamlc. 1he llbrary code conLalned wlLhln sLaLlc
llbrarles wlll form parL of Lhe execuLable (lf referenced) - l.e. all references are resolved
once ('sLaLlcally') aL bulld Llme.
As mosL embedded sysLems are slngle appllcaLlons, Lhls ls Lhe normal model. uynamlc
llbrarles allow Lhe llbrary code Lo be llnked Lo Lhe appllcaLlon aL runLlme, whlch leads Lo
smaller appllcaLlon blnarles, buL requlres a runLlme llnker/loader such as LhaL provlded by
Llnux. 1hls documenL covers sLaLlc llbrarles only, as sysLems mlgraLlng from Lhe lA8
LmbeddedWorkbench Loolchaln wlll noL be Llnux based.

S1ANDAkD LI8kAkILS
1he C and C++ sLandards don'L [usL deflne Lhe language, buL also speclfy a seL of runLlme
llbrarles LhaL need Lo be supporLed.
1he 'sLandard llbrarles provlde faclllLles Lo manlpulaLe daLa aL a level noL supporLed
dlrecLly by Lhe language (e.g. sLrlngs), Lo manage memory allocaLlon dynamlcally (malloc
and free for C, or new and deleLe for C++), and Lo lnLeracL wlLh Lhe underlylng sysLem (flle
lnpuL/ouLpuL, Llme managemenL eLc).

8ulld conLrol



32 | a g e

ln addlLlon Lo Lhe sLandard llbrarles, compllers Lyplcally shlp wlLh whaL are called 'lnLrlnslc'
llbrarles.
1hese are compller speclflc and usually provlde low level rouLlnes whlch Lhe compller
lnvokes auLomaLlcally as parL of Lhe bulld process. lnLrlnslc funcLlons are usually wrlLLen Lo
lmplemenL a language feaLure whlch Lhe underlylng processor cannoL supporL slmply.
lor example 64-blL arlLhmeLlc on a 16 or 32-blL Cu, or floaLlng-polnL arlLhmeLlc on any
Cu wlLhouL a dedlcaLed floaLlng-polnL unlL. rogrammers don'L call lnLrlnslc llbrarles
dlrecLly (Lhey don'L need Lo) and Lhere ls no guaranLee LhaL Lhe funcLlons comply Lo Lhe
normal A8l.
1he lnLrlnslc funcLlons are usually hand opLlmlzed, wrlLLen ln assembler, and
undocumenLed. 1he programmer slmply needs Lo ensure LhaL Lhe lnLrlnslc, or 'language
supporL' llbrary ls lncluded ln Lhe bulld Lo enable Lhe correcL low-level funcLlons Lo be
lncluded ln Lhe flnal appllcaLlon.
A furLher Lype of llbrary flle usually shlpped wlLh a compller ls used Lo supporL sysLems
where 'ob[ecLs' need lnlLlallzaLlon aL sLarLup. 1hls lncludes calllng consLrucLors for global
ob[ecLs ln C++ appllcaLlons, along wlLh Lhe correspondlng desLrucLors should Lhe
appllcaLlon ever exlL. Speclal lnlLlallzaLlon and flnallzaLlon secLlons are lncluded ln Lhe
execuLable flle whlch conLalns code Lo lLeraLe Lhrough a llsL of supplled
consLrucLors/desLrucLors.
ln order Lo ald mlgraLlon, Lhe below Lable provldes an lnslghL lnLo Lhe llbrarles shlpped
wlLh Lhe Cnu C/C++ compller:


8ulld conLrol



33 | a g e

L|brary Language Usage
Llbc.a C 1hls ls Lhe sLandard C runLlme llbrary (noL lncludlng maLhs)
Llbg.a C 1hls ls a debug bulld of Lhe sLandard C runLlme llbrary
Llbm.a C 1hls ls Lhe C sLandard maLhemaLlc llbrary
Llbgcc.a C 1hls ls Lhe lnLrlnslc 'compller supporL' llbrary requlred Lo supporL C
appllcaLlons
LlblberLy.a C a collecLlon of subrouLlnes used by varlous Cnu programs lncludlng
geLopL, obsLack, sLrerror, sLrLol and sLrLoul.
Llbgcov.a C CCC supporLs auLomaLlc lnsLrumenLaLlon of code, by lncludlng gcov, lL ls
posslble Lo analyze programs Lo help creaLe more efflclenL, fasLer
runnlng code Lhrough opLlmlzaLlon
Llbsupc++.a C++ 1hls llbrary provldes supporL for Lhe C++ programmlng language (among
oLher Lhlngs, llbsupc++ conLalns rouLlnes for excepLlon handllng). 1hls
llbrary can be used where Lhe full C++ sLandard llbrary ls noL requlred.
LlbsLdc++.a C++ 1he C++ sLandard llbrary. lL ls used by C++ programs and conLalns
funcLlons LhaL are frequenLly used ln C++ programs. 1hls lncludes Lhe
SLandard 1emplaLe Llbrary (S1L).
crLbegln.o & crLend.o C++ ConsLrucLors and desLrucLor supporL flles
1able 3 - SLandard Llbrarles

LI8kAk CkLA1ICN AND MANAGLMLN1
SLaLlc llbrarles are slmply a collecLlon of complled source modules, Lhey can be creaLed
and managed uslng a sLandard 'archlvlng' Lool, ln Lhe case of Lhe Cnu C/C++ compller, and
Lhls Lool ls called 'ar'.
1o creaLe an archlve from one or more relocaLable ob[ecL flles, use Lhe command llne
below, whlch wlll creaLe a new archlve called ||bmyf||es.a, or updaLe lL lf lL already exlsLs,
replaclng old verslons of modules f||e1.o and f||e2.o lf Lhey exlsL.
ar cru libmyfiles.a file1.o file2.o

8y convenLlon sLaLlc llbrarles have Lhe '.a' exLenslon.
1he lA8 LmbeddedWorkbench llbrary managemenL Lool (larchlve) ls slmllar ln concepL
and capablllLy Lo Lhe Cnu one, whlch makes mlgraLlon of llbrary bulld flles relaLlvely
slmple.
ln Lhe case where legacy lA8 LmbeddedWorkbench blnarles are Lo be used ln Lhe
mlgraLed appllcaLlon, lL ls useful Lo exLracL Lhose modules from Lhe llbrarles Lhey currenLly
exlsL ln, ln order Lo creaLe a 'mlgraLlon llbrary' whlch may also lnclude any A8l wrapper
code requlred.

8ulld conLrol



34 | a g e

lL ls noL recommended Lo slmply llnk agalnsL orlglnal lA8 LmbeddedWorkbench llbrarles,
as Lhey may (wlll) lnclude modules whlch deflne funcLlons or daLa lLems whlch are also
deflned ln Lhe Cnu llbrarles - Lhls wlll creaLe llnk Llme errors due Lo dupllcaLe symbols, or
ln Lhe worsL case overrlde weak symbols ln Lhe Cnu llbrarles resulLlng ln a successfully
llnked appllcaLlon whlch has unexpecLed behavlor.

Lxample commands Lo deLermlne Lhe locaLlon of a symbol ln a llbrary, Lo exLracL Lhe
conLalnlng relocaLable module, and Lo lnclude lL lnLo a mlgraLlon llbrary are shown below.
lor larchlve Lo flnd and exLracL Lhe relocaLable flle (module)
iarchive --symbols mylib.a $!4" "8* 49:;($4 !- $!;)#)9
iarchive -x mylib.a module.o *+")#%" :(26$*<( /)(: "8* $!;)#)9
lor Cnu Lo creaLe/updaLe Lhe mlgraLlon llbrary
ar cru libmigration.a module.o

unless a speclflc Lhlrd parLy llbrary ls used, ln all oLher cases Lhe
recommended way Lo solve llbrary dependencles ls as below.
1. Llnk Lhe appllcaLlon agalnsL Lhe Cnu llbrarles only, noLlng any
'unresolved exLernal' llnker errors.
2. ueLermlne Lhe source of each of Lhe symbols ln Lhe legacy llbrarles.
1hls can be done uslng a comblnaLlon of Lhe llbrary managemenL Lool
and an ob[ecL flle uLlllLy as shown ln Lhe followlng example.
3. LxLracL only Lhe source modules LhaL conLaln Lhe requlred symbols
from Lhe legacy llbrarles creaLlng/updaLlng a mlgraLlon llbrary.
4. 8epeaL from sLep 1 above llnklng agalnsL Lhe updaLed mlgraLlon
llbrary unLll all unresolved exLernals are resolved.


8ulld conLrol



33 | a g e

MIGkA1ING 3kD Ak1 IILLS
lf your exlsLlng pro[ecL conLalns Lhlrd parLy llbrarles, whlch you wlsh, or need, Lo lnclude ln
Lhe mlgraLlon pro[ecL, Lhen Lhe scope of Lhe mlgraLlon needs Lo be enlarged Lo encompass
Lhe efforL Lo achleve Lhls.
As Lhe Cnu Compller Loolchaln porL Lo Lhe A8M archlLecLure ls ublqulLous, lL ls exLremely
llkely LhaL a porL has already been done Lo CCC. uependlng on Lhe way LhaL Lhe llbrary ls
supplled, you may already have a porL!

VLNDCk SULILD Ck1S
Some vendors supply llbrarles ln source form wlLh bulld/conflguraLlon flles. ln such cases,
lL ls llkely LhaL Lhe source flles already supporL CCC compllaLlon Lhrough Lhe use of
condlLlonal compllaLlon. 1he documenLaLlon supplled wlLh Lhe llbrary should provlde
lnformaLlon on bulldlng wlLh Lhe Cnu Lools.
CfLen Lhe llbrarles are supplled ln a blnary formaL, ln order Lo proLecL Lhe lnLellecLual
properLy of Lhe vendor. ln such cases lL ls llkely LhaL a blnary dlsLrlbuLlon for Lhe Cnu
compller Loolchaln ls avallable, Lhough lL wlll be necessary Lo check llcenslng arrangemenLs
wlLh Lhe vendor.

SCUkCL LLVLL Ck1ING
1he meLhod Lo porL Lhlrd parLy source llbrarles Lo CCC ls essenLlally Lhe same as for Lhe
resL of Lhe pro[ecL. ?ou may however need Lo check on Lhe Lerms of Lhe llcense Lo check
wheLher porLlng Lhe source flles Lo anoLher Loolchaln ls permlLLed.
ln order Lo make Lhe porLed llbrary avallable Lo oLher pro[ecLs, lL ls worLh creaLlng a new
pro[ecL ln Lhe !"#$$%& ()*+,(-./01 workspace Lo conLaln lL. 1he workspace envlronmenL
supporLs mulLlple pro[ecLs, each of whlch may be an appllcaLlon or a llbrary. ln addlLlon,
dependencles beLween pro[ecLs may be deflned Lo ensure LhaL Lhe bulld order ls correcL
(l.e. bulld Lhe llbrarles flrsL), and LhaL lf Lhe llbrary ls changed, Lhen Lhe maln appllcaLlon
wlll be rebullL Loo.

8INAk LLVLL Ck1ING
lrom a Lechnlcal perspecLlve Lhls ls Lhe hardesL of Lhe porLlng exerclses Lo achleve. 1he
assumpLlon here ls LhaL Lhere ls a blnary llbrary wlLh assoclaLed header flles, and Lhe user
ls unable Lo convlnce Lhe vendor Lo supply a verslon of Lhe llbrary whlch has been porLed
Lo Lhe Cnu compller Loolchaln.

8ulld conLrol



36 | a g e


1he requlremenL ls Lo be able Lo call all of Lhe llbrary funcLlons from your CCC based
appllcaLlon, passlng daLa lnLo, and recelvlng daLa from Lhem.

1he sLeps Lo follow for slmple lnLegraLlon are:
1. use Lhe lA8 LmbeddedWorkbench archlve Lool Lo exLracL all modules from Lhe
lA8 LmbeddedWorkbench archlve
2. use Lhe Cnu archlve Lool Lo creaLe a new archlve, lmporLlng all of Lhe llbrary
modules
3. Add Lhe new llbrary as flle Lo Lhe maln appllcaLlon pro[ecL
An example of Lhls process ls shown below:
iarchive -x tplib.a module.o *+")#%" :(26$*<( /)(: "8* $!;)#)9
ar -cru libtplib.a *.o %)*#"* # -*0 $!;)#)9 0!"8 #$$ "8* :(26$*4

CkLA1ING A 8INAk IN1LkIACL
ln a small number of cases lL may be necessary Lo consLrucL an lnLerface llbrary Lo Lhe Lhlrd
parLy llbrary. lor C llbrarles, Lhe process ls relaLlvely sLralghL forward. lor C++ llbrarles,
Lhe process may be much more complex, dependlng on Lhe naLure of Lhe llbrary lL may be
prudenL Lo creaLe a C wrapper around Lhe underlylng C++ llbrary, effecLlvely masklng Lhe
dlfferences ln Lhe A8l beLween compllers.
ln some slLuaLlons Lhls may noL be accepLable, ln whlch case C++ wrappers wlll need Lo be
consLrucLed - Lhls requlres a hlgh level of undersLandlng of Lhe low level lmplemenLaLlon
of C++ (how ob[ecLs are consLrucLed ln memory, how polymorphlsm ls supporLed uslng
vlrLual funcLlon polnLer Lables, how excepLlons are Lhrown and caughL), and ls beyond Lhe
scope of Lhls documenL.
Pere follows a serles of meLhods whlch Lhe user can employ Lo perform Lhe ma[orlLy of
mlgraLlon Lasks.
lunC1lCn CALL/8L1u8n
8efore golng lnLo Lhe meLhods used Lo consLrucL blnary lnLerfaces, Lhe flrsL Lhlng LhaL
needs Lo be undersLood ls Lhe funcLlon call/reLurn mechanlsm. 1hls deflnes Lhe reglsLers
As deLalled prevlously ln Lhls documenL, boLh Lhe Cnu and lA8 compllers
supporL Lhe A8M procedure call sLandard, and have conslsLenL ob[ecL flle
formaLs, whlch may enable Lhe llbrary funcLlons Lo be dlrecLly llnked lnLo your
end appllcaLlon. lL ls worLh checklng Lhls rouLe flrsL, before embarklng on
generaLlng A8l wrappers.


8ulld conLrol



37 | a g e

LhaL geL used ln passlng parameLers and reLurnlng resulLs when calllng funcLlons, ln
addlLlon Lo rules on whlch reglsLers may be modlfled by a called funcLlon wlLhouL needlng
Lo be preserved (l.e. saved on enLry and resLored on exlL).
1he lnpuL parameLers are sLored flrsL ln reglsLers, and Lhen on Lhe sLack.

Item Descr|pt|on
lnpuL arameLers r0 Lo r3
r0:r1 and r2:r3 palrs may be used for 64-blL parameLers.
1he flrsL parameLer may be an address:
Lhe 'Lhls' polnLer for C++
Lhe address of a large/composlLe reLurn value
8eLurn value r0, or r0:r1 for 64-blL values
r0 may conLaln Lhe address of Lhe reLurn daLa for large/composlLe daLa
Work reglsLers r0 Lo r3 and r12 may be modlfled by Lhe called funcLlon wlLhouL savlng
Saved reglsLers r4 Lo r11 musL be saved lf modlfled and resLored before reLurnlng
Speclal reglsLers r13 ls Lhe sLack polnLer
r14 ls Lhe llnk reglsLer
r13 ls Lhe program counLer

1hus on reLurn from a funcLlon, reglsLers r4 Lo r11 musL conLaln Lhe same values as when
lL was called, as should Lhe sLack polnLer and llnk reglsLer. 8eglsLer r0 conLalns Lhe reLurn
value. 8eglsLers r1 Lo r3 and r12 may conLaln any daLa.
uSL 1PL CCMlLL8 1C C8LA1L An ln1L8lACL lC8 ?Cu
1he 'ouLgolng' compller may be used Lo consLrucL a call/reLurn lnLerface for use by Lhe
new compller by slmply uslng lLs ablllLy Lo emlL assembler source flles from C/C++ level
lnpuL. 1hls relles on uslng Lhe legacy Loolchaln Lo creaLe a valld assembler lnLerface,
callable from C or C++ whlch may Lhen be lnLegraLed wlLh Lhe new Lools.

As an example, assume Lhe Lhlrd parLy llbrary has a funcLlon 'foo' wlLh Lhe below
proLoLype.
typedef struct s
{
int a;
char *str;
} S;

lL should be noLed LhaL Lhls procedure assumes LhaL Lhe Lwo C/C++ compllers
produce code wlLh lncompaLlble lnLerfaces, lf Lhls ls noL Lhe case, Lhen please
refer Lo prevlous secLlons ln Lhls manual for lnLegraLlng compaLlble llbrarles
lnLo your new pro[ecL.


8ulld conLrol



38 | a g e

S foo (int a, char *str);
1he funcLlon Lakes Lwo parameLers, one of whlch ls a polnLer, and reLurns a sLrucLure. lL ls
assumed LhaL for whaLever reason, Lhe sLrucLure layouL varles beLween Lhe Lwo compllers,
whlch presenL Lhe worsL case scenarlo Lo deal wlLh.
llrsL of all, creaLe a wrapper funcLlon ln C as a basls for Lhe lnLerface and save ln a flle
called wrapper.c.
S foo_w (int a, char *str)
{
S s = foo (a,str);
return (s);
}


1he alm ls Lo produce funcLlon prolog/epllog code sulLable for CCC, and a funcLlon body
sulLable for calllng Lhe underlylng lA8 LmbeddedWorkbench funcLlon.
1o generaLe Lwo assembler flles uslng Lhe Lwo compllers:
gcc -S wrapper.c -o wrapper_g.s -O0 -fomit-frame-pointer
iccarm wrapper.c -lb wrapper_i.s -On --interwork
1hls wlll cause flles wrapper_g.s and wrapper_i.s Lo be generaLed, boLh of whlch have
complled Lhe lnpuL code and generaLed an assembler source flle.
Looklng aL Lhe Lwo flles, lL ls posslble Lo see Lhe parLs of Lhe code responslble for managlng
Lhe funcLlon 'prolog' and 'epllog' - l.e. seLLlng up Lhe sLack frame, managlng lncomlng
parameLers and seLLlng Lhe reLurn value, plus Lhe parLs of Lhe code responslble for calllng
Lhe llbrary funcLlon 'foo'.

1he Lable below shows how Lhe generaLed code can be parLlLloned and merged Lo form a
new funcLlon. ln Lhls slmple example, as boLh compllers conform Lo Lhe procedure call
sLandard, Lhere was no need Lo creaLe Lhe wrapper flle, buL lL enables Lhe mechanlsm Lo
As deflned earller, Lhe procedure call sLandard sLaLes LhaL lf Lhe reLurn value ls
a composlLe Lype (sLrucLure) whlch ls larger Lhan 4 byLes, Lhen an exLra
argumenL ls used Lo speclfy Lhe locaLlon Lhe reLurn value ls Lo be sLored. 1hus
r0 ls used Lo pass ln Lhe address of Lhe memory Lo conLaln Lhe reLurn value. ln
Lhe case of Lhe lA8 generaLed code, Lhe memory ls puL aL Lhe Lop of Lhe sLack,
whereas for Lhe Cnu generaLed code, Lhe memory ls locaLed aL an 8-byLe
offseL lnLo Lhe sLack.

1he source flle should be complled Lwlce, uslng boLh Lhe lA8 and Cnu
compllers, ln boLh cases uslng Lhe compller's faclllLy Lo emlL assembler source
flles, and ln boLh cases wlLh opLlmlzaLlon dlsabled. lL ls lmporLanL Lo remove
opLlmlzaLlon, as oLherwlse Lhe compller may produce code whlch ls exLremely
hard Lo adapL.


8ulld conLrol



39 | a g e

be shown. 1he prolog and epllog code ls shown ln blue, Lhe funcLlon call code ln green, and
Lhe reLurn value processlng ln red.
IAk GNU Merged
foo_w:
PUSH {R2-R6,LR}
MOVS R4,R0
MOVS R5,R1
MOVS R6,R2
MOVS R2,R6
MOVS R1,R5
MOVS R0,SP
BL foo
MOVS R0,SP
LDR R2,[R0, #+0]
LDR R3,[R0, #+4]
STM R4,{R2,R3}
POP {R1,R2,R4-R6,LR}
BX LR

foo_w:
stmfd sp!, {r4, lr}
sub sp, sp, #16
mov r4, r0
str r1, [sp, #4]
str r2, [sp, #0]
add r3, sp, #8
mov r0, r3
ldr r1, [sp, #4]
ldr r2, [sp, #0]
bl foo
mov r3, r4
add r2, sp, #8
ldmia r2, {r0, r1}
stmia r3, {r0, r1}
mov r0, r4
add sp, sp, #16
ldmfd sp!, {r4, lr}
bx lr
foo_w:
stmfd sp!, {r4, lr}
sub sp, sp, #16
mov r4, r0
str r1, [sp, #4]
str r2, [sp, #0]
add r3, sp, #8
MOVS R2,R2 ;not needed
MOVS R1,R1 ;not needed
MOVS R0,R3
BL foo
mov r3, r4
add r2, sp, #8
ldmia r2, {r0, r1}
stmia r3, {r0, r1}
mov r0, r4
add sp, sp, #16
ldmfd sp!, {r4, lr}
bx lr

Cnce Lhe prolog and epllog code has been ldenLlfled, and as Lhe resulLlng funcLlon ls Lo be
called by code generaLed by CCC, Lhe prolog, epllog and reLurn value processlng code ls
copled from Lhe Cnu generaLed code. 1he funcLlon call code ls Lhen copled from Lhe lA8
LmbeddedWorkbench generaLed code, whlch ensures LhaL Lhe funcLlon whlch ls Lo be
called has Lhe parameLers seL ln Lhe correcL manner.

Powever Lhe funcLlon call code has Lo be modlfled Lo reflecL Lhe locaLlons where Lhe
lncomlng values were sLored by Lhe Cnu compller. ln facL, by lnspecLlon, lL can be seen
LhaL Lhe lnpuL values remaln ln reglsLers r1 and r2, so Lhe modlfled lA8
LmbeddedWorkbench code as shown ls really noL requlred. llnally, Lhe r0 parameLer
should polnL Lo Lhe memory whlch has been seL aslde by Lhe Cnu compller for Lhe reLurn
value, so Lhe merged code ls modlfled Lo use r3 raLher Lhan Lhe sLack polnLer.
Pavlng compleLed Lhe merged flle, lL may be lncluded as an assembler source flle lnLo Lhe
overall pro[ecL and bullL accordlngly.
noLe LhaL lf Lhe locaLlon of Lhe lnpuL daLa varled beLween compllers, Lhls
secLlon of code would vary beLween Lhe Lwo assembler flles. ln such cases,
Lhe code hlghllghLed ln green would need Lo map Lhe lncomlng daLa from Lhe
prolog Lo Lhe formaL requlred for Lhe underlylng funcLlon.