about summary refs log tree commit diff stats
path: root/index.html
Commit message (Expand)AuthorAgeFilesLines
* 5485 - promote SubX to top-levelKartik Agaram2019-07-271-306/+4
* 4447Kartik Agaram2018-07-271-1/+1
* 4266 - space for alloc-id in heap allocationsKartik Agaram2018-06-241-12/+10
* 4258 - undo 4257Kartik Agaram2018-06-151-10/+12
* 4257 - abortive attempt at safe fat pointersKartik Agaram2018-06-151-12/+10
* 4228Kartik K. Agaram2018-03-151-0/+5
* 4158Kartik K. Agaram2017-12-091-0/+4
* 4117 - done with delimited continuationsKartik K. Agaram2017-11-061-1/+2
* 4111Kartik K. Agaram2017-11-051-0/+3
* 4110 - add continuations to docsKartik K. Agaram2017-11-051-0/+5
* 4090Kartik K. Agaram2017-10-261-4/+4
* 3995Kartik K. Agaram2017-09-131-4/+4
* 3975Kartik K. Agaram2017-08-201-6/+1
* 3762Kartik K. Agaram2017-03-071-1/+1
* 3641Kartik K. Agaram2016-11-061-2/+3
* 3588 - documentation for filesystem and networkKartik K. Agaram2016-10-241-6/+21
* 3557Kartik K. Agaram2016-10-221-2/+2
* 3415Kartik K. Agaram2016-09-251-1/+1
* 3411Kartik K. Agaram2016-09-231-3/+0
* 3402Kartik K. Agaram2016-09-191-1/+1
* 3401Kartik K. Agaram2016-09-181-1/+1
* 3395Kartik K. Agaram2016-09-171-3/+15
* 3372Kartik K. Agaram2016-09-161-7/+9
* 3355Kartik K. Agaram2016-09-151-1/+1
* 3312Kartik K. Agaram2016-09-101-1/+1
* 3235Kartik K. Agaram2016-08-201-1/+1
* 3227Kartik K. Agaram2016-08-181-1/+4
* 3158Kartik K. Agaram2016-07-271-10/+11
* 3116Kartik K. Agaram2016-07-201-1/+1
* 3103Kartik K. Agaram2016-07-051-24/+20
* 3024Kartik K. Agaram2016-05-281-1/+1
* 3023Kartik K. Agaram2016-05-281-1/+1
* 2997 - new version of http://akkartik.name/aboutKartik K. Agaram2016-05-231-3/+3
* 2996Kartik K. Agaram2016-05-211-99/+112
* 2868Kartik K. Agaram2016-04-251-1/+1
* 2866Kartik K. Agaram2016-04-251-14/+18
* 2814Kartik K. Agaram2016-03-271-22/+22
* 2813Kartik K. Agaram2016-03-271-0/+4
* 2812Kartik K. Agaram2016-03-271-14/+22
* 2811Kartik K. Agaram2016-03-271-4/+4
* 2724 - document failures of /space:globalKartik K. Agaram2016-03-011-3/+5
* 2706 - update htmlKartik K. Agaram2016-02-251-2/+2
* 2605Kartik K. Agaram2016-01-261-10/+10
* 2545Kartik K. Agaram2015-12-151-0/+2
* 2611Kartik K. Agaram2015-11-291-2/+3
* 2430 - make room for more transformsKartik K. Agaram2015-11-131-18/+18
* 2429Kartik K. Agaram2015-11-131-7/+6
* 2423 - describe shape-shifting in html docsKartik K. Agaram2015-11-101-22/+47
* 2300 - remove callcc.mu from docs until it returnsKartik K. Agaram2015-10-281-2/+0
* 2177Kartik K. Agaram2015-09-071-28/+67
generated by cgit-pink 1.4.1-2-gfad0 (git 2.36.2.497.gbbea4dcf42) at 2025-02-20 01:36:26 +0000
`/disp32`: 4 bytes containing `1000` ## Putting it all together Here's an example showing these arguments at work: <img alt='linux/ex3.subx' src='html/ex3.png'> This program sums the first 10 natural numbers. By convention I use horizontal tabstops to help read instructions, dots to help follow the long lines, comments before groups of instructions to describe their high-level purpose, and comments at the end of complex instructions to state the low-level operation they perform. Numbers are always in hexadecimal (base 16) and must start with a digit ('0'..'9'); use the '0x' prefix when a number starts with a letter ('a'..'f'). I tend to also include it as a reminder when numbers look like decimal numbers. --- I recommend you order arguments consistently in your programs. SubX allows arguments in any order, but only because that's simplest to explain/implement. Switching order from instruction to instruction is likely to add to the reader's burden. Here's the order I've been using after opcodes: ``` |<--------- reg/mem --------->| |<- reg/mem? ->| /subop /mod /rm32 /base /index /scale /r32 /displacement /immediate ``` --- Try running this example now: ```sh $ cd linux $ bootstrap/bootstrap translate 000init.subx ex3.subx -o ex3 $ bootstrap/bootstrap run ex3 $ echo $? 55 ``` If you're on Linux you can also run it natively: ```sh $ chmod +x ex3 $ ./ex3 $ echo $? 55 ``` These details should now be enough information for reading and modifying low-level SubX programs. ## Translating SubX programs This repo includes two translators for bare SubX. The first is [the bootstrap translator](bootstrap/bootstrap.md) implemented in C++. In addition, you can use SubX to translate itself. For example, running natively on Linux: ```sh # generate translator phases using the C++ translator $ cd linux $ bootstrap/bootstrap translate [01]*.subx subx-params.subx hex.subx -o hex $ bootstrap/bootstrap translate [01]*.subx subx-params.subx survey_elf.subx -o survey_elf $ bootstrap/bootstrap translate [01]*.subx subx-params.subx pack.subx -o pack $ bootstrap/bootstrap translate [01]*.subx subx-params.subx assort.subx -o assort $ bootstrap/bootstrap translate [01]*.subx subx-params.subx dquotes.subx -o dquotes $ bootstrap/bootstrap translate [01]*.subx subx-params.subx tests.subx -o tests $ chmod +x hex survey_elf pack assort dquotes tests # use the generated translator phases to translate SubX programs $ cat 000init.subx ex1.subx |./tests |./dquotes |./assort |./pack |./survey_elf |./hex > a.elf $ chmod +x a.elf $ ./a.elf $ echo $? 42 # or, automating the above steps $ cd linux $ ./translate_subx 000init.linux ex1.subx $ ./a.elf $ echo $? 42 ``` Or, running in a VM on other platforms (much slower): ```sh $ ./translate_subx_emulated init.linux linux/ex1.subx # generates identical a.elf to above $ bootstrap/bootstrap run a.elf $ echo $? 42 ``` ## Resources - [Single-page cheatsheet for the x86 ISA](https://net.cs.uni-bonn.de/fileadmin/user_upload/plohmann/x86_opcode_structure_and_instruction_overview.pdf) (pdf; [cached local copy](https://github.com/akkartik/mu/blob/main/cheatsheet.pdf)) - [Concise reference for the x86 ISA](https://c9x.me/x86) - [Concise reference for the x86 ISA #2](http://ref.x86asm.net/coder32.html) - [Intel processor manual](http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-instruction-set-reference-manual-325383.pdf) (pdf)
generated by cgit-pink 1.4.1-2-gfad0 (git 2.36.2.497.gbbea4dcf42) at 2025-02-20 01:36:26 +0000