From a8ab3b2c3f5947591a5fe680d3d935ac575d4786 Mon Sep 17 00:00:00 2001 From: Karol Stasiak Date: Fri, 3 Aug 2018 13:00:52 +0200 Subject: [PATCH] Documentation update --- docs/abi/variable-storage.md | 18 +++++++++++++++++- docs/lang/types.md | 18 +++++++++++++++--- 2 files changed, 32 insertions(+), 4 deletions(-) diff --git a/docs/abi/variable-storage.md b/docs/abi/variable-storage.md index 2f9ea9d9..47db5506 100644 --- a/docs/abi/variable-storage.md +++ b/docs/abi/variable-storage.md @@ -46,6 +46,19 @@ but the main disadvantages are: * cannot use them in inline assembly code blocks +The implementation depends on the target architecture: + +* on 6502, the stack pointer is transferred into the X register and used as a base + +* on 65818, the native stack-based addressing mode is used, similar to 6502, just without clobbering X + +* on 8080 and LR35902, the address is calculated from the stackpointer into the HL register pair + +* on Z80, the IX register is used as the base pointer; unlike all the previous platforms, +this makes stack-allocated variables independent from other stack operations +and allows for optimizing them by inlining them into registers +(this can be disabled, so the 8080 method is used, or switched to use IY instead) + ## Automatic variables Automatic variables have lifetime starting with the beginning of the function they're in @@ -53,10 +66,13 @@ and ending when the function returns. Most automatic variables reside in memory. They can share their memory location with other automatic variables and parameters, to conserve memory usage. -Some small automatic variables may be inlined to registers. They are not automatically initialized before reading, reading them before initialization yields an undefined value. Automatic local variables are not safe to use with reentrant functions, see the [relevant documentation](../lang/reentrancy.md) for more details. +Some small automatic variables may be inlined to registers. +On 6502-like architectures, only 1-byte variables may be inlined. +On 8080-like architectures, 1-byte and 2-byte variables may be inlined. + Automatic variables defined with the `register` keyword will have the priority when it comes to register allocation. ## Parameters diff --git a/docs/lang/types.md b/docs/lang/types.md index 6561b36b..574d52f9 100644 --- a/docs/lang/types.md +++ b/docs/lang/types.md @@ -25,11 +25,23 @@ Millfork puts extra limitations on which types can be used in which contexts. * `pointer` – the same as `word`, but variables of this type default to be zero-page-allocated and you can index `pointer` variables (not arbitrary `pointer`-typed expressions though, `f()[0]` won't compile) - -Functions cannot return types longer than 2 bytes. -There's also no reason to make a function return `pointer`, since to dereference it, +You can create pointer values by suffixing `.addr` to the name of a variable, function or array. +**Work in progress**: +There's no reason to make a function return `pointer` yet, since currently to dereference it, you need to put it in a variable first anyway. +You can access single bytes of variables by using the following notations: + +* for 2-byte-sized variables: `.lo` for the least significant byte and `.hi` for the most significant byte + +* for larger variables: `.b0` for the least significant byte and then `.b1`, `.b2` and so on + +You can also access words that are parts of variables: + +* for 3-byte-sized variables: `.loword` is the word formed from `.b1` and `.b0` and `.hiword` is the word formed from `.b2` and `.b1` + +* for 4-byte-sized variables: `.loword` is the word formed from `.b1` and `.b0` and `.hiword` is the word formed from `.b3` and `.b2` + Numeric types can be converted automatically: * from a smaller type to a bigger type (`byte`→`word`)