hello! in this first section of the {uxn tutorial} we talk about the basics of the uxn computer called varvara, its programming paradigm in a language called uxntal, its architecture, and why you would want to learn to program it.
IMPORTANT (12024-03-28)! even though we updated to some extent the tutorial during our {maintenance practice}, and in principle everything that we say here works, keep in mind that it is written from a somewhat outdated perspective. some things are done differently now, and the tutorial doesn't cover all the possibilities in the language that exist nowadays. in doubt, always refer to the official documentation. however, we hope it's still useful to you as an introduction to the uxn ecosystem!
=> https://wiki.xxiivv.com/site/uxn.html XXIIVV — uxn official documentation
if you'd like to contribute improving the tutorial, check out our to-do list in the {roadmap} and {contact} us!
> The Uxn/Varvara ecosystem is a personal computing stack based on a small virtual machine that lies at the heart of our software, and that allows us to run the same application on a variety of systems.
uxn is the core of the varvara virtual computer. it is simple enough to be emulated by many old and new computing platforms, and to be followed by hand.
the uxn core is inspired by forth-machines in that it uses the recombination of simple components to achieve appropriate solutions, and in that it is a stack-based machine.
this implies that it is primarily based on interactions with a "push down stack", where operations are indicated using what is called postfix notation.
> Reverse Polish notation (RPN), also known as Polish postfix notation or simply postfix notation, is a mathematical notation in which operators follow their operands [...]
=> https://en.wikipedia.org/wiki/Reverse_Polish_notation Reverse Polish notation - Wikipedia
* + takes two elements from the top of the stack, adds them, and pushes the result down onto the stack
the book Starting Forth has some great illustrations of this process of addition:
=> https://www.forth.com/starting-forth/1-forth-stacks-dictionary/#The_Stack_Forth8217s_Workspace_for_Arithmetic The Stack: Forth’s Workspace for Arithmetic
## from infix to postfix
more complex expressions in infix notation, that require either parenthesis or rules of operator precedence (and a more complex system for decoding them), can be simplified with postfix notation.
for example, the following infix expression:
``` (2 + 16)/8 + 48
(3 + 5)/2 + 48
```
can be written in postfix notation as:
``` 3 5 + 2 / 48 +
3 5 + 2 / 48 +
```
we can also write it in many other ways, for example:
note: in the case of the division, the operands follow the same left-to-right order. 3/2 would be written as:
``` 3 2 /
3 2 /
```
you'll start seeing how the use of the stack can be very powerful as it can save operands and/or intermediate results without us having to explicitly assign a place in memory for them (i.e. like using "variables" in other programming languages)
we'll come back to postfix notation and the stack very soon!
one of the perks of programming a computer at a low-level of abstraction, as we will be doing with uxn, is that we have to know and be aware of its internal workings.
binary words of 8-bits, also known as bytes, are the basic elements of data encoding and manipulation in uxn.
uxn can also handle binary words of 16-bits (2 bytes), also known as shorts, by concatenating two consecutive bytes. we'll talk more about this in the second day of the tutorial.
numbers in uxn are expressed using the {hexadecimal} system (base 16), where each digit (nibble) goes from 0 to 9 and then from 'a' to 'f' (in lower case).
each byte in the main memory has an address of 16-bits (2 bytes) in size, while each byte in the i/o memory has an address of 8-bits (1 byte) in size. both of them can be accessed randomly.
the first 256 bytes of the main memory constitute a section called the zero-page. this section can be addressed by 8-bits (1 byte), and it is meant for data storage during the runtime of the machine.
the main memory stores the program to be executed, starting at the 257th byte (address 0100 in hexadecimal, or 256 in decimal). it can also store data.
the instruction will normally imply a change in the stack(s), and sometimes it may imply a change of the normal flow of the program counter: instead of pointing to the next byte in memory, it can be made to point elsewhere, "jumping" from a place in memory to another.
to run varvara, you have several options: running it from your (web)browser, downloading it as a pre-built application, or building it from source yourself.
in order to run varvara locally and off the grid we need to get an appropriate emulator.
the 100R website allows you to download the emulators for major desktop systems; these come bundled with a selection of programs in the form of "roms":
=> https://100r.co/site/uxn.html 100R — uxn
for further instructions in how to run varvara in this way, see {uxn running}.
uxntal being an assembly language implies that there's a one-to-one mapping of a written instruction in the language to a corresponding 8-bit word that the cpu can interpret.
for example, the instruction ADD in uxntal is encoded as a single byte with the value 18 in hexadecimal (that's what's called its opcode), and corresponds to the following set of actions: take the top two elements from the stack, add them, and push down the result.
in forth-like systems we can see the following kind of notation to express the operands that an instruction takes from the stack, and the result(s) that it pushes down onto the stack:
```
ADD ( a b -- a+b )
```
this means that ADD takes first the top element 'b', then it takes the new top element 'a', and pushes back the result of adding a+b.
now that we are at it, there's a complementary instruction, SUB (opcode 19), that takes the top two elements from the stack, subtracts them, and pushes down the result:
note that the order of the operands in the subtraction is similar to the order for the division as we discussed above when talking about postfix notation: it is as if we moved the operator from between operands, to the end after the second operand.
the first line is a comment: comments are enclosed between parenthesis. there have to be spaces in between them. similar to other programming languages, comments are ignored by the assembler.
* |0100 : you may remember this number from before—this is the initial value of the program counter; the address of the first byte in the main memory that the cpu reads. we use this notation to indicate that whatever is written afterwards, will be written in memory starting at this address.
* LIT : this appears four times; it is an uxntal instruction that performs the following actions: it pushes the next byte in memory down onto the stack, and it makes the program counter skip that byte.
* 68 : an hexadecimal number that corresponds to the ascii code of the character 'h'.
* 18 : an hexadecimal number that corresponds to an i/o address: device 1, port 8.
* 0a : an hexadecimal number that corresponds to the ascii code of a 'newline'.
* DEO : another uxntal instruction, that we could define as the following: output the given value (1 byte) into the given device address, both taken from the stack ( value address -- )
looking at the devices table from the varvara reference, we can see that the device with address 1 in the high nibble is the console (standard input and output), and that the column with address 8 in the low nibble corresponds to the "write" port.
note that the raw numbers that we wrote, 0100, 18, 68 and 0a, are written in hexadecimal using either 4 digits corresponding to two bytes, or 2 digits corresponding to one byte.
in uxntal we can only write numbers that are 2 or 4 hexadecimal digits (nibbles) long. if, for example, we were only interested in writing a single hexadecimal digit, we would have to include a 0 at its left.
important: remember that this rune (and the others with the word "literal" in their names) is a shorthand for the LIT instruction. this implies that uxn will push these values down into the stack.
if we just want to have a specific number in the main memory, without pushing it into the stack, we would just write the number as is, "raw". this is the way we did it in our first programs above.
even though right now we know that #18 corresponds to pushing the address (18) of the console write device port down onto the stack, for readability and future-proofing of our code it is a good practice to assign a set of labels that would correspond to that device and port.
here, we can see an absolute pad to address 10 (the console device), that assigns the following items to that address. because the address consists of one byte only, once we use the DEO instructions, uxn understands it's referring to the i/o memory space,.
the rune for referring to literal addressess in the zero page or i/o address space, is . (dot), and a / (slash) allows us to refer to one of its sublabels.
note that macros are a helpful way of grouping and reusing code, especially when beginning to learn uxntal. for more advanced uses, macros are replaced by other strategies.
for that reason, some uxntal assemblers like the one in Uxntal Playground, don't allow their use.
if you look at the ascii table, you'll see that the hexadecimal ascii code 30 corresponds to the digit 0, 31 to the digit 1, and so on until 39 that corresponds to digit 9.
remember that the number would have to be written as a complete byte in order to be valid uxntal. if you wanted to test this macro with e.g. number 2, you would have to write it as 02:
in {uxn tutorial day 2} we start exploring the visual aspects of the varvara computer: we talk about the fundamentals of the screen device so that we can start drawing on it!