Linker Reference Manual
Contents
1. Example System Configuration File The following is an example of a system configuration file 25 RCR RAM collision rate percent 133 mhz System clock frequency MPC Freescale Power Architecture In engine A the LOW priority is longer than the MIDDLE So latency is 1 low 1 high shorter MIDDLE not used Engine Channel Function Priority MaxWCL microseconds A 3 UART high 0 95 page 36 Linker Reference Manual C 2007 2015 5 System Configuration Analyses A 4 PWM middle A 5 PWM low In engine A the LOW priority is longer than the MIDDLE So latency is 1 low 1 high shorter MIDDLE not used Engine Channel Function Priority MaxWCL microseconds B 3 QOM high 1 40 B 4 UART middle B 5 UART low The linker generates the following information in the analyses file based on the System Configuration file listed above Worst Case Latency on fe fes pe fs perom fir fan once fe fas en CT CT CT 0 76 us 1 32 us Engine B Channel 3 QOM CR 14005 173 31 0 56 us 2 85 us Engine B Channel 4 UART Middle 30 14 es 0 56 us 5 14 us Engine B Channel 5 UART Les Pie D 16 C 2007 2015 Linker Reference Manual page 37 5 System Configuration Analyses Note WCTL Worst Case Thread Length includes the Steps RAM s TST s Time Slot Transitions and TST RAM s with RCR RAM Collision Rate factored in The two numbers in parantheses are the inst2. C 2007 2015 page 8 Linker Reference Manual 1 Command Line Options License reference manual Display Version Displays the tool name and version number and exits with a non zero exit code without linking Display Licensing Info Outputs the licensing information for this tool Console Message Verbosity Control the verbosity of the linker message output Console Message Suppression Suppress console messages by their type class Multiple types can be specified with multiple verbSuppress options version license license verb lt N gt where N can be in the range of 0 no console output to 9 verbose message output verbSuppress verbSuppress lt T YP SUMMARY E gt where TYPE can be BANNER the ETEC version amp copyright banner SUMMARY the success failure warning error count summary line WARNING all warning messages C 2007 2015 Linker Reference Manual page 9 1 Command Line Options ERROR all error messages does not affect the tool exit code Disable a specific warning warnDis lt ID gt Off WarnDis 41065 where ID is the warning s identification number Strictly treat warnings as Strict Disabled Strict errors If a link warning is encountered treat it as an error such that the link fails Input File Options List of Object Files to link lt ObjectFile1 gt etpuc_cam eao lt ObjectFile2 gt etpuc_crank eao lt ObjectFi
3. if TransitionALatch if TransitionBLatch Global Error 1 error ClearAllLatches 1 IL error 0x0800 1 IL error 0x1000 Legacy mode function that accesses the user defined error handler if IsLinkServiceRequestEvent Test accessing a user error handler in etpuc mode Global Error Func In ETEC mode a user defined global error handler is declared as a thread then inserted directly into the event vector table as follows Get a pointer to the global error handler data extern int _Global_error_data _eTPU_thread MyGlobalErrorHandler eTPU matches enabled Set bit 22 this is user defined error 2 Global error data 1 lt lt 22 Set one or more invalid entries to point the the user defined error handler DEFINE ENTRY TABLE TestClass TestClass standard inputpin autocfsr 1 HSR LSR M1 M2 PIN FO F1 vector sus SNIP 33 ETPU_VECTOR1 0 1 1 1 x 0 x MyGlobalErrorHandler ss SNIP 22 5 page 30 Linker Reference Manual C 2007 2015 3 Global Error Handling C 2007 2015 Linker Reference Manual page 31 page 32 Linker Reference Manual 4 1 4 2 4 Entry Table 4 Entry Table This section covers the entry table Entry Table Base Address assignment There is a command line argument for specifying the entry table base address The eTPU architecture forces the entry table base address to be on a 2K boundary Additionally the entire entry table must be lo
4. no flush seq goto MyFunc2 no flush Sg i oe 9 25 Hard Coded Value Limitation All executable code must be generated using either the assembler or compiler No opcodes generated by hard coding a value are allowed A hard coded opcode is generated when a value is forced as an opcode as follows hex 3F190FF9 Instead in all cases an equivalent valid opcode can be generated using assembly as follows asm alu a a gt gt R p C 2007 2015 Linker Reference Manual page 51 9 Optimization Limitations 9 2 6 Multiply Divide Unit MDU Limitations The MDU significantly complicates the optimizer analyzer because the MDU s results are not available until multiple instructions later When writing code using ETEC there is no issue with multiplies and divides because the compiler generates code that the linker optimizer can handle However when writing code in inline or regular assembly the restriction covered here applies Currently following each MDU operation the following logic that causes the MDU to spin until the operation is completed as indicated by the MacBusy MB flag is required An example of this is shown below asm mdu p macs a MAC BUSY SPIN LOOP if mb I then goto MAC BUSY SPIN LOOP flush alu p mach endasm page 52 Linker Reference Manual C 2007 2015
5. Compiler Inline Assembly Limitations The limitations for inline assembly are the same as those listed in the assembly limitations section C 2007 2015 Linker Reference Manual page 49 9 Optimization Limitations 9 2 9 2 1 9 2 2 9 2 3 page 50 Linker Reference Manual Assembly Optimizer Limitations There are quite a few optimizer limitations to assembled code however these limitations are all detected by the optimizer such that the optimizer will detect and report any constructs that prevent optimization Detected constructs that prevent optimization result in the optimize link stage being abandoned and such that no invalid code is generated Indeterminate Return Value Limitation The optimizer needs to fully understand all possible paths and this is not possible when the RAR register has an un initialized or otherwise indeterminate value For instance the following constructs causes the optimization to fail because the RAR register value is unknown at the time of the return ThreadStart seq return The following construct also causes the optimizer to fail for the reason that if the call is not taken then the RAR register is un initialized ThreadStart seq if n false then call MyFunc flush seq return Hard Coded Return Address Limitation The optimizer does not support code that hardcodes the return address Any writes to the return address register using an ALU instruction is not supported An example
6. assignment begins with 31 and continues with progressively lower numbered values If the entry table is located at address zero but there are user assigned CFSR values then the linker assigns CFSR values starting with the highest numbered value and assigns progressively lower numbered values until zero is reached Then progressively higher numbered values are assigned If the entry table is NOT located at zero and there ARE user assigned CFSR values then CESR values assignment begins with the lowest user assigned CESR value and continues upwards to 31 Then progressively lower numbered values are assigned page 34 Linker Reference Manual C 2007 2015 5 1 5 System Configuration Analyses 9 System Configuration Analyses A system configuration file supports advanced analyses of the generated eTPU code in an actual system System parameters such as system clock speed channel priorities and channel assigned functions are specified Results are displayed in the analyses file System Configuration File The system configuration file is a text file that the user edits to specify the system configuration The linker uses the information contained in this file along with the functional parameters in the code to determine things such as Worst Case Latency for a channel The file is specified on the command line using the sysConfig lt FileName gt The format is line based which each line may contain a single setting or acomment R
7. entry table The entry table supports up to 32 functions but it is rare to actually use all 32 functions The unused entries are considered to be invalid and in normal operation would never get accessed C 2007 2015 Linker Reference Manual page 25 3 Global Error Handling 3 4 3 5 page 26 Linker Reference Manual It is an error to access an unused function in the entry table When possible unused entries are filled with the following address _Error_handler_entry It is not always possible to fill unused entries with this address because unused portions of the entry table can be used to hold code So this address is used where the entry table contains neither eTPU functions nor eTPU code In the SCM OFF Weeds Error Handling The address space of the eTPU is 64K but Freescale generally only fills a very small portion of this code space with physical memory For example the very first MPC5554 version had only 12K of code memory So what happens if due to an error the thread of execution should occur in the unused 52K of code space It is an error to execute from the unused portion of the SCM code memory and when this happens the actual opcode that gets executed is specified by the SCMDATAOFFR register ETEC provides an SCMDATAOFFR register value see the SCM OFF OPCODE define in the auto defines header section that will cause the following error handler to execute Error handler scm off weeds Note that this error hand
8. files into the empty range See the command line options section for a description of how to specify the amount of global memory to allocate for legacy compiler generated COD code C 2007 2015 Linker Reference Manual page 45 8 Linking Legacy COD Code 8 2 8 3 8 4 page 46 Linker Reference Manual Disabling optimization on legacy code Optimizations on legacy code default to enabled When enabled the entry table will likely change to adjust address pointers to the size reduced code and to optimize preloads Opcodes may change some due to optimization though unchanged opcodes will have a bias toward retention of their original packing Optimizations for the imported legacy code COD can be disabled see the command line options for a description of how this is done With optimizations disabled the entry table and executable portions of the code image remain unchanged though any dead space between the entry table and code will use the ETEC fill algorithm The ETEC optimizer makes assumptions about code behavior and certain legacy compiler features may violate these assumptions such that the ETEC optimizer should not be enabled legacy compiler generated code The following is a list of the known features Register allocation to global or static variables The ETEC optimizer assumes that registers need not retain their value across threads Legacy Code Limitations The following restrictions apply to the legacy
9. most up to date list LOLI Note that unsupported compiler versions will in all likelihood still work If the version of the compiler that you are using is not on the supported versions list please contact ASH WARE for support of your compiler version Qualifying Unsupported eTPU_C Versions Although code generated by unsupported eTPU_C compiler versions will generally function when imported it is possible to qualify unsupported versions using the process described in this section The key issue in the qualification process is that not all eTPU C compiler versions are available to ASH WARE Therefore to qualify your eTPU_C compiler version the following process has been established TODO develop a standard test suite e Customer requests ASH WARE to support a specific eTPU_C compiler version e ASH WARE provides customer with a test build suite e Customer builds the test suite and provides ASH WARE with the resulting COD file e ASH WARE adds the COD file to the ETEC test suite and assuming it passes all tests adds this COD version to the list of supported compilers C 2007 2015 9 1 9 Optimization Limitations 9 Optimization Limitations This section covers optimization limitations Compiler Optimizer Limitations The Return Address Regester RAR cannot be written within a called C function For instance the following construct is not allowed MyCFunc rar lt SomeNumber gt
10. page 19 page 20 Linker Reference Manual 2 1 2 Code Location 2 Code Location There is almost no reason at all for the user to care about code location so this section is kind of like describing the difference between blue and red to a color blind person Having said that code gets located beginning at address zero and continues upward The big issues are the entry table and unbreakable code chunks An unbreakable code chunk is a section of code that must remain contiguous in order to function properly and the definition of functioning properly varies between the compiler and assembler Entry table locating is done first followed by code locating If an unbreakable code chunk would over write the entry table then it is moved in its entirety to the first available opcode slot after the entry table ASH WARE reserves the right to change this algorithm but in any case if you are doing something that depends on the locating algorithm then this author suspects you are doing something wrong Code Size Although the eTPU has a code space of 64K bytes the various microcontrollers only populate a portion of this For instance some eTPU derivates in the Coldfire family populate 6K bytes and some eTPU derivatives in the MPC55xx family populate 12K To accommodate this variation in code size between the different eTPU derivates there is a command line argument for specifying the amount of code space actually popul
11. Instruction Packing Convention 40 Linker Reference Manual page 3 Linker Reference Manual Part 7 Part 8 8 1 8 2 8 3 8 4 8 5 8 6 8 7 Part 9 9 1 9 2 Channel HW Sub Instruction Re Ordering 43 Linking Legacy COD Code 45 Legacy Global Memory Allocation ss 45 Disabling optimization on legacy code rrnnnnnnnnnnnnnnnnnnnnnnnnnennnnnnnennnnnnnenn 46 Legacy Code Limitations ssneenns 46 Legacy Restrictions on ETEC nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnennnnnnnennnnnnnennnnnnneenn 46 Legacy ETEC Interactions annnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnennnnnnnennnnnnnennnnnnneen 47 Legacy ETEC Misc Notes sssnnrerennenenennneneennns 47 Auto Header and Auto Defines Information Validity 47 Invalid Legacy Auto Header Information sise 48 Supported ETPU_C Compiler Versions iiiinrrnnnnnnns 48 Qualifying Unsupported eTPU C Versions nine 48 Optimization Limitations 49 Compiler Optimizer Limitations ss 49 Compiler Inline Assembly Limitations iii 49 Assembly Optimizer Limitations rennnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnennnnnnnennnnnnn 50 Indeterminate Return Value Limitation sise 50 Hard Coded Return Address Limitation ins 50 Register Storage between Threads Limitation rernnnvnnnnvvnnnnvnnnnvnnnnnnnnnnnnnnnnnnnnn 50 Invalid Construct Limitation nee 51 Hard Coded Value Limitation rmvesernvrnnrnnennvnnvnnvnnvnnvnnenn
12. It is in these cases that the use of ImpDataEnd is required for most COD file imports it is not required For example if the imported COD uses the 3 byte unit at Ox3FD as temporary storage and uses up through 0x55 in low global memory then the ideal linker options would be ImpData 0x58 ImpDataEnd 0x3FC Disable Imported ImpOpt Disabled ImpOpt Executable Optimizations Optimizations on the imported legacy COD executable file default to enabled This option overrides the default such that optimizations are disabled for imported executables Disable Import of the ErrorLib Enabled ErrorLib Default Error Handling Library When this option is specified the default error handling library is not imported and the memory fill is 0 unless otherwise specified Once disabled users can page 12 Linker Reference Manual C 2007 2015 1 Command Line Options provide their own error handlers using the error handler names _Error_handler_entry etc Output File Options Output File To Produce None out MyOutputFile Executable file name out lt BaseFileName gt Suppress ELF DWARF File elf Generate Generation Suppress Entry Table Debug etdbg Generate Data Some consumers of ELF DWARF files may not be compatible with the entry table debug data this disables its output Output a global data elfgd segment in the ELF output global DWARF file data segment When this opti
13. Linker Reference Manual by John Diener and Andy Klumpp ASH WARE Inc Version 2 40 ASH 11 1 2015 C 2007 2015 ASH WARE Inc page 2 Linker Reference Manual Linker Reference Manual Table of Contents Foreword 5 Part 1 Command Line Options 7 Part 2 Code Location 21 2 1 Gode Size A RIA nee ni fre mnt A Tes enDe rise dec r esse agente es gens 21 Part3 Global Error Handling 23 3 1 Global Error Data iea ena nee doe cdeleevevteceseccecnerevuate ds 24 3 2 Error Handling Library rrernnnnnnvnnnnnnnnnnnnnnnnnnnnnnnennnnnnnnnnnnnnnnnnnnnnnnnnnnnennnnnnr 25 3 3 Invalid Entry Error Handling ss 25 3 4 In the SCM OFF Weeds Error Handling 26 3 5 In the FILL Weeds Error Handling 26 3 6 Unexpected Thread Error Handling 27 3 7 Extending the Error Handler ss 28 3 8 Accessing the Error Handler ss 28 3 9 Creating a User Defined Error Handler 29 Part 4 Entry Table 33 4 1 Entry Table Base Address assignment 33 4 2 CFSR Assignment E E 33 Part5 System Configuration Analyses 35 5 1 System Configuration File ses 35 Part 6 Channel Hardware Instruction Packing 39 6 1 Channel Hardware Sub
14. access a user defined error handler from C that was written in assembly the error handler must be declared as a fragment as follows _eTPU thread Error handler user eTPU matches enabled In ETEC mode these factory defined and user defined error handlers can also be directly injected into the event vector table as follows DEFINE ENTRY TABLE TestClass TestClass standard inputpin autocfsr HSR LSR M1 M2 PIN FO F1 vector ETPU_VECTOR1 1 x x x 0 0 x Error handler user Xose SNIP s4 gt ETPU VECTORL 5 x X X X X X _Error_handler_user ETPU_VECTOR1 6 xX X X X X X _Error_handler_entry ETPU_VECTOR1 7 x X x X X x MyThread ETPU VECTOR1 0 1 1 1 x 0 x Error handler user X rae SNIP ac gt ETPU_VECTOR1 0 1 1 0 x 1 x Error handler user 3 9 Creating a User Defined Error Handler A user defined error handler can be defined using a fragment Use of a fragment is an efficient method because a fragment reduces and in this case eliminates the call return overhead From within the thread simply call the fragment as follows Declare the global error handler as a fragment to eliminate the call return overhead _eTPU_fragment Global Error Func C 2007 2015 Linker Reference Manual page 29 3 Global Error Handling int LI error chan if LinkServiceRequest 1 I error 0x0100 if MatchALatch 1 1 error 0x0200 if MatchBLatch 1 Il error 0x0400
15. am Collision Rate lt PERCENT gt RCR The ram collision rate is specified by the collision rate in percent 0 to 100 Clock Frequency lt FREQUENCY gt mhz System clock frequency in megahertz C 2007 2015 Linker Reference Manual page 35 5 System Configuration Analyses Processor Family lt PROCESSOR FAMILY gt Processor family Valid values are MCF Coldfire MPC Freescale Power Architecture or SPC STMicro Power Architecture Note that the Freescale and STMicro power architectures both take two system clocks to execute one eTPU instruction In the Coldfire architecture each eTPU instruction takes four system clocks to execute OUCH Channel Configuration lt Engine gt lt CHANNEL gt lt FUNCTION gt lt PRIORITY gt lt MAX_WCTL gt ENGINE is the engine of the channel being specified valid values are A and B CHANNEL is the channel number being specified valid range is 0 to 31 FUNCTION is the name of the eTPU Function for legacy style code or the name of the eTPU Class for ETEC style code PRIORITY is the priority assigned to that channel Valid values are high middle and low MAX WCTL is an optional parameter that specifies that maximum allowed Worst Case Thread Length WCTL in micro seconds The link will fail if the calculated WCTL exceeds this specified maximum Comments This is an example C style comment Comment lines using a leading double slashes Empty lines are also treated as comments
16. ated C 2007 2015 Linker Reference Manual page 21 2 Code Location This code size must be aligned to a 2K boundary and must be between 2K and the maximum code space allowed by the eTPU instruction set which is 64K page 22 Linker Reference Manual C 2007 2015 3 Global Error Handling Global Error Handling A variety of causes including alpha particles coding errors and silicon defects could cause eTPU code to execute in un intended ways The key issues to consider are error detection and error correction Undetected errors are the bane of electronic reliability because the probability of their presence accumulates over time code size hours spent coding etc Therefore ETEC places primary emphasis on error detection and has built in hooks for detection of many errors Error correction on the other hand is considered to be the in the user s domain and ASH WARE strongly recommends that each system designer carefully designs their systems with error correction strategies in place Having said that ETEC does support default error correction mechanisms If these default mechanisms are not overridden they will correct a variety of detected error cases The default error handling mechanism is disabled or overridden by using the ErrorLib linker command line option ASH WARE recommends that users create specially named error handlers for a variety of possible error scenarios These handlers are generally written in assemb
17. cannot fit into a single opcode but A and B can fit together and B and C can fit together as well Either of the following two packing combinations satisf the over simplified packing convention as described up to this point Opcode 1 Sub Instruction A Sub Instruction B Opcode 2 Sub Instruction C Or Opcode 1 Sub Instruction A Opcode 2 Sub Instruction B Sub Instruction C Therefore the packing definition is ambiguous and requires further description Starting from the top of the source code lowest line number and working towards the bottom of the file channel hardware sub instructions are packed into opcodes When a sub instruction is encountered that will not fit into the opcode being packed then a new opcode is generated and newly encountered sub instructions are packed into this newly page 40 Linker Reference Manual C 2007 2015 6 Channel Hardware Instruction Packing generated opcode This packing convention only applies to channel hardware sub instructions and only to those sub instructions with ordering dependencies The following sub instruction fields are specifically excluded FLC and CIRC These packed opcodes may experience some movement to reduce code size but in all cases the movement will not result in any functional variation except as noted elsewhere in the documentation With this fully defined description ONLY the following packing order can occur Opcode 1 Sub Instruction A Sub Ins
18. cated within the boundaries of the amount of code actually populated in the eTPU derivate CFSR Assignment Each entry table is assigned a CFSR register value Although this can be done by the user in the compiler and assembler it is generally preferable to allow the linker to assign CFSR values This section describes how un assigned CFSR values are assigned Although this section might seem interesting especially to those who enjoyed the math portion of the SAT specifics of this algorithm should not be counted on by the user In fact ASH WARE reserves the right to change this algorithm with future linker releases Use the auto defines capability to determine which CFSR value the linker has actually assigned to each entry table C 2007 2015 Linker Reference Manual page 33 4 Entry Table The linker assigns un assigned CESR values using the algorithms described here The specific algorithm used depends on whether or not the entry table base address is at address zero the default and if there are any user assigned CESR values The intent of this algorithm is to reduce the number and size of gaps in the entry table thereby improving the code packing efficiency If the entry table is located at address zero and there are no user assigned CFSR values then CFSR assignment begins with zero and continues with progressively higher numbered values If the entry table is NOT located at zero and there are no user assigned CFSR values then
19. compiler generated code The entry table must be located at address zero the normal default Only COD compiler versions TBD are supported Enabling of optimizations for legacy generated code may invalidate any legacy auto generated code The COD s fill opcode is ignored and the ETEC fill algorithm is used instead Legacy Restrictions on ETEC Linking with legacy compiler generated code places some restrictions on the ETEC generated code that can be linked The entry table must be located at address zero ETEC generated code cannot specify a function number that is used by the legacy compiler generated code There must be a gap between the end of the legacy generated entry table and the start of legacy generated code into which the ETEC generated entry table gets placed TBD Can we relocate the BC generated code C 2007 2015 8 5 8 6 8 7 8 Linking Legacy COD Code When compiling the legacy code use the legacy org statement to generate this gap Legacy ETEC Interactions Some interactions between the legacy compiler generated code and ETEC generated code are allowed as listed below Certain types of generally simple global variables declared in legacy generated code can be accessed by ETEC generated code These include the following int24 unsigned int24 int8 unsigned int8 int32 unsigned int32 global int unsigned int char unsigned char Legacy ETEC Misc Notes Ana
20. d not those set aside for future extension Note that the existing error library is accessed by jumping to label Error handler save states When entering this location the P_31_0 register contains the error bits that the user wishes to set File UserErrorHandler sta declare the external error handler data bit that will be set extern int32 Global error data Error handler user Set user defined error bit 2 and leave it in p 31 24 ram p 31 0 Global error data seq goto Error handler save states alu p 31 24 p 31 24 Oxl Set user defined error 2 3 8 Accessing the Error Handler It is possible to access the existing error handler library in both ETEC as well as Legacy mode To access the factory supplied error handlers directly in either mode they are called suchly Link service requests are not supported Make this error observable by calling a factory defined error handler if IsLinkServiceRequestEvent Error Detected the ETEC global error handler in etpuc mode Error handler entry page 28 Linker Reference Manual C 2007 2015 3 Global Error Handling Note that the three factory defined error handlers are defined in factory provided header file ETpu Lib as follows _eTPU_thread _Error_handler_entry _eTPU_matches_enabled _eTPU_thread _Error_handler_scm_off_weeds _eTPU_matches_enabled _eTPU_thread Error handler fill weeds _eTPU_matches_enabled To
21. de observable to the host software so that the problem does not remain undetected The Unexpected Thread error handler can be used both in ETEC mode and legacy mode C as well to detect these types of unexpected errors Note that no overhead is incurred using the methods described below The address of the error handler is injected directly into the entry table In ETEC mode simply add the following to any unused entries TS te 3 amp 7 5 X X X input X X X low enable Error handler unexpected thread Fa 0 In Legacy mode call the _Error_handler_unexpected_thread as a fragment from any unused threads For example do the following for t if hsr 1 Call the error handler as if a fragment The address will be injected directly into the entry table thereby incurring no overhead Error handler unexpected thread In the assemble entry table place the unexpected thread error handler directly in the table as follows hsr lsr transitionB transitionA pin flagl flag0 load matches LU 3 x x input 0 l x l 0 low enable Error handler unexpected thread C 2007 2015 Linker Reference Manual page 27 3 Global Error Handling 3 7 Extending the Error Handler It is possible to extend the custom error handler in assembly by adding assembly code that uses user defined error bits to extend the error library Care must be taken to use error bits set aside for the user an
22. e supports only multiples of 0x800 SCM Code Size CodeSize lt Bytes gt 0x1800 6K CodeSize 0x4000 Fill Opcode Override FillOpcode lt Val gt Jump to FillOpcode 0x123 error library Use specified opcode to fill any unused SCM code space Disable optimizations opt Enabled opt Optimizations default to enabled This option overrides the default such that optimizations are disabled Network License Options Retry Network License networkRetry lt N gt Off networkRetry 600 If unable to acquire a full license from the network license server the application will continue to re try periodically up to the specified number of seconds until it succeeds or the retry time expires Check out Network License Off Attempts to check out a networkCheckout lt Y networkCheckout page 18 Linker Reference Manual C 2007 2015 1 Command Line Options DEPOT ERIE annl SEM DD HH 2010 08 04 18 00 specified date and time MM gt The HH field is in 24 hour time No linking is done only the license check out An exit code of 0 indicates success non zero failure Check in Network License networkCheckin Off networkCheckin Returns a checked out license to the network license server This only needs to be done if the license is being returned before its checkout expiration date No linking is done An exit code of 0 indicates success non zero failure C 2007 2015 Linker Reference Manual
23. e Sub Instruction Packing Convention The channel hardware sub instruction packing convention documented in this section is the default for the ETEC compiler This packing convention is based on ASH WARE s understanding of the legacy compiler The legacy compiler packed channel hardware sub instructions based on an apparently un documented convention That is to say the packing scheme was apparently not documented but the convention would presumably stay the same from one release to the next such that code that functioned in a particular way in one release would retain that same functionality if built using a different compiler release The ETEC packing convention can be disabled using the pragma no_packing_convention and in fact the author recommends disabling the packing convention and instead explicitly specifying the packing constraints as described in section 5 1 Sub Instruction Packing Control Explicitly specifying the packing constraints both reduces code size and increases your own understanding of the quality critical issues associated with channel hardware sub instruction ordering Channel sub instructions that are located adjacently in source code are packed together This definition is ambiguous and requires further description To see that the definition is ambiguous consider the following three sub instructions Sub Instruction A Sub Instruction B Sub Instruction C Consider the case where A B and C
24. executable le c A set of data structures name used to initialize global and channel frame memory Defaults to the executable file name with idata appended to the base file name and c h extensions Suppress IData File idata Generate idata Generation SCM C File scm lt FileName gt None scm MyScmFile c C array of opcodes and entry table data to be included on the host side and copied into the eTPU s SCM Defaults to the executable file name with _scm appended to the base file name and a c extension Suppress SCM C file Generate scm generation Data Size 8 bit Override 32 bit data data8 By default scm and idata data is 32 bit this option overrides and results in 8 bit initialized array output Name of the analyses file to OutputFileBa rd C 2007 2015 Linker Reference Manual page 15 1 Command Line Options produce Defaults to the executable file name with ana appended to the base file name and an html extension Disable analysis file generation Generate Ist files When specified each source file that contributes to code generation is output into a list file with intermixed disassembly information They are named the same as the source file but with a Ist extension When just Ist is used the list files are placed in the executable output path When IstInSrc is used each individual list file is output in the directory that corresponds to its source f
25. ile Last the default executable output path for list files can be overridden by specifying a path with the Ist lt DirName gt option form Istaddr removes the address and opcode page 16 Linker Reference Manual where FileName is seName ana the name of the analyses file to product Enabled Ist Disabled IstInSrc lst lt DirName gt Istaddr C 2007 2015 Ana MyOverriden tName ana Ist IstInSrc Ist ListFiles 1 Command Line Options listings which puts the listing files into a format that is ideal for diff This is particularly helpful when comparing generated code for different compiler versions Generate map file Specify map Disabled Name es map lt FileName gt When specified a map myMapFile map file containing code amp data location information is output The default name is the executable name appended with a map extension in the executable output path The path and name can be overridden using the lt FileName gt option Code Generation Options Target Selection target lt TARGET gt ETPU1 target ETPU2 Select the destination where TARGET can processor for the be compilation ETPU1 compile for the baseline eTPU processor ETPU2 compile for the eTPU2 processor version C 2007 2015 Linker Reference Manual page 17 1 Command Line Options Entry Table Base Address etba lt Addr gt etba 0x800 Underlying architectur
26. leN gt System Configuration File optional sysConfig lt FileName sysConfig MySyst gt where FileName is emCfg SysCfg a file that describes the system configuration Describes system configuration such as system clock frequency which functions are running channels and their priority levels etc running on which channels and at which priority level This is used to calculate the page 10 Linker Reference Manual C 2007 2015 1 Command Line e O O O Ene Ones Worst Case Latency WCL based on the Worst Case Thread Length WCTL Results are displayed in the analyses file Import Executable Imp lt name cod gt None Imp Existing cod Includes a COD legacy file as part of the build Imported Executable Data ImpData lt Bytes gt None ImpData 0x224 Amount of Data Memory in bytes to allocate for the imported legacy COD file This setting is mandatory when importing a COD file Imported Executable Data ImpDataEnd lt byte None End Free Space address gt ImpDataEnd 0x3F When specified this 0 address indicates the end of the global address range available for locating global data from ETEC compiled code The globally addressable address space in the eTPU runs from 0x0 through 0x400 Some COD compilations locate global data both in low global memory and at high global memory leaving a gap in between C 2007 2015 Linker Reference Manual page 11 1 Command Line Options
27. ler will only execute if the define SCM OFF OPCODE lt value gt provided in the automatically generated header file is used to program the ETPUSCMOFFDATAR register In the FILL Weeds Error Handling Say you have 18K of available code memory but use only 15K The remaining 3K of code memory is essentially spare capacity So what happens if the thread of execution somehow moves to this extra 3K of code memory It is an error to execute from this spare memory ETEC defaults to filling this spare memory with a jump to the error handler listed below Note that a jump is used instead of a call so that the user can possibly determine an address based on the return address register RAR of any possible originating return that might have caused this code to get executed in the first place Error handler fill weeds C 2007 2015 3 6 3 Global Error Handling A related issue is the fill opcode specified on the command line If a fill opcode value is specified on the command line then this overrides the default fill opcode that ETEC would have used to jump to this error handler It is therefore an error to both specify a fill opcode and to override this error hander and in fact if a fill opcode is specified then ETEC will neither provide nor allow this error handler to exist Unexpected Thread Error Handling Say you have a function that does not support an incoming link event If a link does occur this is an error condition and should be ma
28. ly and have the following names _Error_handler_entry Error handler scm off weeds Error handler fill weeds Error handler unexpected thread C 2007 2015 Linker Reference Manual page 23 3 Global Error Handling These error handlers should be used to correct the error conditions described later in this section 3 1 Global Error Data If an error is detected information helpful in diagnosing the source of the error is placed in an automatically generated global variable named as follows _Global_error_data This 32 bit variable is used to encode error information as shown in the following table ee mw Spare js fuf fefufofsfefrfefsfefsfefifo EEEVS EECL EECN EESB Encoded Error Source Bits Bit indicates that such an error has been detected Bit 0 indicates that such an error has not been detected Bit 31 indicates that _Error_handler_entry has executed Bit 30 indicates that _Error_handler_scm_off_weeds has executed Bit 29 indicates that _Error_handler_fill_ weeds has executed Bit 28 indicates that _Error_handler_unexpected_thread has executed Bit 27 indicates that undefined ETEC error 2 has occurred Bit 26 indicates that undefined ETEC error 3 has occurred Bit 25 indicates that user defined error 1 has occurred Bit 24 indicates that user defined error 2 has occurred Bit 23 indicates that user defined error 3 has occurred Bit 22 indicates that user defined error 4 has occurred EEEVS Encoded E
29. lyses files are valid for etec generated code Disable optimizations on the legacy generated code to retain validity of certain legacy pragma writes auto header In many cases the legacy code s The ETEC generated auto defines file is valid In certain cases the legacy generated auto header must not be used For example the Auto Header and Auto Defines Information Validity Auto header files are generated by the legacy compiler and auto defines files are generated by the ETEC compiler In all cases information in the ETEC generated auto defines file is valid The safest route is simply to switch to the ETEC generated auto defines file but this may not be an option for all customers This section describes which information from the legacy generated auto header can still be used Information in the legacy generated auto header may or may not be valid depending on the nature of the information and on whether or not optimizations are enabled for the legacy generated code C 2007 2015 Linker Reference Manual page 47 8 Linking Legacy COD Code 8 7 1 8 7 2 8 7 3 page 48 Linker Reference Manual Invalid Legacy Auto Header Information The following list represents information in the legacy generated auto header that are not valid The code block MISC value Global Data Size Supported ETPU_C Compiler Versions The following is a list of supported versions at the time of this printing See our website for the
30. of an unsupported construct is found below alu ReturnAddr b Please contact the factory for hints on overcoming this limitation Register Storage between Threads Limitation It is not possible to store global static variables in registers such that their value remains valid between threads The optimizer assumes that all registers begin each thread with garbage data and that any final register writes at the end of a thread are garbage ThreadStart C 2007 2015 9 Optimization Limitations Seq diob diob 1 Diob contains the thread count Seq end In the above case the optimizer does not see the diob register value getting used between the increment and the end of the thread and therefore will eliminate the opcode 9 24 Invalid Construct Limitation If the Freescale lists a construct as being invalid then use of the construct will cause the optimizer to fail For instance a un flushed seq followed by an flushed seq results in indeterminate eTPU operation per the Freescale documentation seq goto MyFuncl no flush seq goto MyFunc2 flush Another invalid construct per the Freescale documentation is the destination of the first of two sequential un flushed branches being another change in flow instruction For example use of the following construct will cause the optimizer to fail because the first opcode in the called function is a change of flow MyFuncl seq return flush ThreadStart seq goto MyFuncl
31. on is specified a global data segment is generated in the ELF DWARF file It has R W attributes set and an alignment of 4 bytes Defines Header File To defines lt FileName gt Based on Produce executable defines MyDefine C 2007 2015 Linker Reference Manual page 13 1 Command Line RACE Mne i O OO O OOO OOOO A set of defines used name sFile h for host side drivers Defaults to the executable file name with defines appended to the base file name and a h extension Suppress Defines File defines Generate defines Generation Global Mnemonic GM lt Text gt The specified mnemonic gets pre pended to all names in the auto generated header file and executable image array C file This is useful when multiple images are to be used at host load time thereby avoiding naming conflicts Produce Auto Struct autostruct default auto struct Header File Specify Name deprecated file autostruct etpu_if_ A set of structure generation struct h declarations that can be used for host side driver development If no name is specified it defaults to autostruct disable the executable file name auto struct generation with _struct appended to the base file name and a h extension Initialized Data File to idata lt FileName gt idata MyInitDataFi C 2007 2015 autostruct lt FileName gt page 14 Linker Reference Manual 1 Command Line Options Produce
32. ruction steps and the RAM s Configuration e System clock frequency 133 MHz e Ram Collision Rate RCR 25 Processor family Freescale Power Architecture page 38 Linker Reference Manual C 2007 2015 6 Channel Hardware Instruction Packing 6 Channel Hardware Instruction Packing This section describes the most important improvement of this tools suite over other options and the capabilities described are the primary motivating factor behind the development of this compiler that and income of course Consider the following sub mstructions chan clear MatchRecognitionLatchA chan matchA ertA set MatchEnableLatcha It turns out that the parallel nature of the eTPU s instruction set allows these sub instructions to be packed into a single opcode But it is also possible that these sub instructions could be placed into separate opcodes and the trouble is that the eTPU s channel hardware behavior is vastly different depending on which way the optimizer packs these sub instructions The combination of lack of control and lack of documentation has driven this author into a state of apoplectic perdition for the last several years ETEC addresses this issue in two ways one is really good user control and one is well kinda good Convention Documentation These are described in the following two sections C 2007 2015 Linker Reference Manual page 39 6 Channel Hardware Instruction Packing 6 1 Channel Hardwar
33. they cannot join with these fields Conversely if these fields are upstream then they CAN join with these fields C 2007 2015 Linker Reference Manual page 43 page 44 Linker Reference Manual 8 1 8 Linking Legacy COD Code 8 Linking Legacy COD Code ETEC supports linking existing legacy mode eTPU code COD along with object files generated by the ETEC tools chain assembly and C source This capability allows users to migrate to the ETEC tools suite in a gradual manner Legacy Global Memory Allocation Global memory is normally associated with global variables but the legacy compiler also uses global memory to store values across function calls to pass function call variables and for dynamic local variables that overflow the register set The issue unfortunately is that there is no reliable way of determining the amount of global memory that is used by the legacy compiler and ETEC unfortunately requires that you pass this value to the ETEC linker via the command line ImpData In fact global memory allocation is even more complicated than that in some cases because at times a COD compilation also uses high global memory just below address 0x400 typically for temporary storage When this split global locating occurs in the COD file to imported the lower bound of this upper section of data must also be specified ImpDataEnd This allows ETEC to safely locate its global variables from ETEC compiled object
34. truction B Opcode 2 Sub Instruction C To summarize the key points presented in this section are as follows e For optimal quality reduced code size and full understanding of your code s behavior it is best to disable the packing convention described in this section and instead fully specify the packing order as described in the section 5 1 Sub Instruction Packing Control The packing convention defined in this section has been adopted to maximize backward compatibility with the legacy compiler The author recommends not relying on the legacy packing convention The legacy packing convention applies ONLY to channel hardware sub instructions C 2007 2015 Linker Reference Manual page 41 page 42 Linker Reference Manual 7 Channel HW Sub Instruction Re Ordering 1 Channel HW Sub Instruction Re Ordering The CIRC field is considered to be independent of all other channel hardware fields It can be re ordered with no restrictions It is restricted relative to RAM operations though It cannot pass any RAM operations Once in the same instruction as a RAM it cannot be re ordered The FLC field has no re ordering restrictions whatsoever The LSR field has no re ordering restrictions whatsoever It is tied to the TST channel not the channel register MRL and ERW form blocks relative to the following fields OPAC IPAC TDL TBS PSC PSCS MRLE PDCM PDCM and MTD If MRL and ERW are upstream then
35. vent States page 24 Linker Reference Manual C 2007 2015 3 2 3 3 3 Global Error Handling Bit 1 indicates that an event is active Bit 0 indicates that an event is not active Bit 15 contains the LINK state Bit 14 contains the Transition B state Bit 13 contains the Transition A state Bit 12 contains the Match B state Bit 11 contains the Match A state Bit 10 contains zero future expansion Bit 9 contains zero future expansion EECL Encoded Error Conditionals Bit 8 contains the sampled input pin state Bit 7 contains the current output pin state Bit 6 contains the flag 1 state if available Bit 5 contains the flag 0 state if available EECN Encoded Error Channel Number This is the active channel number of the last event handler New incoming event handlers overwrite this value such that if error handlers are executed multiple times then the number contains the last executed time Error Handling Library The ASH WARE defined error handlers are defined in a library named etec_error_handler lib for eTPU1 and etec error handler etpu2 lib for eTPU2 which is provided as part of ETEC The linker automatically includes one of these two libraries based on whether the linker is building for eTPU1 or eTPU2 The error handling library can be disabled from being included in the linking process via the ErrorLib command line option Invalid Entry Error Handling Threads get executed based on pointers found in the
36. vnnnnnnennennennennennennennennnnnnnnnenne 51 Multiply Divide Unit MDU Limitations ueesersenavrnvnnvrnvrnernnvnnennvnnensennennennnvnnnnnennene 52 page 4 Linker Reference Manual Linker Reference Manual Linker Reference Manual page 5 page 6 Linker Reference Manual 1 Command Line Options 1 Command Line Options Type the executable name with the h command line parameter to generate a list of the available options ETEC_link exe h The linker optimizer has the following format ETEC_link exe lt ObjectFilel gt lt ObjectFile2 gt lt options gt The lt options gt can be one or more of the following EFE Display Help This option overrides all others and when it exists no linking is actually done Open Manual Opens the electronic version of this Linker Reference Manual C 2007 2015 Linker Reference Manual page 7 1 Command Line Options Open a Specific Manual man lt MANUAL gt Off man ETPUCIM Opens an electronic where MANUAL is version of the specified one of the following manual TOOLKIT Toolkit User Manual COMP Compiler Reference Manual LINK Linker Reference Manual ASMES eTPU Assembler Reference Manual Freescale Syntax ASMAW eTPU Assembler Reference Manual ASH WARE Syntax ETPUSIM Stand Alone eTpu Simulator Reference Manual MTDT Common reference manual covering all simulator debugger products EXCEPT the eTPU Stand Alone simulator LICENSE
Download Pdf Manuals
Related Search