initialize directive
Syntax
initialize { bycopy|manually} [ withparam,param...] {section-selectors} [ except {section-selectors} ];
where param can be one of:
packing = algorithm
simple ranges
complex ranges
no exclusions
load address support
alignment preservation
copy friendly
For information about section selectors and except clauses, see Section selection.
Parameters
| Splits the section into sections for initializers and initialized data, and handles the initialization at application startup automatically. Note that it is not possible to combine defining blocks |
| Splits the section into sections for initializers and initialized data. The initialization at application startup is not handled automatically. |
| Specifies how to handle the initializers. Choose one of these algorithms:
|
| Selects the simple ranges decompressor variant. |
| Selects the complex ranges decompressor variant. |
| Emits an error if any sections are excluded from initialization. |
| Makes references to |
| Makes the alignment of the initializers the same as the initialized section. |
| This parameter is equal to specifying both |
Description
The initialize directive splits each selected section into one section that holds initializer data and another section that holds the space for the initialized data. The section that holds the space for the initialized data retains the original section name, and the section that holds initializer data gets the name suffix _init. You can choose whether the initialization at startup should be handled automatically (initialize by copy) or whether you should handle it yourself (initialize manually). Optionally, you can use the linker option --initializer_prefix to add a prefix to the sections that hold initializer data, see --initializer_prefix.
When you use the packing method auto (default for initialize by copy), ILINK will automatically choose an appropriate packing algorithm for the initializers. To override this, specify a different packing method. The ‑‑log initialization option shows how ILINK decided which packing algorithm to use.
When initializers are compressed, a decompressor is automatically added to the image.
Each decompressor has two variants: one that can only handle a single source and destination range at a time, and one that can handle more complex cases. By default, the linker chooses a decompressor variant based on whether the associated section placement directives specify a single or multi-range memory region. In general, this is the desired behavior, but you can use the with complex ranges or the with simple ranges modifier on an initialize directive to specify which decompressor variant to use. You can also use the command line option ‑‑default_to_complex_ranges to make initialize directives by default use complex ranges. The simple ranges decompressors are normally hundreds of bytes smaller than the complex ranges variants.
When initializers are compressed, the exact size of the compressed initializers is unknown until the exact content of the uncompressed data is known. If this data contains other addresses, and some of these addresses are dependent on the size of the compressed initializers, the linker fails with error Lp017. To avoid this, place compressed initializers last, or in a memory region together with sections whose addresses do not need to be known.
Due to an internal dependence, generation of compressed initializers can also fail (with error Lp021) if the address of the initialized area depends on the size of its initializers. To avoid this, place the initializers and the initialized area in different parts of the memory (for example, the initializers are placed in ROM and the initialized area in RAM).
If you specify the parameter no exclusions, an error is emitted if any sections are excluded (because they are needed for the initialization). no exclusions can only be used with initialize by copy (automatic initialization), not with initialize manually.
If you use initialize manually, you can specify that references to the Load$$ family of symbols should use the corresponding section$$section_init$$ symbol instead, by using the parameter load address support.
Unless initialize manually is used, ILINK will arrange for initialization to occur during system startup by including an initialization table. Startup code calls an initialization routine that reads this table and performs the necessary initializations.
Zero-initialized sections are not affected by the initialize directive.
The initialize directive is normally used for initialized variables, but can be used for copying any sections, for example, copying executable code from slow ROM to fast RAM, or for overlays. For another example, see define overlay directive.
Sections that are needed for initialization are not affected by the initialize by copy directive. This includes the __low_level_init function and anything it references.
Anything reachable from the program entry label is considered needed for initialization unless reached via a section fragment with a label starting with __iar_init$$done. The ‑‑log sections option, in addition to logging the marking of section fragments to be included in the application, also logs the process of determining which sections are needed for initialization.
You can use the alignment preservation parameter to make the alignment of the initializers the same as the alignment of the initialized section. If you do not specify this parameter, the alignment of the initializers is either 1 (if compression is used) or aligned for memcpy (typically 4).
Example
/* Copy all read-write sections automatically from ROM to RAM at program start */
initialize by copy { rw };
place in RAM { rw };
place in ROM { ro };See also
Initialization at system startup, and do not initialize directive.