├── .gh
    ├── config.js
    ├── header_footer.md
    └── markdown.css
├── .github
    └── workflows
    │   └── build.yml
├── .gitignore
├── Commander X16 Programmer's Reference Guide.md
├── README.md
├── X16 Reference - 01 - Overview.md
├── X16 Reference - 02 - Getting Started.md
├── X16 Reference - 03 - Editor.md
├── X16 Reference - 04 - BASIC.md
├── X16 Reference - 05 - KERNAL.md
├── X16 Reference - 06 - Math Library.md
├── X16 Reference - 07 - Machine Language Monitor.md
├── X16 Reference - 08 - Memory Map.md
├── X16 Reference - 09 - VERA Programmer's Reference.md
├── X16 Reference - 10 - VERA FX Reference.md
├── X16 Reference - 11 - Sound Programming.md
├── X16 Reference - 12 - IO Programming.md
├── X16 Reference - 13 - Working with CMDR-DOS.md
├── X16 Reference - 14 - Hardware.md
├── X16 Reference - 15 - Upgrade Guide.md
├── X16 Reference - Appendix A - Sound.md
├── X16 Reference - Appendix B - VERA Recovery.md
├── X16 Reference - Appendix C - 65C02 Processor.md
├── X16 Reference - Appendix D - Official Expansion Cards.md
├── X16 Reference - Appendix E - Diagnostic Bank.md
├── X16 Reference - Appendix F - 65C816 Processor.md
├── X16 Reference - Appendix G - ZSM File Format.md
├── X16 Reference - Appendix H - Onboard Upgrade Guide.md
├── X16 Reference - Appendix I - Character Sets.md
└── images
    ├── Appendix_B
        └── X16-Serial.png
    ├── Appendix_E
        └── mem-diag-error-code.jpg
    ├── Appendix_I
        ├── 01ISO.png
        ├── 02PETupper-graph.png
        ├── 03PETupper-lower.png
        ├── 04PETupper-graph-thin.png
        ├── 05PETupper-lower-thin.png
        ├── 06ISOthin.png
        ├── 07CP437.png
        ├── 08CyrillicISO.png
        ├── 09CyrillicISOthin.png
        ├── 10EasternLatinISO.png
        ├── 11EasternISOthin.png
        └── 12Katakana-thin.png
    ├── CompositeColors.png
    ├── CompositeColors.svg
    ├── CompositeOverscan.png
    ├── CompositeOverscan.svg
    ├── SNES_Controller_Female.png
    ├── SNES_Controller_Female.svg
    ├── VGA_Port.png
    ├── VGA_Port.svg
    ├── atx_24_pin-small.png
    ├── atx_24_pin.png
    ├── cx16palette.png
    ├── fx_fig1.png
    ├── fx_fig2.png
    ├── iec_port.gif
    ├── monitor.png
    ├── ps2_pinout.png
    ├── ps2_pinout.svg
    ├── redunderline.png
    ├── s_video.png
    ├── s_video.svg
    ├── tl866-3g-icsp.jpg
    ├── tl866-3g-to-vera.png
    ├── vera-prg-hdr.jpg
    └── xgpro-window.png


/.gh/config.js:
--------------------------------------------------------------------------------
 1 | const { marked } = require('marked');
 2 | const renderer = new marked.Renderer();
 3 | 
 4 | // Override function
 5 | renderer.link = (href, title, text) => {
 6 |     
 7 |     const myURL = new URL(href, "http://localhost/");
 8 |     if (myURL.hostname == "localhost") {
 9 |         href = myURL.hash;
10 |     }
11 | 
12 |     return `
13 |             <a href="${href}">
14 |                 ${text}
15 |             </a>
16 |             `
17 |             
18 | }
19 | 
20 | module.exports = {
21 |     marked_options: { renderer },
22 | };
23 | 


--------------------------------------------------------------------------------
/.gh/header_footer.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | pdf_options:
 3 |   format: a4
 4 |   margin: 30mm 20mm
 5 |   printBackground: true
 6 |   headerTemplate: |-
 7 |     <style>
 8 |       section {
 9 |         margin: 0 auto;
10 |         font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
11 |         font-size: 6pt;
12 |         color: black;
13 |       }
14 |     </style>
15 |     <section>
16 |       <div>Commander X16 Programmer's Reference Guide</div>
17 |     </section>
18 |   footerTemplate: |-
19 |     <section>
20 |       <div>
21 |         - <span class="pageNumber"></span> -
22 |       </div>
23 |     </section>
24 | ---
25 | 


--------------------------------------------------------------------------------
/.gh/markdown.css:
--------------------------------------------------------------------------------
  1 | * {
  2 | 	box-sizing: border-box;
  3 | }
  4 | 
  5 | html {
  6 | 	font-size: 100%;
  7 | }
  8 | 
  9 | body {
 10 | 	font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell',
 11 | 		'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
 12 | 	line-height: 1.6;
 13 | 	font-size: 0.6875em; /* 11 pt */
 14 | 	color: #111;
 15 | 	margin: 0;
 16 | }
 17 | 
 18 | body > :first-child {
 19 | 	padding-top: 0;
 20 | 	margin-top: 0;
 21 | }
 22 | 
 23 | body > :last-child {
 24 | 	margin-bottom: 0;
 25 | 	padding-bottom: 0;
 26 | }
 27 | 
 28 | thead {display: table-header-group;}
 29 | tfoot {display: table-footer-group;}
 30 | 
 31 | h1,
 32 | h2,
 33 | h3,
 34 | h4,
 35 | h5,
 36 | h6 {
 37 | 	margin: 0;
 38 | 	padding: 0.5em 0 0.25em;
 39 | }
 40 | 
 41 | h5,
 42 | h6 {
 43 | 	padding: 0;
 44 | }
 45 | 
 46 | h5 {
 47 | 	font-size: 1em;
 48 | }
 49 | 
 50 | h6 {
 51 | 	font-size: 0.875em;
 52 | 	text-transform: uppercase;
 53 | }
 54 | 
 55 | p {
 56 | 	margin: 0.25em 0 1em;
 57 | }
 58 | 
 59 | blockquote {
 60 | 	margin: 0.5em 0 1em;
 61 | 	padding-left: 0.5em;
 62 | 	padding-right: 1em;
 63 | 	border-left: 4px solid gainsboro;
 64 | 	font-style: italic;
 65 | }
 66 | 
 67 | ul,
 68 | ol {
 69 | 	margin: 0;
 70 | 	margin-left: 1em;
 71 | 	padding: 0 1.5em 0.5em;
 72 | }
 73 | 
 74 | pre {
 75 | 	white-space: pre-wrap;
 76 | }
 77 | 
 78 | h1 code,
 79 | h2 code,
 80 | h3 code,
 81 | h4 code,
 82 | h5 code,
 83 | h6 code,
 84 | p code,
 85 | li code,
 86 | pre code {
 87 | 	background-color: #f8f8f8;
 88 | 	padding: 0.1em 0.375em;
 89 | 	border: 1px solid #f8f8f8;
 90 | 	border-radius: 0.25em;
 91 | 	font-family: monospace;
 92 | 	font-size: 1.2em;
 93 | }
 94 | 
 95 | pre code {
 96 | 	display: block;
 97 | 	padding: 0.5em;
 98 | }
 99 | 
100 | .page-break {
101 | 	page-break-after: always;
102 | }
103 | 
104 | img {
105 | 	max-width: 100%;
106 | 	margin: 1em 0;
107 | }
108 | 
109 | table {
110 | 	border-spacing: 0;
111 | 	border-collapse: collapse;
112 | 	display: block;
113 | 	margin: 0 0 1em;
114 | 	width: 100%;
115 | 	overflow: visible;
116 | }
117 | 
118 | table th,
119 | table td {
120 | 	padding: 0.5em 1em;
121 | 	border: 1px solid gainsboro;
122 | }
123 | 
124 | table th {
125 | 	font-weight: 600;
126 | }
127 | 
128 | table tr {
129 | 	background-color: white;
130 | 	border-top: 1px solid gainsboro;
131 | }
132 | 
133 | table tr:nth-child(2n) {
134 | 	background-color: whitesmoke;
135 | }
136 | 


--------------------------------------------------------------------------------
/.github/workflows/build.yml:
--------------------------------------------------------------------------------
 1 | name: Build PRG PDF
 2 | on: [push, pull_request]
 3 | 
 4 | jobs:
 5 |   build-pdf:
 6 |     runs-on: ubuntu-22.04
 7 |     steps:
 8 |       - uses: actions/checkout@v4
 9 |       - uses: actions/setup-python@v5
