SPRUI03F June 2015 – August 2025
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 sections that refer to the current or specified section are not eligible for removal via conditional linking. For example, you may use an .intvecs section to set up interrupt vectors. This section is eligible for removal during conditional linking by default. You can force the .intvecs section and sections that reference it to be retained by applying the .retain and .retainrefs directives to the .intvecs section.
The section name identifies a section. If a directive is used without a section name, it applies to the current initialized section. If a directive is applied to an uninitialized section, a section name is required. The section name must be enclosed in double quotes. Section names 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]