1
0
Fork 0
Learning uxn
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
André Jaenisch af2e7d00e5
Document learnings from day 1 of uxn
4 months ago
..
README.md Document learnings from day 1 of uxn 4 months ago
ex1.tal Document learnings from day 1 of uxn 4 months ago
ex2.tal Document learnings from day 1 of uxn 4 months ago
hello.tal Document learnings from day 1 of uxn 4 months ago
hello_label.tal Document learnings from day 1 of uxn 4 months ago
hello_macro.tal Document learnings from day 1 of uxn 4 months ago
hello_raw.tal Document learnings from day 1 of uxn 4 months ago
hello_short.tal Document learnings from day 1 of uxn 4 months ago

README.md

Day 1

Today I learned the very basics. To easier look them up, here's a summary.

Toolchain

  • uxnasm: the assembler (takes a .tal and a .rom as arguments)
  • uxnemu: the emulator (uses the .rom from the step above)
  • uxncli: a non-interactive console-based emulator

Additional programs

  • wc --bytes <program>.rom to count bytes.
  • hexdump -C <program>.rom to see its contents.

uxnemu controls

  • F1 circles between different zoom levels
  • F2 shows on-screen debugger
  • F3 takes a screenshot of window
  • F4 loads a boot.rom to browse and open roms in cwd

Comments

uxn uses ( comment ) as comment (spaces are important).

Notation

It makes sense to comment the signature of opcodes and macros. ADD ( a b -- a+b ) means it takes the top two elements from the stack (right to left), adds them and pushes the result back into the stack.

Details

  • |0100 this is the initial value (pipe is important). Whatever is written afterwards will be written in memory starting at this address.
  • LIT an opcode (80) to push the next byte in memory down onto the stack. The program counter skip that byte (whatever that means).
  • 68 / 18 are hexadecimals, corresponding to ASCII code (68) and I/O address: device 1 on port 8 (STDOUT)
  • DEO (opcode 17) outputs 1 byte to the given device address: ( value address -- ).
  • Two digits correspond to one byte, four digits to two. These are the only two options to write numbers. (Pad with zeroes if needed). Digits here are also nibbles.

Special characters („runes“)

  • | (absolute pad) defines an absolute pad, i.e. the address where the next written items will be located in memory. If the address is 1 byte long, it is assumed to be an address of the I/O memory space or of the zero page. If the address is 2 bytes long, it is assumed to be an address for the main memory.
  • # (literal hex) is a shorthand for LIT. Can be only used with one or two bytes.
  • ' (raw) reads the next ASCII character and decodes its numerical value. It is not pushing the value onto the stack, i.e. it is not literal.
  • @ defines a label. It is derefernced by . in the I/O address space or zero page.
  • & defines a sub-label. It is dereferenced by / in the I/O address space or zero page.
  • $N skip the number of bytes. Alternatively: the sub-label is a N bytes long word.
  • % define a macro (usually in all-caps). These are replaced recursively. It is recommend to write its signature as comment afterwards.