10 |         with:
11 |           python-version: '3.9'
12 |       - name: Install Dependencies
13 |         run: sudo apt-get update && sudo apt-get install -y build-essential make fonts-dejavu
14 |       - uses: actions/setup-node@v4
15 |         with:
16 |           node-version: 20
17 |       - name: Install md-to-pdf (npm)
18 |         run: |
19 |           npm i md-to-pdf
20 |       - name: Create output directory
21 |         run: |
22 |           mkdir artifacts
23 |       - name: Create Programmer's Reference Guide PDF
24 |         run: |
25 |           export PATH=$(pwd)/node_modules/.bin:$PATH
26 |           cat .gh/header_footer.md \
27 |           "Commander X16 Programmer's Reference Guide.md" \
28 |           "X16 Reference - 01 - Overview.md" \
29 |           "X16 Reference - 02 - Getting Started.md" \
30 |           "X16 Reference - 03 - Editor.md" \
31 |           "X16 Reference - 04 - BASIC.md" \
32 |           "X16 Reference - 05 - KERNAL.md" \
33 |           "X16 Reference - 06 - Math Library.md" \
34 |           "X16 Reference - 07 - Machine Language Monitor.md" \
35 |           "X16 Reference - 08 - Memory Map.md" \
36 |           "X16 Reference - 09 - VERA Programmer's Reference.md" \
37 |           "X16 Reference - 10 - VERA FX Reference.md" \
38 |           "X16 Reference - 11 - Sound Programming.md" \
39 |           "X16 Reference - 12 - IO Programming.md" \
40 |           "X16 Reference - 13 - Working with CMDR-DOS.md" \
41 |           "X16 Reference - 14 - Hardware.md" \
42 |           "X16 Reference - 15 - Upgrade Guide.md" \
43 |           "X16 Reference - Appendix A - Sound.md" \
44 |           "X16 Reference - Appendix B - VERA Recovery.md" \
45 |           "X16 Reference - Appendix C - 65C02 Processor.md" \
46 |           "X16 Reference - Appendix D - Official Expansion Cards.md" \
47 |           "X16 Reference - Appendix E - Diagnostic Bank.md" \
48 |           "X16 Reference - Appendix F - 65C816 Processor.md" \
49 |           "X16 Reference - Appendix G - ZSM File Format.md" \
50 |           "X16 Reference - Appendix H - Onboard Upgrade Guide.md" \
51 |           "X16 Reference - Appendix I - Character Sets.md" \
52 |           | md-to-pdf --config-file .gh/config.js --stylesheet .gh/markdown.css > "artifacts/Commander X16 Programmer's Reference Guide.pdf"
53 |       - uses: actions/upload-artifact@v4
54 |         with:
55 |           name: x16-docs-pdf
56 |           path: artifacts/*
57 | 
58 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | 
2 | .markdownlint.json
3 | 


--------------------------------------------------------------------------------
/Commander X16 Programmer's Reference Guide.md:
--------------------------------------------------------------------------------
1 | README.md


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | <!--
 2 | ********************************************************************************
 3 | NOTICE: This file uses two trailing spaces on some lines to indicate line breaks
 4 | for GitHub's Markdown flavor. Do not remove!
 5 | 
 6 | PDF Export Instructions:
 7 | 
 8 | Anchor links (e.g. link.md#anchor) are required.
 9 | Otherwise links will not function correctly.
10 | 
11 | The top of every page should start with a newline.
12 | 
13 | The bottom of every page should include the div tag (see existing pages for
14 | examples)
15 | ********************************************************************************
16 | -->
17 | 
18 | # Commander X16 Reference Manual
19 | 
20 | This is the official Commander X16 reference manual.
21 | 
22 | Being a reference manual it is light on some details with some expected fundamental
23 | knowledge. If you are brand new to the X16, consider consulting the
24 | [User Guide](https://github.com/X16Community/x16-user-guide/releases/tag/X16_Users_Guide)
25 | first.
26 | 
27 | ## Chapters
28 | 
29 | * [Chapter 1: Overview](X16%20Reference%20-%2001%20-%20Overview.md#chapter-1-overview)
30 | * [Chapter 2: Getting Started](X16%20Reference%20-%2002%20-%20Getting%20Started.md#chapter-2-getting-started)
31 | * [Chapter 3: Editor](X16%20Reference%20-%2003%20-%20Editor.md#chapter-3-editor)
32 | * [Chapter 4: BASIC](X16%20Reference%20-%2004%20-%20BASIC.md#chapter-4-basic-programming)
33 | * [Chapter 5: KERNAL](X16%20Reference%20-%2005%20-%20KERNAL.md#chapter-5-kernal)  
34 | * [Chapter 6: Math Library](X16%20Reference%20-%2006%20-%20Math%20Library.md#chapter-6-math-library)  
35 | * [Chapter 7: Machine Language Monitor](X16%20Reference%20-%2007%20-%20Machine%20Language%20Monitor.md#chapter-7-machine-language-monitor)  
36 | * [Chapter 8: Memory Map](X16%20Reference%20-%2008%20-%20Memory%20Map.md#chapter-8-memory-map)  
37 | * [Chapter 9: VERA Programmer's Reference](X16%20Reference%20-%2009%20-%20VERA%20Programmer's%20Reference.md#chapter-9-vera-programmers-reference)
38 | * [Chapter 10: VERA FX Reference](X16%20Reference%20-%2010%20-%20VERA%20FX%20Reference.md#chapter-10-vera-fx-reference)
39 | * [Chapter 11: Sound Programming](X16%20Reference%20-%2011%20-%20Sound%20Programming.md#chapter-11-sound-programming)
40 | * [Chapter 12: I/O Programming](X16%20Reference%20-%2012%20-%20IO%20Programming.md#chapter-12-io-programming)
41 | * [Chapter 13: Working with CMDR-DOS](X16%20Reference%20-%2013%20-%20Working%20with%20CMDR-DOS.md#chapter-13-working-with-cmdr-dos)
42 | * [Chapter 14: Hardware Pinouts](X16%20Reference%20-%2014%20-%20Hardware.md#chapter-14-hardware-pinouts)  
43 | * [Chapter 15: Upgrade Guide](X16%20Reference%20-%2015%20-%20Upgrade%20Guide.md#chapter-15-upgrade-guide)
44 | * [Appendix A: Sound](X16%20Reference%20-%20Appendix%20A%20-%20Sound.md#appendix-a-sound)
45 | * [Appendix B: VERA Firmware Recovery](X16%20Reference%20-%20Appendix%20B%20-%20VERA%20Recovery.md#appendix-b-vera-firmware-recovery)
46 | * [Appendix C: The 65C02 Processor](X16%20Reference%20-%20Appendix%20C%20-%2065C02%20Processor.md#appendix-c-the-65c02-processor)
47 | * [Appendix D: Official Expansion Cards](X16%20Reference%20-%20Appendix%20D%20-%20Official%20Expansion%20Cards.md#appendix-d-official-expansion-cards)
48 | * [Appendix E: Diagnostic Bank](X16%20Reference%20-%20Appendix%20E%20-%20Diagnostic%20Bank.md#appendix-e-diagnostic-bank)
49 | * [Appendix F: The 65C816 Processor](X16%20Reference%20-%20Appendix%20F%20-%2065C816%20Processor.md#appendix-f-the-65c816-processor)
50 | * [Appendix G: ZSM File Format](X16%20Reference%20-%20Appendix%20G%20-%20ZSM%20File%20Format.md#appendix-g-zsm-file-format)
51 | * [Appendix H: Onboard Upgrade Guide](X16%20Reference%20-%20Appendix%20H%20-%20Onboard%20Upgrade%20Guide.md#appendix-h-how-to-update-your-x16-to-latest-release)
52 | * [Appendix I: Character Sets](X16%20Reference%20-%20Appendix%20I%20-%20Character%20Sets.md#appendix-i-character-sets)
53 | 
54 | ## External Links
55 | 
56 | * [Official Website](https://www.commanderx16.com/)
57 | * [Documentation Source](https://github.com/X16Community/x16-docs)
58 | * [User Guide Source](https://github.com/X16Community/x16-user-guide)
59 | 
60 | <div class="page-break"></div>
61 | 


--------------------------------------------------------------------------------
/X16 Reference - 01 - Overview.md:
--------------------------------------------------------------------------------
 1 | 
 2 | # Chapter 1: Overview
 3 | 
 4 | The Commander X16 is a modern home computer in the philosophy of Commodore computers like the VIC-20 and the C64.
 5 | 
 6 | **Features:**
 7 | 
 8 | * 8-bit 65C02S CPU at 8 MHz ([*](#future-65c816-support))
 9 | * 512 KB banked RAM (upgradeable to 2 MB on the X16 Developer Edition)
10 | * 512 KB ROM
11 | * Expansion Cards (Gen 1) & Cartridges (Gen 1 and Gen 2)
12 |   * Up to 3.5MB of RAM/ROM
13 |   * 5 32-byte Memory-Mapped IO slots
14 | * VERA video controller
15 |   * Up to 640x480 resolution
16 |   * 256 colors from a palette of 4096
17 |   * 128 sprites
18 |   * VGA, NTSC and RGB output
19 |   * Powered by a Lattice ICE40UP5K FPGA
20 | * Three sound sources
21 |   * Yamaha YM2151: 8 channels, 4-operator FM synthesis
22 |   * VERA PSG: 16 channels, 4 waveforms
23 |   * VERA PCM: Up to 48 kHz, 16 bit, stereo
24 | * Connectivity:
25 |   * PS/2 keyboard and mouse
26 |   * 4 NES/SNES controllers
27 |   * SD card
28 |   * Commodore Serial Bus ("IEC")
29 |   * Many Free GPIOs ("user port")
30 | 
31 | As a modern sibling of the line of Commodore home computers, the Commander X16 is reasonably compatible with computers of that line.
32 | 
33 | * Pure BASIC programs are fully backwards compatible with the VIC-20 and the C64.
34 | * POKEs for video and audio are not compatible with any Commodore computer. (There are no VIC or SID chips, for example.)
35 | * Pure machine language programs ($FF81+ KERNAL API) are compatible with Commodore computers.
36 | 
37 | ## Future 65C816 Support
38 | 
39 | A future upgrade path for the X16 may involve the 65C816. It is almost fully
40 | compatible with the 65C02 except for 4 instructions (`BBRx`, `BBSx`, `RMBx`, and `SMBx`).
41 | It is advisable not to use these instructions when writing programs for the X16.
42 | 
43 | <!-- For PDF formatting -->
44 | <div class="page-break"></div>
45 | 


--------------------------------------------------------------------------------
/X16 Reference - 02 - Getting Started.md:
--------------------------------------------------------------------------------
  1 | 
  2 | # Chapter 2: Getting Started
  3 | 
  4 | This is a brief guide to your first few minutes on the Commander X16. For a
  5 | complete New User experience, please refer to the
  6 | [Commander X16 User Guide](https://github.com/X16Community/x16-user-guide).
  7 | 
  8 | ## Finding and starting programs
  9 | 
 10 | When starting your Commander X16, you'll notice that it's not like other
 11 | computers. There is no GUI, and command line commands like `DIR` or `LS` don't
 12 | get you anywhere. Here are some quick tips to getting started:
 13 | 
 14 | The Commander X16 uses a full screen interface known as "Editor". This was unique
 15 | when it was introduced on the PET in 1977, when most computers still treated the
 16 | screen as if it was a teletype display. The full screen Editor lets you use the
 17 | arrow keys to move around the screen and edit or re-enter input from previous
 18 | interactions.
 19 | 
 20 | The first thing you will want to do is view a list of files on your SD card.
 21 | Type the below command and press the Return key (or Enter key) to see a list of
 22 | files:
 23 | 
 24 | ### DOS
 25 | 
 26 | `DOS "$"`
 27 | 
 28 | You can also type `@$` and press Return. All of the commands you type must be
 29 | followed by the Return or Enter key, to actually execute the command.
 30 | 
 31 | Let's try some variations on this command:
 32 | 
 33 | `DOS "$=D"` lists just the subdirectories in the current directory.
 34 | 
 35 | To get the DOS command a little faster, try pressing F8, then typing `$=D`. You
 36 | can even leave off the last quote; DOS doesn't care.
 37 | 
 38 | So now that you have a list of directories, try moving to one:
 39 | 
 40 | `DOS "CD:BASIC"`
 41 | 
 42 | Press F7 or type `DOS"$` again to list the files in this directory. A file with
 43 | .PRG at the end is a "Program" file and can be loaded with the LOAD command. The
 44 | shortcut for LOAD" is the F3 key. Try it now:
 45 | 
 46 | ### LOAD
 47 | 
 48 | `LOAD "MAD.PRG"`
 49 | 
 50 | You can see that the program list loaded by typing `LIST` and pressing Enter.
 51 | 
 52 | ### RUN
 53 | 
 54 | Now type `RUN` and Enter. This will start the loaded program.
 55 | 
 56 | ### STOP
 57 | 
 58 | STOP isn't a command: it's a key. Press it to stop the running program.
 59 | 
 60 | If you are using the official Commander X16 keyboard, the key is labeled
 61 | `RUN STOP` and is up near the upper right corner of the keyboard.
 62 | 
 63 | If you are using a PC keyboard, it's probably labeled `Pause` or `Pause Brk`.
 64 | 
 65 | Holding Control and pressing C (also written as `Control+C` or `^C`) will also
 66 | stop the running program.
 67 | 
 68 | There are a few ways to get back to the text screen, but the quickest is to
 69 | hold Control, Alt, and press the Del key. (Or just press the RESET button.)
 70 | 
 71 | ## Using The Keyboard
 72 | 
 73 | The Commander X16's keyboard is a little different than a standard PC: there are
 74 | three distinct modes of operation, and the keyboard can create graphic symbols
 75 | known as PETSCII characters. There are also some special keys used for
 76 | controlling the computer.
 77 | 
 78 | ### PETSCII Characters
 79 | 
 80 | When the system first boots up, the X16 will be in PETSCII Upper Case/Graphic
 81 | mode. Pressing a letter key without the shift key will generate an upper case
 82 | letter. Unlike a PC or Mac, this mode does not have any lower case text, so
 83 | everything you type is UPPER CASE.
 84 | 
 85 | Now, notice the extra symbols on your keycaps? There are two sets of extra
 86 | symbols: the ones on the lower-right can be accessed by holding SHIFT and a
 87 | letter. Go ahead: try pressing Shift and S. You should see a small heart symbol
 88 | on your screen. We know you'll love the Commander X16 as much as we do. Press
 89 | Alt and a letter, and you'll get the symbol on the lower-left corner of the
 90 | screen. Try pressing Alt and the ` key next to the nummber 1. You should get a
 91 | large + symbol. One of the Plusses of PETSCII is using these line drawing
 92 | symbols to draw shapes on the screen.
 93 | 
 94 | You can also change colors by pressing Control and a number. Go ahead: Press
 95 | Control+1 and type a few letters. Notice they come out in black. Now try Alt+1.
 96 | Notice the cursor changes to orange, and notice the next thing you type comes
 97 | out orange.
 98 | 
 99 | You can also use Control+9 to turn on Reverse Print and Control+0 to turn it off.
100 | 
101 | There are some unexpected changes to the PC keyboard layout, as follows:
102 | 
103 | * The Grave key (`) prints a left arrow (←) symbol.
104 | * Shift+Grave prints the Pi symbol (π). This is actually the constant "pi". Try it by typing `PRINT π` and RETURN.
105 | * Shift+6 prints an up arrow (↑)
106 | * The \ key prints the British Pound (£).
107 | * The pipe (|) is replaced with a triangle corner symbol.
108 | * { and } are replaced with two box drawing symbols.
109 | * Underline (Shift+-) is replaced with a | symbol.
110 | 
111 | Note that programming languages that need {, }, and _ will alter the character
112 | set to show those symbols on the appropriate keys when needed. Or you can use
113 | ISO mode when editing C code in EDIT.
114 | 
115 | ### Lower Case Mode
116 | 
117 | WORKING IN _PETSCII_ MIGHT MAKE PEOPLE THINK YOU'RE YELLING ALL THE TIME.
118 | Fortunately, there's an upper/lower case mode, too: Hold the Alt key and tap
119 | Shift to activate lower case. Notice that the upper case letters shift to lower
120 | case, and the shifted graphic symbols (such as the heart) shift to upper case
121 | letters. The tradeoff of upper/lower case mode is that half of the graphic
122 | symbols are unavailable, but you you get lower case letters.
123 | 
124 | Now try typing a command. `print "Hello World"` and press RETURN. Notice that
125 | you need to type `print` in lower case. If you did it right, you should see
126 | "Hello World" appear on the next line.
127 | 
128 | Now tap Alt+Shift again. The text will change to |ELLO oORLD. Again, this is the
129 | tradeoff: you can have the Shifted graphic symbols or lower case, but not both.
130 | 
131 | ### ISO Mode
132 | 
133 | Finally, the computer has ISO mode. The ISO mode character set operates more
134 | like a PC, with upper case text, lower case text, and an assortment of accented
135 | and other letters. In addition, ISO mode has the \, ~, {, and } symbols, which
136 | are not available in PETSCII modes. ISO mode is useful when you need PC
137 | compatibility or want the letters with accents. Elsewhere in this guide, we have
138 | a full manual on using the Right Alt key to compose accented symbols, like é or
139 | ō. Getting back to PETSCII mode from ISO mode is a little more complicated.
140 | Press Control+Alt+RESTORE (or Control+Alt+PrintScreen) to warm start BASIC and
141 | switch back to PETSCII mode.
142 | 
143 | ### EDIT text modes
144 | 
145 | The built-in EDIT utility includes a character set mode switch: Press Control+E
146 | to cycle through Upper/Graphic, Upper/Lower, and ISO mode.
147 | 
148 | ## Special Keys
149 | 
150 | ### RUN STOP
151 | 
152 | This key actually has two separate functions: "RUN" and "STOP". Holding
153 | Shift+RUN will load the first program on your SD card and automatically run it.
154 | If you are using the SD card that came with your Commander X16, this will print
155 | some information on getting started with your computer.
156 | 
157 | If you are running a BASIC program, pressing STOP will stop the program.
158 | 
159 | ### RESTORE
160 | 
161 | As mentioned above, RESTORE can be used with Control+Alt to perform a
162 | warm start of BASIC. Less drastic than a cold boot, this stops a running
163 | program and returns you to the `READY.` prompt. If you had a BASIC program
164 | loaded, you can still re-start it with RUN or view it with LIST.
165 | 
166 | ### Control+Alt_Delete
167 | 
168 | Yes, the Commander X16 has the famous "3 fingered salute." This performs a cold
169 | boot of the computer, including a full power cycle. You will be returned to the
170 | boot screen, and if you have an AUTOEXEC.X16, it will execute on startup.
171 | 
172 | ### 40/80 DISPLAY
173 | 
174 | This switches the computer between 80x60 text mode and 40x30 text mode. 40x30
175 | is more useful on CRT screens, so you may want to boot up into 40x30 mode. You
176 | can set these modes with BASIC by typing
177 | 
178 | `SCREEN 1` or `SCREEN 3`.
179 | 
180 | Protip: you can force your computer to start in 40-column mode by modifying your
181 | AUTOBOOT.X16 file:
182 | 
183 | ```basic
184 | LOAD "AUTOBOOT.X16"
185 | 0 SCREEN 3
186 | SAVE "@:AUTOBOOT.X16"
187 | BOOT
188 | ```
189 | 
190 | Don't worry, if you don't like this change, you can change it back:
191 | 
192 | ```basic
193 | LOAD "AUTOBOOT.X16"
194 | SCREEN 1
195 | SAVE "@:AUTOBOOT.X16"
196 | BOOT
197 | ```
198 | 
199 | ### F-KEYS
200 | 
201 | The F-keys, also known as the "Function Keys" are pre-loaded with special
202 | shortcuts:
203 | 
204 | **F1** `LIST` Displays your currently loaded BASIC program.
205 | 
206 | **F2** `SAVE"@:` is a quick shortcut for saving a program. The @: allows you to
207 | overwrite an existing file with the same name.
208 | 
209 | **F3** `LOAD "` helps you load a program. Protip: if you use @$ to get a
210 | directory listing, you can then use the arrow keys to move up to a line with a
211 | filename. Press F3 and press RETURN to load a file.
212 | 
213 | **F4** and RETURN swaps between 40 and 80 column screen modes.
214 | 
215 | **F5** `RUN` runs the currently loaded program
216 | 
217 | **F6** `MONITOR` Runs the machine monitor. The monitor allows you to directly
218 | edit memory, view assembly language dumps, and even write short assembly
219 | language programs at your keyboard.
220 | 
221 | **F7** `DOS"$` Lists the current directory
222 | 
223 | **F8** `DOS"` allows you to enter a disk command, such as CD:. More info can be
224 | found in chapter 13.
225 | 
226 | ## WHAT IS `PC  RA RO AC XR YR SP NV#BDIZC`?
227 | 
228 | There are times when the computer will drop to the MONITOR prompt. That looks
229 | like this:
230 | 
231 | ```text
232 | C*
233 |    PC  RA RO AC XR YR SP NV#BDIZC
234 | .;E3BB 01 04 00 65 2B F6 ........
235 | .█
236 | ```
237 | 
238 | This is the MONITOR screen. You can get there in BASIC by typing `MON`.
239 | 
240 | Type `X` and Enter to exit back to BASIC. If you just get bounced to MONITOR
241 | again, then you'll need to Control+Alt+Restore or Control+Alt+Delete to restore
242 | to a working state.
243 | 
244 | MONITOR is covered in [Chapter 7](X16%20Reference%20-%2007%20-%20Machine%20Language%20Monitor.md#chapter-6-machine-language-monitor).
245 | 
246 | <!-- For PDF formatting -->
247 | <div class="page-break"></div>
248 | 


--------------------------------------------------------------------------------
/X16 Reference - 03 - Editor.md:
--------------------------------------------------------------------------------
  1 | 
  2 | # Chapter 3: Editor
  3 | 
  4 | The X16 has a built-in screen editor that is backwards-compatible with the C64, but has many new features.
  5 | 
  6 | ## Modes
  7 | 
  8 | The editor's default mode is 80x60 text mode. The following text mode resolutions are supported:
  9 | 
 10 | | Mode | Description |
 11 | |------|-------------|
 12 | | $00  | 80x60 text  |
 13 | | $01  | 80x30 text  |
 14 | | $02  | 40x60 text  |
 15 | | $03  | 40x30 text  |
 16 | | $04  | 40x15 text  |
 17 | | $05  | 20x30 text  |
 18 | | $06  | 20x15 text  |
 19 | | $07  | 22x23 text  |
 20 | | $08  | 64x50 text  |
 21 | | $09  | 64x25 text  |
 22 | | $0A  | 32x50 text  |
 23 | | $0B  | 32x25 text  |
 24 | | $80  | 320x240@256c<br/>40x30 text |
 25 | 
 26 | Mode $80 contains two layers: a text layer on top of a graphics screen. In this mode, text color 0 is translucent instead of black.
 27 | 
 28 | To switch modes, use the BASIC statement `SCREEN` or the KERNAL API `screen_mode`. In the BASIC editor, the F4 key toggles between modes 0 (80x60) and 3 (40x30).
 29 | 
 30 | <!-- For PDF formatting -->
 31 | <div class="page-break"></div>
 32 | 
 33 | ## ISO Mode
 34 | 
 35 | In addition to PETSCII, the X16 also supports the ISO-8859-15 character encoding. In ISO-8859-15 mode ("ISO mode"):
 36 | 
 37 | * The character set is switched from Commodore-style (with PETSCII drawing characters) to a new ASCII/ISO-8859-15 compatible set, which covers most Western European writing systems.
 38 | * The encoding (`CHR$()` in BASIC and `BSOUT` in machine language) now complies with ASCII and ISO-8859-15.
 39 | * The keyboard driver will return ASCII/ISO-8859-15 codes.
 40 | 
 41 | This is the encoding:
 42 | 
 43 | |        |x0 |x1 |x2 |x3 |x4 |x5 |x6 |x7 |x8 |x9 |xA |xB |xC |xD |xE |xF |
 44 | |--------|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
 45 | | **0x** |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
 46 | | **1x** |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
 47 | | **2x** |   | ! | " | # | $ | % | & | ' | ( | ) | * | + | , | - | . | / |
 48 | | **3x** | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | : | ; | < | = | > | ? |
 49 | | **4x** | @ | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O |
 50 | | **5x** | P | Q | R | S | T | U | V | W | X | Y | Z | [ | \ | ] | ^ | _ |
 51 | | **6x** | ` | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o |
 52 | | **7x** | p | q | r | s | t | u | v | w | x | y | z | { | \| | } | ~ |   |
 53 | | **8x** |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
 54 | | **9x** |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
 55 | | **Ax** |   | ¡ | ¢ | £ | € | ¥ | Š | § | š | © | ª | « | ¬ | 🦋 | ® | ¯ |
 56 | | **Bx** | ° | ± | ² | ³ | Ž | µ | ¶ | · | ž | ¹ | º | » | Œ | œ | Ÿ | ¿ |
 57 | | **Cx** | À | Á | Â | Ã | Ä | Å | Æ | Ç | È | É | Ê | Ë | Ì | Í | Î | Ï |
 58 | | **Dx** | Ð | Ñ | Ò | Ó | Ô | Õ | Ö | × | Ø | Ù | Ú | Û | Ü | Ý | Þ | ß |
 59 | | **Ex** | à | á | â | ã | ä | å | æ | ç | è | é | ê | ë | ì | í | î | ï |
 60 | | **Fx** | ð | ñ | ò | ó | ô | õ | ö | ÷ | ø | ù | ú | û | ü | ý | þ | ÿ |
 61 | 
 62 | * The non-printable areas $00-$1F and $80-$9F in the character set are filled with inverted variants of the codes $40-$5F and $60-$7F, respectively.
 63 | * The code $AD is a non-printable soft hyphen in ISO-8859-15. The ROM character set contains the Commander X16 logo at this location.
 64 | 
 65 | ISO mode can be enabled and disabled using two new control codes:
 66 | 
 67 | * `CHR$($0F)`: enable ISO mode
 68 | * `CHR$($8F)`: enable PETSCII mode (default)
 69 | 
 70 | You can also enable ISO mode in direct mode by pressing Ctrl+`O`.
 71 | 
 72 | **Important:** In ISO mode, BASIC keywords need to be written in upper case, that is, they have to be entered with the Shift key down, and abbreviating keywords is no longer possible.
 73 | 
 74 | ## Background Color
 75 | 
 76 | In regular BASIC text mode, the video controller supports 16 foreground colors and 16 background colors for each character on the screen.
 77 | 
 78 | The new "swap fg/bg color" code is useful to change the background color of the cursor, like this:
 79 | 
 80 | ```basic
 81 | PRINT CHR$(1);   : REM SWAP FG/BG
 82 | PRINT CHR$($1C); : REM SET FG COLOR TO RED
 83 | PRINT CHR$(1);   : REM SWAP FG/BG
 84 | ```
 85 | 
 86 | The new BASIC instruction `COLOR` makes this easier, but the trick above can also be used from machine code programs.
 87 | 
 88 | To set the background color of the complete screen, it just has to be cleared after setting the color:
 89 | 
 90 | ```basic
 91 | PRINT CHR$(147);
 92 | ```
 93 | 
 94 | ## Scrolling
 95 | 
 96 | The C64 editor could only scroll the screen up (when overflowing the last line or printing or entering DOWN on the last line). The X16 editor scrolls both ways: When the cursor is on the first line and UP is printed or entered, the screen contents scroll down by a line.
 97 | 
 98 | ## New Control Characters
 99 | 
100 | This is the set of all supported PETSCII control characters. Entries in bold indicate new codes compared to the C64:
101 | 
102 | If there are two meanings listed, the first indicates input (a keypress) and the second indicates output.
103 | 
104 | | Code  |                            |                           | Code  |
105 | |-------|----------------------------|---------------------------|-------|
106 | | $00  | NULL                       | **VERBATIM MODE**         | $80  |
107 | | $01  | **SWAP COLORS**            | COLOR: ORANGE             | $81  |
108 | | $02  | **PAGE DOWN**              | **PAGE UP**               | $82  |
109 | | $03  | STOP                       | RUN                       | $83  |
110 | | $04  | **END**                    | **HELP**                  | $84  |
111 | | $05  | COLOR: WHITE               | F1                        | $85  |
112 | | $06  | **MENU**                   | F3                        | $86  |
113 | | $07  | **BELL**                   | F5                        | $87  |
114 | | $08  | DISALLOW CHARSET SW (SHIFT+ALT) | F7                        | $88  |
115 | | $09  | **TAB** / ALLOW CHARSET SW | F2                        | $89  |
116 | | $0A  | **LF**                     | F4                        | $8A  |
117 | | $0B  | -                          | F6                        | $8B  |
118 | | $0C  | -                          | F8                        | $8C  |
119 | | $0D  | RETURN                     | SHIFTED RETURN            | $8D  |
120 | | $0E  | CHARSET: LOWER/UPPER       | CHARSET: UPPER/PETSCII    | $8E  |
121 | | $0F  | **CHARSET: ISO ON**        | **CHARSET: ISO OFF**      | $8F  |
122 | | $10  | **F9**                     | COLOR: BLACK              | $90  |
123 | | $11  | CURSOR: DOWN               | CURSOR: UP                | $91  |
124 | | $12  | REVERSE ON                 | REVERSE OFF               | $92  |
125 | | $13  | HOME                       | CLEAR                     | $93  |
126 | | $14  | DEL (PS/2 BACKSPACE)       | INSERT                    | $94  |
127 | | $15  | **F10**                    | COLOR: BROWN              | $95  |
128 | | $16  | **F11**                    | COLOR: LIGHT RED          | $96  |
129 | | $17  | **F12**                    | COLOR: DARK GRAY          | $97  |
130 | | $18  | **SHIFT+TAB**              | COLOR: MIDDLE GRAY        | $98  |
131 | | $19  | **FWD DEL (PS/2 DEL)**     | COLOR: LIGHT GREEN        | $99  |
132 | | $1A  | -                          | COLOR: LIGHT BLUE         | $9A  |
133 | | $1B  | ESC                        | COLOR: LIGHT GRAY         | $9B  |
134 | | $1C  | COLOR: RED                 | COLOR: PURPLE             | $9C  |
135 | | $1D  | CURSOR: RIGHT              | CURSOR: LEFT              | $9D  |
136 | | $1E  | COLOR: GREEN               | COLOR: YELLOW             | $9E  |
137 | | $1F  | COLOR: BLUE                | COLOR: CYAN               | $9F  |
138 | 
139 | **Notes:**
140 | 
141 | * $01: SWAP COLORS swaps the foreground and background colors in text mode
142 | * \$07/\$09/\$0A/\$18/\$1B: have been added for ASCII compatibility. *[\$0A/\$18/\$1B do not have any effect on output. Outputs of \$08/\$09 have their traditional C64 effect]*
143 | * \$80: VERBATIM MODE prints the next character (only!) as a glyph without interpretation. This is similar to quote mode, but also includes codes CR (\$0D) and DEL (\$14).
144 | * F9-F12: these codes match the C65 additions
145 | * $84: This code is generated when pressing SHIFT+END.
146 | * Additionally, the codes \$04/\$06/\$0B/\$0C are interpreted when printing in graphics mode using `GRAPH_put_char`.
147 | 
148 | <!-- For PDF formatting -->
149 | <div class="page-break"></div>
150 | 
151 | ## Keyboard Layouts
152 | 
153 | The editor supports multiple keyboard layouts.
154 | 
155 | ## Default Layout
156 | 
157 | On boot, the US layout (`ABC/X16`) is active:
158 | 
159 | * In PETSCII mode, it matches the US layout where possible, and can reach all PETSCII symbols.
160 | * In ISO mode, it matches the Macintosh US keyboard and can reach all ISO-8859-15 characters. Some characters are reachable through key combinations:
161 | 
162 | | Key               | Result |
163 | |-------------------|--------|
164 | | Alt+`1`           | ¡      |
165 | | Alt+`3`           | £      |
166 | | Alt+`4`           | ¢      |
167 | | Alt+`5`           | §      |
168 | | Alt+`7`           | ¶      |
169 | | Alt+`9`           | ª      |
170 | | Alt+`0`           | º      |
171 | | Alt+`q`           | œ      |
172 | | Alt+`r`           | ®      |
173 | | Alt+`t`           | Þ      |
174 | | Alt+`y`           | ¥      |
175 | | Alt+`o`           | ø      |
176 | | Alt+`\`           | «      |
177 | | Alt+`s`           | ß      |
178 | | Alt+`d`           | ð      |
179 | | Alt+`g`           | ©      |
180 | | Alt+`l`           | ¬      |
181 | | Alt+`'`           | æ      |
182 | | Alt+`m`           | µ      |
183 | | Alt+`/`           | ÷      |
184 | | Shift+Alt+`2`     | €      |
185 | | Shift+Alt+`8`     | °      |
186 | | Shift+Alt+`9`     | ·      |
187 | | Shift+Alt+`-`     | X16 logo |
188 | | Shift+Alt+`=`     | ±      |
189 | | Shift+Alt+`q`     | Π     |
190 | | Shift+Alt+`t`     | þ      |
191 | | Shift+Alt+`\`     | »      |
192 | | Shift+Alt+`a`     | ¹      |
193 | | Shift+Alt+`d`     | Ð      |
194 | | Shift+Alt+`k`     | X16 logo |
195 | | Shift+Alt+`'`     | Æ      |
196 | | Shift+Alt+`c`     | ³      |
197 | | Shift+Alt+`b`     | ²      |
198 | | Shift+Alt+`/`     | ¿      |
199 | 
200 | (The X16 logo is code point \\xad, SHY, soft-hyphen.)
201 | 
202 | The following combinations are dead keys:
203 | 
204 | * Alt+<tt>&#96;</tt>
205 | * Alt+`6`
206 | * Alt+`e`
207 | * Alt+`u`
208 | * Alt+`p`
209 | * Alt+`a`
210 | * Alt+`k`
211 | * Alt+`;`
212 | * Alt+`x`
213 | * Alt+`c`
214 | * Alt+`v`
215 | * Alt+`n`
216 | * Alt+`,`
217 | * Alt+`.`
218 | * Shift+Alt+`S`
219 | 
220 | They generate additional characters when combined with a second keypress:
221 | 
222 | | First <br/>Key      | Second <br/>Key | Result |
223 | |--------------------|-----|---|
224 | | Alt+<tt>&#96;</tt> | `a` | à |
225 | | Alt+<tt>&#96;</tt> | `e` | è |
226 | | Alt+<tt>&#96;</tt> | `i` | ì |
227 | | Alt+<tt>&#96;</tt> | `o` | ò |
228 | | Alt+<tt>&#96;</tt> | `u` | ù |
229 | | Alt+<tt>&#96;</tt> | `A` | À |
230 | | Alt+<tt>&#96;</tt> | `E` | È |
231 | | Alt+<tt>&#96;</tt> | `I` | Ì |
232 | | Alt+<tt>&#96;</tt> | `O` | Ò |
233 | | Alt+<tt>&#96;</tt> | `U` | Ù |
234 | | Alt+<tt>&#96;</tt> | `␣` | &#96; |
235 | | Alt+`6`            | `e` | ê |
236 | | Alt+`6`            | `u` | û |
237 | | Alt+`6`            | `i` | î |
238 | | Alt+`6`            | `o` | ô |
239 | | Alt+`6`            | `a` | â |
240 | | Alt+`6`            | `E` | Ê |
241 | | Alt+`6`            | `U` | Û |
242 | | Alt+`6`            | `I` | Î |
243 | | Alt+`6`            | `O` | Ô |
244 | | Alt+`6`            | `A` | Â |
245 | | Alt+`e`            | `e` | é |
246 | | Alt+`e`            | `y` | ý |
247 | | Alt+`e`            | `u` | ú |
248 | | Alt+`e`            | `i` | í |
249 | | Alt+`e`            | `o` | ó |
250 | | Alt+`e`            | `a` | á |
251 | | Alt+`e`            | `E` | É |
252 | | Alt+`e`            | `Y` | Ý |
253 | | Alt+`e`            | `U` | Ú |
254 | | Alt+`e`            | `I` | Í |
255 | | Alt+`e`            | `O` | Ó |
256 | | Alt+`e`            | `A` | Á |
257 | | Alt+`u`            | `e` | ë |
258 | | Alt+`u`            | `y` | ÿ |
259 | | Alt+`u`            | `u` | ü |
260 | | Alt+`u`            | `i` | ï |
261 | | Alt+`u`            | `o` | ö |
262 | | Alt+`u`            | `a` | ä |
263 | | Alt+`u`            | `E` | Ë |
264 | | Alt+`u`            | `Y` | Ÿ |
265 | | Alt+`u`            | `U` | Ü |
266 | | Alt+`u`            | `I` | Ï |
267 | | Alt+`u`            | `O` | Ö |
268 | | Alt+`u`            | `A` | Ä |
269 | | Alt+`p`            | `␣` | , |
270 | | Alt+`a`            | `␣` | ¯ |
271 | | Alt+`k`            | `a` | å |
272 | | Alt+`k`            | `A` | Å |
273 | | Alt+`x`            | `␣` | . |
274 | | Alt+`c`            | `c` | ç |
275 | | Alt+`c`            | `C` | Ç |
276 | | Alt+`v`            | `s` | š |
277 | | Alt+`v`            | `z` | ž |
278 | | Alt+`v`            | `S` | Š |
279 | | Alt+`v`            | `Z` | Ž |
280 | | Alt+`n`            | `o` | õ |
281 | | Alt+`n`            | `a` | ã |
282 | | Alt+`n`            | `n` | ñ |
283 | | Alt+`n`            | `O` | Õ |
284 | | Alt+`n`            | `A` | Ã |
285 | | Alt+`n`            | `N` | Ñ |
286 | | Shift+Alt+`s`      | `␣` | \\xa0 |
287 | | Shift+Alt+`;`      | `=` | × |
288 | 
289 | "␣" denotes the space bar.
290 | 
291 | ### ROM Keyboard Layouts
292 | 
293 | The following keyboard layouts are available from ROM. You can select one directly with the BASIC `KEYMAP` command, e.g. `KEYMAP"ABC/X16"`, or via the X16 Control Panel with the BASIC `MENU` command.
294 | 
295 | | Identifier  | Description                         | Code                                       |
296 | |-------------|-------------------------------------|--------------------------------------------|
297 | | `ABC/X16`   | ABC - Extended (X16)                | -                                          |
298 | | `EN-US/INT` | United States - International       | [00020409](http://kbdlayout.info/00020409) |
299 | | `EN-GB`     | United Kingdom                      | [00000809](http://kbdlayout.info/00000809) |
300 | | `SV-SE`     | Swedish                             | [0000041D](http://kbdlayout.info/0000041D) |
301 | | `DE-DE`     | German                              | [00000407](http://kbdlayout.info/00000407) |
302 | | `DA-DK`     | Danish                              | [00000406](http://kbdlayout.info/00000406) |
303 | | `IT-IT`     | Italian                             | [00000410](http://kbdlayout.info/00000410) |
304 | | `PL-PL`     | Polish (Programmers)                | [00000415](http://kbdlayout.info/00000415) |
305 | | `NB-NO`     | Norwegian                           | [00000414](http://kbdlayout.info/00000414) |
306 | | `HU-HU`     | Hungarian                           | [0000040E](http://kbdlayout.info/0000040E) |
307 | | `ES-ES`     | Spanish                             | [0000040A](http://kbdlayout.info/0000040A) |
308 | | `FI-FI`     | Finnish                             | [0000040B](http://kbdlayout.info/0000040B) |
309 | | `PT-BR`     | Portuguese (Brazil ABNT)            | [00000416](http://kbdlayout.info/00000416) |
310 | | `CS-CZ`     | Czech                               | [00000405](http://kbdlayout.info/00000405) |
311 | | `JA-JP`     | Japanese                            | [Custom IME](https://github.com/X16Community/x16-rom/pull/364) (since r49) |
312 | | `FR-FR`     | French                              | [0000040C](http://kbdlayout.info/0000040C) |
313 | | `DE-CH`     | Swiss German                        | [00000807](http://kbdlayout.info/00000807) |
314 | | `EN-US/DVO` | United States - Dvorak              | [00010409](http://kbdlayout.info/00010409) |
315 | | `ET-EE`     | Estonian                            | [00000425](http://kbdlayout.info/00000425) |
316 | | `FR-BE`     | Belgian French                      | [0000080C](http://kbdlayout.info/0000080C) |
317 | | `EN-CA`     | Canadian French                     | [00001009](http://kbdlayout.info/00001009) |
318 | | `IS-IS`     | Icelandic                           | [0000040F](http://kbdlayout.info/0000040F) |
319 | | `PT-PT`     | Portuguese                          | [00000816](http://kbdlayout.info/00000816) |
320 | | `HR-HR`     | Croatian                            | [0000041A](http://kbdlayout.info/0000041A) |
321 | | `SK-SK`     | Slovak                              | [0000041B](http://kbdlayout.info/0000041B) |
322 | | `SL-SI`     | Slovenian                           | [00000424](http://kbdlayout.info/00000424) |
323 | | `LV-LV`     | Latvian                             | [00000426](http://kbdlayout.info/00000426) |
324 | | `LT-LT`     | Lithuanian IBM                      | [00000427](http://kbdlayout.info/00000427) |
325 | 
326 | All remaining keyboards are based on the respective Windows layouts. `EN-US/INT` differs from `EN-US` only in Alt/AltGr combinations and some dead keys.
327 | 
328 | The BASIC command `KEYMAP` allows activating a specific keyboard layout. It can be added to the auto-boot file, e.g.:
329 | 
330 | ```basic
331 | 10 KEYMAP"NB-NO"
332 | SAVE"AUTOBOOT.X16
333 | ```
334 | 
335 | ### Loadable Keyboard Layouts
336 | 
337 | The tables for the active keyboard layout reside in banked RAM, at $A000 on bank 0:
338 | 
339 | | Addresses     | Description |
340 | |---------------|-------------|
341 | | \$A000-\$A07F | Table 0     |
342 | | \$A080-\$A0FF | Table 1     |
343 | | \$A100-\$A17F | Table 2     |
344 | | \$A180-\$A1FF | Table 3     |
345 | | \$A200-\$A27F | Table 4     |
346 | | \$A280-\$A07F | Table 5     |
347 | | \$A300-\$A37F | Table 6     |
348 | | \$A380-\$A3FF | Table 7     |
349 | | \$A400-\$A47F | Table 8     |
350 | | \$A480-\$A4FF | Table 9     |
351 | | \$A500-\$A57F | Table 10    |
352 | | \$A580-\$A58F | big-endian bitfield:<br/>keynum codes for which Caps means Shift |
353 | | \$A590-\$A66F | dead key table |
354 | | \$A670-\$A67E | ASCIIZ identifier (e.g. "ABC/X16") |
355 | 
356 | The first byte of each of the 11 tables is the table ID which contains the encoding and the combination of modifiers that this table is for.
357 | 
358 | | Bit | Description        |
359 | |-----|--------------------|
360 | | 7   | 0: PETSCII, 1: ISO |
361 | | 6-3 | always 0           |
362 | | 2   | Ctrl               |
363 | | 1   | Alt                |
364 | | 0   | Shift              |
365 | 
366 | * AltGr is represented by Ctrl+Alt.
367 | * ID $C6 represents Alt _or_ AltGr (ISO only)
368 | * ID $C7 represents Shift+Alt _or_ Shift+AltGr (ISO only)
369 | * Empty tables have an ID of $FF.
370 | 
371 | The identifier is followed by 127 output codes for the keynum inputs 1-127.
372 | 
373 | * Dead keys (i.e. keys that don't generate anything by themselves but modify the next key) have a code of 0 and are further described in the dead key table (ISO only)
374 | * Keys that produce nothing have an entry of 0. (They can be distinguished from dead keys as they don't have an entry in the dead key table.)
375 | 
376 | The dead key table has one section for every dead key with the following layout:
377 | 
378 | | Byte | Description                                  |
379 | |------|----------------------------------------------|
380 | | 0    | dead key ID (PETSCII/ISO and Shift/Alt/Ctrl) |
381 | | 1    | dead key scancode                            |
382 | | 2    | full length of this table in bytes           |
383 | | 3    | first additional key ISO code                |
384 | | 4    | first effective key ISO code                 |
385 | | 5    | second additional key ISO code               |
386 | | 6    | second effective key ISO code                |
387 | | ...  | ...                                          |
388 | | n-1  | terminator 0xFF                              |
389 | 
390 | Custom layouts can be loaded from disk like this:
391 | 
392 | ```BASIC
393 | BLOAD"KEYMAP",8,0,$A000
394 | ```
395 | 
396 | Here is an example that activates a layout derived from "ABC/X16", with unshifted Y and Z swapped in PETSCII mode:
397 | 
398 | ```BASIC
399 | 100 KEYMAP"ABC/X16"                               :REM START WITH DEFAULT LAYOUT
400 | 110 BANK 0                                        :REM ACTIVATE RAM BANK 0
401 | 120 FORI=0TO11:B=$A000+128*I:IFPEEK(B)<>0THENNEXT :REM SEARCH FOR TABLE $00
402 | 130 POKEB+$2E,ASC("Y")                            :REM SET KEYNUM $2E ('Z') to 'Y'
403 | 140 POKEB+$16,ASC("Z")                            :REM SET KEYNUM $16 ('Y') to 'Z'
404 | 170 REM
405 | 180 REM *** DOING THE SAME FOR SHIFTED CHARACTERS
406 | 190 REM *** IS LEFT AS AN EXERCISE TO THE READER
407 | ```
408 | 
409 | ### Custom BASIN PETSCII code override handler
410 | 
411 | **Note**: This is a new feature in R44
412 | 
413 | Some use cases of the BASIN (CHRIN) API call may benefit from being able to modify its behavior, such as intercepting or redirecting certain PETSCII codes.  The Machine Language Monitor uses this mechanism to implement custom behavior for F-keys and for loading additional disassembly or memory display when scrolling the screen.
414 | 
415 | To set up a custom handler, one must configure it before each call to BASIN.
416 | 
417 | The key handler vector is in RAM bank 0 at addresses $ac03-$ac05.  The first two bytes are the call address, and the next byte is the RAM or ROM bank.  If your callback routine is in low ram, specifying the bank in $ac05 is not necessary.
418 | 
419 | The editor will call your callback for every keystroke received and pass the PETSCII code in the A register with carry set.  If your handler does not want to override, simply return with carry set.
420 | 
421 | If you do wish to override, return with carry clear.  The editor will then unblink the cursor and call your callback a second time with carry clear _for the same PETSCII code_.  This is your opportunity to override. Before returning, you are free to update the screen or perform other KERNAL API calls (with the exception of BASIN). At the end of your routine, set `A` to the PETSCII code you wish the editor to process. If you wish to suppress the input keystroke, set `A` to `0`.
422 | 
423 | ```ASM
424 | ram_bank = $00
425 | edkeyvec = $ac03
426 | edkeybk  = $ac05
427 | 
428 | BASIN    = $ffcf
429 | BSOUT    = $ffd2
430 | 
431 | .segment "ONCE"
432 | .segment "STARTUP"
433 |     jmp start
434 | .segment "CODE"
435 | 
436 | keyhandler:
437 |     bcs @check
438 |     cmp #$54 ; 'T'
439 |     bne :+
440 |     lda #$57 ; 'W'
441 |     rts
442 | :   lda #$54 ; 'T'
443 |     rts
444 | @check:
445 |     cmp #$54 ; 'T'
446 |     beq @will_override
447 |     cmp #$57 ; 'W'
448 |     beq @will_override
449 |     sec
450 |     rts
451 | @will_override:
452 |     clc
453 |     rts
454 | 
455 | enable_basin_callback:
456 |     lda ram_bank
457 |     pha
458 |     stz ram_bank ; RAM bank 0 contains the handler vector
459 |     php
460 |     sei
461 |     lda #<keyhandler
462 |     sta edkeyvec
463 |     lda #>keyhandler
464 |     sta edkeyvec+1
465 |     ; setting the bank is optional and unnecessary
466 |     ; if the handler is in low RAM.
467 |     ; lda #0
468 |     ; sta edkeybk
469 |     plp
470 |     pla
471 |     sta ram_bank
472 |     rts
473 | 
474 | start:
475 |     jsr enable_basin_callback
476 |     ; T and W are swapped
477 | @1: jsr BASIN
478 |     cmp #13
479 |     bne @1
480 |     jsr BSOUT
481 |     ; normal BASIN
482 | @2: jsr BASIN
483 |     cmp #13
484 |     bne @2
485 | 
486 |     rts
487 | 
488 | ```
489 | 
490 | ### Custom Keyboard Keynum Code Handler
491 | 
492 | **Note**: This is new behavior for R43, differing from previous releases.
493 | 
494 | If you need more control over the translation of keynum codes into PETSCII/ISO codes, or if you need to intercept any key down or up event, you can hook the custom scancode handler vector at $032E/$032F.
495 | 
496 | On all key down and key up events, the keyboard driver calls this vector with
497 | 
498 | * .A: keycode, where bit 7 (most-significant) is clear on key down, and set on key up.
499 | 
500 | The keynum codes are enumerated [here](https://github.com/X16Community/x16-rom/blob/master/inc/keycode.inc), and their names, similar to that of PS/2 codes, are based on their function in the US layout.
501 | 
502 | The handler needs to return a key event the same way in .A
503 | 
504 | * To remove a keypress so that it is not added to the keyboard queue, return .A = 0.
505 | * To manually add a key to the keyboard queue, use the `kbdbuf_put` KERNAL API.
506 | 
507 | You can even write a completely custom keyboard translation layer:
508 | 
509 | * Place the code at $A000-$A58F in RAM bank 0. This is safe, since the tables won't be used in this case, and the active RAM bank will be set to 0 before entry to the handler.
510 | * Fill the locale at $A590.
511 | * For every keynum that should produce a PETSCII/ISO code, use `kbdbuf_put` to store it in the keyboard buffer.
512 | * Always set .A = 0 before return from the custom handler.
513 | 
514 | ```ASM
515 | ;EXAMPLE: A custom handler that prints "A" on Alt key down
516 | 
517 | setup:
518 |     sei
519 |     lda #<keyhandler
520 |     sta $032e
521 |     lda #>keyhandler
522 |     sta $032f
523 |     cli
524 |     rts
525 | 
526 | keyhandler:
527 |     pha
528 | 
529 |     and #$ff    ;ensure A sets flags
530 |     bmi exit    ;A & 0x80 is key up
531 | 
532 |     cmp #$3c    ;Left Alt keynum
533 |     bne exit
534 | 
535 |     lda #'a'
536 |     jsr $ffd2
537 | 
538 | exit:
539 |     pla
540 |     rts
541 | ```
542 | 
543 | ### Function Key Shortcuts
544 | 
545 | The following Function key macros are pre-defined for your convenience. These shortcuts only work in the screen editor. When a program is running, the F-keys generate the corresponding PETSCII character code.
546 | 
547 | | Key | Function   | Comment   |
548 | |-----|------------|-----------|
549 | | F1  | `LIST:`    | Lists the current program |
550 | | F2  | `SAVE"@:`  | Press F2 and then type a filename to save your program. The `@:` instructs DOS to allow overwrite. |
551 | | F3  | `LOAD "`   | Load a file directly, or cursor up over a file listing and press F3 to load a program. |
552 | | F4  | 40/80      | Toggles between 40 and 80 column screen modes, clearing the screen. Pressing return is required to prevent accidental mode switches. |
553 | | F5  | `RUN:`     | Run the current program. |
554 | | F6  | `MONITOR`  | Opens the Supermon machine language monitor. |
555 | | F7  | `DOS"$<cr>`| Displays a directory listing. |
556 | | F8  | `DOS"`     | Issue DOS commands. |
557 | | F9  | -          | Not defined.  Formerly cycled through keyboard layouts. Instead, use the `MENU` command to enter the X16 Control Panel, select one, and optionally save the layout as a boot preference. |
558 | | F10 | -          | Not defined |
559 | | F11 | -          | Not defined |
560 | | F12 | debug      | debug features in emulators |
561 | 
562 | <!-- For PDF formatting -->
563 | <div class="page-break"></div>
564 | 


--------------------------------------------------------------------------------
/X16 Reference - 06 - Math Library.md:
--------------------------------------------------------------------------------
  1 | 
  2 | # Chapter 6: Math Library
  3 | 
  4 | The Commander X16 contains a floating point Math library with a precision of 40 bits, which corresponds to 9 decimal digits. It is a stand-alone derivative of the library contained in Microsoft BASIC. Except for the different base address, it is compatible with the C128 and C65 libraries.
  5 | 
  6 | The full documentation of these functions can be found in the book [C128 Developers Package for Commodore 6502 Development](http://www.zimmers.net/anonftp/pub/cbm/schematics/computers/c128/servicemanuals/C128_Developers_Package_for_Commodore_6502_Development_(1987_Oct).pdf). The Math Library documentation starts in Chapter 13. (PDF page 257)
  7 | 
  8 | The following functions are available from machine language code after setting the ROM bank to 4, which is the default.
  9 | 
 10 | ## Format Conversions
 11 | 
 12 | | Address | Symbol   | Description                                                                                  |
 13 | |---------|----------|----------------------------------------------------------------------------------------------|
 14 | | $FE00   | `AYINT`  | convert floating point to integer (signed word)                                              |
 15 | | $FE03   | `GIVAYF` | convert integer (signed word) to floating point                                              |
 16 | | $FE06   | `FOUT`   | convert floating point to ASCII string                                                       |
 17 | | $FE09   | `VAL_1`  | convert ASCII string in .X:.Y length in .A, to floating point in FACC. _Caveat! Read below!_ |
 18 | | $FE0C   | `GETADR` | convert floating point to an address (unsigned word)                                         |
 19 | | $FE0F   | `FLOATC` | convert address (unsigned word) to floating point                                            |
 20 | 
 21 | **Important caveat ragarding the `VAL_1` routine in its current implementation:**
 22 | 
 23 | Unlike the other routines in the math library, this routine calls into the VAL implementation
 24 | that is inside BASIC, and so it requires much of the BASIC zeropage to be intact to function correctly.
 25 | The reason is that that routine ultimately relies on some internal BASIC routines that use a lot of BASIC zero page space.
 26 | Ideally in the future, the `VAL_1` routine gets a new implementation that doesn't rely on the code in BASIC, thereby removing this restriction.
 27 | 
 28 | **X16 Additions**
 29 | 
 30 | The following calls are new to the X16 and were not part of the C128 math library API:
 31 | 
 32 | | Address | Symbol   | Description                                     |
 33 | |---------|----------|-------------------------------------------------|
 34 | | $FE87  | `FLOAT`  | FACC = (s8).A   convert signed byte to float     |
 35 | | $FE8A  | `FLOATS` | FACC = (s16)facho+1:facho                        |
 36 | | $FE8D  | `QINT`   | facho:facho+1:facho+2:facho+3 = u32(FACC)        |
 37 | | $FE93  | `FOUTC`  | Convert FACC to ASCIIZ string at fbuffr - 1 + .Y |
 38 | 
 39 | ## Movement
 40 | 
 41 | `PACK` indicates a conversion from a normalized floating-point number in FACC to its packed format in memory; `UNPACK` indicates a conversion from the packed format in memory to the normalized format in the destination.
 42 | 
 43 | | Address | Symbol   | Description                          |
 44 | |---------|----------|--------------------------------------|
 45 | | $FE5A  | `CONUPK` | ARG = UNPACK(RAM MEM)                |
 46 | | $FE5D  | `ROMUPK` | ARG = UNPACK(ROM MEM) (use `CONUPK`) |
 47 | | $FE60  | `MOVFRM` | FACC = UNPACK(RAM MEM) (use `MOVFM`) |
 48 | | $FE63  | `MOVFM`  | FACC = UNPACK(ROM MEM)               |
 49 | | $FE66  | `MOVMF`  | MEM = PACK(ROUND(FACC))              |
 50 | | $FE69  | `MOVFA`  | FACC = ARG                           |
 51 | | $FE6C  | `MOVAF`  | FACC = ROUND(FACC); ARG = FACC       |
 52 | 
 53 | **X16 Additions**
 54 | 
 55 | The following calls are new to the X16 and were not part of the C128 math library API:
 56 | 
 57 | | Address | Symbol  | Description                                     |
 58 | |---------|---------|-------------------------------------------------|
 59 | | $FE81  | `MOVEF` | ARG = FACC                                      |
 60 | 
 61 | ## Math Functions
 62 | 
 63 | | Address | Symbol   | Description                           |
 64 | |---------|----------|---------------------------------------|
 65 | | $FE12  | `FSUB`   | FACC = MEM - FACC                     |
 66 | | $FE15  | `FSUBT`  | FACC = ARG - FACC                     |
 67 | | $FE18  | `FADD`   | FACC = MEM + FACC                     |
 68 | | $FE1B  | `FADDT`  | FACC = ARG + FACC                     |
 69 | | $FE1E  | `FMULT`  | FACC = MEM * FACC                     |
 70 | | $FE21  | `FMULTT` | FACC = ARG * FACC                     |
 71 | | $FE24  | `FDIV`   | FACC = MEM / FACC                     |
 72 | | $FE27  | `FDIVT`  | FACC = ARG / FACC                     |
 73 | | $FE2A  | `LOG`    | FACC = natural log of FACC            |
 74 | | $FE2D  | `INT`    | FACC = INT() truncate of FACC         |
 75 | | $FE30  | `SQR`    | FACC = square root of FACC            |
 76 | | $FE33  | `NEGOP`  | negate FACC (switch sign)             |
 77 | | $FE36  | `FPWR`   | FACC = raise ARG to the MEM power     |
 78 | | $FE39  | `FPWRT`  | FACC = raise ARG to the FACC power    |
 79 | | $FE3C  | `EXP`    | FACC = EXP of FACC                    |
 80 | | $FE3F  | `COS`    | FACC = COS of FACC                    |
 81 | | $FE42  | `SIN`    | FACC = SIN of FACC                    |
 82 | | $FE45  | `TAN`    | FACC = TAN of FACC                    |
 83 | | $FE48  | `ATN`    | FACC = ATN of FACC                    |
 84 | | $FE4B  | `ROUND`  | FACC = round FACC                     |
 85 | | $FE4E  | `ABS`    | FACC = absolute value of FACC         |
 86 | | $FE51  | `SIGN`   | .A = test sign of FACC                |
 87 | | $FE54  | `FCOMP`  | .A = compare FACC with MEM            |
 88 | | $FE57  | `RND_0`  | FACC = random floating point number   |
 89 | 
 90 | **X16 Additions to math functions**
 91 | 
 92 | The following calls are new to the X16 and were not part of the C128 math library API:
 93 | 
 94 | | Address | Symbol   | Description                               |
 95 | |---------|----------|-------------------------------------------|
 96 | | $FE6F  | `FADDH`  | FACC += .5                                |
 97 | | $FE72  | `ZEROFC` | FACC = 0                                  |
 98 | | $FE75  | `NORMAL` | Normalize FACC                            |
 99 | | $FE78  | `NEGFAC` | FACC = -FACC   (just use NEGOP)           |
100 | | $FE7B  | `MUL10`  | FACC *= 10                                |
101 | | $FE7E  | `DIV10`  | FACC /= 10                                |
102 | | $FE84  | `SGN`    | FACC = sgn(FACC)                          |
103 | | $FE90  | `FINLOG` | FACC += (s8).A   add signed byte to float |
104 | | $FE96  | `POLYX`  | Polynomial Evaluation 1 (SIN/COS/ATN/LOG) |
105 | | $FE99  | `POLY`   | Polynomial Evaluation 2 (EXP)             |
106 | 
107 | ## How to use the routines
108 | 
109 | **Concepts:**
110 | 
111 | * **FACC** (sometimes abbreviated to FAC): the floating point accumulator. You can compare this to the 6502 CPU's .A register,
112 |   which is the accumulator for most integer operations performed by the CPU.
113 |   FACC is the primary floating point register. Calculations are done on the value in this register,
114 |   usually combined with ARG. After the operation, usually the original value in FACC has been replaced by the result of the calculation.
115 | * **ARG**: the second floating point register, used in most calculation functions. Often the value in this register will be lost after a calculation.
116 | * **MEM**: means a floating point value stored in system memory somewhere.  The format is [40 bits (5 bytes) Microsoft binary format](https://en.wikipedia.org/wiki/Microsoft_Binary_Format).
117 |   To be able to work with given values in calculations, they need to be stored in memory somewhere in this format.
118 |   To do this you'll likely need to use a separate program to pre-convert floating point numbers to this format, unless you are using a compiler that
119 |   directly supports it.
120 | 
121 | *Note that FACC and ARG are just a bunch of zero page locations. This means you can poke around in them.
122 | But that's not good practice because their locations aren't guaranteed/public, and the format is slightly different
123 | than how the 5-byte floats are normally stored into memory. Just use one of the Movement routines to
124 | copy values into or out of FACC and ARG.*
125 | 
126 | To perform a floating point calculation, follow the following pattern:
127 | 
128 | 1. load a value into FACC. You can convert an integer, or move a MEM float number into FACC.
129 | 1. do the same but for ARG, the second floating point register.
130 | 1. call the required floating point calculation routine that will perform a calculation on FACC with ARG.
131 | 1. repeat the previous 2 steps if required.
132 | 1. the result is in FACC, move it into MEM somewhere or convert it to another type or string.
133 | 
134 | An example program that calculates and prints the distance an object has fallen over a certain period
135 | using the formula $d = \dfrac{1}{2} g {t}^{2}$
136 | 
137 | ```ASM
138 | ; calculate how far an object has fallen:  d = 1/2 * g * t^2.
139 | ; we set g = 9.81 m/sec^2, time = 5 sec -> d = 122.625 m.
140 | 
141 | CHROUT = $ffd2
142 | FOUT   = $fe06
143 | FMULTT = $fe21
144 | FDIV   = $fe24
145 | CONUPK = $fe5a
146 | MOVFM  = $fe63
147 | 
148 |     lda  #4
149 |     sta  $01         ; rom bank 4 (BASIC) contains the fp routines.
150 |     lda  #<flt_two
151 |     ldy  #>flt_two
152 |     jsr  MOVFM
153 |     lda  #<flt_g
154 |     ldy  #>flt_g
155 |     jsr  FDIV        ; FACC= g/2
156 |     lda  #<flt_time
157 |     ldy  #>flt_time
158 |     jsr  CONUPK      ; ARG = time
159 |     jsr  FMULTT      ; FACC = g/2 * time
160 |     lda  #<flt_time
161 |     ldy  #>flt_time
162 |     jsr  CONUPK      ; again ARG = time
163 |     jsr  FMULTT      ; FACC = g/2 * time * time
164 |     jsr  FOUT        ; to string
165 |     ; print string in AY
166 |     sta  $02
167 |     sty  $03
168 |     ldy  #0
169 | loop:
170 |     lda  ($02),y
171 |     beq  done
172 |     jsr  CHROUT
173 |     iny
174 |     bne  loop
175 | done:
176 |     rts
177 | 
178 | flt_g:      .byte  $84, $1c, $f5, $c2, $8f  ; float 9.81
179 | flt_time:   .byte  $83, $20, $00, $00, $00  ; float 5.0
180 | flt_two:    .byte  $82, $00, $00, $00, $00  ; float 2.0
181 | ```
182 | 
183 | ## Notes
184 | 
185 | * `RND_0`: For .Z=1, the X16 behaves differently than the C128 and C65 versions. The X16 version takes entropy from .A/.X/.Y instead of from a CIA timer. So in order to get a "real" random number, you would use code like this:
186 | 
187 | ```ASM
188 | LDA #$00
189 | PHP
190 | JSR entropy_get ; KERNAL call to get entropy into .A/.X/.Y
191 | PLP             ; restore .Z=1
192 | JSR RND_0
193 | ```
194 | 
195 | * The calls `FADDT`, `FMULTT`, `FDIVT` and `FPWRT` were broken on the C128/C65. They are fixed on the X16.
196 | * For more information on the additional calls, refer to [Mapping the Commodore 64](http://unusedino.de/ec64/technical/project64/mapping_c64.html) by Sheldon Leemon, ISBN 0-942386-23-X, but note these errata:
197 |   * `FMULT` adds mem to FACC, not ARG to FACC
198 | 
199 | <!-- For PDF formatting -->
200 | <div class="page-break"></div>
201 | 


--------------------------------------------------------------------------------
/X16 Reference - 07 - Machine Language Monitor.md:
--------------------------------------------------------------------------------
 1 | 
 2 | # Chapter 7: Machine Language Monitor
 3 | 
 4 | <img src="images/monitor.png">
 5 | 
 6 | The built-in machine language monitor can be started with the `MON` BASIC command. It is based on the monitor of the Final Cartridge III and supports most of its features.
 7 | 
 8 | If you invoke the monitor by mistake, you can exit with by typing `X`, followed by the `RETURN` key.
 9 | 
10 | Some features specific to this monitor are:
11 | 
12 | * The `I` command prints a PETSCII/ISO-encoded memory dump.
13 | * The `EC` command prints a binary memory dump. This is also useful for character sets.
14 | * Scrolling the screen with the cursor keys or F3/F5 will continue memory dumps and disassemblies, and even disassemble backwards.
15 | 
16 | The following commands are used to dump memory contents in various formats:
17 | 
18 | | Dump | Prefix  | description
19 | |------|---------|---------------
20 | | `M`  |  `:`    | 8 hex bytes
21 | | `I`  |  `'`    | 32 PETSCII/ISO characters
22 | | `EC` |  `[`    | 1 binary byte (character data)
23 | | `ES` |  `]`    | 3 binary bytes (sprite data)
24 | | `D`  |  `,`    | disassemble
25 | | `R`  |  `;`    | registers
26 | 
27 | Except for `R`, these commands take a start address and an optional end address (inclusive). The dumps are prefixed with one of the "Prefix" characters in the table above, so they can be edited by navigating the cursor over a printed line, changing the data and pressing RETURN.
28 | 
29 | Note that editing a disassembled line (prefix `,`) only allows changing the 1-3 opcode bytes. To edit the assembly, change the prefix to `A` (see below).
30 | 
31 | These are the remaining commands:
32 | 
33 | | Command | Syntax                          | Description            |
34 | |---------|---------------------------------|------------------------|
35 | | `F`     | _start_ _end_ _byte_            | fill                   |
36 | | `H`     | _start_ _end_ _byte_ [_byte_...]| hunt                   |
37 | | `C`     | _start_ _end_ _start_           | compare                |
38 | | `T`     | _start_ _end_ _start_           | transfer               |
39 | | `A`     | _address_ _instruction_         | assemble               |
40 | | `G`     | [_address_]                     | run code               |
41 | | `J`     | [_address_]                     | run subroutine         |
42 | | `$`     | _value_                         | convert hex to decimal |
43 | | `#`     | _value_                         | convert decimal to hex |
44 | | `X`     |                                 | exit monitor           |
45 | | `O`     | _bank_                          | set ROM bank           |
46 | | `K`     | _bank_                          | set RAM/VRAM bank/I2C  |
47 | | `L`     | ["_filename_"[,_dev_[,_start_]]]| load file              |
48 | | `S`     | "_filename_",_dev_,_start_,_end_| save file              |
49 | | `@`     | _command_                       | send drive command     |
50 | 
51 | * All addresses have to be 4 digits.
52 | * All bytes have to be 2 digits (including device numbers).
53 | * The end address of `S` is exclusive.
54 | * The bank argument for `K` is
55 |   * `00`-`FF`: switch to main RAM, set RAM bank
56 |   * `V0`-`V1`: switch to Video RAM, set VRAM bank
57 |   * `I`: switch to the I2C address space
58 | * The bank argument for `O` is
59 |   * `00`-`FF`: set ROM bank
60 | * `@` takes:
61 |   * `8`, `9` to change the default drive (also for `L`)
62 |   * `$` to display the disk directory
63 |   * anything else as a disk command
64 | 
65 | Monitor Display
66 | ```
67 | MON
68 | C*
69 |    PC  RA RO AC XR YR SP NV#BDIZC
70 | .;E3bb 01 04 00 00 00 F6 ........
71 | .
72 | ```
73 | | Column  | Description |
74 | |---------|-------------|
75 | |PC       | Program Counter and the current address
76 | |RA       | Active RAM Bank
77 | |RO       | Active ROM Bank
78 | |AC       | Accumulator Value
79 | |XR       | X Register Value
80 | |YR       | Y Register Value
81 | |SP       | Stack Pointer
82 | |NV#BDIZC | Status Register
83 | 
84 | | Status Register Bits | Bit Description |
85 | |----------------------|-----------------|
86 | |  N                   | Negative
87 | |  V                   | Overflow Vector
88 | | \#                   | Unused
89 | |  B                   | A Break Point is Active
90 | |  D                   | Decimal Mode Active (also known as Binary Code Decimal)
91 | |  I                   | IRQ is Inhibited
92 | |  Z                   | Zero Bit
93 | |  C                   | Carry Bit
94 | 
95 | <!-- For PDF formatting -->
96 | <div class="page-break"></div>
97 | 


--------------------------------------------------------------------------------
/X16 Reference - 08 - Memory Map.md:
--------------------------------------------------------------------------------
  1 | 
  2 | # Chapter 8: Memory Map
  3 | 
  4 | The Commander X16 has 512 KB of ROM and 2,088 KB (2 MB[^1] + 40 KB) of RAM with up to 3.5MB of RAM or ROM available to cartridges.
  5 | 
  6 | Some of the ROM/RAM is always visible at certain address ranges, while the remaining ROM/RAM is banked into one of two address windows.
  7 | 
  8 | This is an overview of the X16 memory map:
  9 | 
 10 | |Addresses  |Description                                                                             |
 11 | |-----------|----------------------------------------------------------------------------------------|
 12 | |\$0000-\$9EFF|Fixed RAM (40 KB minus 256 bytes)                                                       |
 13 | |\$9F00-\$9FFF|I/O Area (256 bytes)                                                                    |
 14 | |\$A000-\$BFFF|Banked RAM (8 KB window into one of 256 banks for a total of 2 MB)                      |
 15 | |\$C000-\$FFFF|Banked System ROM and Cartridge ROM/RAM (16 KB window into one of 256 banks, see below) |
 16 | 
 17 | ## Banked Memory
 18 | 
 19 | Writing to the following zero-page addresses sets the desired RAM or ROM bank:
 20 | 
 21 | |Address  |Description                                                   |
 22 | |---------|--------------------------------------------------------------|
 23 | |$0000    |Current RAM bank (0-255)                                      |
 24 | |$0001    |Current ROM/Cartridge bank (ROM is 0-31, Cartridge is 32-255) |
 25 | 
 26 | The currently set banks can also be read back from the respective memory locations. Both settings default to 0 on RESET.
 27 | 
 28 | ## ROM Allocations
 29 | 
 30 | Here is the ROM/Cartridge bank allocation:
 31 | 
 32 | |Bank  |Name   |Description                                            |
 33 | |------|-------|-------------------------------------------------------|
 34 | |0     |KERNAL |KERNAL operating system and drivers                    |
 35 | |1     |KEYBD  |Keyboard layout tables                                 |
 36 | |2     |CMDRDOS|The computer-based CMDR-DOS for FAT32 SD cards         |
 37 | |3     |FAT32  |The FAT32 driver itself                                |
 38 | |4     |BASIC  |BASIC interpreter                                      |
 39 | |5     |MONITOR|Machine Language Monitor                               |
 40 | |6     |CHARSET|PETSCII and ISO character sets (uploaded into VRAM)    |
 41 | |7     |DIAG   |Memory diagnostic                                      |
 42 | |8     |GRAPH  |Kernal graph and font routines                         |
 43 | |9     |DEMO   |Demo routines                                          |
 44 | |10    |AUDIO  |Audio API routines                                     |
 45 | |11    |UTIL   |System Configuration (Date/Time, Display Preferences)  |
 46 | |12    |BANNEX |BASIC Annex (code for some added BASIC functions)      |
 47 | |13-14 |X16EDIT|The built-in text editor                               |
 48 | |15    |BASLOAD|A transpiler that converts BASLOAD dialect to BASIC V2 |
 49 | |16-31 |–      |_[Currently unused]_                                   |
 50 | |32-255|–      |Cartridge RAM/ROM                                      |
 51 | 
 52 | **Important**: The layout of the banks may still change.
 53 | 
 54 | ### Cartridge Allocation
 55 | 
 56 | Cartridges can use the remaining 32-255 banks in any combination of ROM, RAM, Memory-Mapped IO, etc. See Kevin's reference cartridge design
 57 | for ideas on how this may be used. This provides up to 3.5MB of additional RAM or ROM.
 58 | 
 59 | Bootable cartridge: See [Hardware - Booting from Cartridges](X16%20Reference%20-%2014%20-%20Hardware.md#booting-from-cartridges)
 60 | 
 61 | **Important**: The layout of the banks is not yet final.
 62 | 
 63 | ## RAM Contents
 64 | 
 65 | This is the allocation of fixed RAM in the KERNAL/BASIC environment.
 66 | 
 67 | |Addresses   |Description                                                      |
 68 | |------------|-----------------------------------------------------------------|
 69 | |\$0000-\$00FF|Zero page                                                       |
 70 | |\$0100-\$01FF|CPU stack                                                       |
 71 | |\$0200-\$03FF|KERNAL and BASIC variables, vectors                             |
 72 | |\$0400-\$07FF|Available for machine code programs or custom data storage      |
 73 | |\$0800-\$9EFF|BASIC program/variables; available to the user                  |
 74 | 
 75 | The `$0400-$07FF` can be seen as the equivalent of `$C000-$CFFF` on a C64. A typical use would be for helper machine code called by BASIC.
 76 | 
 77 | ### Zero Page
 78 | 
 79 | |Addresses   |Description                             |
 80 | |------------|----------------------------------------|
 81 | |\$0000-\$0001|Banking registers                      |
 82 | |\$0002-\$0021|16 bit registers r0-r15 for KERNAL API |
 83 | |\$0022-\$007F|Available to the user                  |
 84 | |\$0080-\$009C|Used by KERNAL and DOS                 |
 85 | |\$009D-\$00A8|Reserved for DOS/BASIC                 |
 86 | |\$00A9-\$00D3|Used by the Math library (and BASIC)   |
 87 | |\$00D4-\$00FF|Used by BASIC                          |
 88 | 
 89 | Machine code applications are free to reuse the BASIC area, and if they don't use the Math library, also that area.
 90 | 
 91 | ### Banking
 92 | 
 93 | This is the allocation of banked RAM in the KERNAL/BASIC environment.
 94 | 
 95 | |Bank |Description                                    |
 96 | |-----|-----------------------------------------------|
 97 | |0    |Used for KERNAL/CMDR-DOS variables and buffers |
 98 | |1-255|Available to the user                          |
 99 | 
100 | (On systems with only 512 KB RAM, banks 64-255 are unavailable.)
101 | 
102 | During startup, the KERNAL activates RAM bank 1 as the default for the user.
103 | 
104 | ### Bank 0
105 | 
106 | |Addresses   |Description                             |
107 | |------------|----------------------------------------|
108 | |\$A000-\$BEFF| System Reserved                       |
109 | |\$BF00-\$BFFF| Parameter passing space               |
110 | 
111 | You can use the space at $0:BF00-0:$BFFF to pass parameters between programs.
112 | This space is initalized to zeroes, so you may use it however you wish.
113 | 
114 | The suggested use is to store a PETSCII string in this space and use
115 | semicolons to separate parameters. The string should be null terminated:
116 | 
117 | Example:
118 | 
119 | `FRANK;3;BLUE\x00`
120 | 
121 | A program that reads the parameters is responsible for resetting the data to
122 | zeroes, so that another program does not see unexpected data and malfunction.
123 | 
124 | ## I/O Area
125 | 
126 | This is the memory map of the I/O Area:
127 | 
128 | |Addresses    |Description                          |Speed|
129 | |-------------|-------------------------------------|-----|
130 | |\$9F00-\$9F0F|VIA I/O controller #1. [Details](X16%20Reference%20-%2012%20-%20IO%20Programming.md#chapter-12-io-programming) |8 MHz|
131 | |\$9F10-\$9F1F|VIA I/O controller #2                |8 MHz|
132 | |\$9F20-\$9F3F|VERA video controller. [Details](X16%20Reference%20-%2009%20-%20VERA%20Programmer's%20Reference.md#registers) |8 MHz|
133 | |\$9F40-\$9F41|YM2151 audio controller. [Details](X16%20Reference%20-%2011%20-%20Sound%20Programming.md#ym2151-opm-fm-synthesis) |2 MHz|
134 | |\$9F42-\$9F5F|Unavailable                          | --- |
135 | |\$9F50-\$9F5F|Planned for X16GS. [Details](https://x16community.github.io/faq/gs-faq.html) | --- |
136 | |\$9F60-\$9F7F|Expansion Card Memory Mapped IO3     |8 MHz|
137 | |\$9F80-\$9F9F|Expansion Card Memory Mapped IO4     |8 MHz|
138 | |\$9FA0-\$9FBF|Expansion Card Memory Mapped IO5     |2 MHz|
139 | |\$9FB0-\$9FBF|Used by emulator. [Details](https://github.com/X16Community/x16-emulator?tab=readme-ov-file#emulator-io-registers) | --- |
140 | |\$9FC0-\$9FDF|Expansion Card Memory Mapped IO6     |2 MHz|
141 | |\$9FE0-\$9FFF|Cartidge/Expansion Memory Mapped IO7 |2 MHz|
142 | 
143 | ### Expansion Cards & Cartridges
144 | 
145 | Expansion cards can be accessed via memory-mapped I/O (MMIO), as well as I2C. Cartridges are
146 | essentially expansion cards which are housed in an external enclosure and may contain RAM, ROM
147 | and an I2C EEPOM (for save data). Internal expansion cards may also use the RAM/ROM space,
148 | though this could cause conflicts.
149 | 
150 | While they may be uncomon, since cartridges are essentially external expansion cards in a
151 | shell, that means they can also use MMIO. This is only necessary when a cartridge includes
152 | some sort of hardware expansion and MMIO was desired (as opposed to using the I2C bus). In
153 | that case, it is recommended cartridges use the IO7 range and that range should be the
154 | last option used by expansion cards in the system.
155 | **MMIO is unneeded for cartridges which simply have RAM/ROM.**
156 | 
157 | For more information, consult the
158 | [Hardware](X16%20Reference%20-%2014%20-%20Hardware.md#chapter-14-hardware-pinouts) section of the manual.
159 | 
160 | ---
161 | 
162 | [^1]: Current development systems have 2 MB of bankable RAM.
163 | Actual hardware is currently planned to have an option of either 512 KB or 2 MB of RAM.
164 | 
165 | <!-- For PDF formatting -->
166 | <div class="page-break"></div>
167 | 


--------------------------------------------------------------------------------
/X16 Reference - 12 - IO Programming.md:
--------------------------------------------------------------------------------
  1 | 
  2 | # Chapter 12: I/O Programming
  3 | 
  4 | There are two 65C22 "Versatile Interface Adapter" (VIA) I/O controllers in the system, VIA#1 at address \$9F00 and VIA#2 at address \$9F10. The IRQ out pin of VIA#1 is connected to the CPU's IRQ line, while the IRQ out pin of VIA#2 can be configured via jumper to connect to either the CPU's IRQ or NMI line on production boards (those beginning with serial PR), or hardwired to the CPU's IRQ line on earlier boards.  
  5 | 
  6 | The-following tables describe the connections of the I/O pins:
  7 | 
  8 | **VIA#1**
  9 | 
 10 | |Pin  |Name      | Description                     |
 11 | |-----|----------|---------------------------------|
 12 | | PA0 | I2CDATA  | I2C Data                        |
 13 | | PA1 | I2CCLK   | I2C Clock                       |
 14 | | PA2 | NESLATCH | NES LATCH (for all controllers) |
 15 | | PA3 | NESCLK   | NES CLK   (for all controllers) |
 16 | | PA4 | NESDAT3  | NES DATA  (controller 3)        |
 17 | | PA5 | NESDAT2  | NES DATA  (controller 2)        |
 18 | | PA6 | NESDAT1  | NES DATA  (controller 1)        |
 19 | | PA7 | NESDAT0  | NES DATA  (controller 0)        |
 20 | | PB0 | _Unused_ |                                 |
 21 | | PB1 | _Unused_ |                                 |
 22 | | PB2 | _Unused_ |                                 |
 23 | | PB3 | SERATNO  | Serial ATN  out                 |
 24 | | PB4 | SERCLKO  | Serial CLK  out                 |
 25 | | PB5 | SERDATAO | Serial DATA out                 |
 26 | | PB6 | SERCLKI  | Serial CLK  in                  |
 27 | | PB7 | SERDATAI | Serial DATA in                  |
 28 | | CA1 | _Unused_ |                                 |
 29 | | CA2 | _Unused_ |                                 |
 30 | | CB1 | IECSRQ   |                                 |
 31 | | CB2 | _Unused_ |                                 |
 32 | 
 33 | The KERNAL uses Timer 2 for timing transmissions on the Serial Bus.
 34 | 
 35 | **VIA#2**
 36 | 
 37 | The second VIA is completely unused by the KERNAL. All its 16 GPIOs and 4 handshake I/Os can be freely used by user software.
 38 | 
 39 | ## I2C Bus
 40 | 
 41 | The Commander X16 contains an I2C bus, which is implemented through two pins of VIA#1. The system management controller (SMC) and the real-time clock (RTC) are connected through this bus. The KERNAL APIs `i2c_read_byte` and `i2c_write_byte` allow talking to these devices.
 42 | 
 43 | ### System Management Controller
 44 | 
 45 | The system management controller (SMC) is device $42 on the I2C bus. It controls the activity LED, and can be used to power down the system or inject RESET and NMI signals. It also handles communication with
 46 | the PS/2 keyboard and mouse.
 47 | 
 48 | | Register | Value          | Description               |
 49 | |----------|----------------|---------------------------|
 50 | | $01      | $00            | Power off                 |
 51 | | $01      | $01            | Hard reboot               |
 52 | | $02      | $00            | Inject RESET              |
 53 | | $03      | $00            | Inject NMI                |
 54 | | $05      | \$00/\$FF      | Activity LED off/on       |
 55 | | $07      | -              | Read from keyboard buffer |
 56 | | $08      | \$00..\$FF     | Echo                      |
 57 | | $18      | -              | Read ps2 status           |
 58 | | $19      | \$00..\$FF     | Send ps2 command          |
 59 | | $1A      | \$0000..\$FFFF | Send ps2 command (2 bytes) |
 60 | | $20      | $00            | Set mouse device ID, standard mouse |
 61 | | $20      | $03            | Set mouse device ID, Intellimouse with scroll wheel |
 62 | | $20      | $04            | Set mouse device ID, Intellimouse with scroll wheel+extra buttons |
 63 | | $21      | -              | Read from mouse buffer    |
 64 | | $22      | -              | Get mouse device ID |
 65 | | $30      | -              | Get SMC firmware version, major |
 66 | | $31      | -              | Get SMC firmware version, minor |
 67 | | $32      | -              | Get SMC firmare version, patch |
 68 | | $8F      | $31            | Start bootloader, if present |  
 69 | 
 70 | ### Real-Time-Clock
 71 | 
 72 | The Commander X16 contains a battery-backed Microchip MCP7940N real-time-clock (RTC) chip as device $6F. It provides a real-time clock/calendar, two alarms and 64 bytes of battery-backed SRAM (non-volatile RAM).
 73 | 
 74 | | Register | Description        |
 75 | |----------|--------------------|
 76 | | $00      | Clock seconds      |
 77 | | $01      | Clock minutes      |
 78 | | $02      | Clock hours        |
 79 | | $03      | Clock weekday      |
 80 | | $04      | Clock day          |
 81 | | $05      | Clock month        |
 82 | | $06      | Clock year         |
 83 | | $07      | Control            |
 84 | | $08      | Oscillator trim    |
 85 | | $09      | _reserved_         |
 86 | | $0A      | Alarm 0 seconds    |
 87 | | $0B      | Alarm 0 minutes    |
 88 | | $0C      | Alarm 0 hours      |
 89 | | $0D      | Alarm 0 weekday    |
 90 | | $0E      | Alarm 0 day        |
 91 | | $0F      | Alarm 0 month      |
 92 | | $10      | _reserved_         |
 93 | | $11      | Alarm 1 seconds    |
 94 | | $12      | Alarm 1 minutes    |
 95 | | $13      | Alarm 1 hours      |
 96 | | $14      | Alarm 1 weekday    |
 97 | | $15      | Alarm 1 day        |
 98 | | $16      | Alarm 1 month      |
 99 | | $17      | _reserved_         |
100 | | $18      | Power-fail minutes |
101 | | $19      | Power-fail hours   |
102 | | $1A      | Power-fail day     |
103 | | $1B      | Power-fail month   |
104 | | $1C      | Power-up minutes   |
105 | | $1D      | Power-up hours     |
106 | | $1E      | Power-up day       |
107 | | $1F      | Power-up month     |
108 | | \$20-\$5F  | 64 Bytes SRAM      |
109 | 
110 | ####  SRAM (NVRAM)
111 | | Register  | Description        |
112 | |-----------|--------------------|
113 | | \$20-\$3F | User NVRAM         |
114 | | \$40-\$5F | KERNAL NVRAM       |
115 | | $40       | Active profile     |
116 | | \$41-\$4D | Profile 0 (80x60)  |
117 | | \$4E-\$5A | Profile 1 (40x30)  |
118 | | \$41/\$4E | Screen mode        |
119 | | \$42/\$4F | VERA_DC_VIDEO      |
120 | | \$43/\$50 | VERA_DC_HSCALE     |
121 | | \$44/\$51 | VERA_DC_VSCALE     |
122 | | \$45/\$52 | VERA_DC_BORDER     |
123 | | \$46/\$53 | VERA_DC_HSTART     |
124 | | \$47/\$54 | VERA_DC_HSTOP      |
125 | | \$48/\$55 | VERA_DC_VSTART     |
126 | | \$49/\$56 | VERA_DC_VSTOP      |
127 | | \$4A/\$57 | Color (bg/fg)      |
128 | | \$4B/\$58 | Keymap             |
129 | | \$4C/\$59 | Typematic          |
130 | | \$4D/\$5A | Unused             |
131 | | \$5B-\$5E | Expansion (unused) |
132 | | $5F       | Checksum           |
133 | 
134 | 
135 | The second half of the RTC's SRAM (NVRAM) is reserved for use by the KERNAL. \$20-\$3F is available for use by user programs.
136 | 
137 | For more information, please refer to this device's datasheet.
138 | 
139 | <!-- For PDF formatting -->
140 | <div class="page-break"></div>
141 | 


--------------------------------------------------------------------------------
/X16 Reference - 13 - Working with CMDR-DOS.md:
--------------------------------------------------------------------------------
  1 | 
  2 | # Chapter 13: Working With CMDR-DOS
  3 | 
  4 | This manual describes Commodore DOS on FAT32, aka CMDR-DOS.
  5 | 
  6 | ## CMDR-DOS
  7 | 
  8 | Commander X16 duplicates and extends the programming interface used by Commodore's line of disk drives, including the
  9 | famous (or infamous) VIC-1541. CMDR-DOS uses the industry-standard FAT-32 format. Partitions can be 32MB up to
 10 | (in theory) 2TB and supports CMD-style partitions, subdirectories, timestamps and filenames up to 255 characters.
 11 | It is the DOS built into the [Commander X16](https://www.commanderx16.com).
 12 | 
 13 | There are three basic interfaces for CMDR-DOS: the binary interface (LOAD, SAVE, etc.), the data file interface (OPEN,
 14 | PRINT#, INPUT#, GET#), and the command interface. We will give a brief summary of BASIC commands here, but please refer
 15 | to  [Chapter 4: BASIC Programming](X16%20Reference%20-%2004%20-%20BASIC.md#chapter-4-basic-programming) for full syntax of each command.
 16 | 
 17 | If you are familiar with the SD2IEC or the CMD hard drive, navigating partitions and subdirectories is similar, with "CD", "MD", and "RD" commands
 18 | to navigate directories.
 19 | 
 20 | ## Binary Load/Save
 21 | 
 22 | The primary use of the binary interface is loading and saving program files and loading binary files into RAM.
 23 | 
 24 | Your binary commands are LOAD, SAVE, BLOAD, VLOAD, BVLOAD, VERIFY, and BVERIFY.
 25 | 
 26 | This is a brief summary of the LOAD and SAVE commands. For full documentation, refer to [Chapter 4: BASIC Programming](X16%20Reference%20-%2004%20-%20BASIC.md#chapter-4-basic-programming).
 27 | 
 28 | ### LOAD
 29 | 
 30 | `LOAD <filename> [,device][,secondary_address]`
 31 | `LOAD <filename> [,device][,ram_bank,start_address]`
 32 | 
 33 | This reads a program file from disk. The first two bytes of the file are the memory location to which the file will be
 34 | loaded, with the low byte first. BASIC programs will start with $01 $08, which translates to $0801, the start of BASIC
 35 | memory.
 36 | The device number should be 8 for reading from the SD card.
 37 | 
 38 | If using the first form, secondary_address has multiple meanings:
 39 | 
 40 | * 0 or not present: load the data to address $0801, regardless of the address header.
 41 | 
 42 | * 1: load to the address specified in the file's header
 43 | 
 44 | * 2: load the file headerless to the location $0801.
 45 | 
 46 | If using the second form, ram_bank sets the bank for the load, and start_address is the location to read your data into.
 47 | 
 48 | The value of the ram_bank argument only affects the load when the start_address is set in the range of \$A000-\$BFFF.
 49 | 
 50 | Examples:
 51 | 
 52 | `LOAD "ROBOTS.PRG",8,1` loads the program "ROBOTS.PRG" into memory at the address encoded in the file.
 53 | 
 54 | `LOAD "HELLO",8` loads a program to the start of BASIC at $0801.
 55 | 
 56 | `LOAD "*",8,1` loads the first program in the current directory. See the section below on wildcards for more
 57 | information about using * and ? to access files of a certain type or with unprintable characters.
 58 | 
 59 | `LOAD "DATA.BIN",8,1,$A000` loads a file into banked RAM, RAM bank 1, starting at $A000. The first two bytes of the file are skipped. To avoid skipping the first two bytes, use the `BLOAD` command instead.
 60 | 
 61 | ### SAVE
 62 | 
 63 | `SAVE <filename>[,device]`
 64 | 
 65 | Saves a file from the computer to the SD card. SAVE always reads from the beginning of BASIC memory at $0801, up to the
 66 | end of the BASIC program. Device is optional and defaults to 8 (the SD card, or an IEC disk drive, if one is plugged in.)
 67 | 
 68 | One word of caution: CMDR-DOS will not let you overwrite a file by default. To overwrite a file, you need to prefix
 69 | the filename with @:, like this:
 70 | 
 71 | `SAVE "@:DEMO.PRG"`
 72 | 
 73 | ### BSAVE
 74 | 
 75 | `BSAVE <filename>,<device>,<ram_bank>,<start_address>,<end_address>`
 76 | 
 77 | Saves an arbitrary region of memory to a file without a two-byte header. To allow concatenating multiple regions of RAM into a single file with multiple successive calls to BSAVE, BSAVE allows the use of append mode in the filename string. To make use of this option, the first call to BSAVE can be called normally, which creates the file anew, while subsequent calls should be in append mode to the same file.
 78 | 
 79 | Another way to save arbitrary binary data from arbitrary locations is to use the S command in the MONITOR: [Chapter 7: Machine Language Monitor](X16%20Reference%20-%2007%20-%20Machine%20Language%20Monitor.md#chapter-7-machine-language-monitor).
 80 | 
 81 | `S "filename",8,<start_address>,<end_address>`
 82 | 
 83 | Where <start_address> and <end_address> are a 16-bit hexadecimal address.
 84 | 
 85 | After a SAVE or BSAVE, the DOS command is implicitly run to show the drive status. The Commodore file I/O model does not report certain failures back to BASIC, so you should double-check the result after a write operation.
 86 | 
 87 | ```BASIC
 88 | 00, OK,00,00
 89 | 
 90 | READY.
 91 | ```
 92 | 
 93 | An OK reply means the file saved correctly. Any other result is an error that should be addressed:
 94 | 
 95 | ```BASIC
 96 | 63,FILE EXISTS,00,00
 97 | ```
 98 | 
 99 | CMDR-DOS does not allow files to be overwritten without special handling. If you get FILE EXISTS, either change your file's name or save it with the @: prefix, like this:
100 | 
101 | `SAVE "@:HELLO"`
102 | 
103 | ### BLOAD
104 | 
105 | BLOAD loads a file _without an address header_ to an arbitrary location in memory. Usage is similar to LOAD. However, BLOAD does not require
106 | or use the 2-byte header. The first byte in the file is the first byte loaded into memory.
107 |   
108 | `BLOAD "filename",8,<ram_bank>,<start_address>`
109 | 
110 | ### VLOAD
111 | 
112 | Read binary data into VERA. VLOAD skips the 2-byte address header and starts reading at the third byte of the file.
113 | 
114 | `VLOAD "filename",8,<vram_bank>,<start_address>`
115 | 
116 | ### BVLOAD
117 | 
118 | Read binary data into VERA without a header. This works like BLOAD, but into VERA RAM.
119 | 
120 | `BVLOAD "filename",8,<vram_bank>,<start_address>`
121 | 
122 | ### DOS WEDGE
123 | 
124 | The DOS wedge allows you to issue quick commands from BASIC with the > or @
125 | symbol.
126 | 
127 | | Command | Action |
128 | |-|-|
129 | | `/<filename>` | Load a BASIC program into RAM |
130 | | `%<filename>` | Load a machine language program into RAM (like `,8,1`) |
131 | | `↑<filename>` | Load a BASIC program into RAM and then unconditionally run it |
132 | | `←<filename>` | Save a BASIC program to disk |
133 | | `@` | Display (and clear) the disk drive status |
134 | | `@$` | Display the disk directory without overwriting the BASIC program in memory |
135 | | `@#<device number>` | Change default DOS device |
136 | | `@<command>` | Execute a disk drive command (e.g. `@S0:<filename>`) |
137 | | `><command>` | Execute a disk drive command (e.g. `>CD:<dir>`) |
138 | 
139 | ## Sequential Files
140 | 
141 | Sequential files have two basic modes: read and write. The OPEN command opens a file for reading or writing. The PRINT# command writes to a file, and the GET# and INPUT# commands read from the file.
142 | 
143 | todo: examples
144 | 
145 | ## Command Channel
146 | 
147 | The command channel allows you to send commands to the CMDR-DOS interface. You can open and write to the command channel using the OPEN command, or you can use the DOS command to issue commands and read the status. While DOS can be used in immediate mode or in a program, only the combination of OPEN/INPUT# can read the command response back into a variable for later processing.
148 | 
149 | In either case, the ST psuedo-variable will allow you to quickly check the status. A status of 64 is "okay", and any
150 | other value should be checked by reading the error channel (shown below.)
151 | 
152 | To open the command channel, you can use the OPEN command with secondary address 15.
153 | 
154 | `10 OPEN 15,8,15`
155 | 
156 | If you want to issue a command immediately, add your command string at the end of the OPEN statement:
157 | 
158 | `10 OPEN 15,8,15, "CD:/"`
159 | 
160 | This example changes to the root directory of your SD card.
161 | 
162 | To know whether the OPEN command succeeded, you must open the command channel and read the result. To read the command channel (and clear the error status if an error occurred), you need to read four values:
163 | 
164 | `20 INPUT#15,A,B$,C,D`
165 | 
166 | A is the error number. B$ is the error message. C and D are unused in CMDR-DOS for most responses, but will return the track and sector when used with a disk drive on the IEC connector.
167 | 
168 | ```BASIC
169 | 30 PRINT A;B$;C;D
170 | 40 CLOSE 15
171 | ```
172 | 
173 | So the entire program looks like:
174 | 
175 | ```BASIC
176 | 10 OPEN 15,8,15, "CD:/"
177 | 20 INPUT#15,A,B$,C,D
178 | 30 PRINT A;B$;C;D
179 | 40 CLOSE 15
180 | ```
181 | 
182 | If the error number (`A`) is less than 20, no error occurred. Usually this result is 0 (or 00) for OK.
183 | 
184 | You can also use the DOS command to send a command to CMDR-DOS. Entering DOS by itself will print the drive's status on the screen. Entering a command in quotes or a string variable will execute the command. We will talk more about the status variable and DOS status message in the next section.
185 | 
186 | ```BASIC
187 | DOS
188 | 00, 0K, 00, 00
189 | READY.
190 | DOS "CD:/"
191 | ```
192 | 
193 | The special case of `DOS "$"` will print a directory listing.
194 | 
195 | `DOS "$"`
196 | 
197 | You can also read the name of the current directory with DOS"$=C"
198 | 
199 | `DOS "$=C"`
200 | 
201 | ## DOS Features
202 | 
203 | This is the base features set compared to other Commodore DOS devices:
204 | 
205 | | Feature          | 1541 | 1571/1581 | CMD HD/FD | SD2IEC   | _CMDR-DOS_      |
206 | |------------------|------|-----------|-----------|----------|-----------------|
207 | | Sequential files | yes  | yes       | yes       | yes      | yes             |
208 | | Relative files   | yes  | yes       | yes       | yes      | not yet         |
209 | | Block access     | yes  | yes       | yes       | yes      | not yet         |
210 | | Code execution   | yes  | yes       | yes       | no       | yes             |
211 | | Burst commands   | no   | yes       | yes       | no       | no              |
212 | | Timestamps       | no   | no        | yes       | yes      | yes             |
213 | | Time API         | no   | no        | yes       | yes      | not yet         |
214 | | Partitions       | no   | no        | yes       | yes      | yes             |
215 | | Subdirectories   | no   | no        | yes       | yes      | yes             |
216 | 
217 | It consists of the following components:
218 | 
219 | * Commodore DOS interface
220 |   * `dos/main.s`: TALK/LISTEN dispatching
221 |   * `dos/parser.s`: filename/path parsing
222 |   * `dos/cmdch.s`: command channel parsing, status messages
223 |   * `dos/file.s`: file read/write
224 | * FAT32 interface
225 |   * `dos/match.s`: FAT32 character set conversion, wildcard matching
226 |   * `dos/dir.s`: FAT32 directory listing
227 |   * `dos/function.s`: command implementations for FAT32
228 | * FAT32 implementation
229 |   * `fat32/*`: [FAT32 for 65c02 library](https://github.com/X16Community/x16-rom/tree/master/fat32)
230 | 
231 | All currently unsupported commands are decoded in `cmdch.s` anyway, but hooked into `31,SYNTAX ERROR,00,00`, so adding features should be as easy as adding the implementation.
232 | 
233 | CMDR-DOS implements the TALK/LISTEN layer (Commodore Peripheral Bus layer 3), it can therefore be directly hooked up to the Commodore IEEE KERNAL API (`talk`, `tksa`, `untlk`, `listn`, `secnd`, `unlsn`, `acptr`, `ciout`) and be used as a computer-based DOS, like on the C65 and the X16.
234 | 
235 | CMDR-DOS does not contain a layer 2 implementation, i.e. IEEE-488 (PET) or Commodore Serial (C64, C128, ...). By adding a Commodore Serial (aka "IEC") implementation, CMDR-DOS could be adapted for use as the system software of a standalone 65c02-based Serial device for Commodore computers, similar to an sd2iec device.
236 | 
237 | The Commodore DOS side and the FAT32 side are well separated, so a lot of code could be reused for a DOS that uses a different filesystem.
238 | 
239 | Or the core feature set, these are the supported functions:
240 | 
241 | | Feature                          | Syntax                        | Supported | Comment                                                                                                                       |
242 | |----------------------------------|-------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------|
243 | | Reading                          | `,?,R`                        | yes       |                                                                                                                               |
244 | | Writing                          | `,?,W`                        | yes       |                                                                                                                               |
245 | | Appending                        | `,?,A`                        | yes       | Warning, see below<sup>1</sup>                                                                                                |
246 | | Modifying                        | `,?,M`                        | yes       |                                                                                                                               |
247 | | Types                            | `,S`/`,P`/`,U`/`,L`           | yes       | ignored on FAT32                                                                                                              |
248 | | Overwriting                      | `@:`                          | yes       |                                                                                                                               |
249 | | Magic channels 0/1               |                               | yes       |                                                                                                                               |
250 | | Channel 15 command               | _command_`:`_args_...         | yes       |                                                                                                                               |
251 | | Channel 15 status                | _code_`,`_string_`,`_a_`,`_b_ | yes       |                                                                                                                               |
252 | | CMD partition syntax             | `0:`/`1:`/...                 | yes       |                                                                                                                               |
253 | | CMD subdirectory syntax          | `//DIR/:`/`/DIR/:`            | yes       |                                                                                                                               |
254 | | Directory listing                | `$`                           | yes       |                                                                                                                               |
255 | | Dir with name filtering          | `$:FIL*`                      | yes       |                                                                                                                               |
256 | | Dir with name and type filtering | `$:*=P`/`$:*=D`/`$:*=A`       | yes       |                                                                                                                               |
257 | | Dir with timestamps              | `$=T`                         | yes       | with ISO-8601 times                                                                                                           |
258 | | Dir with time filtering          | `$=T<`/`$=T>`                 | not yet   |                                                                                                                               |
259 | | Dir long listing                 | `$=L`                         | yes       | shows human readable file size instead of blocks, time in ISO-8601 syntax, attribute byte, and exact file size in hexadecimal |
260 | | Partition listing                | `$=P`                         | yes       |                                                                                                                               |
261 | | Partition filtering              | `$:NAME*=P`                   | no        |                                                                                                                               |
262 | | Current Working Directory        | `$=C`                         | yes       |                                                                                                                               |
263 | 
264 | * <sup>1</sup>: Warning: Risk of corrupting SD cards on older ROM versions, see [Appending to file](#appending-to-file)
265 | 
266 | And this table shows which of the standard commands are supported:
267 | 
268 | | Name             | Syntax                                                | Description                     | Supported |
269 | |------------------|-------------------------------------------------------|---------------------------------|-----------|
270 | | BLOCK-ALLOCATE   | `B-A` _medium_ _medium_ _track_ _sector_              | Allocate a block in the BAM     | no<sup>1</sup>|
271 | | BLOCK-EXECUTE    | `B-E` _channel_ _medium_ _track_ _sector_             | Load and execute a block        | not yet   |
272 | | BLOCK-FREE       | `B-F` _medium_ _medium_ _track_ _sector_              | Free a block in the BAM         | no<sup>1</sup>|
273 | | BLOCK-READ       | `B-R` _channel_ _medium_ _track_ _sector_             | Read block                      | no<sup>1</sup>|
274 | | BLOCK-STATUS     | `B-S` _channel_ _medium_ _track_ _sector_             | Check if block is allocated     | no<sup>1</sup>|
275 | | BLOCK-WRITE      | `B-W` _channel_ _medium_ _track_ _sector_             | Write block                     | no<sup>1</sup>|
276 | | BUFFER-POINTER   | `B-P` _channel_ _index_                               | Set r/w pointer within buffer   | not yet   |
277 | | CHANGE DIRECTORY | `CD`[_path_]`:`_name_                                 | Change the current sub-directory| yes       |
278 | | CHANGE DIRECTORY | `CD`[_medium_]`:←`                                    | Change sub-directory up         | yes       |
279 | | CHANGE PARTITION | `CP` _num_                                            | Make a partition the default    | yes       |
280 | | COPY             | `C`[_path_a_]`:`_target_name_`=`[_path_b_]`:`_source_name_[`,`...] | Copy/concatenate files | yes   |
281 | | COPY             | `C`_dst_medium_`=`_src_medium_                        | Copy all files between disk     | no<sup>1</sup>|
282 | | DUPLICATE        | `D:`_dst_medium_``=``_src_medium_                     | Duplicate disk                  | no<sup>1</sup>|
283 | | FILE LOCK        | `F-L`[_path_]`:`_name_[`,`...]                        | Enable file write-protect       | yes       |
284 | | FILE RESTORE     | `F-R`[_path_]`:`_name_[`,`...]                        | Restore a deleted file          | not yet   |
285 | | FILE UNLOCK      | `F-U`[_path_]`:`_name_[`,`...]                        | Disable file write-protect      | yes       |
286 | | GET DISKCHANGE   | `G-D`                                                 | Query disk change               | yes       |
287 | | GET PARTITION    | `G-P`[_num_]                                          | Get information about partition | yes       |
288 | | INITIALIZE       | `I`[_medium_]                                         | Re-mount filesystem             | yes       |
289 | | LOCK             | `L`[_path_]`:`_name_                                  | Toggle file write protect       | yes       |
290 | | MAKE DIRECTORY   | `MD`[_path_]`:`_name_                                 | Create a sub-directory          | yes       |
291 | | MEMORY-EXECUTE   | `M-E` _addr_lo_ _addr_hi_                             | Execute code                    | yes       |
292 | | MEMORY-READ      | `M-R` _addr_lo_ _addr_hi_ [_count_]                   | Read RAM                        | yes       |
293 | | MEMORY-WRITE     | `M-W` _addr_lo_ _addr_hi_ _count_ _data_              | Write RAM                       | yes       |
294 | | NEW              | `N`[_medium_]`:`_name_`,`_id_`,FAT32`                 | File system creation            | yes<sup>3</sup>|
295 | | PARTITION        | `/`[_medium_][`:`_name_]                              | Select 1581 partition           | no        |
296 | | PARTITION        | `/`[_medium_]`:`_name_`,`_track_ _sector_ _count_lo_ _count_hi_ `,C` | Create 1581 partition | no   |
297 | | POSITION         | `P` _channel_ _record_lo_ _record_hi_ _offset_        | Set record index in REL file    | not yet   |
298 | | REMOVE DIRECTORY | `RD`[_path_]`:`_name_                                 | Delete a sub-directory          | yes       |
299 | | RENAME           | `R`[_path_]`:`_new_name_`=`_old_name_                 | Rename file                     | yes       |
300 | | RENAME-HEADER    | `R-H`[_medium_]`:`_new_name_                          | Rename a filesystem             | yes       |
301 | | RENAME-PARTITION | `R-P:`_new_name_`=`_old_name_                         | Rename a partition              | no<sup>1</sup>|
302 | | SCRATCH          | `S`[_path_]`:`_pattern_[`,`...]                       | Delete files                    | yes       |
303 | | SWAP             | `S-`{`8`&#x7c;`9`&#x7c;`D`}                           | Change primary address          | yes       |
304 | | TIME READ ASCII  | `T-RA`                                                | Read Time/Date (ASCII)          | no<sup>4</sup>|
305 | | TIME READ BCD    | `T-RB`                                                | Read Time/Date (BCD)            | no<sup>4</sup>|
306 | | TIME READ DECIMAL| `T-RD`                                                | Read Time/Date (Decimal)        | no<sup>4</sup>|
307 | | TIME READ ISO    | `T-RI`                                                | Read Time/Date (ISO)            | no<sup>4</sup>|
308 | | TIME WRITE ASCII | `T-WA` _dow_ _mo_`/`_da_`/`_yr_ _hr_`:`_mi_`:`_se_ _ampm_ | Write Time/Date (ASCII)     | no<sup>4</sup>|
309 | | TIME WRITE BCD   | `T-WB` _b0_ _b1_ _b2_ _b3_ _b4_ _b5_ _b6_ _b7_ _b8_   | Write Time/Date (BCD)           | no<sup>4</sup>|
310 | | TIME WRITE DECIMAL| `T-WD` _b0_ _b1_ _b2_ _b3_ _b4_ _b5_ _b6_ _b7_       | Write Time/Date (Decimal)       | no<sup>4</sup>|
311 | | TIME WRITE ISO   | `T-WI` _yyyy_`-`_mm_`-`_dd_`T`_hh_`:`_mm_`:`_ss_ _dow_| Write Time/Date (ISO)           | no<sup>4</sup>|
312 | | U1/UA            | `U1` _channel_ _medium_ _track_ _sector_              | Raw read of a block             | not yet   |
313 | | U2/UB            | `U2` _channel_ _medium_ _track_ _sector_              | Raw write of a block            | not yet   |
314 | | U3-U8/UC-UH      | `U3` - `U8`                                           | Execute in user buffer          | not yet   |
315 | | U9/UI            | `UI`                                                  | Soft RESET                      | yes       |
316 | | U:/UJ            | `UJ`                                                  | Hard RESET                      | yes       |
317 | | USER             | `U0>` _pa_                                            | Set unit primary address        | yes       |
318 | | USER             | `U0>B` _flag_                                         | Enable/disable Fast Serial      | yes<sup>6</sup>|
319 | | USER             | `U0>D`_val_                                           | Set directory sector interleave | no<sup>1</sup>|
320 | | USER             | `U0>H` _number_                                       | Select head 0/1                 | no<sup>1</sup>|
321 | | USER             | `U0>L`_flag_                                          | Large REL file support on/off   | no        |
322 | | USER             | `U0>M` _flag_                                         | Enable/disable 1541 emulation mode| no<sup>1</sup>|
323 | | USER             | `U0>R` _num_                                          | Set number fo retries           | no<sup>1</sup>|
324 | | USER             | `U0>S` _val_                                          | Set sector interleave           | no<sup>1</sup>|
325 | | USER             | `U0>T`                                                | Test ROM checksum               | no<sup>5</sup>|
326 | | USER             | `U0>V` _flag_                                         | Enable/disable verify           | no<sup>1</sup>|
327 | | USER             | `U0>` _pa_                                            | Set unit primary address        | yes       |
328 | | USER             | `UI`{`+`&#x7c;`-`}                                    | Use C64/VIC-20 Serial protocol  | no<sup>1</sup>|
329 | | UTILITY LOADER   | `&`[[_path_]`:`]_name_                                | Load and execute program        | no<sup>1</sup>|
330 | | VALIDATE         | `V`[_medium_]                                         | Filesystem check                | no<sup>2</sup>|
331 | | WRITE PROTECT    | `W-`{`0`&#x7c;`1`}                                    | Set/unset device write protect  | yes       |
332 | 
333 | * <sup>1</sup>: outdated API, not useful, or can't be supported on FAT32
334 | * <sup>2</sup>: is a no-op, returns `00, OK,00,00`
335 | * <sup>3</sup>: third argument `FAT32` _has_ to be passed
336 | * <sup>4</sup>: CMDR-DOS was architected to run on the main computer, so it shouldn't be DOS that keeps track of the time
337 | * <sup>5</sup>: Instead of testing the ROM, this command currently verifies that no buffers are allocated, otherwise it halts. This is used by unit tests to detect leaks.
338 | * <sup>6</sup>: Repurposed for SD card read and write mode. _flag_ selects whether fast read (auto_tx) and fast writes are enabled. 0=none, 1=auto_tx, 2=fast writes, 3=both
339 | 
340 | The following special file syntax and `OPEN` options are specific to CMDR-DOS:
341 | 
342 | | Feature               | Syntax      | Description                                                                    |
343 | |-----------------------|-------------|--------------------------------------------------------------------------------|
344 | | Open for Read & Write | `,?,M`      | Allows arbitrarily reading, writing and setting the position (`P`)<sup>7</sup> |
345 | | Get current working directory | `$=C` | Produces a directory listing containing the name of the current working directory followed by all parent directory names all the way up to `/` |
346 | 
347 | * <sup>7</sup>: once the EOF has been reached while reading, no further reads or writes are possible.
348 | 
349 | The following added command channel features are specific to CMDR-DOS:
350 | 
351 | | Feature               | Syntax      | Description                                                                    |
352 | |-----------------------|-------------|--------------------------------------------------------------------------------|
353 | | POSITION              | `P` _channel_ _p0_ _p1_ _p2_ _p3_  | Set position within file (like sd2iec); all args binary |
354 | | TELL<sup>8</sup>                  | `T` _channel_ | Return the current position within a file and the file's size; channel arg is binary |
355 | 
356 | * <sup>8</sup>: available in ROM version R48 and later
357 | 
358 | To use the POSITION and TELL commands, you need to open two channels: a data channel and the command channel. The _channel_ argument should be the same as the secondary address of the data channel.
359 | 
360 | If POSITION succeeds, `00, OK,00,00` is returned on the command channel.  
361 | 
362 | If TELL succeeds, `07,pppppppp ssssssss,00,00` is returned on the command channel, where `pppppppp` is a hexadecimal representation of the position, and `ssssssss` is a hexadecimal represenation of the file's size.  
363 | 
364 | ### Examples
365 | 
366 | ```BASIC
367 | OPEN 1,8,2,"LEVEL.DAT,S,R"
368 | OPEN 15,8,15,"P"+CHR$(2)+CHR$(0)+CHR$(1)+CHR$(0)+CHR$(0)
369 | ```
370 | 
371 | The above opens LEVEL.DAT for reading and positions the read/write pointer at byte 256.
372 | 
373 | ```BASIC
374 | 10 OPEN 2,8,5,"LEVEL.DAT,S,R"
375 | 20 OPEN 15,8,15,"T"+CHR$(5)
376 | 30 INPUT#15,A,A$,T,S
377 | 40 CLOSE 15
378 | 50 IF A>=20 THEN 90
379 | 60 SZ=VAL("$"+MID$(A$,10))
380 | 70 PRINT "SIZE=";SZ
381 | 80 GOTO 100
382 | 90 PRINT"ERROR"
383 | 100 CLOSE 2
384 | ```
385 | 
386 | This time, the secondary address is 5, and we're fetching only the file's size.
387 | 
388 | ### Current Working Directory
389 | 
390 | The $=C command will list the current working directory and its parent path. The current directory will be at the top of the listing, with each parent
391 | directory beneath, with / at the bottom.
392 | 
393 | ```BASIC
394 | DOS"$=C"
395 | 
396 | 0 "/TEST            " 
397 | 0    "TEST"             DIR
398 | 0    "/"                DIR
399 | 65535 BLOCKS FREE.
400 | ```
401 | ### Appending to file
402 | 
403 | To append data to an existing file, open the file with `,?,A` and write to it.
404 | 
405 | **Warning:** Appending to an empty file using R48 or older, will corrupt the file system, due to a severe Kernal bug. The bug is fixed in [#369](https://github.com/X16Community/x16-rom/pull/369). Keep this in mind when releasing software which appends to files, as some users may have older ROM versions installed.
406 | 
407 | ## License
408 | 
409 | Copyright 2020-2024 Michael Steil <<mist64@mac.com>>, et al.
410 | 
411 | Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
412 | 
413 | 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
414 | 
415 | 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
416 | 
417 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
418 | 
419 | <!-- For PDF formatting -->
420 | <div class="page-break"></div>
421 | 


--------------------------------------------------------------------------------
/X16 Reference - 14 - Hardware.md:
--------------------------------------------------------------------------------
  1 | 
  2 | # Chapter 14: Hardware Pinouts
  3 | 
  4 | This chapter covers pinout for the I/O ports and headers.
  5 | 
  6 | ## Port and Socket Listing
  7 | 
  8 | * VERA Connectors
  9 | * SNES Controller Ports (x2)
 10 | * IEC Port
 11 | * PS/2 Keyboard and mouse
 12 | * Expansion Slots (x4 in Gen1)
 13 | * User Port Header
 14 | * ATX Power Supply
 15 | * Front Panel
 16 | 
 17 | Chip sockets are not listed; pinouts are available on their respective data sheets.
 18 | 
 19 | ## Disclaimer
 20 | 
 21 | The instructions and information in this document are the best available information at the time of writing. This information is subject to change, and no warranty is implied. We are not liable for damage or injury caused by use or misuse of this information, including damage caused by inaccurate information. Interfacing and modifying your Commander X16 is done solely at your own risk.
 22 | 
 23 | If you attempt to upgrade your firmware and the process fails, one of our community members may be able to help. Please visit the forums or the Discord community, both of which can be reached through <https://commanderx16.com>.
 24 | 
 25 | ### SNES Ports
 26 | 
 27 | The computer contains two SNES style ports and will work with Super Nintendo compatible game pads. An on-board pin header is accessible to connect two additional SNES ports.
 28 | 
 29 | ![SNES Controller Port](images/SNES_Controller_Female.png)
 30 | 
 31 | | Pin # | Description | Wire Color  |
 32 | |-------|-------------|-------------|
 33 | | 1     | +5v         | White       |
 34 | | 2     | Data Clock  | Yellow/Red  |
 35 | | 3     | Data Latch  | Orange      |
 36 | | 4     | Serial Data | Red/Yellow  |
 37 | | 5     | N/C         | -           |
 38 | | 6     | N/C         | -           |
 39 | | 7     | Ground      | Brown       |
 40 | 
 41 | The Data Clock and Data Latch are generated by the computer and are shared across all SNES ports. The Serial Data line is unique per controller.
 42 | 
 43 | Thanks to [Console Mods Wiki](https://consolemods.org/wiki/SNES:Connector_Pinouts)
 44 | 
 45 | ### IEC Port
 46 | 
 47 | The IEC port is a female 6 pin DIN 45322 connector. The pinout and specifications are the same as the Commodore 128 computer, with the required lines for Fast IEC, as used by the 1571 and 1581 diskette drives. 1541 drives are also compatible, using standard IEC mode at 400-600 bytes/sec.
 48 | 
 49 | ![IEC Serial Port](images/iec_port.gif)
 50 | 
 51 | |Pin | Description  | Signal Direction  | Remark |
 52 | |----|--------------|-------------------|--------|
 53 | | 1  | SERIAL SRQ   | IN                | Serial Service Request In, at the C128 "Fast Serial Clock" |
 54 | | 2  | GND          | -                 | Ground, signal ground (0V) |
 55 | | 3  | SERIAL ATN   | OUT               | Attention, for the selection of a device at beginning/end of a transmission |
 56 | | 4  | SERIAL CLK   | IN/OUT            | Clock (for data transmission) |
 57 | | 5  | SERIAL DATA  | IN/OUT            | Data  |
 58 | | 6  | SERIAL RESET | OUT(/IN)          | Reset |
 59 | 
 60 | The IEC protocol is beyond the scope of this document. Please see [Wikipedia](https://en.wikipedia.org/wiki/Commodore_bus) for more information.
 61 | 
 62 | ### PS/2 Keyboard and Mouse
 63 | 
 64 | ![PS/2 Pinout](images/ps2_pinout.png)
 65 | 
 66 | | Pin | Name  | Description    |
 67 | |-----|-------|----------------|
 68 | | 1   | +DATA | Data           |
 69 | | 2   | NC    | Not connected  |
 70 | | 3   | GND   | Ground         |
 71 | | 4   | Vcc   | +5 VDC         |
 72 | | 5   |+CLK   | Clock          |
 73 | | 6   | NC    | Not Connected  |
 74 | 
 75 | ### Expansion Cards / Cartridges
 76 | 
 77 | The expansion slots can be used for I/O modules and RAM/ROM cartridges and expose the
 78 | full CPU address and data bus, plus the ROM bank select lines, stereo audio, and 5 IO select lines.
 79 | 
 80 | The expansion/cartridge port is a 60-pin edge connector with 2.54mm pitch.
 81 | Pin 1 is in the rear-left corner.
 82 | 
 83 | |   Desc |  Pin |   | Pin  | Desc |
 84 | |-------:|-----:|---|------|------|
 85 | |   -12V |   1 |\[ \]| 2  | +12V  |
 86 | |    GND |   3 |\[ \]| 4  | +5V   |
 87 | |AUDIO_L |   5 |\[ \]| 6  | GND   |
 88 | |AUDIO_R |   7 |\[ \]| 8  | ROMB7 |
 89 | |    IO3 |   9 |\[ \]| 10 | ROMB0 |
 90 | |    IO4 |  11 |\[ \]| 12 | ROMB1 |
 91 | |    IO7 |  13 |\[ \]| 14 | ROMB6 |
 92 | |    IO5 |  15 |\[ \]| 16 | ROMB2 |
 93 | |    IO6 |  17 |\[ \]| 18 | ROMB5 |
 94 | |   RESB |  19 |\[ \]| 20 | ROMB3 |
 95 | |    RDY |  21 |\[ \]| 22 | ROMB4 |
 96 | |   IRQB |  23 |\[ \]| 24 | PHI2  |
 97 | |     BE |  25 |\[ \]| 26 | RWB   |
 98 | |   NMIB |  27 |\[ \]| 28 | MLB   |
 99 | |   SYNC |  29 |\[ \]| 30 | D0    |
100 | |     A0 |  31 |\[ \]| 32 | D1    |
101 | |     A1 |  33 |\[ \]| 34 | D2    |
102 | |     A2 |  35 |\[ \]| 36 | D3    |
103 | |     A3 |  37 |\[ \]| 38 | D4    |
104 | |     A4 |  39 |\[ \]| 40 | D5    |
105 | |     A5 |  41 |\[ \]| 42 | D6    |
106 | |     A6 |  43 |\[ \]| 44 | D7    |
107 | |     A7 |  45 |\[ \]| 46 | A15   |
108 | |     A8 |  47 |\[ \]| 48 | A14   |
109 | |     A9 |  49 |\[ \]| 50 | A13   |
110 | |    A10 |  51 |\[ \]| 52 | A12   |
111 | |    A11 |  53 |\[ \]| 54 | SDA   |
112 | |    GND |  55 |\[ \]| 56 | SCL   |
113 | |    +5V |  57 |\[ \]| 58 | GND   |
114 | |   +12V |  59 |\[ \]| 60 | -12V  |
115 | 
116 | To simplify address decoding, pins IO3-IO7 are active for specific, 32-byte memory mapped IO
117 | (MMIO) address ranges.
118 | 
119 | | Address     | Usage                               |Speed|
120 | |-------------|-------------------------------------|-----|
121 | |$9F60-$9F7F|Expansion Card Memory Mapped IO3       |8 MHz|
122 | |$9F80-$9F9F|Expansion Card Memory Mapped IO4       |8 MHz|
123 | |$9FA0-$9FBF|Expansion Card Memory Mapped IO5       |2 MHz|
124 | |$9FC0-$9FDF|Expansion Card Memory Mapped IO6       |2 MHz|
125 | |$9FE0-$9FFF|Cartidge/Expansion Memory Mapped IO7   |2 MHz|
126 | 
127 | Expansion cards can use the IO3-IO6 lines as enable lines to provide their IO address range
128 | (s), or decode the address from the address bus directly. To prevent conflicts with other
129 | devices, expansion boards should allow the user to select their desired I/O bank with jumpers
130 | or DIP switches. IO7 is given priority to external cartridges that use MMIO and should be
131 | only used by an expansion card if there are no other MMIO ranges available. Doing so may
132 | cause a bus conflict with cartridges that make use of MMIO (such as those with expansion
133 | hardware). See below for more information on cartridges.
134 | 
135 | ROMB0-ROMB7 are connected to the ROM bank latch at address `$01`. Values 0-31 (`$00`-`$1F`)
136 | address the on-board ROM chips, and 32-255 are intended for expansion ROM or RAM chips
137 | (typically used by cartridges, see below). This allows for a total of 3.5MB of address space
138 | in the `$C000-$FFFF` address range.
139 | 
140 | SCL and SDA pins are shared with the i2c connector on J9 and can be used to access i2c
141 | peripherals on cartridges or expansion cards.
142 | 
143 | AUDIO_L and AUDIO_R are routed to J10, the audio option header.
144 | 
145 | The other pins are connected to the system bus and directly to the 65C02 processor.
146 | 
147 | #### Cartridges
148 | 
149 | Cartridges are essentially an expansion card housed in an external enclosure. Typically they are
150 | used for applications (e.g. games) with the X16 being able to boot directly from a cartridge at
151 | power on. They contain banked ROM and/or RAM and an optional I2C EEPROM
152 | (for storing game save states).
153 | 
154 | They can also function as an expansion card which means they can also use MMIO. Similarly an internal
155 | expansion card could contain RAM/ROM as well.
156 | 
157 | Because of this, while develoeprs are free to use the hardware as they please, to avoid
158 | conflcits, the banked ROM/RAM space is suggested to be used only by cartridges and
159 | cartridges should avoid using MMIO IO3-IO6. Instead, IO7 should be the default option
160 | for cartridges and the last option for expansion cards (only used if there are no
161 | other IO ranges available).
162 | 
163 | This helps avoid bus conflicts and an otherwise bad user experience given a
164 | cartridge should be simple to use from the standpoint of the user
165 | ("insert game -> play game").
166 | 
167 | These are soft guidelines. There is nothing physically preventing an expansion card from using
168 | banked ROM/RAM or a cartridge using any of the MMIO addresses. Doing so risks conflicts and
169 | compatibility issues.
170 | 
171 | Cartridges with additional hardware would be similar to expansion chips found on some NES and
172 | SNES cartridges (think VRC6, Super FX, etc.) and could be used for really anything,
173 | such as having a MIDI input for a cartridge that is meant as a music maker;
174 | some sort of hardware accelerator FPGA; network support, etc.
175 | 
176 | For more information about the memory map visit
177 | [Chapter 8: Memory Map](X16%20Reference%20-%2008%20-%20Memory%20Map.md#chapter-8-memory-map).
178 | 
179 | ##### Booting from Cartridges
180 | 
181 | After the X16 finishes it's hardware initialization, the kernel checks bank 32 for the signature "CX16"
182 | at `$C000`. If found, it then jumps to `$C004` and leaves interrupts disabled.
183 | 
184 | ### ATX Power Supply
185 | 
186 | The Commander X16 has a socket for an industry standard 24-pin ATX power supply connector. Either a 24-pin or 20-pin PSU connector can be plugged in, though only the pins for the older 20-pin standard are used by the computer. You don't need an expensive power supply, but it must supply the -12v rail. Not all do, so check your unit to make sure. If you can't tell from the label, you can check Pin 12 and COM. If the clip side is facing away from you, pin 14 will be the second pin on the left on the clip side. For a 20-pin cable, -12v is on pin 12, but at the same relative position &mdash; the second pin on the left on the clip side.
187 | 
188 | |24-pin ATX power connector, cable end|
189 | |-|
190 | |![Cable end view of ATX power connector](images/atx_24_pin-small.png)|
191 | 
192 | By CalvinTheMan - Own work, CC BY-SA 4.0, <https://commons.wikimedia.org/w/index.php?curid=50881708>
193 | 
194 | The Commander X16 does not use the 4-pin CPU power, GPU power, 4-pin drive power, or SATA power connectors.
195 | 
196 | To save space, when running a bare motherboard, we recommend a "Pico PSU" power supply, which derives all of the necessary power lines from a single 12V source.
197 | 
198 | ### J1 ROM Write Protect
199 | 
200 | Remove J1 to write protect system ROM. With J1 installed, users can program the system ROM using an appropriate ROM flash program.
201 | 
202 | ### J2 NMI
203 | 
204 | Connect a button here to generate an Non Maskable Interrupt (NMI) on the CPU. This will execute a BASIC warm start, which will stop any existing program, clear the screen, and print the READY prompt.
205 | 
206 | ### J3 Parallel/user port pullup resistors
207 | 
208 | When connected, activates 4.7k pullup resistors for PB0, PB4, PB6, PB7 and CA1 of the user port.
209 | 
210 | Printed on PCB: Connect J8 for LPT Compat. (TODO: Is this the Centronics parallel port mode Lorin hinted at early on?)
211 | 
212 | ### J4 Extra 65C22 Pins
213 | 
214 | PRxxxxx:
215 | | Pin | Desc |
216 | |-----|------|
217 | |  1  | PB0  |
218 | |  2  | PB1  |
219 | |  3  | PB2  |
220 | |  4  | CB2  |
221 | 
222 | DEVxxxxx:
223 | | Pin | Desc |
224 | |-----|------|
225 | |  1  | CA1  |
226 | |  2  | CA2  |
227 | |  3  | PB0  |
228 | |  4  | PB1  |
229 | |  5  | PB2  |
230 | |  6  | CB2  |
231 | 
232 | These pins are connected to VIA 1 at $9F00-$9F0F.
233 | 
234 | ### J5 SMC I2C (DEVxxxxx boards only)
235 | 
236 | DEVxxxxx boards: Remove jumpers from J5 to disconnect SMC from I2C bus. This allows serial programming of SMC via J9.
237 | 
238 | PRxxxxx boards: J5 is not present. On-board serial programming of SMC is not possible.
239 | 
240 | | Desc    | Pin |   | Pin | Desc    |
241 | |--------:|----:|---|-----|---------|
242 | | SCL_SMC |  1  |. .|  2  | SDA_SMC |
243 | | SCL     |  3  |. .|  4  | SDA     |
244 | 
245 | ### J6 System Speed
246 | 
247 | | Pin    | Desc          |
248 | |--------|---------------|
249 | |  1 - 2 | 8 MHz         |
250 | |  3 - 4 | 4 MHz         |
251 | |  5 - 6 | 2 MHz         |
252 | 
253 | ### J7 SNES 3/4
254 | 
255 | | Desc  | Pin |   | Pin | Desc |
256 | |------:|----:|---|-----|------|
257 | | CLC   |  1  |. .|  2  | VCC  |
258 | | LATCH |  3  |. .|  4  | DAT4 |
259 | | DAT3  |  5  |. .|  6  | GND  |
260 | 
261 | These pins will allow for two additional SNES controllers, for a total of four controllers on the system.
262 | 
263 | ### J8 Front Panel
264 | 
265 | |   Desc    | Pin |   | Pin | Desc      |
266 | |----------:|----:|---|-----|-----------|
267 | | HDD LED+  |  1  |. .|  2  | POW LED + |
268 | | HDD LED-  |  3  |. .|  4  | POW LED - |
269 | | RESET BUT |  5  |. .|  6  | POW BUT   |
270 | | RESET BUT |  7  |. .|  7  | POW BUT   |
271 | | +5VDC     |  9  |. .|  10 | NC        |
272 | 
273 | This pinout is compatible with newer ATX style motherboards. AT motherboards and older ATX cases may still have a 3-pin power LED connector (with a blank pin in the middle.) You will need to move the + (red) wire on the power LED connector to the center pin, if this is the case. Or you can use two Male-Female breadboard cables to jumper the header to your power LED connector.
274 | 
275 | There is no on-board speaker header. Instead, all audio is routed to the rear panel headphone jack via the Audio Option header.
276 | 
277 | ### J9 I2C/SMC Header
278 | 
279 | There are two different layouts for the SMC header.
280 | 
281 | This is the layout on the production boards (PRxxxxx):
282 | 
283 | | Desc             | Pin |   | Pin | Desc        |
284 | |-----------------:|----:|---|-----|-------------|
285 | | I2C SDA           |  1  |. .|  2  | +5V        |
286 | | RTC MFP           |  3  |. .|  4  | SMC TX     |
287 | | RESB              |  5  |. .|  6  | SMC RX     |
288 | | I2C SCL           |  7  |. .|  8  | GND        |
289 | | 5VSB              |  9  |. .|  10 | GND        |
290 | 
291 | This is the layout on the DEVxxxxx boards:
292 | 
293 | | Desc             | Pin |   | Pin | Desc        |
294 | |-----------------:|----:|---|-----|-------------|
295 | | SMC MOSI/I2C SDA  |  1  |. .|  2  | +5VSB      |
296 | | RTC MFP           |  3  |. .|  4  | SMC TX     |
297 | | SMC Reset         |  5  |. .|  6  | SMC RX     |
298 | | SMC SCK/I2C SCL   |  7  |. .|  8  | GND        |
299 | | MISO              |  9  |. .|  10 | GND        |
300 | 
301 | DEVxxxxx boards supports in-system serial programming using J9 and J5. This is not possible with PRxxxxx boards.
302 | 
303 | Note that pin 5 is connected to different SMC pins for DEV and PR boards, despite similar names. "SMC reset" (DEV) resets SMC, while "RESB" (PR) resets the rest of the system.
304 | 
305 | ### J10 Audio Option
306 | 
307 | | Desc   | Pin |   | Pin | Desc  |
308 | |-------:|----:|---|-----|-------|
309 | | SDA    |  1  |. .|  2  | RESB  |
310 | | SCL    |  3  |. .|  4  | VCC   |
311 | |        |  5  |. .|  6  |       |
312 | | +12V   |  7  |. .|  8  | -12V  |
313 | |        |  9  |. .| 10  |       |
314 | | VERA_L | 11  |. .| 12  | BUS_L |
315 | |        | 13  |. .| 14  |       |
316 | | VERA_R | 15  |. .| 16  | BUS_R |
317 | |        | 17  |. .| 18  |       |
318 | | YM_L   | 19  |. .| 20  | OUT_L |
319 | |        | 21  |. .| 22  |       |
320 | | YM_R   | 23  |. .| 24  | OUT_R |
321 | 
322 | 5,6,9,10,13,14,17,18,21,22 - GND
323 | 
324 | Next to the audio header is a set of jumper pads, JP1-JP6. Cutting these traces allows you to extract isolated audio from each of the system devices or build a mixer to adjust the relative balance of the audio devices.
325 | 
326 | In order to avoid ground loop and power supply noise, we recommend installing a ground loop isolator when using an external mixer. 2 or 3 isolators will be required (one for each stereo pair.)  (TODO: measure noise and test with pro audio gear.)
327 | 
328 | ### J12 User Port
329 | 
330 | | Desc    | Pin |   | Pin | Desc    |
331 | |--------:|----:|---|-----|---------|
332 | | PB0     |  1  |. .|  2  | PB4     |
333 | | PA0     |  3  |. .|  4  | PB5     |
334 | | PA1     |  5  |. .|  6  | PB6/CB1 |
335 | | PA2     |  7  |. .|  8  | PB7/CB2 |
336 | | PA3     |  9  |. .| 10  | GND     |
337 | | PA4     | 11  |. .| 12  | GND     |
338 | | PA5     | 13  |. .| 14  | GND     |
339 | | PA6     | 15  |. .| 16  | GND     |
340 | | PA7     | 17  |. .| 18  | GND     |
341 | | CA1     | 19  |. .| 20  | GND     |
342 | | PB1     | 21  |. .| 22  | GND     |
343 | | PB2     | 23  |. .| 24  | GND     |
344 | | PB3/CA2 | 25  |. .| 16  | VCC     |
345 | 
346 | User port is connected to VIA 2 at address $9F10-$9F1F. This can be used for serial or parallel port I/O. Commander X16 does not have support for a serial port device in the KERNAL.
347 | 
348 | ## VERA Video Header (J11)
349 | 
350 | | Desc    | Pin |   | Pin | Desc    |
351 | |--------:|----:|---|-----|---------|
352 | | VCC     |  1  |. .|  2  | GND     |
353 | | D7      |  3  |. .|  4  | D6      |
354 | | D5      |  5  |. .|  6  | D4      |
355 | | D3      |  7  |. .|  8  | D2      |
356 | | D1      |  9  |. .| 10  | D0      |
357 | | /IO1    | 11  |. .| 12  | RESB    |
358 | | /MEMWE  | 13  |. .| 14  | IRQB    |
359 | | A4      | 15  |. .| 16  | /MEMOE  |
360 | | A2      | 17  |. .| 18  | A3      |
361 | | A0      | 19  |. .| 20  | A1      |
362 | | GND     | 21  |. .| 22  | GND     |
363 | | VERA_L  | 23  |. .| 24  | VERA_R  |
364 | 
365 | VERA is connected to I/O ports at $9F20-$9F3F. See [Chapter 9: VERA Programmer's Reference](X16%20Reference%20-%2009%20-%20VERA%20Programmer's%20Reference.md#chapter-9-vera-programmers-reference)
366 | for details.
367 | 
368 | ### VGA Connector
369 | 
370 | ![VGA Connector](images/VGA_Port.png)
371 | 
372 | | Pin | Desc      |
373 | |-----|-----------|
374 | | 1   | RED |
375 | | 2   | GREEN |
376 | | 3   | BLUE |
377 | | 4   | |
378 | | 5   | GND |
379 | | 6   | RED_RTN |
380 | | 7   | GREEN_RTN |
381 | | 8   | BLUE_RTN |
382 | | 9   | |
383 | | 10  | GND |
384 | | 11  | |
385 | | 12  | |
386 | | 13  | HSync |
387 | | 14  | VSync |
388 | | 15  | |
389 | 
390 | The VGA connector is a female [DE-15](https://en.wikipedia.org/wiki/D-subminiature#Description,_nomenclature,_and_variants) jack.
391 | 
392 | The video resolution is 640x480 59.5FPS progressive scan, RGB color, and separated H/V sync.
393 | 
394 | In interlace mode, both horizontal and vertical sync pulses will appear on the HSync pin. (TODO: Test with OSSC).
395 | 
396 | VERA does not use the ID/DDC lines.
397 | 
398 | ### Composite Connector
399 | 
400 | The Composite video is a standard RCA connector. Center pin carries signal. Shield is signal ground.
401 | 
402 | The signal is NTSC Composite baseband video.
403 | 
404 | The video is 480 lines 59.97Hz interlaced. Composite is not available when VGA is running at 59.5Hz progressive scan.
405 | 
406 | ### S-Video Connector
407 | 
408 | ![S-Video Connector](images/s_video.png)
409 | 
410 | | Pin | Desc      |                       |
411 | |-----|-----------|-----------------------|
412 | | 1   | GND (Y)   |                       |
413 | | 2   | GND (C)   |                       |
414 | | 3   | Y         | Intensity (Luminance) |
415 | | 4   | C         | Color (Chrominance)   |
416 | 
417 | The connector is a 4-pin Mini-DIN connector. While the same size as a PS/2 connector, the PS/2 connector has a plastic key at the bottom. Do not attempt to plug a keyboard or mouse into the S-Video port, or bent pins will occur.
418 | 
419 | The signal is NTSC baseband Y/C separated video. S-Video provides better resolution than composite, since the color and intensity are provided on separate pins. you can use a splitter cable to separate the Y and C signals to drive a Commodore 1702 or compatible monitor.
420 | 
421 | The video is 480 lines 59.97Hz interlaced. Composite is not available when VGA is running at 59.5Hz progressive scan.
422 | 
423 | ### J2 VERA Programming Interface
424 | 
425 | | Pin | Desc          |
426 | |-----|---------------|
427 | |  1  | +5V           |
428 | |  2  | FPGA_CDONE    |
429 | |  3  | FPGA_CRESET_B |
430 | |  4  | SPI_MISO      |
431 | |  5  | SPI_MOSI      |
432 | |  6  | SPI_SCK       |
433 | |  7  | SPI_SSEL_N    |
434 | |  8  | GND           |
435 | 
436 | ### VERA J7 Remote SD Card Option
437 | 
438 | | Pin | Desc |
439 | |-----|------|
440 | |  1  | CS   |
441 | |  2  | SCK  |
442 | |  3  | MOSI |
443 | |  4  | MISO |
444 | |  5  | +5V  |
445 | |  6  | GND  |
446 | 
447 | This requires an EEPROM programmer and an interface board to program. See [Chapter 15](X16%20Reference%20-%2015%20-%20Upgrade%20Guide.md#chapter-15-upgrade-guide) for the programming adapter and instructions.
448 | 
449 | <!-- For PDF formatting -->
450 | <div class="page-break"></div>
451 | 


--------------------------------------------------------------------------------
/X16 Reference - 15 - Upgrade Guide.md:
--------------------------------------------------------------------------------
 1 | 
 2 | # Chapter 15: Upgrade Guide
 3 | 
 4 | This chapter provides tips for running upgrades on the various programmable chips.
 5 | 
 6 | **WARNING**: flashing any of these components has a risk of leading to an unbootable system. At the current time, doing hardware flash updates requires skill and knowledge beyond that of an ordinary end user and is not recommended without guidance from the community on the Commander X16 Discord.
 7 | 
 8 | Under the headings of each component is a matrix which indicates which software tools can be used to perform the flash of that component, depending on which flashing hardware you have access to and the operating system of the computer you have the device connected to. Some components of the Commander X16 can be self-flashed, but the risk of a failed flash rendering your X16 unbootable is high, in which case an external programmer must be used to flash the component and thus "unbrick" the system.
 9 | 
10 | ### Flashable components
11 | * System ROM
12 | * SMC (PS/2 and Power controller)
13 | * VERA
14 | 
15 | ## System ROM
16 | 
17 | Official community system ROMs will be posted as releases at [X16Community/x16-emulator](https://github.com/X16Community/x16-emulator/releases) inside the distribution for the Emulator.
18 | 
19 | TODO: link to instructions for each solution in the matrix
20 | 
21 | | ↓ Hardware / OS → | Windows | Linux | Mac OS | Commander X16 |
22 | |-|-|-|-|-|
23 | | Commander X16 | - | - | - | x16-flash |
24 | | XGecu TL866II+ | Xgpro | minipro | minipro | - |
25 | | XGecu TL866-3G / T48 | Xgpro | - | - | - |
26 | 
27 | ## SMC
28 | 
29 | Official community SMC ROMs will be posted as releases at [X16Community/x16-smc](https://github.com/X16Community/x16-smc/releases).
30 | 
31 | TODO: link to instructions for each solution in the matrix
32 | 
33 | | ↓ Hardware / OS → | Windows | Linux | Mac OS | Commander X16 |
34 | |-|-|-|-|-|
35 | | Commander X16 | - | - | - | - |
36 | | USBtinyISP | arduino | arduino | arduino | - |
37 | | XGecu TL866II+ | Xgpro | - | - | - |
38 | | XGecu TL866-3G / T48 | Xgpro | - | - | - |
39 | 
40 | ## VERA 
41 | 
42 | TODO: link to instructions for each solution in the matrix
43 | 
44 | Official community VERA bitstreams will be posted as releases at [X16Community/vera-module](https://github.com/X16Community/vera-module/releases)
45 | 
46 | | ↓ Hardware / OS → | Windows | Linux | Mac OS | Commander X16 |
47 | |-|-|-|-|-|
48 | | Commander X16 | - | - | - | flashvera |
49 | | XGecu TL866II+ | Xgpro | minipro | minipro | - |
50 | | XGecu TL866-3G / T48 | [Xgpro](X16%20Reference%20-%20Appendix%20B%20-%20VERA%20Recovery.md#appendix-b-vera-firmware-recovery) | - | - | - |
51 | 
52 | <!-- For PDF formatting -->
53 | <div class="page-break"></div>
54 | 


--------------------------------------------------------------------------------
/X16 Reference - Appendix A - Sound.md:
--------------------------------------------------------------------------------
  1 | 
  2 | # Appendix A: Sound
  3 | 
  4 | ## FM instrument patch presets
  5 | | # | Instrument Name | | # | Instrument Name |
  6 | |-|-|-|-|-|
  7 | | 0 | Acoustic Grand Piano | | 64 | Soprano Sax &#8224; |
  8 | | 1 | Bright Acoustic Piano | | 65 | Alto Sax &#8224; |
  9 | | 2 | Electric Grand Piano | | 66 | Tenor Sax &#8224; |
 10 | | 3 | Honky-tonk Piano | | 67 | Baritone Sax |
 11 | | 4 | Electric Piano 1 | | 68 | Oboe &#8224; |
 12 | | 5 | Electric Piano 2 | | 69 | English Horn &#8224; |
 13 | | 6 | Harpsichord | | 70 | Bassoon |
 14 | | 7 | Clavinet | | 71 | Clarinet &#8224; |
 15 | | 8 | Celesta | | 72 | Piccolo |
 16 | | 9 | Glockenspiel | | 73 | Flute &#8224; |
 17 | | 10 | Music Box | | 74 | Recorder |
 18 | | 11 | Vibraphone &#8224; | | 75 | Pan Flute |
 19 | | 12 | Marimba | | 76 | Blown Bottle |
 20 | | 13 | Xylophone | | 77 | Shakuhachi |
 21 | | 14 | Tubular Bells | | 78 | Whistle &#8224; |
 22 | | 15 | Dulcimer | | 79 | Ocarina |
 23 | | 16 | Drawbar Organ &#8224; | | 80 | Lead 1 (Square) &#8224; |
 24 | | 17 | Percussive Organ &#8224; | | 81 | Lead 2 (Sawtooth) &#8224; |
 25 | | 18 | Rock Organ &#8224; | | 82 | Lead 3 (Triangle) &#8224; |
 26 | | 19 | Church Organ | | 83 | Lead 4 (Chiff+Sine) &#8224; |
 27 | | 20 | Reed Organ | | 84 | Lead 5 (Charang) &#8224; |
 28 | | 21 | Accordion | | 85 | Lead 6 (Voice) &#8224; |
 29 | | 22 | Harmonica | | 86 | Lead 7 (Fifths) &#8224; |
 30 | | 23 | Bandoneon | | 87 | Lead 8 (Solo) &#8224; |
 31 | | 24 | Acoustic Guitar (Nylon) | | 88 | Pad 1 (Fantasia) &#8224; |
 32 | | 25 | Acoustic Guitar (Steel) | | 89 | Pad 2 (Warm) &#8224; |
 33 | | 26 | Electric Guitar (Jazz) | | 90 | Pad 3 (Polysynth) &#8224; |
 34 | | 27 | Electric Guitar (Clean) | | 91 | Pad 4 (Choir) &#8224; |
 35 | | 28 | Electric Guitar (Muted) | | 92 | Pad 5 (Bowed) |
 36 | | 29 | Electric Guitar (Overdriven) | | 93 | Pad 6 (Metallic) |
 37 | | 30 | Electric Guitar (Distortion) | | 94 | Pad 7 (Halo) &#8224; |
 38 | | 31 | Electric Guitar (Harmonics) | | 95 | Pad 8 (Sweep) &#8224; |
 39 | | 32 | Acoustic Bass | | 96 | FX 1 (Raindrop) |
 40 | | 33 | Electric Bass (finger) | | 97 | FX 2 (Soundtrack) &#8224; |
 41 | | 34 | Electric Bass (picked) | | 98 |FX 3 (Crystal) |
 42 | | 35 | Fretless Bass | | 99 | FX 4 (Atmosphere) &#8224; |
 43 | | 36 | Slap Bass 1 | | 100 | FX 5 (Brightness) &#8224; |
 44 | | 37 | Slap Bass 2 | | 101 | FX 6 (Goblin) |
 45 | | 38 | Synth Bass 1 | | 102 | FX 7 (Echo) |
 46 | | 39 | Synth Bass 2 | | 103 | FX 8 (Sci-Fi) &#8224; |
 47 | | 40 | Violin &#8224; | | 104 | Sitar |
 48 | | 41 | Viola &#8224; | | 105 | Banjo |
 49 | | 42 | Cello &#8224; | | 106 | Shamisen |
 50 | | 43 | Contrabass &#8224; | | 107 | Koto |
 51 | | 44 | Tremolo Strings &#8224; | | 108 | Kalimba |
 52 | | 45 | Pizzicato Strings | | 109 | Bagpipe |
 53 | | 46 | Orchestral Harp | | 110 | Fiddle &#8224; |
 54 | | 47 | Timpani | | 111 | Shanai &#8224; |
 55 | | 48 | String Ensemble 1 &#8224; | | 112 | Tinkle Bell |
 56 | | 49 | String Ensemble 2 &#8224; | | 113 | Agogo |
 57 | | 50 | Synth Strings 1 &#8224; | | 114 | Steel Drum |
 58 | | 51 | Synth Strings 2 &#8224; | | 115 | Woodblock |
 59 | | 52 | Choir Aahs &#8224; | | 116 | Taiko Drum |
 60 | | 53 | Voice Doos | | 117 | Melodic Tom |
 61 | | 54 | Synth Voice &#8224; | | 118 | Synth Drum |
 62 | | 55 | Orchestra Hit | | 119 | Reverse Cymbal |
 63 | | 56 | Trumpet &#8224; | | 120 | Fret Noise |
 64 | | 57 | Trombone | | 121 | Breath Noise |
 65 | | 58 | Tuba | | 122 | Seashore &#8224; |
 66 | | 59 | Muted Trumpet &#8224; | | 123 | Bird Tweet |
 67 | | 60 | French Horn | | 124 | Telephone Ring |
 68 | | 61 | Brass Section | | 125 | Helicopter |
 69 | | 62 | Synth Brass 1 | | 126 | Applause &#8224; |
 70 | | 63 | Synth Brass 2 | | 127 | Gunshot |
 71 | 
 72 | &#8224; Instrument is affected by the LFO, giving it a vibrato or tremolo effect.
 73 | 
 74 | ## FM extended instrument patch presets
 75 | These presets exist mainly to support playback of drum sounds, and many of them only work correctly or sound musical at certain pitches or within a small range of pitches.
 76 | 
 77 | | # | Instrument Name | | # | Instrument Name |
 78 | |-|-|-|-|-|
 79 | | 128 | Silent | | 146 | Vibraslap | |
 80 | | 129 | Snare Roll | | 147 | Bongo | |
 81 | | 130 | Snap | | 148 | Maracas | |
 82 | | 131 | High Q | | 149 | Short Whistle |
 83 | | 132 | Scratch | | 150 | Long Whistle |
 84 | | 133 | Square Click | | 151 | Short Guiro |
 85 | | 134 | Kick | | 152 | Long Guiro |
 86 | | 135 | Rim | | 153 | Mute Cuica |
 87 | | 136 | Snare | | 154 | Open Cuica |
 88 | | 137 | Clap | | 155 | Mute Triangle |
 89 | | 138 | Tom | | 156 | Open Triangle |
 90 | | 139 | Closed Hi-Hat | | 157 | Jingle Bell |
 91 | | 140 | Pedal Hi-Hat | | 158 | Bell Tree |
 92 | | 141 | Open Hi-Hat | | 159 | Mute Surdo |
 93 | | 142 | Crash | | 160 | Pure Sine |
 94 | | 143 | Ride Cymbal | | 161 | Timbale |
 95 | | 144 | Splash Cymbal | | 162 | Open Surdo |
 96 | | 145 | Tambourine | |
 97 | 
 98 | ## Drum presets
 99 | These are the percussion instrument mappings for the drum number argument of the `ym_playdrum` and `ym_setdrum` API calls, and the `FMDRUM` BASIC command.
100 | 
101 | | # | Instrument Name | | # | Instrument Name |
102 | |-|-|-|-|-|
103 | | | | | 56 | Cowbell |
104 | | 25 | Snare Roll | | 57 | Crash Cymbal 2 |
105 | | 26 | Finger Snap | | 58 | Vibraslap |
106 | | 27 | High Q | | 59 | Ride Cymbal 2 |
107 | | 28 | Slap | | 60 | High Bongo |
108 | | 29 | Scratch Pull | | 61 | Low Bongo |
109 | | 30 | Scratch Push | | 62 | Mute High Conga |
110 | | 31 | Sticks | | 63 | Open High Conga |
111 | | 32 | Square Click | | 64 | Low Conga |
112 | | 33 | Metronome Bell | | 65 | High Timbale |
113 | | 34 | Metronome Click | | 66 | Low Timbale |
114 | | 35 | Acoustic Bass Drum | | 67 | High Agogo |
115 | | 36 | Electric Bass Drum | | 68 | Low Agogo |
116 | | 37 | Side Stick | | 69 | Cabasa |
117 | | 38 | Acoustic Snare | | 70 | Maracas |
118 | | 39 | Hand Clap | | 71 | Short Whistle |
119 | | 40 | Electric Snare | | 72 | Long Whistle |
120 | | 41 | Low Floor Tom | | 73 | Short Guiro |
121 | | 42 | Closed Hi-Hat | | 74 | Long Guiro |
122 | | 43 | High Floor Tom | | 75 | Claves |
123 | | 44 | Pedal Hi-Hat | | 76 | High Woodblock |
124 | | 45 | Low Tom | | 77 | Low Woodblock |
125 | | 46 | Open Hi-Hat | | 78 | Mute Cuica |
126 | | 47 | Low-Mid Tom | | 79 | Open Cuica |
127 | | 48 | High-Mid Tom | | 80 | Mute Triangle |
128 | | 49 | Crash Cymbal 1 | | 81 | Open Triangle |
129 | | 50 | High Tom | | 82 | Shaker |
130 | | 51 | Ride Cymbal 1 | | 83 | Jingle Bell |
131 | | 52 | Chinese Cymbal | | 84 | Belltree |
132 | | 53 | Ride Bell | | 85 | Castanets |
133 | | 54 | Tambourine | | 86 | Mute Surdo |
134 | | 55 | Splash Cymbal | | 87 | Open Surdo |
135 | 
136 | ___
137 | 
138 | ## BASIC FMPLAY and PSGPLAY string macros
139 | 
140 | ### Overview
141 | 
142 | The play commands use a string of tokens to define sequences of notes to be played on a single voice of the corresponding sound chip. Tokens cause various effects to happen, such as triggering notes, changing the playback speed, etc. In order to
143 | minimize the amount of text required to specify a sequence of sound, the player
144 | maintains an internal state for most note parameters.
145 | 
146 | ##### Stateful Player Behavior:
147 | 
148 | Playback parameters such as tempo, octave, volume, note duration, etc do not need to be specified for each note. These states are global between all voices of both the FM and PSG sound chips. The player maintains parameter state during and after playback. For instance, setting the octave to 5 in an `FMPLAY` command will result in subsequent `FMPLAY` and `PSGPLAY` statements beginning with the octave set to 5.
149 | 
150 | The player state is reset to default values whenever `FMINIT` or `PSGINIT` are used.
151 | 
152 | Parameter    |Default|Equivalent Token
153 | -------------|-------|----------------
154 | Tempo        | 120   | T120
155 | Octave       | 4     | O4
156 | Length       | 4     | L4
157 | Note Spacing | 1     | S1
158 | 
159 | 
160 | ##### Using Tokens:
161 | The valid tokens are: **`A-G,I,K,L,O,P,R,S,T,V,<,>`**.
162 | 
163 | Each token may be followed by optional modifiers such as numbers or symbols. Options to a token must be given in the order they are expected, and must have no spacing between them. Tokens may have spaces between them as desired. Any unknown
164 | characters are ignored.
165 | 
166 | Example:
167 | ```BASIC
168 | FMPLAY 0,"L4"      : REM DEFAULT LENGTH = QUARTER NOTE
169 | FMPLAY 0,"A2. C+." : REM VALID
170 | FMPLAY 0,"A.2 C.+" : REM INVALID
171 | ```
172 | The valid command plays A as a dotted half, followed by C&#9839; as a dotted quarter.
173 | 
174 | The invalid example would play A as a dotted quarter (not half) because length must come before dots. Next, it would ignore the 2 as garbage. Then it would play natural C (not sharp) as a dotted quarter. Finally, it would ignore the + as garbage, because sharp/flat must precede length and dot.
175 | 
176 | ### Token definitions:
177 | 
178 | ### Musical notes
179 | * Synopsis: Play a musical note, optionally setting the length.
180 | * Syntax: `<A-G>[<+/->][<length>][.]`
181 | 
182 | Example:
183 | ```BASIC
184 | FMPLAY 0,"A+2A4C.G-8."
185 | ```
186 | On the YM2151 using channel 0, plays in the current octave an **A&#9839;** [half note<sup>?</sup>](# "minim") followed by an **A** [quarter note<sup>?</sup>](# "crotchet"), followed by **C** dotted quarter note, followed by **G&#9837;** dotted [eighth note<sup>?</sup>](# "quaver").
187 | 
188 | Lengths and dots after the note name or rest set the length just for the current note or rest.  To set the default length for subsequent notes and rests, use the `L` macro.
189 | 
190 | 
191 | ### Rests
192 | * Synopsis: Wait for a period of silence equal to the length of a note, optionally setting the length.
193 | * Syntax: `R[<length>][.]`
194 | 
195 | Example:
196 | ```BASIC
197 | PSGPLAY 0,"CR2DRE"
198 | ```
199 | On the VERA PSG using voice 0, plays in the current octave a **C** quarter note, followed by a half rest (silence), followed by a quarter **D**, followed by a quarter rest (silence), and finally a quarter **E**.
200 | 
201 | The numeral `2` in `R2` sets the length for the `R` itself but does not alter the
202 | default note length (assumed as 4 - quarter notes in this example).
203 | 
204 | ### Note Length
205 | * Synopsis: Set the default length for notes and rests that follow
206 | * Syntax: `L[<length>][.]`
207 | 
208 | Example values:
209 | * L4 = quarter note (crotchet)
210 | * L16 = sixteenth note (semiquaver)
211 | * L12 = 8th note triplets (quaver triplet)
212 | * L4. = dotted quarter note (1.5x the length)
213 | * L4.. = double-dotted quarter note (1.75x the length)
214 | 
215 | Example program:
216 | ```BASIC
217 | 10 FMPLAY 0,"L4"
218 | 20 FOR I=1 TO 2
219 | 30 FMPLAY 0,"CDECL8"
220 | 40 NEXT
221 | ```
222 | On the YM2151 using channel 0, this program, when RUN, plays in the current octave the sequence **C** **D** **E** **C** first as quarter notes, then as eighth notes the second time around.
223 | 
224 | ### Articulation
225 | * Synopsis: Set the spacing between notes, from legato to extreme staccato
226 | * Syntax: `S<0-7>`
227 | 
228 | `S0` indicates legato. For FMPLAY, this also means that notes after the first in a phrase don't implicitly retrigger.
229 | 
230 | `S1` is the default value, which plays a note for 7/8 of the duration of the note, and releases the note for the remaining 1/8 of the note's duration.
231 | 
232 | You can think of `S` is, out of 8, how much space is put between the notes.
233 | 
234 | Example:
235 | ```BASIC
236 | FMPLAY 0,"L4S1CDES0CDES4CDE"
237 | ```
238 | On the YM2151 using channel 0, plays in the current octave the sequence **C** **D** **E** three times, first with normal articulation, next with legato (notes all run together and without retriggering), and finally with a moderate staccato.
239 | 
240 | 
241 | ### Explicit retrigger
242 | * Synopsis: on the YM2151, when using `S0` legato, retrigger on the next note.
243 | * Syntax: `K`
244 | 
245 | Example:
246 | ```BASIC
247 | FMPLAY 0,"S0CDEKFGA"
248 | ```
249 | On the YM2151 using channel 0, plays in the current octave the sequence **C** **D** **E** using legato, only triggering on the first note, then the sequence **F** **G** **A** the same way. The note **F** is triggered without needing to release the previous note early.
250 | 
251 | 
252 | ### Octave
253 | * Synopsis: Explicitly set the octave number for notes that follow
254 | * Syntax: `O<0-7>`
255 | 
256 | Example:
257 | ```BASIC
258 | PSGPLAY 0,"O4AO2AO6CDE"
259 | ```
260 | On the VERA PSG using voice 0, changes to octave 4 and plays **A** (440Hz), then switches to octave 2, and plays **A** (110Hz), then switches to octave 6 and plays the sequence **C** **D** **E**
261 | 
262 | ### Octave Up
263 | * Synopsis: Increases the octave by 1
264 | * Syntax: `>`
265 | 
266 | If the octave would go above 7, this macro has no effect.
267 | 
268 | Example:
269 | ```BASIC
270 | PSGPLAY 0,"O4AB>C+DE"
271 | ```
272 | On the VERA PSG using voice 0, changes to octave 4 and plays the first five notes of the **A major** scale by switching to octave 5 starting at the **C&#9839;**
273 | 
274 | ### Octave Down
275 | * Synopsis: Decreases the octave by 1
276 | * Syntax: `<`
277 | 
278 | If the octave would go below 0, this macro has no effect.
279 | Example:
280 | ```BASIC
281 | PSGPLAY 0,"O5GF+EDC<BAG"
282 | ```
283 | On the VERA PSG using voice 0, changes to octave 5 and plays the **G major** scale from the top down by switching to octave 4 starting at the **B**
284 | 
285 | ### Tempo
286 | * Synopsis: Sets the BPM, the number of quarter notes per minute
287 | * Syntax: `T<1-255>`
288 | 
289 | High tempo values and short notes tend to have inaccurate lengths due to quantization error. Delays within a string do keep track of fractional frames so the overall playback length should be relatively consistent.
290 | 
291 | Low tempo values that cause delays (lengths) to exceed 255 frames will also end up being inaccurate. For very long notes, it may be better to use legato to string several together.
292 | 
293 | Example:
294 | ```BASIC
295 | 10 FMPLAY 0,"T120C4CGGAAGR"
296 | 20 FMPLAY 0,"T180C4CGGAAGR"
297 | ```
298 | On the YM2151 using channel 0, plays in the current octave the first 7 notes of *Twinkle Twinkle Little Star*, first at 120 beats per minute, then again 1.5 times as fast at 180 beats per minute.
299 | 
300 | ### Volume
301 | * Synopsis: Set the channel or voice volume
302 | * Syntax: `V<0-63>`
303 | 
304 | This macro mirrors the `PSGVOL` and `FMVOL` BASIC commands for setting a channel or voice's volume. 0 is silent, 63 is maximum volume.
305 | 
306 | Example:
307 | ```BASIC
308 | FMPLAY 0,"V40ECV45ECV50ECV55ECV60ECV63EC"
309 | ```
310 | On the YM2151 using channel 0, starting at a moderate volume, plays the sequence **E** **C**, repeatedly, increasing the volume steadily each time.
311 | 
312 | 
313 | ### Panning
314 | * Synopsis: Sets the stereo output of a channel or voice to left, right, or both.
315 | * Syntax: `P<1-3>`
316 | 
317 | 1 = Left  
318 | 2 = Right  
319 | 3 = Both  
320 | 
321 | Example:
322 | ```BASIC
323 | 10 FOR I=1 TO 4
324 | 20 PSGPLAY 0,"P1CP2B+"
325 | 30 NEXT I
326 | 40 PSGPLAY 0,"P3C"
327 | ```
328 | On the VERA PSG using voice 0, in the current octave, repeatedly plays a **C** out of the left speaker, then a **B&#9839;** (effectively a **C** one octave higher) out of the right speaker.  After 4 such loops, it plays a **C** out of both speakers.
329 | 
330 | ### Instrument change
331 | * Synopsis: Sets the FM instrument (like FMINST) or PSG waveform (like PSGWAV)
332 | * Syntax: `I<0-255>` (0-162 for FM)
333 | 
334 | Note: This macro is available starting in ROM version R43.
335 | 
336 | Example:
337 | ```BASIC
338 | 10 FMINIT
339 | 20 FMVIB 200,15
340 | 30 FMCHORD 0,"I11CI11EI11G"
341 | ```
342 | This program sets up appropriate vibrato/tremolo and plays a C major chord with the vibraphone patch across FM channels 0, 1, and 2.
343 | 
344 | <!-- For PDF formatting -->
345 | <div class="page-break"></div>
346 | 


--------------------------------------------------------------------------------
/X16 Reference - Appendix B - VERA Recovery.md:
--------------------------------------------------------------------------------
 1 | 
 2 | # Appendix B: VERA Firmware Recovery
 3 | 
 4 | **WARNING: This is a draft that may contain errors or omissions that could damage your hardware.**
 5 | 
 6 | ## Using a Windows PC to upgrade or recover a VERA
 7 | 
 8 | **Target Component:** VERA  
 9 | **Programmer:** TL866-3G/T48  
10 | **Software:** Xgpro  
11 | **Host OS:** Windows  
12 | 
13 | 
14 | ### Before You Start
15 | 
16 | Before starting, it is recommended to disconnect the Commander X16's PSU's power from the wall socket.  You will need to reconnect power later, but while connecting the programmer to the system, it is safer to disconnect mains power from the power supply. Power is supplied to parts of the main board even when the computer is turned off.use_directory_urls
17 | To perform the upgrade, you will need the following:
18 | - A TL866-3G/T48 programmer
19 | - The Xgpro software
20 | - Female-to-female jumper wires
21 | 
22 | 
23 | ### Programmer Wiring Setup
24 | 
25 | The VERA 8-pin header should be connected as follows:
26 | 
27 | | VERA J2 Pin   | Connect to                       |
28 | |---------------|----------------------------------|
29 | | 1 (+5V)       | Not connected                    |
30 | | 2 (CDONE)     | Not connected                    |
31 | | 3 (CRESET_B)  | VERA, J7 GND pin                 |
32 | | 4 (SPI_MISO)  | TL866-3G/T48, ICSP pin 5 (MISO)  |
33 | | 5 (SPI_MOSI)  | TL866-3G/T48, ICSP pin 15 (MOSI) |
34 | | 6 (SPI_SCK)   | TL866-3G/T48, ICSP pin 7 (SCK)   |
35 | | 7 (SPI_SEL_N) | TL866-3G/T48, ICSP pin 1 (/CS)   |
36 | | 8 (GND)       | TL866-3G/T48, ICSP pin 16 (GND)  |
37 | 
38 | Image 1: Vera J2 programming header and J7 header.<br>
39 | <img src="images/vera-prg-hdr.jpg" width="400" />
40 | 
41 | Image 2: TL866-3G/T48 ICSP header.<br>
42 | <img src="images/tl866-3g-icsp.jpg" width="400" />
43 | 
44 | Image 3: Schematics for connection between the VERA board and the TL866-3G/T48.<br>
45 | <img src="images/tl866-3g-to-vera.png" width="400" />
46 | 
47 | 
48 | ### Powering the Target Component
49 | 
50 | The VERA board is programmed while it is still mounted in the Commander X16 and 
51 | will be powered by the computer's PSU, not by the programmer.
52 | 
53 | Before proceeding with the firmware upgrade, ensure that the wiring is correct. 
54 | Then, connect the Commander X16 to the wall socket and press the computer's power 
55 | button to ensure that 5V is supplied to the VERA board.
56 | 
57 | Please note that the VERA's FPGA is held in reset because 
58 | VERA pin 3 (CRESET_B) is connected to ground. As a result, 
59 | you will not see any screen output during the upgrade process.
60 | 
61 | 
62 | ### Programmer Software Setup
63 | 
64 | Open the Xgpro software and configure the following settings:
65 | 
66 | - Select target chip: W25Q16JV
67 | - Setup interface: Choose ICSP port and uncheck ICSP_VCC_Enable
68 | - Click on "ID Check" to verify the connection
69 |     - The response value should be EF 40 15
70 |     - If it is not, double-check the wiring before proceeding
71 | 
72 | <img src="images/xgpro-window.png" width="600" />
73 | 
74 | 
75 | ### Update/Flash Procedure
76 | 
77 | In the Xgpro software, follow these steps:
78 | 
79 | - Click on "Load" to load the firmware into the software buffer
80 | - After loading the firmware into the software buffer, click on "Prog." to upload the firmware to the VERA board.
81 | 
82 | Once the update is complete, press the power button to turn off the Commander X16. Then, disconnect the computer from the wall socket. Finally, remove all wires from the VERA pin header.
83 | 
84 | Congratulations! The firmware update for VERA is now complete.
85 | 
86 | <!-- For PDF formatting -->
87 | <div class="page-break"></div>
88 | 


--------------------------------------------------------------------------------
/X16 Reference - Appendix D - Official Expansion Cards.md:
--------------------------------------------------------------------------------
 1 | 
 2 | # Appendix D: Official Expansion Cards
 3 | 
 4 | This is just a stub as a proposal for how to document official expansion cards
 5 | (namely those made by the core X16 team).
 6 | 
 7 | ## Serial/MIDI UART/Wavetable Expansion Card
 8 | 
 9 | Kevin is designing an EIA compliant UART expansion card which is capable of supporting 
10 | standard serial as well as MIDI and even has a header to install wavetable cards.
11 | It uses the Texas Instruments [TL16C2550](https://www.ti.com/product/TL16C2550).
12 | 
13 | ![Prototype Serial Card](images/Appendix_B/X16-Serial.png)
14 | 
15 | As the card is still in development there are not any demos or code examples available,
16 | though the datasheet contains information on how to set things up (see below). Kevin
17 | also provided [some information](https://discord.com/channels/547559626024157184/548715649065811989/1183801692878295101) on how to set up the card in his original announcement on the community Discord.
18 | 
19 | <!-- For PDF formatting -->
20 | <div class="page-break"></div>
21 | 


--------------------------------------------------------------------------------
/X16 Reference - Appendix E - Diagnostic Bank.md:
--------------------------------------------------------------------------------
  1 | 
  2 | # Appendix E: Diagnostic Bank
  3 | 
  4 | The Diagnostic ROM bank can run a full diagnostic on the system memory (base + 512K-2048K extended) of the Commander X16.
  5 | 
  6 | ## Index
  7 | 
  8 | * [Running Diagnostics](#Running-Diagnostics)
  9 | * [Progress indicators](#Progress-Indicators)
 10 | 	* [Without screen](#without-screen)
 11 | 	* [With screen](#with-screen)
 12 | * [Error communication](#Error-communication)
 13 | * [Test algorithm](#test-algorithm)
 14 | 	* [Theory](#theory)
 15 | 	* [Implementation](#implementation)
 16 | 
 17 | ## Running Diagnostics
 18 | ### Functional system
 19 | The memory diagnostics can be started in two different ways. If the system is functional enough to actually boot into BASIC, the diagnostics can be started from there with the following:  
 20 | ```BASIC
 21 | BANK 0,7: SYS $C000
 22 | ```
 23 | 
 24 | It is also possible to jump directly to the diagnostic ROM bank from assembly.  
 25 | ```asm
 26 | 	lda	#$07    ; ROM bank 7 is the diagnostic bank
 27 | 	sta	$01     ; Write ROM bank to ROM bank registers
 28 | 	jmp	$C000   ; Jump to beginning of diagnostic ROM
 29 | ```  
 30 | 
 31 | NOTE: The Diagnostic ROM is not able to return to BASIC or any program that has called. The only way to exit the Diagnostic ROM is by resetting or power cycling the system.
 32 | ### Non functional system
 33 | If the Commander X16 is not able to boot into BASIC, the memory diagnostics can be started by keeping the power button pressed for about a second when powering on the system.  
 34 | This will make the Commander X16 boot directly into the diagnostic ROM bank and start the memory diagnostics.
 35 | 
 36 | ## Progress indicators
 37 | ### Without screen
 38 | When the diagnostic ROM bank starts, it will use the activity LED to indicate the progress.  
 39 | * ON - while zero-page memory is tested (very brief)
 40 | * OFF - for 1st test of base memory (\$0100-\$9EFF)
 41 | * ON - for 2nd test of base memory (\$0100-\$9EFF)
 42 | * OFF - for 3rd test of base memory (\$0100-\$9EFF)
 43 | * ON - for 4th test of base memory (\$0100-\$9EFF)
 44 |   
 45 | After the initial test of base memory, the number of available memory banks is tested, VERA is initialized and both the activity LED and the keyboard LEDs are used to indicate the progress.  
 46 | The keyboard LEDs are used as a binary counter:  
 47 | | Num | Binary | Num Lock | Caps Lock | Scroll Lock |
 48 | |-----|--------|----------|-----------|-------------|
 49 | |  0  |  000   |    0     |     0     |      0      |
 50 | |  1  |  001   |    0     |     0     |      1      |
 51 | |  2  |  010   |    0     |     1     |      0      |
 52 | |  3  |  011   |    0     |     1     |      1      |
 53 | |  4  |  100   |    1     |     0     |      0      |
 54 | |  5  |  101   |    1     |     0     |      1      |
 55 | |  6  |  110   |    1     |     1     |      0      |
 56 | |  7  |  111   |    1     |     1     |      1      |
 57 |   
 58 | #### Main test loop
 59 | During the first test iteration, the keyboard LEDs will display 0 0 1  
 60 | When the test is done, the activity light will blink once.  
 61 | During the second test iteration, the keyboard LEDs will display 0 1 0  
 62 | When the test is done, the activity light will blink once.  
 63 | During the third test iteration, the keyboard LEDs will display 0 1 1  
 64 | When the test is done, the activity light will blink once.  
 65 | During the fourth test iteration, the keyboard LEDs will display 1 0 0  
 66 | When the test is done, the activity light will blink once.  
 67 | 
 68 | As the last part of the test loop, the base memory is tested. Keyboard LEDs will show 1 0 1  
 69 | When the test loop is done, keyboard LEDs will show 1 1 1 and the activity LED will blink 3 times before starting over.
 70 | ### With screen
 71 | When the base memory has been tested the first time, VERA is initialized with output to VGA.  
 72 | On the screen there is detailed information about the progress of each test iteration.  
 73 | Each time through the main test loop, the output of VERA will be switched between VGA and Composite/S-Video.  
 74 | 
 75 | ## Error communication
 76 | If an error is detected before VERA is initialized, the error will be reported with the activity LED by blinking every half second 3 times, staying off for 1 second and repeating. - All tests stop.  
 77 |   
 78 | This means that if an error occurs before VERA is initialized, you have no way of figuring out exactly where the error is, but you do know that the error has happened in base memory.  
 79 |   
 80 | When the initial test of base memory has succeeded and VERA is initialized, any errors will be reported to the display. Only if more than 32 errors are encountered, will the tests stop and the activity LED will flash the same way as when an error is encountered before VERA initialization.  
 81 |   
 82 | Even when tests are stopped, VERA output will still be switched between VGA and Composite/S-Video about every minute.
 83 |   
 84 | The error codes on screen are as follows:
 85 | ![Error code definition](images/Appendix_E/mem-diag-error-code.jpg)
 86 | 
 87 | ## Test algorithm
 88 | ### Theory
 89 | RAM diagnostics are performed with the March C- algorithm. This algorithm should be fairly good at finding most common memory errors.  
 90 |   
 91 | In short, the algorithm is described as follows:
 92 | 1. Write 0 to all memory cells
 93 | 2. For each cell, check that it contains 0 and write 1 in ascending order
 94 | 3. For each cell, check that it contains 1 and write 0 in ascending order
 95 | 4. For each cell, check that it contains 0 and write 1 in descending order
 96 | 5. For each cell, check that it contains 1 and write 0 in descending order
 97 | 6. Check that all cells contain 0
 98 |   
 99 | On the Commander X16 and most other 6502 based computers, above algorithm would take a very long time to complete. For this reason, the algorithm has been modified slightly to write and compare entire bytes instead of single bits.
100 | To catch most memory errors, the following bit patterns are tested:
101 | * 0000 0000
102 | * 0101 0101
103 | * 0011 0011
104 | * 0000 1111
105 |   
106 | The algorithm is then implemented in the following way:
107 | 1. Write pattern to all memory addresses
108 | 2. For each address, check the pattern and write the inverted pattern in ascending order
109 | 3. For each address, check the inverted pattern and write the original pattern in ascending order
110 | 4. For each address, check the original pattern and write the inverted pattern in descending order
111 | 5. For each address, check the inverted pattern and write the original pattern in descending order
112 | 6. Check all addresses contain the original pattern
113 | ### Implementation
114 | When memory test starts, the first thing that happens is that zero-page is tested by itself. If this test passes, the rest of base memory is tested from \$0100-\$9EFF while ensuring that these tests do not affect zero-page memory.  
115 |   
116 | When base memory has passed the initial test, zero-page is used for variables and stack pointer is initialized to enable pushing and popping of registers and function calls.  
117 | VERA is initialized and the number of memory banks is tested.  
118 |   
119 | All available memory banks are tested together as opposed to checking and clearing a single memory page at a time.  
120 | When all memory banks have been tested, the base memory \$0200-\$9EFF is tested again.  
121 |   
122 | Memory banks and base memory is tested in continuous loop.  
123 |   
124 | If an error is detected, this is either communicated through the activity LED, if VERA has not yet been initialized, or by writing information about the error on the display.
125 | <!-- For PDF formatting -->
126 | <div class="page-break"></div>
127 | 


--------------------------------------------------------------------------------
/X16 Reference - Appendix G - ZSM File Format.md:
--------------------------------------------------------------------------------
  1 | 
  2 | # Appendix G: ZSM File Format
  3 | 
  4 | #### Zsound Repo
  5 | 
  6 | The Zsound suite of Commander X16 audio tools contains the original ZSM reference player, found at:  
  7 | https://github.com/ZeroByteOrg/zsound/
  8 | 
  9 | A newer, more flexible, and more recently maintained library with PCM support, ZSMKit, is available at:  
 10 | https://github.com/mooinglemur/ZSMKit/
 11 | 
 12 | #### Current ZSM Revision: 1
 13 | 
 14 | ZSM is a standard specifying both a data stream format and a file structure for containing the data stream. This document provides the standard for both the ZSM stream format and for the ZSM container file format.
 15 | 
 16 | Whenever it becomes necessary to modify the ZSM standard in such a way that existing software will not be compatible with files using the newer standard, this version number will be incremented, up to a maximum value of 254.
 17 | 
 18 | Version 255 (-1) is reserved for internal use by the player
 19 | 
 20 | #### Headerless Data File Format:
 21 | 
 22 |  Since Kernal version r39, it is possible to load data files that do not have the CBM 2-byte load-to-address header. As of version r41, this functionality is equally accessible in the standard interactive BASIC interface. As the "PRG" header is no longer necessary, ZSM files will NOT contain this header in order to appear as any other common data file such as ``.wav``, ``.png``, etc. As such, users and programs must use the "headerless mode" when loading a ZSM into memory on the Commander X16. The previously-suggested dummy PRG header has been incorporated to the ZSM header as a magic header for file identity verification purposes.
 23 | 
 24 | 
 25 | ## ZSM file composition
 26 | 
 27 |  Offset|Length|Field
 28 |  --|--|--
 29 |  0x00|16|ZSM HEADER
 30 |  0x10|variable|ZSM STREAM
 31 |  ?|?|(optional) PCM HEADER
 32 |  ?|variable|(optional) PCM DATA
 33 | 
 34 | ### ZSM Header
 35 | 
 36 | The ZSM header is 16 bytes long.
 37 | 
 38 | - All multi-byte values are little endian unless specified otherwise
 39 | - All offsets are relative to the beginning of the ZSM header
 40 | 
 41 | Offset|Length|Field|Description
 42 | ---|---|---|---
 43 | 0x00|2|Magic Header| The string 'zm' (binary 0x7a 0x6d)
 44 | 0x02|1|Version| ZSM Version. 0-0xFE (0xFF is reserved)
 45 | 0x03|3|Loop Point|Offset to the starting point of song loop. 0 = no loop.
 46 | 0x06|3|PCM offset|Offset to the beginning of the PCM index table (if present). 0 = no PCM header or data is present.
 47 | 0x09|1|FM channel mask|Bit 0-7 are set if the corresponding OPM channel is used by the music.
 48 | 0x0a|2|PSG channel mask|Bits 0-15 are set if the corresponding PSG channel is used by the music.
 49 | 0x0c|2|Tick Rate|The rate (in Hz) for song delay ticks. *60Hz (one tick per frame) is recommended.*
 50 | 0x0e|2|reserved| Reserved for future use. Set to zero.
 51 | 
 52 | 
 53 | ### ZSM Music Data Stream Format
 54 | 
 55 | Byte 0|Byte 1 (variable)|Byte n|Byte n+1 (variable)|...|End of stream
 56 | ---|---|---|---|---|---
 57 | CMD|DATA|CMD|DATA|...|0x80
 58 | 
 59 | #### CMD (command) byte values
 60 | CMD bytes are bit-packed to hold a command Type ID and a value (n) as follows:
 61 | 
 62 | CMD|Bit Pattern|Type|Arg. Bytes|Action
 63 | ---|--|--|--|-----
 64 | 0x00-0x3F|`00nnnnnn`|PSG write|1  | Write the following byte into PSG register offset *n*. (from 0x1F9C0 in VRAM)
 65 |  0x40     |`01000000`|EXTCMD  |1+?| The following byte is an extension command. (see below for EXTCMD syntax)
 66 |  0x41-0x7F|`01nnnnnn`|FM write |2*n*  | Write the following *n* reg/val pairs into the YM2151.
 67 | 0x80|`10000000`|EOF   |0  |This byte MUST be present at the end of the data stream. Player may loop or halt as necessary.
 68 | 0x81-0xFF|`1nnnnnnn`|Delay   |0  |Delay *n* ticks.
 69 | 
 70 | #### EXTCMD:
 71 | The EXTCMD byte is formatted as `ccnnnnnn` where `c`=channel and `n`=number of bytes that follow. If the player wishes to ignore a channel, it can simply advance `n` bytes and continue processing. See EXTCMD Channel Specifications below for more details.
 72 | 
 73 | ### PCM Header
 74 | 
 75 | If the PCM header exists in the ZSM file, it will immediately follow the 0x80 end-of-data marker. The PCM header exists only if at least one PCM instrument exists.
 76 | 
 77 | Since each instrument defined is 16 bytes, the size of the PCM header can be calculated
 78 | as 4+(16*(last_instrument_index+1)).
 79 | 
 80 | Offset|Type|Value
 81 | --|--|--
 82 | 0x00-0x02|String|"PCM"
 83 | 0x03|Byte|The last PCM instrument index
 84 | 0x04-0x13|Mixed|Instrument definition for instrument 0x00
 85 | 0x14-0x23|Mixed|(optional) Instrument definition for instrument 0x01
 86 | ...
 87 | 
 88 | ### Instrument definition
 89 | Offset|Type|Value
 90 | --|--|--
 91 | 0x00|Byte|This instrument's index
 92 | 0x01|Bitmask|AUDIO_CTRL: 00**DC**0000: D is set for 16-bit, and clear for 8-bit. C is set for stereo and clear for mono
 93 | 0x02-0x04|24-bit int|Little-endian offset into the PCM data block
 94 | 0x05-0x07|24-bit int|Little-endian length of PCM data
 95 | 0x08|Bitmask|Features: **L**xxxxxxx: L is set if the sample is looped
 96 | 0x09-0x0b|24-bit int|Little-endian loop point offset (relative, 0 is the beginning of this instrument's sample)
 97 | 0x0c-0x0f|...|Reserved for expansion
 98 | 
 99 | Any offset values contained in the PCM data header block are relative to the beginning of the PCM sample data section, not to the PCM header or ZSM header. The intention is to present the digital audio portion as a set of digi clips ("samples" in tracker terminology) whose playback can be triggered by EXTCMD channel zero.
100 | 
101 | ### PCM Sample Data
102 | 
103 | This is a blob of PCM data with no internal formatting. Offsets into this blob are provided via the PCM header. The end of this blob will be the end of the ZSM file.
104 | 
105 | ## EXTCMD Channel Specifications
106 | 
107 | Extension commands provide optional functionality within a ZSM music file. EXTCMD may be ignored by any player. EXTCMD defines 4 "channels" of message streams. Players may implement support for any, all, or none of the channels as desired. An EXTCMD may specify up to 63 bytes of data. If more data than this is required, then it must be broken up into multiple EXTCMDs.
108 | 
109 | ##### EXTCMD in ZSM stream context:
110 | 
111 | ...|CMD 0x40|EXTCMD|N bytes|CMD|...
112 | ---|---|---|---|---|---
113 | 
114 | ##### EXTCMD byte format:
115 | 
116 | Bit Pattern|C|N
117 | --|--|--
118 | `ccnnnnnn`|Extension Channel ID|Number of bytes that follow
119 | 
120 | 
121 | 
122 | ##### EXTCMD Channels:
123 | 0. PCM instrument channel
124 | 1. Expansion Sound Devices
125 | 2. Synchronization events
126 | 3. Custom
127 | 
128 | The formatting of the data within these 4 channels is presently a work in progress. Definitions for channels 0-3 will be part of the official ZSM specifications and implemented in the Zsound library. Significant changes within one of these three channels' structure may result in a new ZSM version number being issued. The formatting and content of the 3 official EXTCMD channels will be covered here.
129 | 
130 | The Custom channel data may take whatever format is desired for any particular purpose with the understanding that the general ecosystem of ZSM-aware applications will most likely ignore them.
131 | 
132 | ### EXTCMD Channel:
133 | #### 0: PCM audio
134 | 
135 | This EXTCMD stream can contain one or more command + argument pairs.
136 | 
137 | command|meaning|argument|description
138 | ---|---|---|---
139 | 0x00|AUDIO_CTRL byte|byte|This byte sets PCM channel volume and/or clears the FIFO
140 | 0x01|AUDIO_RATE byte|byte|A value from 0x00-0x80 to set the sample rate (playback speed)
141 | 0x02|Instrument trigger|byte|Triggers the PCM instrument specified by this byte index
142 | 
143 | #### 1: Expansion Sound Devices
144 | 
145 | This channel is for data intended for "well-known" expansion hardware used with the Commander X16. As the community adopts various expansion hardware, such devices will be given a standard "ID" number so that all ZSM files will agree on which device is being referenced by expansion HW data.
146 | 
147 | The specification of new chip IDs should not affect the format of ZSM itself, and thus will not result in a ZSM version update. Players will simply need to update their list of known hardware.
148 | 
149 | Players implementing this channel should implement detection routines during init to determine which (if any) expansion hardware is present. Any messages intended for a chip that is not present in the system should be skipped.
150 | 
151 | An expansion HW write will contain the following data:
152 | 
153 | Chip ID|`nnnnnn-1` bytes of data
154 | --|--
155 | one byte|nnnnnn-1 bytes
156 | 
157 | - The length of the EXTCMD `nnnnnn` encompasses the chip_id byte and the data bytes which follow.
158 | 
159 | ##### Chip IDs
160 | * 0x00 - reserved
161 | * 0x01 - MIDI 1 (Primary MIDI)
162 |     * MIDI data embedded in ZSM is limited to status bytes 0x80-0xF8 inclusive, and their arguments, i.e. data which is intended to be transmitted to a synthesizer.
163 |     * Metadata such as MIDI header data, ticks per beat, track names, lyrics, and tempo are not included in the data.
164 |     * Delta times are not embedded in the MIDI data. Native ZSM delays are used instead.
165 |     * With the exception of multiple EXTCMDs for the same Chip ID within the same tick, the first byte of data must be a status byte 0x80-0xF8.
166 |     * Status continuation is not permitted from prior ticks, but is allowed within the same tick.
167 |         * This restriction allows for simultaneous access to the MIDI device by multiple agents, such as a song player and sound effects player on non-overlapping MIDI channels.
168 |     * An example of an EXTCMD containing a single note-on event might look as follows: `0x40 0x44 0x01 0x90 0x69 0x7F`
169 | * 0x02 - MIDI 2 (Secondary MIDI)
170 |     * A second separate MIDI stream can be used by players that support multiple active MIDI devices. The data format and restrictions are the same as for Chip ID 0x01.
171 | * 0x03 - reserved
172 | * 0x70-0x7F - Private use area
173 |     * These will be ignored by the stock reference players, but can be used for testing or for custom purposes for a particular application.
174 | * 0x80-0xFF - reserved for possible expansion to 15-bit chip IDs
175 | 
176 | #### 2: Synchronization Events
177 | 
178 | The purpose of this channel is to provide for music synchronization cues that applications may use to perform operations in sync with the music (such as when the Goombas jump in New Super Mario Bros in time with the BOP! BOP! notes in the music). It is intended for the reference player to provide a sync channel callback, passing the data bytes to the callback function, and then to proceed with playback.
179 | 
180 | The synchronization format currently defines these event types:
181 | 
182 | Event Type|Description|Message Format
183 | --|--|--
184 | `0x00`|Generic sync message|`xx` (any value from `0x00`-`0xff`)
185 | `0x01`|Song tuning|a signed byte indicating an offset from A-440 tuning represented in 256ths of a semitone
186 | 
187 | An example of an EXTCMD containing one sync event might look as follows: `0x40 0x82 0x00 0x05`
188 | 
189 | 
190 | #### 3: Custom
191 | 
192 | The purpose for this channel is that any project with an idea that does not fit neatly into the above categories may pack data into the project's music files in whatever form is required. It should be understood that these ZSMs will not be expected to use the extended behaviors outside of the project they were designed for. The music itself, however, should play properly. The only constraint is that the data must conform to the EXTCMD byte - supplying exactly the specified number of bytes per EXTCMD.
193 | 
194 | The reference playback library in Zsound will implement this channel as a simple callback passing the memory location and data size to the referenced function, and take no further action internally.
195 | 
196 | <!-- For PDF formatting -->
197 | <div class="page-break"></div>
198 | 


--------------------------------------------------------------------------------
/X16 Reference - Appendix H - Onboard Upgrade Guide.md:
--------------------------------------------------------------------------------
  1 | 
  2 | 
  3 | 
  4 | # Appendix H: How to update your X16 to latest release
  5 | 
  6 | These instructions will guide you how to update your X16 firmware from any previous version to the latest version. This guide will be updated once there are new releases. This guide is applicable for Gen 1 hardware, PRxxxxx boards.
  7 | 
  8 | ## Table Of Contents
  9 | 
 10 | 1. [Latest release](#latest-release)
 11 | 2. [Requirements](#requirements)
 12 | 3. [Update instructions](#update-instructions)
 13 | 4. [Appendix: Release history](#appendix-release-history)
 14 | 5. [Appendix: Stock version numbers](#appendix-stock-version-numbers)
 15 | 6. [Appendix: How to downgrade from latest release to first release](#appendix-how-to-downgrade-from-latest-release-to-first-release)
 16 | 
 17 | ## Latest release
 18 | 
 19 | | Firmware        | Version | Date       | Link                                                               |
 20 | |-----------------|---------|------------|--------------------------------------------------------------------|
 21 | | ROM             | R48     | 2024-09-06 | https://github.com/X16Community/x16-rom/releases/tag/r48           |
 22 | | SMC             | 48.0.0  | 2024-12-23 | https://github.com/X16Community/x16-smc/releases/tag/r48.0.0       |
 23 | | VERA            | 48.0.1  | 2025-01-08 | https://github.com/X16Community/vera-module/releases/tag/v48.0.1   |
 24 | | SMC bootloader  | 3       | 2024-09-13 | https://github.com/X16Community/x16-smc-bootloader/releases/tag/v3 |
 25 | 
 26 | 
 27 | ## Requirements
 28 | | Property | Requirement            |
 29 | |----------|------------------------|
 30 | | Hardware | Gen 1 PRxxxxx board    |
 31 | | ROM      | Minimum version R43    |
 32 | | SMC      | Minimum version 43.0.0 |
 33 | | VERA     | No minimum version     |
 34 | 
 35 | 
 36 | ## Update instructions
 37 | 
 38 | 
 39 | ### Step 1: Note down your current ROM/SMC/VERA versions (recommended)
 40 | 
 41 | #### 1.1 ROM/SMC/VERA versions
 42 | Use the `HELP` command to see which versions you currently have.
 43 | You may want to take a picture of the screen or write it down, for future reference.
 44 | 
 45 | #### 1.2 SMC bootloader version
 46 | - Poll bootloader version with this command: `PRINT I2CPEEK($42,$8E)`
 47 | 	- This should be 2 if you have a stock PR board. Note that if you have bootloader 3 it may incorrectly display as 255.
 48 | - If you have SMC version 47.2.3 or later, you can use the tool "SMCBLD7.PRG" inside [smc tools] (see step 3) to identify bootloader version based on its CRC-16 checksum, making this a more accurate bootloader test.
 49 | - Take a picture of the screen, for future reference.
 50 | 
 51 | 
 52 | ### Step 2: Take a backup of what you have
 53 | 
 54 | #### 2.1 SD card (highly recommended)
 55 | - Plug SD card in your PC and make a backup of all files. In case SD card gets corrupted, damaged, or you loose your files otherwise.
 56 | - If needed, you can download the latest version of the SD card bundle here: https://github.com/cx16forum/sdcard
 57 | 
 58 | #### 2.2 ROM/SMC/VERA (optional)
 59 | - If you know your current version numbers (step 1), and do not care about rolling back, you can safely skip this step.
 60 | - If you like to preserve the history, and your version is not already archived, you may want to dump it before overwriting it.
 61 | 
 62 | <details><summary>CLICK FOR DETAILS</summary>
 63 | <p>
 64 | 
 65 | If your version is not archived (e.g. ROM prerelease), you may want to make a backup of this one (and give a heads-up on Discord, #kernel).
 66 |   - Dump tool for ROM/SMC/VERA/RTC: https://cx16forum.com/forum/viewtopic.php?p=34970
 67 | - Archive of official releases:
 68 |   - ROM: https://github.com/X16Community/x16-rom/releases/
 69 |   - SMC: https://github.com/X16Community/x16-smc/releases/
 70 |   - VERA: https://github.com/X16Community/vera-module/releases/
 71 |   - SMC bootloaders: https://github.com/X16Community/x16-smc-bootloader/releases
 72 | - Unofficial releases, known to have been delivered with some machines:
 73 |   - SMC 45.1.0: Dump: https://github.com/FlightControl-User/x16-flash/releases/download/r3.0.0/R45-BINS.zip
 74 |   - SMC bootloader v2(bad): Dump: Inside [bootloader tools] https://github.com/X16Community/x16-smc/pull/53#issuecomment-2362330198 / src: https://github.com/X16Community/x16-smc/pull/20
 75 |   - ROM R47 prerelease git 8929A57+: Dump: https://cx16forum.com/forum/viewtopic.php?p=31112 / src: X16Community/x16-rom#213 (exact source is ambiguous due to the +)
 76 |   - ROM R47 prerelease git 33ACE3A4: Dump: https://cx16forum.com/forum/viewtopic.php?p=31112 / src: X16Community/x16-rom#241
 77 | </p>
 78 | </details>
 79 | 
 80 | ### Step 3: Download files and place on SD card
 81 | 
 82 | - BIN files and their associated programming tool must stay in the same folder
 83 | - Note that the x16-flash tool (UPDATE.PRG) will attempt to program both ROM, SMC and VERA if it finds associated .BIN files in its folder, so make sure that its folder only contains ROM.BIN
 84 | 
 85 | #### Suggested folder structure:
 86 | - UPDATE
 87 | 	- VERA
 88 | 		- FLASHVERA.PRG
 89 | 		- VERA.BIN (downloaded file must be renamed to VERA.BIN)
 90 | 	- ROM
 91 | 		- UPDATE.PRG
 92 | 		- ROM.BIN
 93 | 	- SMC
 94 | 		- SMCUPDATE-x.x.x.PRG (do not rename)
 95 | 	- SMCTOOLS
 96 | 		- SMCBLD7.PRG
 97 | 		- SMCBLW19.PRG
 98 | 		- BOOT3.BIN
 99 | 
100 | To organize multiple ROM and VERA versions on the SD card, you may e.g. add folders with version numbers, and place firmware inside.
101 | 
102 | #### Downloads:
103 | - VERA 48.0.1
104 | 	- https://github.com/X16Community/vera-module/releases/tag/v48.0.1
105 | 		- Download Assets -> VERA_48.0.1.BIN
106 |     - https://github.com/mooinglemur/flashvera/releases/tag/v0.2
107 | 		- Download Assets -> FLASHVERA.PRG
108 | - ROM R48
109 | 	- https://github.com/X16Community/x16-rom/releases/tag/r48
110 | 		- Download Assets -> Release.R48.ROM.Image.zip
111 | 			- Extract "rom.bin"
112 | 	- https://github.com/FlightControl-User/x16-flash/releases/tag/r3.0.0
113 | 		- Download Assets -> CX16-UPDATE-R3.0.0.PRG
114 | - SMC 48.0.0
115 | 	- https://github.com/X16Community/x16-smc/releases/tag/r48.0.0
116 | 		- Download Assets -> X16-SMC_r48.0.0.zip
117 | 			- Extract "SMCUPDATE-48.0.0.PRG"
118 | - SMC tools v6
119 | 	- https://github.com/X16Community/x16-smc/pull/53#issuecomment-2362330198
120 | 		- Download smc-flash-manipulation-6.zip
121 | 			- Extract files mentioned under SMCTOOLS above
122 | 
123 | #### Copy to SD card
124 | - Prepare the folder structure on the SD card.
125 | - Copy downloaded files to SD card, inside the folder structure mentioned above.
126 | - Rename files as needed. Uppercase/lowercase is not important.
127 | 
128 | #### Navigating the file system on X16
129 | - To list files in current folder, or change folder, you use the commands `DOS"$"` or `DOS"CD:folder"`.
130 | - A shortcut is to use the `@` prefix, e.g. `@$` and `@CD:folder`
131 | - To enter the VERA folder, you can e.g. use the command `@CD:/UPDATE/VERA`
132 | - You can also navigate like this:
133 | 
134 | ```
135 | @CD:/UPDATE
136 | @$
137 | @CD:VERA
138 | @$
139 | ```
140 | 
141 | ### Step 4: Update VERA to 48.0.1
142 | VERA have best backward compatibility, and should be flashed first.
143 | - 48.0.1 supports at least ROM 47 prerelease, and probably older ROMs as well.
144 | - Release page: https://github.com/X16Community/vera-module/releases/tag/v48.0.1
145 | - Follow instructions on release page to program VERA.
146 | 
147 | ```
148 | @CD:/UPDATE/VERA
149 | LOAD "FLASHVERA.PRG"
150 | RUN
151 | ```
152 | 
153 | - After programming, restart machine and type `HELP` to verify VERA version.
154 | 
155 | ### Step 5: Update ROM to R48
156 | - Minimum SMC version: 43.0.0
157 | - Minimum VERA version: 0.3.1
158 | - You may follow this guide: https://github.com/FlightControl-User/x16-flash
159 | 
160 | ```
161 | @CD:/UPDATE/ROM
162 | LOAD "UPDATE.PRG"
163 | RUN
164 | ```
165 | 
166 | - Follow the instructions on screen.
167 | - Note that the J1 jumper must be on, to allow ROM to be reprogrammed. Disconnect jumper after programming, to ensure ROM is write protected.
168 | - Important: Only program ROM in this step, not VERA or SMC.
169 | 
170 | 
171 | ### Step 6: Update SMC to 48.0.0
172 | - To update SMC, a little program on the SMC called "bootloader" is used to replace its main program.
173 | - All PR boards up to ~900 seem to have been delivered with version 45.1.0, and with a bootloader which claims to be version 2, but, unfortunately, is a corrupt version of version 2 (also referred to as the "bad" bootloader). This have the consequence that, if you attempt to program, the x16 will hang at the end of programming. If you attempt to fix the hang problem by disconnecting power, and plug it back in, your SMC will be "bricked", and you cannot use your x16 until you disconnect the SMC and program it manually using an external programmer or Arduino [recovery-with-arduino].
174 | - To update your SMC with bad bootloader, you have 2 options:
175 | 	- Option 1: Disconnect the SMC, connect to an external programmer, and install latest firmware https://github.com/X16Community/x16-smc/blob/main/doc/recovery-with-arduino.md
176 | 	- Option 2: Reset the SMC by shorting its reset pin to GND, using a jumper wire. Instruction: https://github.com/X16Community/x16-smc/blob/main/doc/update-with-bad-bootloader-v2.md
177 | 		- NB: If you plan to do option 2, ref the instructions, you should practice doing this reset while at the READY prompt. Once you get the hang of it, you can do it during programming. It is important that you get it correct at the critical moment when the SMC is hanging inside the bad bootloader.
178 | - If you have a different SMC version than 45.1.0, you most likely do not have the bad bootloader.
179 | 
180 | #### Recommended install method, SMCUPDATE-48.0.0.PRG
181 | - The recommended method to upgrade SMC to latest version 48.0.0, is to use an installer with version 48.0.0 bundled together with the installer.
182 | - If there is a risk of having the bad v2 bootloader, have a jumper wire ready
183 | - Load and run the installer
184 | ```
185 | @CD:/UPDATE/SMC
186 | LOAD "SMCUPDATE-48.0.0.PRG"
187 | RUN
188 | ```
189 | - Use the jumper wire if needed, ref the "update-with-bad-bootloader-v2.md" instructions
190 | 
191 | #### Alternative tools
192 | 
193 | <details><summary>CLICK FOR DETAILS</summary>
194 | <p>
195 | 
196 | - The tool SMCUPDATE 2.0 allows you to specify a .hex file to install
197 | 	- This tool works with bootloader 2, but not with bootloader 3
198 | 	- Tool: https://github.com/stefan-b-jakobsson/x16-smc-update/releases/tag/2.0
199 | 	- When prompted for file name, enter "x16-smc.ino.hex"
200 | - The tool x16-flash allows you to program the .bin file from the release page
201 | 	- This tool ignores bootloader version, and works with both v2 and v3
202 | 	- If bootloader version is 2, you cannot reprogram with the same version
203 | 	- This tool gives bad recommendation in the case of bad bootloader
204 | 	- Tool: https://github.com/FlightControl-User/x16-flash/releases/tag/r3.0.0
205 | - These tools can work with the .hex and .bin files found in the release page
206 | 	- https://github.com/X16Community/x16-smc/releases/tag/r48.0.0
207 | 
208 | </p>
209 | </details>
210 | 
211 | 
212 | 
213 | ### Step 7: Install bootloader v3
214 | Follow instructions inside the text file in [smc tools] ("smc-flash-manipulation-6.zip")
215 | 
216 | - Run SMCBLD7.PRG to get bootloader checksum, version and failsafe status
217 | ```
218 | @CD:/UPDATE/SMCTOOLS
219 | LOAD "SMCBLD7.PRG"
220 | RUN
221 | ```
222 | - Run SMCBLW19.PRG to install BOOT3.BIN
223 | ```
224 | @CD:/UPDATE/SMCTOOLS
225 | LOAD "SMCBLW19.PRG"
226 | RUN
227 | ```
228 | - Run SMCBLD7.PRG to validate checksum again, confirm it BF63 (v3)
229 | - To install "Boot v3 failsafe", you need to update SMC a second time (repeat step 6)
230 | - Run SMCBLD7.PRG, to confirm that boot v3 failsafe is installed
231 | 
232 | With Boot V3 failsafe installed, you have a fallback mechanism in case SMC firmware gets corrupted.
233 | 
234 | 
235 | ## Appendix: Release history
236 | | Date       | ROM               | SMC     | VERA   | SMC bootloader | Notes                           |
237 | |------------|-------------------|---------|--------|----------------|---------------------------------|
238 | | 2025-01-08 |                   |         | 48.0.1 |                | XOR Sawtooth + bus stability    |
239 | | 2024-12-23 |                   | 48.0.0  |        |                | Kbd initstate, read fuse++      |
240 | | 2024-09-13 |                   |         |        | 3              | Boot v3, with failsafe          |
241 | | 2024-09-06 | R48               |         |        |                | Release R48 ("Cadmium")         |
242 | | 2024-07-05 |                   | 47.2.3  |        |                | Bootloader manipulation ++      |
243 | | 2024-03-30 | R47               | 47.0.0  | 47.0.2 |                | Release R47 ("Roswell")         |
244 | | 2023-12-24 | R47 pre 33ACE3A4* |         |        |                | Unreleased ROM version*         |
245 | | 2023-11-20 |                   |         | 0.3.2  |                | Experimental FX                 |
246 | | 2023-11-06 | R47 pre 8929A57+* |         |        |                | Unreleased ROM version*         |
247 | | 2023-11-06 | R46               |         |        |                | Release R46 ("Winnipeg")        |
248 | | 2023-10-18 |                   | 45.1.0* |        |                | Unreleased*, bootloader support |
249 | | 2023-10-17 | R45               |         |        |                | Release R45 ("Nuuk")            |
250 | | 2023-10-04 |                   |         |        | 2              | Boot v2, auto power off         |
251 | | 2023-10-04 |                   |         |        | 2 (bad)*       | Bad version*                    |
252 | | 2023-08-14 | R44               |         |        |                | Release R44 ("Milan")           |
253 | | 2023-08-09 |                   |         | 0.3.1  |                | Experimental FX                 |
254 | | 2023-05-17 | R43               | 43.0.0  |        |                | Release R43 ("Stockholm")       |
255 | | 2023-04-19 |                   |         |        | 1              | Boot v1                         |
256 | | 2023-03-23 |                   |         | 0.1.1  |                | VERA 0.1.1                      |
257 | | 2023-03-07 | R42               | R42     |        |                | Release R42 ("Cambridge")       |
258 | 
259 | * A few releases are not official, but, these have been delivered with some of the machines, see below.
260 | 
261 | 
262 | ## Appendix: Stock version numbers
263 | 
264 | 
265 | <details><summary>CLICK FOR DETAILS</summary>
266 | <p>
267 | 
268 | This is based on feedback from users on Discord, and is very approximate. If you have updated info, feel free to send a message on Discord.
269 | 
270 | ### PR00001 to PR00300
271 | 
272 | | Firmware        | Version              | Date       | Link                                                                                                                                                                  |
273 | |-----------------|----------------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
274 | | ROM             | R47pre git 8929A57+* | 2023-11-06 | Build: https://cx16forum.com/forum/viewtopic.php?p=31112 / src: https://github.com/X16Community/x16-rom/pull/213 (exact source is ambiguous due to the +)             |
275 | | SMC             | 45.1.0*              | 2023-10-18 | Build: https://github.com/FlightControl-User/x16-flash/blob/main/arduino/x16-smc-r45.1-bootloader.hex / src: https://github.com/X16Community/x16-smc/pull/20          |
276 | | VERA            | 0.3.2                | 2023-11-20 | https://github.com/X16Community/vera-module/releases/tag/v0.3.2                                                                                                       |
277 | | SMC bootloader  | 2 (bad)*             | 2023-10-04 | Build: https://github.com/FlightControl-User/x16-flash/blob/main/arduino/x16-smc-r45.1-bootloader.hex / src: https://github.com/stople/x16-smc-bootloader/tree/bad_v2 |
278 | 
279 | ### PR00301 to PR00900
280 | 
281 | | Firmware        | Version              | Date       | Link                                                                                                             |
282 | |-----------------|----------------------|------------|------------------------------------------------------------------------------------------------------------------|
283 | | ROM             | R47pre git 33ACE3A4* | 2023-12-24 | Build: https://cx16forum.com/forum/viewtopic.php?p=31112 / src: https://github.com/X16Community/x16-rom/pull/241 |
284 | | SMC             | 45.1.0*              | 2023-10-18 |                                                                                                                  |
285 | | VERA            | 0.3.2                | 2023-11-20 |                                                                                                                  |
286 | | SMC bootloader  | 2 (bad)*             | 2023-10-04 |                                                                                                                  |
287 | 
288 | ### PR00901 to PR01000
289 | 
290 | | Firmware        | Version | Date       | Link                                                               |
291 | |-----------------|---------|------------|--------------------------------------------------------------------|
292 | | ROM             | R47     | 2024-03-30 | https://github.com/X16Community/x16-rom/releases/tag/r47           |
293 | | SMC             | 47.0.0  | 2024-03-30 | https://github.com/X16Community/x16-smc/releases/tag/r47.0.0       |
294 | | VERA            | 47.0.2  | 2024-03-30 | https://github.com/X16Community/vera-module/releases/tag/v47.0.2   |
295 | | SMC bootloader  | 2       | 2023-10-04 | https://github.com/X16Community/x16-smc-bootloader/releases/tag/v2 |
296 | 
297 | ### PR01001 to PR?????
298 | 
299 | | Firmware        | Version | Date       | Link                                                               |
300 | |-----------------|---------|------------|--------------------------------------------------------------------|
301 | | ROM             | R48     | 2024-09-06 | https://github.com/X16Community/x16-rom/releases/tag/r48           |
302 | | SMC             | 47.2.3  | 2024-07-05 | https://github.com/X16Community/x16-smc/releases/tag/r47.2.3       |
303 | | VERA            | 47.0.2  | 2024-03-30 | https://github.com/X16Community/vera-module/releases/tag/v47.0.2   |
304 | | SMC bootloader  | 2       | 2023-10-04 | https://github.com/X16Community/x16-smc-bootloader/releases/tag/v2 |
305 | 
306 | ### Some stock versions
307 | | Machine | ROM                  | SMC     | VERA   | SMC bootloader |
308 | |---------|----------------------|---------|--------|----------------|
309 | | PR00015 | R47pre git 8929A57+* |         |        |                |
310 | | PR00102 | R47pre git 8929A57+* | 45.1.0* | 0.3.2  | 2 (bad)*       |
311 | | PR00499 | R47pre git 33ACE3A4* |         |        |                |
312 | | PR00831 | R47pre git 33ACE3A4* | 45.1.0* | 0.3.2  | 2 (bad)*       |
313 | | PR00923 |                      | 47.0.0  |        |                |
314 | | PR01011 | R48                  | 47.2.3  | 47.0.2 | 2              |
315 | 
316 | </p>
317 | </details>
318 | 
319 | 
320 | ## Appendix: How to downgrade from latest release to first release
321 | 
322 | <details><summary>CLICK FOR DETAILS</summary>
323 | <p>
324 | 
325 | ### Step 1: Downgrade bootloader
326 | This is optional, as all bootloaders are backward compatible. If you do not plan to downgrade bootloader, go to step 2.
327 | 
328 | Run SMCBLD7.PRG. Check if "Boot v3 failsafe" is installed. If it is, and you plan to downgrade to bootloader v2 or older, you must:
329 | - Ensure [any working SMC programming tool and SMC version] is present on SD card
330 | 	- SMCUPDATE-47.2.3 can be used
331 | 	- NB: x16-flash with bootloader 2 rejects programming SMC to the same version!
332 | - Downgrade bootloader, using SMCBLW19.PRG
333 | - Computer is now in a critical state. If you power it off, it is bricked.
334 | - In this state, you must perform a SMC programming, to any version, with any tool, to uninstall "boot v3 failsafe".
335 | 	- If you installed bad v2 bootloader, remember to reset it using jumper wire
336 | 
337 | ### Step 2: Downgrade SMC
338 | Downgrade SMC using any tool
339 | - SMCUPDATE or x16-update
340 | - Note that SMC 45.1.0* or newer is needed if you want to use the bootloader afterwards
341 | - SMC older than R42 is intended for an incompatible hardware revision
342 | 
343 | ### Step 3: Downgrade ROM
344 | Downgrade ROM
345 | - ROM older than R42 is intended for an incompatible hardware revision
346 | 
347 | ### Step 4: Downgrade VERA
348 | Downgrade VERA
349 | - If using VERA.BIN from release page, use the associated FLASHVERA
350 | - If using VERA.BIN released together with x16-flash, use x16-flash to program it
351 | 
352 | </p>
353 | </details>
354 | 
355 | 
356 | <!-- For PDF formatting -->
357 | <div class="page-break"></div>
358 | 


--------------------------------------------------------------------------------
/X16 Reference - Appendix I - Character Sets.md:
--------------------------------------------------------------------------------
 1 | 
 2 | # Appendix I: Character Sets
 3 | 
 4 | From ROM version R48 there are a total of 12 character sets build in. The different character sets are listed below with a short description of their history and/or use cases.
 5 | 
 6 | ## Index
 7 | 
 8 | 1) [ISO](#iso)
 9 | 2) [PET Uppercase / Graphics](#pet-uppercase--graphics)
10 | 3) [PET Uppercase / Lowercase](#pet-uppercase--lowercase)
11 | 4) [PET Uppercase / Graphis (thin)](#pet-uppercase--graphics-thin)
12 | 5) [PET Uppercase / Lowercase (thin)](#pet-uppercase--lowercase-thin)
13 | 6) [ISO (thin)](#iso-thin)
14 | 7) [CP437](#cp437)
15 | 8) [Cyrillic ISO](#cyrillic-iso)
16 | 9) [Cyrillic ISO (thin)](#cyrillic-iso-thin)
17 | 10) [Eastern Latin ISO](#eastern-latin-iso)
18 | 11) [Eastern ISO (thin)](#eastern-iso-thin)
19 | 12) [Katakana (thin)](#katakana-thin)
20 | 
21 | <div style="page-break-after: always; visibility: hidden;"></div>
22 | 
23 | # ISO
24 | ![ISO](images/Appendix_I/01ISO.png)  
25 | Added to the kernal early on to provide a characterset with international letters and glyphs.
26 | 
27 | <div style="page-break-after: always; visibility: hidden;"></div>
28 | 
29 | # PET Uppercase / Graphics
30 | ![PET upper/graphic](images/Appendix_I/02PETupper-graph.png)  
31 | The default character set of the Commodore 64 and Commander X16, usually referred to as PETSCII. It provides only uppercase letters along with glyphs that can be used for doing simple text based drawings.
32 | 
33 | <div style="page-break-after: always; visibility: hidden;"></div>
34 | 
35 | # PET Uppercase / Lowercase
36 | ![PET upper/lower](images/Appendix_I/03PETupper-lower.png)  
37 | This character set is also present in the Commodore 64 kernal and provides both upper- and lowercase letters at the expense of some of the glyphs used for text based drawing.
38 | 
39 | <div style="page-break-after: always; visibility: hidden;"></div>
40 | 
41 | # PET Uppercase / Graphics (thin)
42 | ![PET upper/graphic (thin)](images/Appendix_I/04PETupper-graph-thin.png)  
43 | The default PETSCII character set, but with thinner characters to give a different aesthetic.
44 | 
45 | <div style="page-break-after: always; visibility: hidden;"></div>
46 | 
47 | # PET Uppercase / Lowercase (thin)
48 | ![PET upper/lower (thin)](images/Appendix_I/05PETupper-lower-thin.png)  
49 | The standard upper- and lowercase PETSCII character set made thin for a different aesthetic.
50 | 
51 | <div style="page-break-after: always; visibility: hidden;"></div>
52 | 
53 | # ISO (thin)
54 | ![ISO (thin)](images/Appendix_I/06ISOthin.png)  
55 | The ISO character set with thin characters for a different aesthetic.
56 | 
57 | <div style="page-break-after: always; visibility: hidden;"></div>
58 | 
59 | # CP437
60 | ![CP437](images/Appendix_I/07CP437.png)  
61 | Added in ROM version R47. This is the character set of the original IBM PC, sometimes referred to as the ANSI character set. It is useful for displaying text created on a PC for example when connecting to BBS'es.
62 | 
63 | <div style="page-break-after: always; visibility: hidden;"></div>
64 | 
65 | # Cyrillic ISO
66 | ![Cyrillic ISO](images/Appendix_I/08CyrillicISO.png)  
67 | Added in ROM version R47. Provides Cyrillic letters used in languages such as Bulgarian, Belarusian, Russian, Serbian and Macedonian. Also known as ISO-8859-5.
68 | 
69 | <div style="page-break-after: always; visibility: hidden;"></div>
70 | 
71 | # Cyrillic ISO (thin)
72 | ![Cyrillic ISO (thin)](images/Appendix_I/09CyrillicISOthin.png)  
73 | Added in ROM version R47. Thin version of the Cyrillic character set.
74 | 
75 | <div style="page-break-after: always; visibility: hidden;"></div>
76 | 
77 | # Eastern Latin ISO
78 | ![Eastern Latin ISO](images/Appendix_I/10EasternLatinISO.png)  
79 | Added in ROM version R47. Provides eastern european letters used in languages such as Albanian, Croatian, Hungarian, Polish, Romanian, Serbian and Slovenian, but also French, German and Italian. Also known as ISO-8859-16.
80 | 
81 | <div style="page-break-after: always; visibility: hidden;"></div>
82 | 
83 | # Eastern ISO (thin)
84 | ![Eastern ISO (thin)](images/Appendix_I/11EasternISOthin.png)  
85 | Added in ROM version R47. Thin version of the Eastern Latin ISO character set.
86 | 
87 | <div style="page-break-after: always; visibility: hidden;"></div>
88 | 
89 | # Katakana (thin)
90 | ![Katakana (thin)](images/Appendix_I/12Katakana-thin.png)  
91 | Added in ROM version R48. Provides katakana characters for the Japanese and Ainu languages.
92 | 


--------------------------------------------------------------------------------
/images/Appendix_B/X16-Serial.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/Appendix_B/X16-Serial.png


--------------------------------------------------------------------------------
/images/Appendix_E/mem-diag-error-code.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/Appendix_E/mem-diag-error-code.jpg


--------------------------------------------------------------------------------
/images/Appendix_I/01ISO.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/Appendix_I/01ISO.png


--------------------------------------------------------------------------------
/images/Appendix_I/02PETupper-graph.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/Appendix_I/02PETupper-graph.png


--------------------------------------------------------------------------------
/images/Appendix_I/03PETupper-lower.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/Appendix_I/03PETupper-lower.png


--------------------------------------------------------------------------------
/images/Appendix_I/04PETupper-graph-thin.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/Appendix_I/04PETupper-graph-thin.png


--------------------------------------------------------------------------------
/images/Appendix_I/05PETupper-lower-thin.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/Appendix_I/05PETupper-lower-thin.png


--------------------------------------------------------------------------------
/images/Appendix_I/06ISOthin.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/Appendix_I/06ISOthin.png


--------------------------------------------------------------------------------
/images/Appendix_I/07CP437.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/Appendix_I/07CP437.png


--------------------------------------------------------------------------------
/images/Appendix_I/08CyrillicISO.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/Appendix_I/08CyrillicISO.png


--------------------------------------------------------------------------------
/images/Appendix_I/09CyrillicISOthin.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/Appendix_I/09CyrillicISOthin.png


--------------------------------------------------------------------------------
/images/Appendix_I/10EasternLatinISO.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/Appendix_I/10EasternLatinISO.png


--------------------------------------------------------------------------------
/images/Appendix_I/11EasternISOthin.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/Appendix_I/11EasternISOthin.png


--------------------------------------------------------------------------------
/images/Appendix_I/12Katakana-thin.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/Appendix_I/12Katakana-thin.png


--------------------------------------------------------------------------------
/images/CompositeColors.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/CompositeColors.png


--------------------------------------------------------------------------------
/images/CompositeOverscan.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/CompositeOverscan.png


--------------------------------------------------------------------------------
/images/SNES_Controller_Female.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/SNES_Controller_Female.png


--------------------------------------------------------------------------------
/images/SNES_Controller_Female.svg:
--------------------------------------------------------------------------------
1 | <?xml version="1.0" encoding="UTF-8"?><svg id="Layer_2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 93.5 34.13"><defs><style>.cls-1{fill:#fff;}.cls-2{stroke-width:2px;}.cls-2,.cls-3,.cls-4{stroke:#000;stroke-miterlimit:10;}.cls-2,.cls-4{fill:#4d4d4d;}.cls-3{fill:#e6e6e6;}.cls-5{fill:#fbb03b;}</style></defs><g id="Layer_1-2"><path class="cls-2" d="M4.4,9.13H81.25c6.21,0,11.25,5.04,11.25,11.25v1.51c0,6.21-5.04,11.25-11.25,11.25H4.4c-1.88,0-3.4-1.53-3.4-3.4V12.53c0-1.88,1.53-3.4,3.4-3.4Z"/><rect class="cls-3" x="6.5" y="14.63" width="44" height="13" rx="2.14" ry="2.14"/><path class="cls-3" d="M54.7,14.63h25.5c3.48,0,6.3,2.82,6.3,6.3v.4c0,3.48-2.82,6.3-6.3,6.3h-25.5c-1.22,0-2.2-.99-2.2-2.2v-8.6c0-1.22,.99-2.2,2.2-2.2Z"/><circle class="cls-4" cx="12.5" cy="21.13" r="4"/><circle class="cls-4" cx="23.5" cy="21.13" r="4"/><circle class="cls-4" cx="33.5" cy="21.13" r="4"/><circle class="cls-4" cx="44.5" cy="21.13" r="4"/><circle class="cls-4" cx="58.5" cy="21.13" r="4"/><circle class="cls-4" cx="69.5" cy="21.13" r="4"/><circle class="cls-4" cx="80.5" cy="21.13" r="4"/><circle class="cls-5" cx="12.5" cy="21.13" r="1.5"/><circle class="cls-5" cx="23.5" cy="21.13" r="1.5"/><circle class="cls-5" cx="33.5" cy="21.13" r="1.5"/><circle class="cls-5" cx="44.5" cy="21.13" r="1.5"/><circle class="cls-5" cx="58.5" cy="21.13" r="1.5"/><circle class="cls-5" cx="69.5" cy="21.13" r="1.5"/><circle class="cls-5" cx="80.5" cy="21.13" r="1.5"/><g><path d="M11.98,7.08V2.22c-.33,.11-.8,.21-1.11,.23h-.14V1.15l.1-.02c.62-.11,1.26-.45,1.63-.85l.04-.04h1.24V7.08h-1.77Z"/><path class="cls-1" d="M13.63,.37V6.95h-1.52V2.03c-.31,.14-.9,.26-1.24,.29V1.25c.66-.12,1.31-.47,1.7-.89h1.06m.25-.25h-1.42l-.07,.08c-.36,.39-.97,.7-1.56,.81l-.21,.04v1.55l.27-.02c.26-.02,.65-.09,.97-.19V7.2h2.02V.12h0Z"/></g><g><path d="M20.92,7.13v-.12c0-1.33,.62-2.3,2.08-3.31,.96-.67,1.21-.87,1.21-1.39s-.25-.76-.74-.76c-.53,0-.79,.25-.89,.87l-.02,.1h-1.68v-.14c.1-1.06,.82-2.19,2.59-2.19s2.49,1.09,2.49,2.11-.46,1.5-1.76,2.37c-.6,.4-.98,.74-1.17,1.02h3.2l-.23,1.44h-5.08Z"/><path class="cls-1" d="M23.47,.31c1.76,0,2.37,1.01,2.37,1.99s-.44,1.42-1.7,2.27c-.85,.57-1.19,.95-1.3,1.25h3.26l-.19,1.19h-4.85v-.09c0-1.15,.53-2.08,2.02-3.12,.97-.68,1.26-.91,1.26-1.49s-.29-.89-.87-.89c-.68,0-.92,.4-1.01,.97h-1.44c.09-1.13,.87-2.08,2.45-2.08m0-.25c-1.85,0-2.61,1.19-2.7,2.31l-.02,.27h1.92l.03-.21c.09-.55,.3-.76,.77-.76,.43,0,.62,.2,.62,.64s-.19,.61-1.16,1.28c-1.49,1.04-2.13,2.03-2.13,3.32v.34h5.32l.03-.21,.19-1.19,.05-.29h-3.09c.2-.22,.53-.49,.98-.79,1.28-.86,1.81-1.39,1.81-2.48S25.4,.06,23.47,.06h0Z"/></g><g><path d="M33.43,7.19c-1.85,0-2.59-1.06-2.66-2.04v-.13h1.68l.02,.1c.07,.33,.3,.73,1,.73,.58,0,.91-.32,.91-.87,0-.58-.32-.85-1-.85h-.75v-1.35h.68c.7,0,.83-.24,.83-.64s-.26-.63-.75-.63c-.6,0-.75,.29-.82,.6l-.02,.1h-1.66l.02-.14c.05-.45,.39-1.92,2.53-1.92,1.79,0,2.42,1.03,2.42,1.91,0,.73-.39,1.13-.72,1.34,.4,.19,.98,.64,.98,1.61,0,1.07-.71,2.2-2.69,2.2Z"/><path class="cls-1" d="M33.44,.25c1.59,0,2.3,.86,2.3,1.79,0,.79-.48,1.17-.86,1.34v.03c.45,.15,1.12,.56,1.12,1.58,0,.95-.59,2.08-2.57,2.08-1.85,0-2.47-1.06-2.54-1.93h1.45c.09,.45,.42,.83,1.13,.83s1.03-.42,1.03-1c0-.61-.33-.98-1.13-.98h-.63v-1.1h.55c.68,0,.96-.22,.96-.77,0-.45-.28-.76-.88-.76-.7,0-.87,.38-.94,.7h-1.42c.09-.81,.69-1.81,2.41-1.81m0-.25c-1.79,0-2.55,1.05-2.66,2.03l-.03,.28h1.9l.04-.19c.06-.26,.16-.5,.7-.5,.63,0,.63,.38,.63,.51,0,.3-.05,.52-.71,.52h-.8v1.6h.88c.77,0,.88,.37,.88,.73,0,.48-.28,.75-.78,.75s-.8-.21-.88-.63l-.04-.2h-1.92l.02,.27c.08,1.04,.85,2.16,2.79,2.16,2.08,0,2.82-1.2,2.82-2.33,0-.9-.46-1.38-.87-1.62,.31-.25,.61-.66,.61-1.33,0-.94-.67-2.04-2.55-2.04h0Z"/></g><g><path d="M44.88,7.07v-1.48h-3.1v-1.37L44.7,.25h1.82v3.94h.85l-.18,1.41h-.67v1.48h-1.64Zm0-2.89v-1.04c0-.42,0-.74,0-1.01-.35,.56-.91,1.34-1.42,2.05h1.41Z"/><path class="cls-1" d="M46.39,.37v3.94h.83l-.15,1.16h-.69v1.48h-1.39v-1.48h-3.1v-1.25l2.86-3.85h1.63m-1.36,1.25c-.27,.55-1.17,1.8-1.82,2.69h1.78v-1.17c0-.71,0-1.11,.03-1.52m1.61-1.5h-2l-.07,.1-2.86,3.85-.05,.07v1.58h3.1v1.48h1.89v-1.48h.66l.03-.22,.15-1.16,.04-.28h-.87V.12h0Zm-2.93,3.94c.38-.52,.75-1.05,1.05-1.49,0,.17,0,.36,0,.58v.92h-1.04Z"/></g><g><path d="M58.48,7.13c-1.46,0-2.47-.75-2.63-1.95l-.02-.14h1.73l.03,.09c.13,.44,.43,.65,.92,.65,.81,0,.93-.69,.93-1.09,0-.72-.3-1.05-.93-1.05-.58,0-.8,.23-.94,.58l-.04,.09-1.58-.2,.03-.13c.19-.83,.48-2.81,.59-3.68v-.11h4.45l-.25,1.42h-2.75c-.04,.26-.09,.6-.14,.87,.29-.15,.65-.22,1.07-.22,1.36,0,2.24,.91,2.24,2.31,0,1.24-.71,2.56-2.71,2.56Z"/><path class="cls-1" d="M60.88,.31l-.21,1.17h-2.76c-.04,.35-.16,.98-.21,1.25,.26-.2,.65-.35,1.24-.35,1.36,0,2.12,.94,2.12,2.19s-.73,2.44-2.59,2.44c-1.36,0-2.35-.67-2.5-1.84h1.49c.14,.45,.46,.74,1.04,.74,.71,0,1.05-.5,1.05-1.22s-.26-1.18-1.05-1.18c-.64,0-.9,.27-1.05,.66l-1.35-.17c.19-.83,.48-2.79,.59-3.69h4.17m.3-.25h-4.69l-.03,.22c-.11,.87-.4,2.83-.59,3.66l-.06,.27,.27,.03,1.35,.17,.19,.02,.07-.18c.12-.31,.31-.5,.82-.5,.56,0,.8,.28,.8,.93,0,.44-.14,.97-.8,.97-.43,0-.69-.18-.8-.56l-.05-.18h-1.96l.04,.28c.17,1.27,1.23,2.06,2.75,2.06,2.09,0,2.84-1.39,2.84-2.69,0-1.46-.95-2.44-2.37-2.44-.34,0-.64,.05-.9,.14,.03-.18,.06-.37,.09-.54h2.75l.04-.21,.21-1.17,.05-.29h0Z"/></g><g><path d="M69.59,7.19c-1.82,0-2.79-1.19-2.79-3.45,0-1.09,.28-3.61,2.87-3.61,1.53,0,2.3,.92,2.38,1.83v.14h-1.67l-.02-.09c-.07-.26-.21-.54-.76-.54-.61,0-.95,.41-1.05,1.27,.29-.22,.74-.42,1.41-.42,1.34,0,2.27,.95,2.27,2.3,0,1.54-1.06,2.57-2.64,2.57Zm-.04-3.52c-.62,0-.93,.34-.93,1.01,0,.11,.03,1.11,.93,1.11,.85,0,.94-.74,.94-1.06,0-.72-.31-1.06-.94-1.06Z"/><path class="cls-1" d="M69.68,.25c1.49,0,2.18,.9,2.25,1.72h-1.45c-.08-.32-.27-.63-.88-.63-.92,0-1.16,.82-1.2,1.71,.29-.34,.78-.61,1.56-.61,1.26,0,2.15,.89,2.15,2.18,0,1.41-.94,2.45-2.51,2.45-1.99,0-2.66-1.47-2.66-3.33,0-1.71,.64-3.49,2.75-3.49m-.12,5.68c.73,0,1.06-.52,1.06-1.19,0-.63-.24-1.19-1.06-1.19-.67,0-1.05,.38-1.05,1.14,0,.53,.26,1.24,1.05,1.24m.12-5.93c-1.9,0-3,1.36-3,3.74s1.01,3.58,2.91,3.58c1.65,0,2.76-1.08,2.76-2.7,0-1.28-.8-2.22-1.98-2.4h1.83l-.02-.27c-.09-.97-.89-1.95-2.5-1.95h0Zm-.96,2.48c.16-.77,.54-.89,.88-.89,.43,0,.56,.17,.64,.44l.05,.18c-.11-.01-.21-.02-.33-.02-.54,0-.94,.12-1.24,.29h0Zm.83,3.2c-.78,0-.8-.89-.8-.99,0-.61,.26-.89,.8-.89,.35,0,.81,.1,.81,.94,0,.35-.11,.94-.81,.94h0Z"/></g><g><path d="M78.77,7.07l.02-.14c.25-1.81,1.34-4,2.3-5.25h-3.1V.25h5.01V1.43c-1,1.4-2.14,3.53-2.42,5.53l-.02,.11h-1.79Z"/><path class="cls-1" d="M82.87,.37V1.43c-1.09,1.48-2.15,3.61-2.42,5.52h-1.53c.27-1.94,1.5-4.26,2.43-5.4h-3.24V.37h4.76m.25-.25h-5.26V1.8h2.98c-.93,1.3-1.93,3.37-2.17,5.11l-.04,.28h2.04l.03-.21c.28-1.98,1.41-4.09,2.38-5.4l.05-.07V.12h0Z"/></g></g></svg>


--------------------------------------------------------------------------------
/images/VGA_Port.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/VGA_Port.png


--------------------------------------------------------------------------------
/images/VGA_Port.svg:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0" encoding="utf-8"?>
 2 | <!-- Generator: Adobe Illustrator 23.1.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
 3 | <svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
 4 | 	 viewBox="0 0 1122 548" style="enable-background:new 0 0 1122 548;" xml:space="preserve">
 5 | <style type="text/css">
 6 | 	.st0{fill:#FFFFFF;stroke:#000000;stroke-width:2;stroke-miterlimit:10;}
 7 | 	.st1{fill:#0B4E9A;stroke:#000000;stroke-width:2;stroke-miterlimit:10;}
 8 | 	.st2{fill:none;}
 9 | 	.st3{font-family:'DejaVuSansCondensed-Bold', sans-serif; font-stretch: condensed; font-weight: bold;}
10 | 	.st4{font-size:31px;}
11 | </style>
12 | <polygon class="st0" points="46.5,288.94 138.1,248.29 219.1,307.29 208.5,406.94 116.9,447.59 35.9,388.59 "/>
13 | <polygon class="st0" points="975.5,250.94 1065,289.91 1076,386.91 997.5,444.94 908,405.96 897,308.96 "/>
14 | <circle class="st0" cx="127.5" cy="347.94" r="36.88"/>
15 | <circle class="st0" cx="986.5" cy="347.94" r="36.88"/>
16 | <g>
17 | 	<g>
18 | 		<path class="st0" d="M634.34,214.5H483.16H354c-41.49,0-72.92,40.33-65.72,84.33l17.57,107.29c5.62,34.34,33.33,59.38,65.72,59.38
19 | 			h70.48h233.39h70.48c32.38,0,60.09-25.04,65.72-59.38l17.57-107.29c7.2-44-24.23-84.33-65.72-84.33H634.34z"/>
20 | 		<path class="st1" d="M629.12,231.5H488.38H368.15c-38.62,0-67.88,34.87-61.18,72.91l16.36,92.76
21 | 			c5.23,29.69,31.03,51.33,61.18,51.33h65.61h217.26h65.61c30.15,0,55.94-21.64,61.18-51.33l16.36-92.76
22 | 			c6.71-38.04-22.55-72.91-61.18-72.91H629.12z"/>
23 | 		<circle class="st0" cx="392.5" cy="271.75" r="25.25"/>
24 | 		<circle class="st0" cx="632.31" cy="271.75" r="25.25"/>
25 | 		<circle class="st0" cx="712.25" cy="271.75" r="25.25"/>
26 | 		<circle class="st0" cx="552.38" cy="271.75" r="25.25"/>
27 | 		<circle class="st0" cx="472.44" cy="271.75" r="25.25"/>
28 | 		<circle class="st0" cx="392.5" cy="410" r="25.25"/>
29 | 		<circle class="st0" cx="632.31" cy="410" r="25.25"/>
30 | 		<circle class="st0" cx="712.25" cy="410" r="25.25"/>
31 | 		<circle class="st0" cx="552.38" cy="410" r="25.25"/>
32 | 		<circle class="st0" cx="472.44" cy="410" r="25.25"/>
33 | 		<circle class="st0" cx="432.38" cy="340.88" r="25.25"/>
34 | 		<circle class="st0" cx="672.19" cy="340.88" r="25.25"/>
35 | 		<circle class="st0" cx="752.13" cy="340.88" r="25.25"/>
36 | 		<circle class="st0" cx="592.25" cy="340.88" r="25.25"/>
37 | 		<circle class="st0" cx="512.31" cy="340.88" r="25.25"/>
38 | 	</g>
39 | 	<g>
40 | 		<path d="M606,102.5c0,0-32.76,3.25-45.19,3.25s-45.19-3.25-45.19-3.25s-4.52-23.56-4.52-32.5s4.52-32.5,4.52-32.5
41 | 			s32.76-3.25,45.19-3.25S606,37.5,606,37.5s4.52,23.56,4.52,32.5S606,102.5,606,102.5z"/>
42 | 		<rect x="486.19" y="19" width="5.56" height="102"/>
43 | 		<rect x="625.75" y="19" width="5.56" height="102"/>
44 | 	</g>
45 | </g>
46 | <rect x="0.5" y="0.5" class="st2" width="1121" height="547"/>
47 | <text transform="matrix(1 0 0 1 704.5488 282.3125)" class="st3 st4">1</text>
48 | <text transform="matrix(1 0 0 1 743.4692 351.2332)" class="st3 st4">6</text>
49 | <text transform="matrix(1 0 0 1 695.5977 420.8582)" class="st3 st4">11</text>
50 | <text transform="matrix(1 0 0 1 624.5687 282.3127)" class="st3 st4">2</text>
51 | <text transform="matrix(1 0 0 1 664.4893 351.2335)" class="st3 st4">7</text>
52 | <text transform="matrix(1 0 0 1 614.8676 420.8585)" class="st3 st4">12</text>
53 | <text transform="matrix(1 0 0 1 544.5884 282.3127)" class="st3 st4">3</text>
54 | <text transform="matrix(1 0 0 1 584.509 351.2335)" class="st3 st4">8</text>
55 | <text transform="matrix(1 0 0 1 535.1372 420.8585)" class="st3 st4">13</text>
56 | <text transform="matrix(1 0 0 1 463.6085 282.313)" class="st3 st4">4</text>
57 | <text transform="matrix(1 0 0 1 504.5288 351.2327)" class="st3 st4">9</text>
58 | <text transform="matrix(1 0 0 1 455.4073 420.8577)" class="st3 st4">14</text>
59 | <text transform="matrix(1 0 0 1 384.6284 282.312)" class="st3 st4">5</text>
60 | <text transform="matrix(1 0 0 1 414.5977 351.2337)" class="st3 st4">10</text>
61 | <text transform="matrix(1 0 0 1 375.6772 420.8587)" class="st3 st4">15</text>
62 | </svg>
63 | 


--------------------------------------------------------------------------------
/images/atx_24_pin-small.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/atx_24_pin-small.png


--------------------------------------------------------------------------------
/images/atx_24_pin.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/atx_24_pin.png


--------------------------------------------------------------------------------
/images/cx16palette.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/cx16palette.png


--------------------------------------------------------------------------------
/images/fx_fig1.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/fx_fig1.png


--------------------------------------------------------------------------------
/images/fx_fig2.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/fx_fig2.png


--------------------------------------------------------------------------------
/images/iec_port.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/iec_port.gif


--------------------------------------------------------------------------------
/images/monitor.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/monitor.png


--------------------------------------------------------------------------------
/images/ps2_pinout.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/ps2_pinout.png


--------------------------------------------------------------------------------
/images/ps2_pinout.svg:
--------------------------------------------------------------------------------
  1 | <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  2 | <!-- Created with Inkscape (http://www.inkscape.org/) -->
  3 | <svg
  4 |    xmlns:svg="http://www.w3.org/2000/svg"
  5 |    xmlns="http://www.w3.org/2000/svg"
  6 |    version="1.0"
  7 |    width="455"
  8 |    height="455"
  9 |    viewBox="-9.302 -9.782 455 455"
 10 |    id="Layer_1"
 11 |    xml:space="preserve"><defs
 12 |    id="defs60" />
 13 | <path
 14 |    d="M 19.581,217.723 C 19.578,327.416 108.502,416.339 218.195,416.338 C 327.886,416.338 416.815,327.417 416.815,217.723 C 416.812,108.03 327.885,19.098 218.194,19.098 C 108.501,19.099 19.58,108.03 19.581,217.723 z "
 15 |    style="fill:white;stroke:black;stroke-width:6.91480017"
 16 |    id="path3" />
 17 | <path
 18 |    d="M 344.022,91.413 C 318.213,65.607 286.474,49.358 253.196,42.644 L 253.196,74.218 L 252.196,74.218 L 183.197,74.218 L 182.196,74.218 L 182.196,42.647 C 148.916,49.364 117.179,65.615 91.376,91.421 C 32.347,150.449 23.283,240.5 64.146,309.077 L 126.331,309.077 L 126.331,371.282 C 182.447,404.727 252.939,404.728 309.056,371.284 L 309.056,309.081 L 371.244,309.081 C 412.112,240.499 403.053,150.442 344.022,91.413 z "
 19 |    style="fill:none;stroke:black;stroke-width:6.91480017"
 20 |    id="path5" />
 21 | <rect
 22 |    width="62.341999"
 23 |    height="110.828"
 24 |    x="186.466"
 25 |    y="122.695"
 26 |    style="fill:none;stroke:black;stroke-width:6.91480017"
 27 |    id="rect7" />
 28 | <g
 29 |    id="g9">
 30 | 	<circle
 31 |    cx="126.093"
 32 |    cy="141.746"
 33 |    r="19.554001"
 34 |    style="fill:none;stroke:black;stroke-width:6.91480017"
 35 |    id="circle11" />
 36 | 	<circle
 37 |    cx="102.949"
 38 |    cy="233.33099"
 39 |    r="19.554001"
 40 |    style="fill:none;stroke:black;stroke-width:6.91480017"
 41 |    id="circle13" />
 42 | 	<circle
 43 |    cx="332.33099"
 44 |    cy="233.33099"
 45 |    r="19.554001"
 46 |    style="fill:none;stroke:black;stroke-width:6.91480017"
 47 |    id="circle15" />
 48 | 	<circle
 49 |    cx="170.961"
 50 |    cy="324.452"
 51 |    r="19.554001"
 52 |    style="fill:none;stroke:black;stroke-width:6.91480017"
 53 |    id="circle17" />
 54 | 	<circle
 55 |    cx="309.18301"
 56 |    cy="141.745"
 57 |    r="19.554001"
 58 |    style="fill:none;stroke:black;stroke-width:6.91480017"
 59 |    id="circle19" />
 60 | 	<circle
 61 |    cx="264.315"
 62 |    cy="324.45099"
 63 |    r="19.554001"
 64 |    style="fill:none;stroke:black;stroke-width:6.91480017"
 65 |    id="circle21" />
 66 | </g>
 67 | <g
 68 |    id="g23">
 69 | 	<rect
 70 |    width="42"
 71 |    height="42"
 72 |    x="144.198"
 73 |    y="102.218"
 74 |    style="fill:none"
 75 |    id="rect25" />
 76 | 	<path
 77 |    d="M 172.854,108.025 C 171.99,107.977 170.886,108.073 169.686,108.265 C 163.014,109.321 159.558,114.169 158.838,119.353 L 158.934,119.353 C 160.422,117.337 163.062,115.705 166.518,115.705 C 172.038,115.705 175.926,119.737 175.926,125.785 C 175.926,131.545 172.038,136.825 165.51,136.825 C 158.886,136.825 154.518,131.641 154.518,123.529 C 154.518,117.385 156.678,112.537 159.798,109.417 C 162.39,106.873 165.846,105.289 169.782,104.809 C 171.03,104.617 172.086,104.569 172.854,104.569 L 172.854,108.025 L 172.854,108.025 z M 165.606,133.561 C 169.206,133.561 171.654,130.537 171.654,126.073 C 171.654,121.609 169.11,118.921 165.222,118.921 C 162.678,118.921 160.278,120.457 159.126,122.761 C 158.886,123.241 158.694,123.817 158.694,124.585 C 158.742,129.721 161.142,133.561 165.558,133.561 L 165.606,133.561 z "
 78 |    id="path27" />
 79 | </g>
 80 | <g
 81 |    id="g29">
 82 | 	<rect
 83 |    width="42"
 84 |    height="42"
 85 |    x="249.19701"
 86 |    y="102.218"
 87 |    style="fill:none"
 88 |    id="rect31" />
 89 | 	<path
 90 |    d="M 278.669,108.649 L 266.766,108.649 L 265.566,116.569 C 266.286,116.473 266.958,116.377 268.11,116.377 C 270.558,116.377 272.91,116.905 274.83,118.057 C 277.278,119.401 279.294,122.137 279.294,126.169 C 279.294,132.265 274.446,136.825 267.679,136.825 C 264.271,136.825 261.439,135.865 259.903,134.905 L 260.959,131.689 C 262.255,132.457 264.799,133.417 267.68,133.417 C 271.616,133.417 275.072,130.825 275.024,126.601 C 275.024,122.473 272.288,119.641 266.096,119.641 C 264.272,119.641 262.879,119.785 261.728,119.977 L 263.744,105.097 L 278.672,105.097 L 278.672,108.649 L 278.669,108.649 z "
 91 |    id="path33" />
 92 | </g>
 93 | <g
 94 |    id="g35">
 95 | 	<rect
 96 |    width="42"
 97 |    height="42"
 98 |    x="149.198"
 99 |    y="260.21799"
100 |    style="fill:none"
101 |    id="rect37" />
102 | 	<path
103 |    d="M 160.046,294.297 L 160.046,291.705 L 163.358,288.489 C 171.326,280.904 174.974,276.873 174.974,272.169 C 174.974,269.001 173.486,266.072 168.83,266.072 C 165.998,266.072 163.646,267.512 162.206,268.713 L 160.862,265.736 C 162.974,263.961 166.094,262.568 169.694,262.568 C 176.366,262.568 179.198,267.176 179.198,271.64 C 179.198,277.4 175.022,282.056 168.446,288.392 L 165.998,290.697 L 165.998,290.793 L 179.966,290.793 L 179.966,294.297 L 160.046,294.297 L 160.046,294.297 z "
104 |    id="path39" />
105 | </g>
106 | <g
107 |    id="g41">
108 | 	<rect
109 |    width="42"
110 |    height="42"
111 |    x="244.19701"
112 |    y="260.21799"
113 |    style="fill:none"
114 |    id="rect43" />
115 | 	<path
116 |    d="M 264.213,267.032 L 264.117,267.032 L 258.693,269.961 L 257.877,266.745 L 264.693,263.097 L 268.293,263.097 L 268.293,294.297 L 264.213,294.297 L 264.213,267.032 L 264.213,267.032 z "
117 |    id="path45" />
118 | </g>
119 | <g
120 |    id="g47">
121 | 	<rect
122 |    width="42"
123 |    height="42"
124 |    x="124.198"
125 |    y="193.218"
126 |    style="fill:none"
127 |    id="rect49" />
128 | 	<path
129 |    d="M 148.102,227.297 L 148.102,218.801 L 133.606,218.801 L 133.606,216.065 L 147.526,196.097 L 152.086,196.097 L 152.086,215.537 L 156.454,215.537 L 156.454,218.801 L 152.086,218.801 L 152.086,227.297 L 148.102,227.297 L 148.102,227.297 z M 148.102,215.537 L 148.102,205.073 C 148.102,203.441 148.15,201.809 148.246,200.177 L 148.102,200.177 C 147.142,202.001 146.374,203.345 145.51,204.833 L 137.878,215.441 L 137.878,215.537 L 148.102,215.537 L 148.102,215.537 z "
130 |    id="path51" />
131 | </g>
132 | <g
133 |    id="g53">
134 | 	<rect
135 |    width="42"
136 |    height="42"
137 |    x="269.19699"
138 |    y="193.218"
139 |    style="fill:none"
140 |    id="rect55" />
141 | 	<path
142 |    d="M 281.053,222.497 C 282.252,223.217 284.989,224.417 287.964,224.417 C 293.341,224.417 295.068,221.009 295.021,218.369 C 294.973,214.001 291.037,212.129 286.957,212.129 L 284.605,212.129 L 284.605,208.961 L 286.957,208.961 C 290.029,208.961 293.917,207.377 293.917,203.681 C 293.917,201.185 292.333,198.977 288.445,198.977 C 285.949,198.977 283.549,200.081 282.205,201.041 L 281.054,197.969 C 282.734,196.769 285.902,195.569 289.262,195.569 C 295.406,195.569 298.19,199.217 298.19,203.009 C 298.19,206.273 296.222,209.009 292.43,210.401 L 292.43,210.497 C 296.27,211.217 299.39,214.097 299.39,218.465 C 299.39,223.457 295.453,227.825 288.014,227.825 C 284.51,227.825 281.438,226.721 279.902,225.713 L 281.053,222.497 z "
143 |    id="path57" />
144 | </g>
145 | </svg>


--------------------------------------------------------------------------------
/images/redunderline.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/redunderline.png


--------------------------------------------------------------------------------
/images/s_video.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/s_video.png


--------------------------------------------------------------------------------
/images/s_video.svg:
--------------------------------------------------------------------------------
  1 | <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  2 | <!-- Created with Inkscape (http://www.inkscape.org/) -->
  3 | <svg
  4 |    xmlns:svg="http://www.w3.org/2000/svg"
  5 |    xmlns="http://www.w3.org/2000/svg"
  6 |    version="1.0"
  7 |    width="454.99899"
  8 |    height="455"
  9 |    viewBox="-9.302 -9.782 454.999 455"
 10 |    id="Layer_1"
 11 |    xml:space="preserve"><defs
 12 |    id="defs3586" />
 13 | <path
 14 |    d="M 19.082,217.723 C 19.079,327.416 108.003,416.339 217.696,416.338 C 327.385,416.338 416.313,327.417 416.313,217.723 C 416.311,108.03 327.385,19.098 217.695,19.098 C 108.002,19.099 19.081,108.03 19.082,217.723 z "
 15 |    style="fill:#ffffff;stroke:#000000;stroke-width:6.91480017"
 16 |    id="path3545" />
 17 | <path
 18 |    d="M 344.021,91.413 C 318.214,65.607 286.474,49.358 253.196,42.644 L 253.196,74.218 L 252.196,74.218 L 183.197,74.218 L 182.196,74.218 L 182.196,42.647 C 148.916,49.364 117.179,65.615 91.376,91.421 C 32.346,150.449 23.282,240.5 64.145,309.077 L 126.33,309.077 L 126.33,371.282 C 182.446,404.728 252.939,404.729 309.056,371.284 L 309.056,309.081 L 371.243,309.081 C 412.111,240.499 403.053,150.442 344.021,91.413 z "
 19 |    style="fill:none;stroke:#000000;stroke-width:6.91480017"
 20 |    id="path3547" />
 21 | <rect
 22 |    width="100.161"
 23 |    height="56.34"
 24 |    x="167.617"
 25 |    y="311.43701"
 26 |    style="fill:none;stroke:#000000;stroke-width:6.2493"
 27 |    id="rect3549" />
 28 | <g
 29 |    id="g3551">
 30 | 	<circle
 31 |    cx="126.152"
 32 |    cy="141.746"
 33 |    r="19.554001"
 34 |    style="fill:none;stroke:#000000;stroke-width:6.91480017"
 35 |    id="circle3553" />
 36 | 	<circle
 37 |    cx="103.008"
 38 |    cy="233.33099"
 39 |    r="19.554001"
 40 |    style="fill:none;stroke:#000000;stroke-width:6.91480017"
 41 |    id="circle3555" />
 42 | 	<circle
 43 |    cx="332.38599"
 44 |    cy="233.33099"
 45 |    r="19.554001"
 46 |    style="fill:none;stroke:#000000;stroke-width:6.91480017"
 47 |    id="circle3557" />
 48 | 	<circle
 49 |    cx="309.23901"
 50 |    cy="141.745"
 51 |    r="19.554001"
 52 |    style="fill:none;stroke:#000000;stroke-width:6.91480017"
 53 |    id="circle3559" />
 54 | 	<g
 55 |    id="g3561">
 56 | 		<rect
 57 |    width="40"
 58 |    height="43.999001"
 59 |    x="268.25299"
 60 |    y="214.217"
 61 |    style="fill:none"
 62 |    id="rect3563" />
 63 | 		<path
 64 |    d="M 287.207,221.457 L 287.207,250.424 L 291.542,250.424 L 291.542,217.276 L 287.718,217.276 L 280.476,221.151 L 281.343,224.568 L 287.106,221.459 L 287.207,221.457 L 287.207,221.457 z "
 65 |    id="path3565" />
 66 | 	</g>
 67 | 	<g
 68 |    id="g3567">
 69 | 		<rect
 70 |    width="40"
 71 |    height="43.999001"
 72 |    x="127.255"
 73 |    y="214.217"
 74 |    style="fill:none"
 75 |    id="rect3569" />
 76 | 		<path
 77 |    d="M 136.468,250.425 L 157.634,250.425 L 157.634,246.7 L 142.793,246.7 L 142.793,246.597 L 145.394,244.149 C 152.381,237.419 156.819,232.47 156.819,226.35 C 156.819,221.608 153.809,216.713 146.72,216.713 C 142.895,216.713 139.58,218.192 137.336,220.076 L 138.764,223.238 C 140.294,221.964 142.793,220.433 145.802,220.433 C 150.749,220.433 152.33,223.544 152.33,226.911 C 152.33,231.908 148.454,236.192 139.987,244.252 L 136.467,247.669 L 136.468,250.425 L 136.468,250.425 z "
 78 |    id="path3571" />
 79 | 	</g>
 80 | 	<g
 81 |    id="g3573">
 82 | 		<rect
 83 |    width="40"
 84 |    height="44"
 85 |    x="241.25301"
 86 |    y="121.217"
 87 |    style="fill:none"
 88 |    id="rect3575" />
 89 | 		<path
 90 |    d="M 250.313,155.743 C 251.945,156.814 255.209,157.987 258.931,157.987 C 266.836,157.987 271.018,153.346 271.018,148.042 C 271.018,143.401 267.704,140.341 263.622,139.576 L 263.622,139.474 C 267.651,137.995 269.742,135.088 269.742,131.62 C 269.742,127.591 266.784,123.715 260.257,123.715 C 256.688,123.715 253.32,124.99 251.535,126.265 L 252.76,129.529 C 254.189,128.509 256.739,127.336 259.39,127.336 C 263.522,127.336 265.203,129.682 265.203,132.334 C 265.203,136.261 261.072,137.944 257.808,137.944 L 255.309,137.944 L 255.309,141.31 L 257.808,141.31 C 262.143,141.31 266.325,143.299 266.374,147.94 C 266.426,150.745 264.589,154.366 258.877,154.366 C 255.716,154.366 252.81,153.091 251.533,152.326 L 250.313,155.743 z "
 91 |    id="path3577" />
 92 | 	</g>
 93 | 	<g
 94 |    id="g3579">
 95 | 		<rect
 96 |    width="40"
 97 |    height="44"
 98 |    x="154.255"
 99 |    y="121.217"
100 |    style="fill:none"
101 |    id="rect3581" />
102 | 		<path
103 |    d="M 177.34,157.426 L 181.574,157.426 L 181.574,148.399 L 186.215,148.399 L 186.215,144.931 L 181.574,144.931 L 181.574,124.276 L 176.729,124.276 L 161.939,145.492 L 161.939,148.399 L 177.339,148.399 L 177.34,157.426 L 177.34,157.426 z M 177.34,144.931 L 166.478,144.931 L 166.478,144.829 L 174.586,133.558 C 175.504,131.977 176.32,130.549 177.34,128.611 L 177.493,128.611 C 177.391,130.345 177.34,132.079 177.34,133.813 L 177.34,144.931 L 177.34,144.931 z "
104 |    id="path3583" />
105 | 	</g>
106 | </g>
107 | </svg>


--------------------------------------------------------------------------------
/images/tl866-3g-icsp.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/tl866-3g-icsp.jpg


--------------------------------------------------------------------------------
/images/tl866-3g-to-vera.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/tl866-3g-to-vera.png


--------------------------------------------------------------------------------
/images/vera-prg-hdr.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/vera-prg-hdr.jpg


--------------------------------------------------------------------------------
/images/xgpro-window.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/X16Community/x16-docs/ce298752c1ee5f23d9d5eab8c2f5301a30610db1/images/xgpro-window.png


--------------------------------------------------------------------------------