SPRUI03E June 2015 – January 2023
Conditionally Retain Sections In Object Module Output
.retain["section name"]
.retainrefs["section name"]
The .retain directive indicates that the current or specified section is not eligible for removal via conditional linking. You can also override conditional linking for a given section with the --retain linker option. You can disable conditional linking entirely with the --unused_section_elimination=off linker option.
The .retainrefs directive indicates that any sections that refer to the current or specified section are not eligible for removal via conditional linking. For example, applications may use an .intvecs section to set up interrupt vectors. The .intvecs section is eligible for removal during conditional linking by default. You can force the .intvecs section and any sections that reference it to be retained by applying the .retain and .retainrefs directives to the .intvecs section.
The section name identifies the section. If the directive is used without a section name, it applies to the current initialized section. If the directive is applied to an uninitialized section, the section name is required. The section name must be enclosed in double quotes. A section name can contain a subsection name in the form section name:subsection name.
The linker assumes that all sections by default are eligible for removal via conditional linking. (However, the linker does automatically retain the .reset section.) The .retain directive is useful for overriding this default conditional linking behavior for sections that you want to keep included in the link, even if the section is not referenced by any other section in the link. For example, you could apply a .retain directive to an interrupt function that you have written in assembly language, but which is not referenced from any normal entry point in the application.
This example of an interrupt function that has a .retain directive applied to it.
.sect ".text:interrupts:retain"
.retain
.global _int_func1
_int_func1:
STW .D2 FP,*SP++(-88) ; [B_D] |31|
STW .D2 B3,*SP(80) ; [B_D] |31|
STW .D2 A4,*SP(24) ; [B_D] |31|
STW .D2 B2,*SP(84) ; [B_D] |31|
STW .D2 B9,*SP(76) ; [B_D] |31|
STW .D2 B8,*SP(72) ; [B_D] |31|
STW .D2 B7,*SP(68) ; [B_D] |31|
STW .D2 B6,*SP(64) ; [B_D] |31|
STW .D2 B5,*SP(60) ; [B_D] |31|
STW .D2 B4,*SP(56) ; [B_D] |31|
STW .D2 B1,*SP(52) ; [B_D] |31|
STW .D2 B0,*SP(48) ; [B_D] |31|
STW .D2 A7,*SP(36) ; [B_D] |31|
STW .D2 A6,*SP(32) ; [B_D] |31|
STW .D2 A5,*SP(28) ; [B_D] |31|
CALL .S1 _foo ; [A_S] |32|
|| STW .D2 A8,*SP(40) ; [B_D] |31|
...
STW .D2 B4,*+DP(_a_i) ; [B_D] |33|
RET .S2 IRP ; [B_Sb] |34|
|| LDW .D2 *SP(56),B4 ; [B_D] |34|
LDW .D2 *++SP(88),FP ; [B_D] |34|
NOP 4 ; [A_L]