urbit/ares
1
1
Fork 0
mirror of https://github.com/urbit/ares.git synced 2024-11-22 15:08:54 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #62 from urbit/jon/noun-rep-docs

Browse Source 
docs: corrects docs on noun representation
This commit is contained in:
Edward Amsden 2023-06-22 23:00:49 -05:00 committed by GitHub
commit b7579dcf3f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 16 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
docs/stack.md
View File

@ -11,25 +11,29 @@ By treating a 0 MSB as the tag for a direct atom, we can compute directly with d
| MSBs | Noun | | MSBs | Noun |
|------|-----------------------| |------|-----------------------|
| 0 | Direct Atom | | 0 | Direct Atom |
| 10 | Cell Pointer | | 10 | Indirect Atom Pointer |
| 110 | Indirect Atom Pointer | | 110 | Cell Pointer |
A direct atom is an atom which fits in a machine word, less one bit for the tag. It is stored directly. A direct atom is an atom which fits in a machine word, less one bit for the tag. It is stored directly.
An indirect atom is an atom which is too big to be a direct atom. An indirect atom is an atom which is too big to be a direct atom. It is thus represented as a tagged
It is thus represented as a tagged pointer. pointer. The memory referenced is 64-bit aligned. The first 64 bits are metadata, followed by the
The memory referenced is at least 64-bit aligned. size in 64-bit words, then the actual value of the atom, whose number of words
The first 64 bits are the size of the atom in bytes. is equal to the size in little-endian order. The metadata field is primarily used for
This is followed by that number of bytes containing the atom in little-endian order. the mug. The first three bits of the size are reserved for a possible forwarding pointer tag.
A cell is represented as a tagged pointer. A cell is represented as a tagged pointer. The memory referenced is adjacent machine words.
The memory referenced is adjacent machine words. The machine word at the pointer is metadata. The machine word directly following (higher in memory)
The machine word at the pointer is the noun representation of the head (left side/first) of the cell. is the noun representation of the head, followed by the noun representation of the tail. The metadata
The machine word directly following (higher in memory) is the noun representation of the tail (right side/second) of the cell. field is primarily used for the mug.
During collection the memory for indirect atoms and cells may be rewritten to indicate a _forwarding pointer_. During collection the memory for indirect atoms and cells may be rewritten to indicate a _forwarding pointer_.
This is discussed further in the "Memory Layout" section. When an indirect atom is copied from one stack frame to another, its size is replaced with a
forwarding pointer. When a cell is copied from one stack frame to another, its
head is replaced with a forwarding pointer.
The tag for a forwarding pointer is 111.
## Memory Layout ## Memory Layout