7.2. bin Extensions to the SECTION Directive

7.2. `bin` Extensions to the `SECTION` Directive
Prev	Chapter 7. `bin`: Flat-Form Binary Output	Next

7.2. `bin` Extensions to the `SECTION` Directive

The bin object format allows the use of multiple sections of arbitrary names. It also extends the SECTION (or SEGMENT) directive to allow complex ordering of the segments both in the output file or initial load address (also known as LMA) and at the ultimate execution address (the virtual address or VMA).

The VMA is the execution address. Yasm calculates absolute memory references within a section assuming that the program code is at the VMA while being executed. The LMA, on the other hand, specifies where a section is initially loaded, as well as its location in the output file.

Often, VMA will be the same as LMA. However, they may be different if the program or another piece of code copies (relocates) a section prior to execution. A typical example of this in an embedded system would be a piece of code stored in ROM, but is copied to faster RAM prior to execution. Another example would be overlays: sections loaded on demand from different file locations to the same execution location.

The bin extensions to the SECTION directive allow flexible specification of both VMA and LMA, including alignment constraints. As with other object formats, additional attributes may be added after the section name. The available attributes are listed in Table 7.1.

Table 7.1. bin Section Attributes

Attribute	Indicates the section
`progbits`	is stored in the disk image, as opposed to allocated and initialized at load.
`nobits`	is allocated and initialized at load (the opposite of `progbits`). Only one of `progbits` or `nobits` may be specified; they are mutually exclusive attributes.
`start=address`	has an LMA starting at `address`. If a LMA alignment constraint is given, it is checked against the provided address and a warning is issued if `address` does not meet the alignment constraint.
`follows=sectname`	should follow the section named `sectname` in the output file (LMA). If a LMA alignment constraint is given, it is respected and a gap is inserted such that the section meets its alignment requirement. Note that as LMA overlap is not allowed, typically only one section may follow another.
`align=n`	requires a LMA alignment of `n` bytes. The value `n` must always be a power of 2. LMA alignment defaults to 4 if not specified.
`vstart=address`	has an VMA starting at `address`. If a VMA alignment constraint is given, it is checked against the provided address and a warning is issued if `address` does not meet the alignment constraint.
`vfollows=sectname`	should follow the section named `sectname` in the output file (VMA). If a VMA alignment constraint is given, it is respected and a gap is inserted such that the section meets its alignment requirement. VMA overlap is allowed, so more than one section may follow another (possibly useful in the case of overlays).
`valign=n`	requires a VMA alignment of `n` bytes. The value `n` must always be a power of 2. VMA alignment defaults to the LMA alignment if not specified.

Only one of start or follows may be specified for a section; the same restriction applies to vstart and vfollows.

Unless otherwise specified via the use of follows or start, Yasm by default assumes the implicit ordering given by the order of the sections in the input file. A section named .text is always the first section. Any code which comes before an explicit SECTION directive goes into the .text section. The .text section attributes may be overridden by giving an explicit SECTION .text directive with attributes.

Also, unless otherwise specified, Yasm defaults to setting VMA=LMA. If just “valign` is specified, Yasm just takes the LMA and aligns it to the required alignment. This may have the effect of pushing following sections” VMAs to non-LMA addresses as well, to avoid VMA overlap.

Yasm treats nobits sections in a special way in order to minimize the size of the output file. As nobits sections can be 0-sized in the LMA realm, but cannot be if located between two other sections (due to the VMA=LMA default), Yasm moves all nobits sections with unspecified LMA to the end of the output file, where they can savely have 0 LMA size and thus not take up any space in the output file. If this behavior is not desired, a nobits section LMA (just like a progbits section) may be specified using either the follows or start section attribute.