Fix the mapping of addresses on labels

There was a big missunderstanding on how things were to be laid out in
the end file, and so it was needed to create a proper understanding on
what's a Mapping and what's a Segment. These turned out to be
fundamental concepts that I failed to grok up until this commit.

Hence, this commit re-arranges completely how variables and labels are
stored in the Context, and how these objects can then be translated into
bundles that can be spit out to the caller.

This commit, besides introducing the new Mapping struct, also introduced
a more general Object, which abstracts things from the Bundle struct,
and allows us to pass certain metadata about the bundle at hand.

Signed-off-by: Miquel Sabaté Solà <mikisabate@gmail.com>

1 files changed, 38 insertions, 2 deletions

diff --git a/lib/xixanta/src/lib.rs b/lib/xixanta/src/lib.rs
index 0b68ac9..0ad901f 100644
--- a/lib/xixanta/src/lib.rs
+++ b/lib/xixanta/src/lib.rs
@@ -2,9 +2,45 @@
 extern crate lazy_static;
 
 pub mod assembler;
-pub mod context;
 pub mod errors;
-pub mod mapping;
 pub mod node;
+pub mod object;
 pub mod opcodes;
 pub mod parser;
+
+/// Mapping defines structures for laying out how the code will be assembled
+/// both on memory and on the ROM file itself. Notice that we take a different
+/// approach than 'cc65' because that compiler has to take into account a
+/// myriad of machines that had the MOS 6502 processor. Here we have a clear
+/// target and we can be more specific. That is, the community has settled on a
+/// very specific ROM file format, and hence the "linker configuration" turns
+/// out to be simpler. The code here takes it into consideration by defining
+/// three regions on the ROM file:
+///
+///   1. The header (i.e. `SectionType::Header`) will be allocated exactly on
+///      the first 16 bytes of the file. Moreover, the first 6 bytes are
+///      absolutely mandatory to be filled by the programmer.
+///   2. The PRG ROM (i.e. `SectionType::PrgRom`) will be allocated next to the
+///      header (i.e. trainer support is not available on this assembler). This
+///      section is laid out in blocks of 8KB and contains the program.
+///   3. The CHR ROM (i.e. `SectionType::ChrRom`) will be allocated just after
+///      the PRG ROM and is laid out in blocks of 4KB, containing the ROM data (if
+///      available).
+///
+/// This is the layout for the ROM file itself, but it can itself be subdivided
+/// into "mappings" (i.e. `Mapping`). A Mapping is a configuration inside of
+/// one of these three sections. For a simple section like the header having
+/// only one mapping will be enough, but for PRG ROM we might define a mapping
+/// for each bank, for example. And even in simple scenarios, it's quite usual
+/// to split this section at least with "CODE" (which contains the actual
+/// program), and "VECTORS" (6 bytes containing the addresses for the vectors
+/// for a 6502 processor). A Mapping contains quite a lot of info, but you can
+/// think of it as a way to subdivide a section, defining stuff like where it
+/// starts, its size, how to fill it if the programmer did not occupy the
+/// region fully, etc.
+///
+/// Inside of a mapping there might be multiple segments. This is in turn a way
+/// to further subdivide the memory region, and it defines contiguous space
+/// inside of a mapping. This way, regardless of where you define a segment,
+/// there are some guarantees on the order.
+pub mod mapping;