diff options
| -rw-r--r-- | blob2xex.1 | 47 | ||||
| -rw-r--r-- | blob2xex.rst | 43 |
2 files changed, 87 insertions, 3 deletions
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BLOB2XEX" 1 "2024-04-24" "0.2.1" "Urchlay's Atari 8-bit Tools" +.TH "BLOB2XEX" 1 "2024-04-25" "0.2.1" "Urchlay's Atari 8-bit Tools" .SH NAME blob2xex \- Create Atari 8-bit executables from arbitrary data .\" RST source for blob2xex(1) man page. Convert with: @@ -96,8 +96,51 @@ Print usage message and exit. Print version number and exit. .UNINDENT .SH EXAMPLES +.SS Simple Example .sp -TODO: come up with a few examples. +You\(aqve written an Atari 8\-bit program that loads at \fB$2000\fP, which +is also the run address. The assembler you used doesn\(aqt create Atari +\&.xex files, so you\(aqve got a \fBprogram.bin\fP that\(aqs just raw object +code. To turn it into a runnable .xex file, use: +.INDENT 0.0 +.INDENT 3.5 +blob2xex program.xex \-l \(aq$2000\(aq \-r \(aq$2000\(aq program.bin +.UNINDENT +.UNINDENT +.sp +Notice the use of quotes around the addresses? That\(aqs because the +$ character must be quoted, or the shell will try to interpret it +as a variable reference. You could also have typed \fB$2000\fP or +\fB0x2000\fP\&. +.SS More Complex Example +.sp +Suppose you want to write a program that can run on an Atari 800, +but you want to use the International Character Set font from the +XL/XE machines. Also suppose that you have the XL ROM image as +\fIatarixl.rom\fP\&. +.sp +The way to use the XL ICS font on the 800 is to load it somewhere +in memory, on a 1K boundary. Suppose you\(aqve decided to load it at +\fB$8000\fP\&. +.sp +Any good reference book or other documentation on the Atari XL/XE +computers will tell you the ICS font is located at \fB$CC00\fP\&. The ROM +image starts at \fB$C000\fP (the start of XL/XE ROM), so the font is +located at offset \fB$0C00\fP within the ROM image. As always for Atari +fonts, it\(aqs 1KB, or \fB$0400\fP bytes. +.sp +So you can create a .xex file of the ROM font with: +.INDENT 0.0 +.INDENT 3.5 +blob2xex romfont.xex \-l 0x8000 \-o 0x0c00 \-s 0x0400 atarixl.rom +.UNINDENT +.UNINDENT +.sp +Since fonts aren\(aqt executable programs, there are no run (\fB\-r\fP) or +init (\fB\-i\fP) address options. +.sp +The resulting \fIromfont.xex\fP can be combined with the rest of your +program with \fBxexcat\fP(1). .SH COPYRIGHT .sp WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details. diff --git a/blob2xex.rst b/blob2xex.rst index 4166f64..3f80a0b 100644 --- a/blob2xex.rst +++ b/blob2xex.rst @@ -77,6 +77,47 @@ not **-l0x2000**. EXAMPLES ======== -TODO: come up with a few examples. +Simple Example +-------------- + +You've written an Atari 8-bit program that loads at **$2000**, which +is also the run address. The assembler you used doesn't create Atari +.xex files, so you've got a **program.bin** that's just raw object +code. To turn it into a runnable .xex file, use: + + blob2xex program.xex -l '$2000' -r '$2000' program.bin + +Notice the use of quotes around the addresses? That's because the +$ character must be quoted, or the shell will try to interpret it +as a variable reference. You could also have typed **\$2000** or +**0x2000**. + +More Complex Example +-------------------- + +Suppose you want to write a program that can run on an Atari 800, +but you want to use the International Character Set font from the +XL/XE machines. Also suppose that you have the XL ROM image as +*atarixl.rom*. + +The way to use the XL ICS font on the 800 is to load it somewhere +in memory, on a 1K boundary. Suppose you've decided to load it at +**$8000**. + +Any good reference book or other documentation on the Atari XL/XE +computers will tell you the ICS font is located at **$CC00**. The ROM +image starts at **$C000** (the start of XL/XE ROM), so the font is +located at offset **$0C00** within the ROM image. As always for Atari +fonts, it's 1KB, or **$0400** bytes. + +So you can create a .xex file of the ROM font with: + + blob2xex romfont.xex -l 0x8000 -o 0x0c00 -s 0x0400 atarixl.rom + +Since fonts aren't executable programs, there are no run (**-r**) or +init (**-i**) address options. + +The resulting *romfont.xex* can be combined with the rest of your +program with **xexcat**\(1). .. include:: manftr.rst |