@@ -248,7 +248,7 @@ <h3 class="Ss" id="Symbol_interpolation"><a class="permalink" href="#Symbol_inte
248248</ div >
249249< p class ="Pp "> Although, for these examples, < code class ="Ic "> STRFMT</ code > would
250250 be more appropriate; see < a class ="Sx " href ="#String_expressions "> String
251- expressions</ a > further below.</ p >
251+ expressions</ a > below.</ p >
252252</ section >
253253</ section >
254254< section class ="Sh ">
@@ -262,7 +262,7 @@ <h2 class="Sh" id="EXPRESSIONS"><a class="permalink" href="#EXPRESSIONS">EXPRESS
262262 case, unless a label is involved, as explained in the
263263 < a class ="Sx " href ="#SYMBOLS "> SYMBOLS</ a > section. However, some operators
264264 can be constant even with non-constant operands, as explained in
265- < a class ="Sx " href ="#Operators "> Operators</ a > further below.</ p >
265+ < a class ="Sx " href ="#Operators "> Operators</ a > below.</ p >
266266< p class ="Pp "> The instructions in the macro-language generally require constant
267267 expressions.</ p >
268268< section class ="Ss ">
@@ -1200,15 +1200,17 @@ <h3 class="Ss" id="RAM_code"><a class="permalink" href="#RAM_code">RAM
12001200 the current < code class ="Ic "> LOAD</ code > block before performing its own
12011201 function.</ p >
12021202< p class ="Pp "> < code class ="Ic "> LOAD</ code > blocks can use the
1203- < code class ="Ic "> UNION</ code > modifier as described below, but not the
1204- < code class ="Ic "> FRAGMENT</ code > modifier.</ p >
1203+ < code class ="Ic "> UNION</ code > modifier as described in
1204+ < a class ="Sx " href ="#Unionized_sections "> Unionized sections</ a > below, but
1205+ not the < code class ="Ic "> FRAGMENT</ code > modifier.</ p >
12051206</ section >
12061207< section class ="Ss ">
12071208< h3 class ="Ss " id ="Unionized_sections "> < a class ="permalink " href ="#Unionized_sections "> Unionized
12081209 sections</ a > </ h3 >
12091210< p class ="Pp "> When you're tight on RAM, you may want to define overlapping
12101211 static memory allocations, as explained in the
1211- < a class ="Sx " href ="#Unions "> Unions</ a > section. However, a
1212+ < a class ="Sx " href ="#Allocating_overlapping_spaces_in_RAM "> Allocating
1213+ overlapping spaces in RAM</ a > section. However, a
12121214 < code class ="Ic "> UNION</ code > only works within a single file, so it can't
12131215 be used e.g. to define temporary variables across several files, all of
12141216 which use the same statically allocated memory. Unionized sections solve
@@ -1237,8 +1239,9 @@ <h3 class="Ss" id="Unionized_sections"><a class="permalink" href="#Unionized_sec
12371239</ ul >
12381240< p class ="Pp "> Different declarations of the same unionized section are not
12391241 appended, but instead overlaid on top of each other, just like
1240- < a class ="Sx " href ="#Unions "> Unions</ a > . Similarly, the size of an unionized
1241- section is the largest of all its declarations.</ p >
1242+ < a class ="Sx " href ="#Allocating_overlapping_spaces_in_RAM "> Allocating
1243+ overlapping spaces in RAM</ a > . Similarly, the size of an unionized section
1244+ is the largest of all its declarations.</ p >
12421245</ section >
12431246< section class ="Ss ">
12441247< h3 class ="Ss " id ="Section_fragments "> < a class ="permalink " href ="#Section_fragments "> Section
@@ -1335,8 +1338,8 @@ <h3 class="Ss" id="Labels"><a class="permalink" href="#Labels">Labels</a></h3>
13351338 < a class ="permalink " href ="#global "> < i class ="Em " id ="global "> global</ i > </ a >
13361339 (not to be mistaken with “exported”, explained in
13371340 < a class ="Sx " href ="#Exporting_and_importing_symbols "> Exporting and
1338- importing symbols</ a > further below). More than one dot in label names is
1339- not allowed.</ p >
1341+ importing symbols</ a > below). More than one dot in label names is not
1342+ allowed.</ p >
13401343< p class ="Pp "> For convenience, local labels can use a shorthand syntax: when a
13411344 symbol name starting with a dot is found (for example, inside an expression,
13421345 or when declaring a label), then the current “label scope” is
@@ -1853,39 +1856,6 @@ <h3 class="Ss" id="Predeclared_symbols"><a class="permalink" href="#Predeclared_
18531856< h2 class ="Sh " id ="DEFINING_DATA "> < a class ="permalink " href ="#DEFINING_DATA "> DEFINING
18541857 DATA</ a > </ h2 >
18551858< section class ="Ss ">
1856- < h3 class ="Ss " id ="Statically_allocating_space_in_RAM "> < a class ="permalink " href ="#Statically_allocating_space_in_RAM "> Statically
1857- allocating space in RAM</ a > </ h3 >
1858- < p class ="Pp "> < code class ="Ic "> DS</ code > statically allocates a number of empty
1859- bytes. This is the preferred method of allocating space in a RAM section.
1860- You can also use < code class ="Ic "> DB</ code > , < code class ="Ic "> DW</ code > and
1861- < code class ="Ic "> DL</ code > without any arguments instead (see
1862- < a class ="Sx " href ="#Defining_constant_data_in_ROM "> Defining constant data
1863- in ROM</ a > below).</ p >
1864- < div class ="Bd Pp Bd-indent Li ">
1865- < pre > DS 42 ; Allocates 42 bytes</ pre >
1866- </ div >
1867- < p class ="Pp "> Empty space in RAM sections will not be initialized. In ROM
1868- sections, it will be filled with the value passed to the
1869- < code class ="Fl "> -p</ code > command-line option, except when using overlays
1870- with < code class ="Fl "> -O</ code > .</ p >
1871- < p class ="Pp "> Instead of an exact number of bytes, you can specify
1872- < code class ="Ic "> ALIGN</ code > [< var class ="Ar "> align</ var > ,
1873- < var class ="Ar "> offset</ var > ] to allocate however many bytes are required to
1874- align the subsequent data. Thus, ‘< code class ="Ic "> DS
1875- ALIGN</ code > [< var class ="Ar "> align</ var > , < var class ="Ar "> offset</ var > ],
1876- < span class ="No "> ...</ span > ’ is equivalent to
1877- ‘< code class ="Ic "> DS</ code > < var class ="Ar "> n</ var > ,
1878- < span class ="No "> ...</ span > ’ followed by
1879- ‘< code class ="Ic "> ALIGN</ code > [< var class ="Ar "> align</ var > ,
1880- < var class ="Ar "> offset</ var > ]’, where < var class ="Ar "> n</ var > is the
1881- minimum value needed to satisfy the < code class ="Ic "> ALIGN</ code > constraint
1882- (see < a class ="Sx " href ="#Requesting_alignment "> Requesting alignment</ a >
1883- below). Note that < code class ="Ic "> ALIGN</ code > [< var class ="Ar "> align</ var > ]
1884- is a shorthand for
1885- < code class ="Ic "> ALIGN</ code > [< var class ="Ar "> align</ var > ,
1886- < span class ="No "> 0</ span > ].</ p >
1887- </ section >
1888- < section class ="Ss ">
18891859< h3 class ="Ss " id ="Defining_constant_data_in_ROM "> < a class ="permalink " href ="#Defining_constant_data_in_ROM "> Defining
18901860 constant data in ROM</ a > </ h3 >
18911861< p class ="Pp "> < code class ="Ic "> DB</ code > defines a list of bytes that will be
@@ -1927,8 +1897,8 @@ <h3 class="Ss" id="Defining_constant_data_in_ROM"><a class="permalink" href="#De
19271897 < code class ="Ic "> VRAM</ code > / < code class ="Ic "> SRAM</ code > section.</ p >
19281898</ section >
19291899< section class ="Ss ">
1930- < h3 class ="Ss " id ="Including_binary_files "> < a class ="permalink " href ="#Including_binary_files "> Including
1931- binary files</ a > </ h3 >
1900+ < h3 class ="Ss " id ="Including_binary_data_files "> < a class ="permalink " href ="#Including_binary_data_files "> Including
1901+ binary data files</ a > </ h3 >
19321902< p class ="Pp "> You probably have some graphics, level data, etc. you'd like to
19331903 include. Use < code class ="Ic "> INCBIN</ code > to include a raw binary file as
19341904 it is. If the file isn't found in the current directory, the include-path
@@ -1949,7 +1919,41 @@ <h3 class="Ss" id="Including_binary_files"><a class="permalink" href="#Including
19491919 be included.</ p >
19501920</ section >
19511921< section class ="Ss ">
1952- < h3 class ="Ss " id ="Unions "> < a class ="permalink " href ="#Unions "> Unions</ a > </ h3 >
1922+ < h3 class ="Ss " id ="Statically_allocating_space_in_RAM "> < a class ="permalink " href ="#Statically_allocating_space_in_RAM "> Statically
1923+ allocating space in RAM</ a > </ h3 >
1924+ < p class ="Pp "> < code class ="Ic "> DS</ code > statically allocates a number of empty
1925+ bytes. This is the preferred method of allocating space in a RAM section.
1926+ You can also use < code class ="Ic "> DB</ code > , < code class ="Ic "> DW</ code > and
1927+ < code class ="Ic "> DL</ code > without any arguments instead (see
1928+ < a class ="Sx " href ="#Defining_constant_data_in_ROM "> Defining constant data
1929+ in ROM</ a > below).</ p >
1930+ < div class ="Bd Pp Bd-indent Li ">
1931+ < pre > DS 42 ; Allocates 42 bytes</ pre >
1932+ </ div >
1933+ < p class ="Pp "> Empty space in RAM sections will not be initialized. In ROM
1934+ sections, it will be filled with the value passed to the
1935+ < code class ="Fl "> -p</ code > command-line option, except when using overlays
1936+ with < code class ="Fl "> -O</ code > .</ p >
1937+ < p class ="Pp "> Instead of an exact number of bytes, you can specify
1938+ < code class ="Ic "> ALIGN</ code > [< var class ="Ar "> align</ var > ,
1939+ < var class ="Ar "> offset</ var > ] to allocate however many bytes are required to
1940+ align the subsequent data. Thus, ‘< code class ="Ic "> DS
1941+ ALIGN</ code > [< var class ="Ar "> align</ var > , < var class ="Ar "> offset</ var > ],
1942+ < span class ="No "> ...</ span > ’ is equivalent to
1943+ ‘< code class ="Ic "> DS</ code > < var class ="Ar "> n</ var > ,
1944+ < span class ="No "> ...</ span > ’ followed by
1945+ ‘< code class ="Ic "> ALIGN</ code > [< var class ="Ar "> align</ var > ,
1946+ < var class ="Ar "> offset</ var > ]’, where < var class ="Ar "> n</ var > is the
1947+ minimum value needed to satisfy the < code class ="Ic "> ALIGN</ code > constraint
1948+ (see < a class ="Sx " href ="#Requesting_alignment "> Requesting alignment</ a >
1949+ below). Note that < code class ="Ic "> ALIGN</ code > [< var class ="Ar "> align</ var > ]
1950+ is a shorthand for
1951+ < code class ="Ic "> ALIGN</ code > [< var class ="Ar "> align</ var > ,
1952+ < span class ="No "> 0</ span > ].</ p >
1953+ </ section >
1954+ < section class ="Ss ">
1955+ < h3 class ="Ss " id ="Allocating_overlapping_spaces_in_RAM "> < a class ="permalink " href ="#Allocating_overlapping_spaces_in_RAM "> Allocating
1956+ overlapping spaces in RAM</ a > </ h3 >
19531957< p class ="Pp "> Unions allow multiple static memory allocations to overlap, like
19541958 unions in C. This does not increase the amount of memory available, but
19551959 allows re-using the same memory region for different purposes.</ p >
@@ -1999,6 +2003,34 @@ <h3 class="Ss" id="Unions"><a class="permalink" href="#Unions">Unions</a></h3>
19992003 < a class ="Sx " href ="#Statically_allocating_space_in_RAM "> Statically
20002004 allocating space in RAM</ a > ).</ p >
20012005</ section >
2006+ < section class ="Ss ">
2007+ < h3 class ="Ss " id ="Requesting_alignment "> < a class ="permalink " href ="#Requesting_alignment "> Requesting
2008+ alignment</ a > </ h3 >
2009+ < p class ="Pp "> While < code class ="Ic "> ALIGN</ code > as presented in
2010+ < a class ="Sx " href ="#SECTIONS "> SECTIONS</ a > is often useful as-is, sometimes
2011+ you instead want a particular piece of data (or code) in the middle of the
2012+ section to be aligned. This is made easier through the use of mid-section
2013+ < code class ="Ic "> ALIGN</ code > < var class ="Ar "> align</ var > ,
2014+ < var class ="Ar "> offset</ var > . It will retroactively alter the section's
2015+ attributes to ensure that the location the < code class ="Ic "> ALIGN</ code >
2016+ directive is at, has its < var class ="Ar "> align</ var > lower bits equal to
2017+ < var class ="Ar "> offset</ var > .</ p >
2018+ < p class ="Pp "> If the constraint cannot be met (for example because the section
2019+ is fixed at an incompatible address), an error is produced. Note that
2020+ < code class ="Ic "> ALIGN</ code > < var class ="Ar "> align</ var > is a shorthand for
2021+ < code class ="Ic "> ALIGN</ code > < var class ="Ar "> align</ var > ,
2022+ < span class ="No "> 0</ span > .</ p >
2023+ < p class ="Pp "> There may be times when you don't just want to specify an
2024+ alignment constraint at the current location, but also skip ahead until the
2025+ constraint can be satisfied. In that case, you can use < code class ="Ic "> DS
2026+ ALIGN</ code > [< var class ="Ar "> align</ var > , < var class ="Ar "> offset</ var > ] to
2027+ allocate however many bytes are required to align the subsequent data.</ p >
2028+ < p class ="Pp "> If the constraint cannot be met by skipping any amount of space,
2029+ an error is produced. Note that
2030+ < code class ="Ic "> ALIGN</ code > [< var class ="Ar "> align</ var > ] is a shorthand
2031+ for < code class ="Ic "> ALIGN</ code > [< var class ="Ar "> align</ var > ,
2032+ < span class ="No "> 0</ span > ].</ p >
2033+ </ section >
20022034</ section >
20032035< section class ="Sh ">
20042036< h2 class ="Sh " id ="THE_MACRO_LANGUAGE "> < a class ="permalink " href ="#THE_MACRO_LANGUAGE "> THE
@@ -2480,34 +2512,6 @@ <h3 class="Ss" id="Changing_options_while_assembling"><a class="permalink" href=
24802512POPO</ pre >
24812513</ div >
24822514</ section >
2483- < section class ="Ss ">
2484- < h3 class ="Ss " id ="Requesting_alignment "> < a class ="permalink " href ="#Requesting_alignment "> Requesting
2485- alignment</ a > </ h3 >
2486- < p class ="Pp "> While < code class ="Ic "> ALIGN</ code > as presented in
2487- < a class ="Sx " href ="#SECTIONS "> SECTIONS</ a > is often useful as-is, sometimes
2488- you instead want a particular piece of data (or code) in the middle of the
2489- section to be aligned. This is made easier through the use of mid-section
2490- < code class ="Ic "> ALIGN</ code > < var class ="Ar "> align</ var > ,
2491- < var class ="Ar "> offset</ var > . It will alter the section's attributes to
2492- ensure that the location the < code class ="Ic "> ALIGN</ code > directive is at,
2493- has its < var class ="Ar "> align</ var > lower bits equal to
2494- < var class ="Ar "> offset</ var > .</ p >
2495- < p class ="Pp "> If the constraint cannot be met (for example because the section
2496- is fixed at an incompatible address), an error is produced. Note that
2497- < code class ="Ic "> ALIGN</ code > < var class ="Ar "> align</ var > is a shorthand for
2498- < code class ="Ic "> ALIGN</ code > < var class ="Ar "> align</ var > ,
2499- < span class ="No "> 0</ span > .</ p >
2500- < p class ="Pp "> There may be times when you don't just want to specify an
2501- alignment constraint at the current location, but also skip ahead until the
2502- constraint can be satisfied. In that case, you can use < code class ="Ic "> DS
2503- ALIGN</ code > [< var class ="Ar "> align</ var > , < var class ="Ar "> offset</ var > ] to
2504- allocate however many bytes are required to align the subsequent data.</ p >
2505- < p class ="Pp "> If the constraint cannot be met by skipping any amount of space,
2506- an error is produced. Note that
2507- < code class ="Ic "> ALIGN</ code > [< var class ="Ar "> align</ var > ] is a shorthand
2508- for < code class ="Ic "> ALIGN</ code > [< var class ="Ar "> align</ var > ,
2509- < span class ="No "> 0</ span > ].</ p >
2510- </ section >
25112515</ section >
25122516< section class ="Sh ">
25132517< h2 class ="Sh " id ="SEE_ALSO "> < a class ="permalink " href ="#SEE_ALSO "> SEE
0 commit comments