git @ Cat's Eye Technologies SixtyPical / 21a187a
Update docs. Chris Pressey 2 years ago
3 changed file(s) with 99 addition(s) and 50 deletion(s). Raw diff Collapse all Expand all
1515 can also be given.
1616 * Accessing a `table` through a `pointer` must be done in
1717 the context of a `point ... into` block. This allows the
18 analyzer to check *which* table is being modified.
18 analyzer to check *which* table is being accessed.
1919 * Added `--dump-exit-contexts` option to `sixtypical`.
2020
2121 0.18
00 SixtyPical
11 ==========
22
3 _Version 0.18. Work-in-progress, everything is subject to change._
3 _Version 0.19. Work-in-progress, everything is subject to change._
44
5 **SixtyPical** is a low-level programming language with advanced
6 static analysis. Many of its primitive instructions resemble
7 those of the 6502 CPU — in fact it is intended to be compiled to
8 6502 machine code — but along with these instructions are
9 constructs which ease structuring and analyzing the code. The
10 language aims to fill this niche:
5 **SixtyPical** is a [very low-level](#very-low-level) programming language
6 supporting a [sophisticated static analysis](#sophisticated-static-analysis).
117
12 * You'd use assembly, but you don't want to spend hours
13 debugging (say) a memory overrun that happened because of a
14 ridiculous silly error.
15 * You'd use C or some other "high-level" language, but you don't
16 want the extra overhead added by the compiler to manage the
17 stack and registers.
18
19 SixtyPical gives the programmer a coding regimen on par with assembly
20 language in terms of size and hands-on-ness, but also able to catch
21 many ridiculous silly errors at compile time, such as
22
23 * you forgot to clear carry before adding something to the accumulator
24 * a subroutine that you called trashes a register you thought it preserved
25 * you tried to read or write a byte beyond the end of a byte array
26 * you tried to write the address of something that was not a routine, to
27 a jump vector
28
29 Many of these checks are done with _abstract interpretation_, where we
30 go through the program step by step, tracking not just the changes that
31 happen during a _specific_ execution of the program, but _sets_ of changes
32 that could _possibly_ happen in any run of the program.
33
34 SixtyPical also provides some convenient operations based on
35 machine-language programming idioms, such as
36
37 * copying values from one register to another (via a third register when
38 there are no underlying instructions that directly support it); this
39 includes 16-bit values, which are copied in two steps
40 * explicit tail calls
41 * indirect subroutine calls
42
43 SixtyPical is defined by a specification document, a set of test cases,
44 and a reference implementation written in Python 2. The reference
45 implementation can analyze and compile SixtyPical programs to 6502 machine
46 code, which can be run on several 6502-based 8-bit architectures:
47
48 * Commodore 64
49 * Commodore VIC-20
50 * Atari 2600 VCS
51 * Apple II
8 Its reference compiler can generate [efficient code](#efficient-code) for
9 [several 6502-based platforms](#target-platforms) while catching many
10 common mistakes at compile-time, reducing the time spent in debugging.
5211
5312 Quick Start
5413 -----------
5514
56 If you have the [VICE][] emulator installed, from this directory, you can run
15 Make sure you have Python (2.7 or 3.5+) installed. Then
16 clone this repository and put its `bin` directory on your
17 executable search path. Then run:
18
19 sixtypical
20
21 If you have the [VICE][] emulator installed, you can run
5722
5823 ./loadngo.sh c64 eg/c64/hearts.60p
5924
6631 tree, which contains more extensive examples, including an entire
6732 game(-like program); see [eg/README.md](eg/README.md) for a listing.
6833
69 [VICE]: http://vice-emu.sourceforge.net/
34 Features
35 --------
36
37 SixtyPical aims to fill this niche:
38
39 * You'd use assembly, but you don't want to spend hours
40 debugging (say) a memory overrun that happened because of a
41 ridiculous silly error.
42 * You'd use C or some other "high-level" language, but you don't
43 want the extra overhead added by the compiler to manage the
44 stack and registers.
45
46 SixtyPical gives the programmer a coding regimen on par with assembly
47 language in terms of size and hands-on-ness, but also able to catch
48 many ridiculous silly errors at compile time.
49
50 ### Very low level
51
52 Many of SixtyPical's primitive instructions resemble
53 those of the 6502 CPU — in fact it is intended to be compiled to
54 6502 machine code — but along with these instructions are
55 constructs which ease structuring and analyzing the code.
56
57 However, SixtyPical also does provide some "higher-level" operations
58 based on common 8-bit machine-language programming idioms, including
59
60 * copying values from one register to another (via a third register when
61 there are no underlying instructions that directly support it)
62 * copying, adding, and comparing 16-bit values (done in two steps)
63 * explicit tail calls
64 * indirect subroutine calls
65
66 While a programmer will find these constructs convenient, their
67 inclusion in the language is primarily to make programs easier to analyze.
68
69 ### Sophisticated static analysis
70
71 The language defines an [effect system][], and the reference
72 compiler [abstractly interprets][] the input program to check that
73 it conforms to it. It can detect common mistakes such as
74
75 * you forgot to clear carry before adding something to the accumulator
76 * a subroutine that you called trashes a register you thought it preserved
77 * you tried to read or write a byte beyond the end of a byte array
78 * you tried to write the address of something that was not a routine, to
79 a jump vector
80
81 ### Efficient code
82
83 Unlike most languages, in SixtyPical the programmer must manage memory very
84 explicitly, selecting the registers and memory locations to store all data in.
85 So, unlike a C compiler such as [cc65][], a SixtyPical compiler doesn't need
86 to generate code to handle stack management or register spilling. This results
87 in smaller (and thus faster) programs.
88
89 The flagship demo, a minigame for the Commodore 64, compiles to
90 a **930**-byte `.PRG` file.
91
92 ### Target platforms
93
94 The reference implementation can analyze and compile SixtyPical programs to
95 6502 machine code formats which can run on several 6502-based 8-bit architectures:
96
97 * [Commodore 64][] -- examples in [eg/c64/](eg/c64/)
98 * [Commodore VIC-20][] -- examples in [eg/vic20/](eg/vic20/)
99 * [Atari 2600][] -- examples in [eg/atari2600/](eg/atari2600/)
100 * [Apple II series][] -- examples in [eg/apple2/](eg/apple2/)
70101
71102 Documentation
72103 -------------
104
105 SixtyPical is defined by a specification document, a set of test cases,
106 and a reference implementation written in Python.
73107
74108 * [Design Goals](doc/Design%20Goals.md)
75109 * [SixtyPical specification](doc/SixtyPical.md)
81115 * [6502 Opcodes used/not used in SixtyPical](doc/6502%20Opcodes.md)
82116 * [Output formats supported by `sixtypical`](doc/Output%20Formats.md)
83117 * [TODO](TODO.md)
118
119 [VICE]: http://vice-emu.sourceforge.net/
120 [cc65]: https://cc65.github.io/
121 [Commodore 64]: https://en.wikipedia.org/wiki/Commodore_64
122 [Commodore VIC-20]: https://en.wikipedia.org/wiki/Commodore_VIC-20
123 [Atari 2600]: https://en.wikipedia.org/wiki/Atari_2600
124 [Apple II series]: https://en.wikipedia.org/wiki/Apple_II_series
2727 inner block has finished -- even if there is no `call`.)
2828
2929 These holes need to be plugged.
30
31 ### Reset pointer in `point into` blocks
32
33 We have `point into` blocks, but maybe the action when entering such a
34 block shouldn't always be to set the given pointer to the start of the given table.
35
36 That is, sometimes we would like to start at some fixed offset. And
37 sometimes we want to (re)set the pointer, without closing and starting a new block.
3038
3139 ### Pointers associated globally with a table
3240