From 2d50267bd87a1b616f8985b10242f69f71897357 Mon Sep 17 00:00:00 2001 From: Greg King Date: Sat, 7 Mar 2015 16:37:58 -0500 Subject: [PATCH] Added a second OSI C1P program file format. Unlike the first format, the new format is already loadable; it doesn't need to be converted. --- cfg/osic1p-asm.cfg | 18 +++-- cfg/osic1p.cfg | 26 ++++--- doc/intro.sgml | 121 +++++++++++++++++++++++---------- doc/osi.sgml | 77 +++++++++++++-------- libsrc/osic1p/bootstrap.s | 138 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 301 insertions(+), 79 deletions(-) create mode 100644 libsrc/osic1p/bootstrap.s diff --git a/cfg/osic1p-asm.cfg b/cfg/osic1p-asm.cfg index d37f17f88..d9f128f8a 100644 --- a/cfg/osic1p-asm.cfg +++ b/cfg/osic1p-asm.cfg @@ -2,19 +2,23 @@ FEATURES { STARTADDRESS: default = $0200; } SYMBOLS { +# Add "-u __BOOT__" to a command line if you want a file that can be loaded directly. +# __BOOT__: type = import; __STACKSIZE__: type = weak, value = $0400; # 1 kB stack __HIMEM__: type = weak, value = $8000; # 32 kB RAM } MEMORY { - # for size of ZP see runtime/zeropage.s and c1p/extzp.s + # for size of ZP, see runtime/zeropage.s and c1p/extzp.s ZP: file = "", define = yes, start = $0002, size = $001A + $0006; + HEAD: file = %O, start = $0000, size = $00AA; RAM: file = %O, define = yes, start = %S, size = __HIMEM__ - __STACKSIZE__ - %S; } SEGMENTS { - INIT: load = RAM, type = ro, define = yes, optional = yes; - CODE: load = RAM, type = rw; - RODATA: load = RAM, type = rw; - DATA: load = RAM, type = rw; - BSS: load = RAM, type = bss, define = yes; - ZEROPAGE: load = ZP, type = zp; + BOOT: load = HEAD, type = ro, optional = yes; + INIT: load = RAM, type = ro, define = yes, optional = yes; + CODE: load = RAM, type = rw; + RODATA: load = RAM, type = rw; + DATA: load = RAM, type = rw; + BSS: load = RAM, type = bss, define = yes; + ZEROPAGE: load = ZP, type = zp; } diff --git a/cfg/osic1p.cfg b/cfg/osic1p.cfg index 4771639a6..0ad2f8939 100644 --- a/cfg/osic1p.cfg +++ b/cfg/osic1p.cfg @@ -2,24 +2,28 @@ FEATURES { STARTADDRESS: default = $0200; } SYMBOLS { +# Add "-u __BOOT__" to a command line if you want a file that can be loaded directly. +# __BOOT__: type = import; __STACKSIZE__: type = weak, value = $0400; # 1 kB stack __HIMEM__: type = weak, value = $8000; # 32 kB RAM } MEMORY { - # for size of ZP see runtime/zeropage.s and c1p/extzp.s - ZP: file = "", define = yes, start = $0002, size = $001A + $0005; + # for size of ZP, see runtime/zeropage.s and c1p/extzp.s + ZP: file = "", define = yes, start = $0002, size = $001A + $0006; + HEAD: file = %O, start = $0000, size = $00AA; RAM: file = %O, define = yes, start = %S, size = __HIMEM__ - __STACKSIZE__ - %S; } SEGMENTS { - STARTUP: load = RAM, type = ro; - LOWCODE: load = RAM, type = ro, optional = yes; - INIT: load = RAM, type = ro, define = yes, optional = yes; - CODE: load = RAM, type = rw; - RODATA: load = RAM, type = rw; - DATA: load = RAM, type = rw; - BSS: load = RAM, type = bss, define = yes; - ZEROPAGE: load = ZP, type = zp; - EXTZP: load = ZP, type = rw, define = yes; + BOOT: load = HEAD, type = ro, optional = yes; + STARTUP: load = RAM, type = ro; + LOWCODE: load = RAM, type = ro, optional = yes; + INIT: load = RAM, type = ro, define = yes, optional = yes; + CODE: load = RAM, type = rw; + RODATA: load = RAM, type = rw; + DATA: load = RAM, type = rw; + BSS: load = RAM, type = bss, define = yes; + ZEROPAGE: load = ZP, type = zp; + EXTZP: load = ZP, type = zp, define = yes, optional = yes; } FEATURES { CONDES: type = constructor, diff --git a/doc/intro.sgml b/doc/intro.sgml index 10693aa4a..d92fd1d20 100644 --- a/doc/intro.sgml +++ b/doc/intro.sgml @@ -6,8 +6,9 @@ , , - -2015-2-27 +, + +2015-03-07 How to use the cc65 C language system -- an introduction. @@ -520,28 +521,18 @@ directory notePad. Look at the eight file-positions on each page until you see The output is shown in a GEOS dialog box; click Ohio Scientific Challenger 1P

-Available at : - -Emulates the Ohio Scientific Challenger 1P computer in different configurations. -The 32 kb RAM machine that must be used with the default compiler settings is -. - -In addition to cc65 the srec_cat program from the - -tool collection must be installed. Some Linux distributions also provide the -srecord package directly as an installable package. -The osic1p runtime library returns to the boot prompt when the -main() program exits. Therefore the C file in the tutorial must be slightly -modified in order to see the results on the screen. Otherwise the program -would print the text string and then jump to the boot prompt, making it +Ohio Scientific Challenger 1P

+The #include @@ -552,7 +543,7 @@ extern const char text[]; /* In text.s */ int main (void) { clrscr (); - cprintf ("%s\r\nPress \r\n", text); + cprintf ("%s\r\nPress .\r\n", text); cgetc (); return EXIT_SUCCESS; } @@ -560,35 +551,97 @@ int main (void) Compile the tutorial with + +cl65 -O -t osic1p -u __BOOT__ -o hello.lod hello.c text.s + + +The program is configured for a Challenger 1P computer with, at least, 32 kB +of RAM. See the for instructions about how to +compile for other RAM sizes. + +Plug a cassette player into your C1P computer; or, connect an RS-232 cable +between your C1P and a PC (set the PC's serial port to 300 Bits Per Second, +8 data bits, No parity, and 2 stop bits). (Turn on the computers.) + +Tap the " +Hello world! +Press . + + +(Stop the cassette player.) After hitting the RETURN key, you should see the +boot prompt again. + +WinOSI

+Available at : + +Emulates the Ohio Scientific Challenger computers in different configurations. +Configure it to emulate a C1P (model 600 board) with 32 kB of RAM. + +Compile the tutorial with the same command that is used to make the program +for a real machine. + +Start the emulator. Tap the " +Hello world! +Press . + + +After hitting the RETURN key, you should see the boot prompt again. + +C1Pjs

+Available at : + +Emulates the Ohio Scientific Challenger 1P computer in different configurations. +The 32 kB RAM machine that must be used with the default compiler settings is +. + +In addition to cc65, the +must be installed. Some Linux distributions also provide srecord directly as +an installable package. + +Compile the tutorial with this command line: + cl65 -O -t osic1p hello.c text.s -Convert the executable file into a text file that can be loaded via -the Ohio Scientific 65V PROM monitor at start address 0x200: +Convert the binary file into a text file that can be loaded via +the Ohio Scientific 65V PROM monitor, at start address 0x200: srec_cat hello -binary -offset 0x200 -o hello.c1p -Ohio_Scientific -execution-start-address=0x200 -Open the URL -and wait until the emulator has been loaded. Click on the "BREAK" -button to display the boot prompt, then press the "M" key to enter the -65V PROM monitor. Click the "Choose File" button and select the file "hello.c1p" -that was created as the output of the above invocation of the "srec_cat" -command. Press the "Load" button. You should see the following text on the -screen: +Open the URL that points to the 32 kB machine; and, wait until the emulator +has been loaded. Click on the " Hello world! -Press +Press . -After hitting the RETURN key you should see the boot prompt again. +After hitting the RETURN key, you should see the boot prompt again. -The program can also be uploaded over the serial port to a real Challenger 1P -computer with 32 kB RAM. See the for instructions how to -compile for other RAM sizes. Contributions wanted

diff --git a/doc/osi.sgml b/doc/osi.sgml index e360daf7a..0167b2bd1 100644 --- a/doc/osi.sgml +++ b/doc/osi.sgml @@ -4,8 +4,9 @@ Ohio Scientific-specific information for cc65 <author> -<url url="mailto:stephan.muehlstrasser@web.de" name="Stephan Mühlstrasser"><newline> -<date>2015-02-04 +<url url="mailto:stephan.muehlstrasser@web.de" name="Stephan Mühlstrasser">,<newline> +<url url="mailto:greg.king5@verizon.net" name="Greg King"> +<date>2015-03-07 <abstract> An overview over the Ohio Scientific runtime system as it is implemented for the cc65 C @@ -34,42 +35,63 @@ information. Currently the target "osic1p" is implemented. This works for the Ohio Scientific Challenger 1P machine. -<sect>Binary format<p> +<sect>Program file formats<p> -The standard binary output format generated by the linker for the osic1p target -is a machine language program.<p> +<descrip> + <tag/Binary, then text/ + The standard binary output format generated by the linker for the osic1p + target is a pure machine language program. + + For uploading into a real machine over its serial port or into an emulator, + that program must be converted into a text file that can be understood by + the 65V PROM monitor. For that purpose, the <bf/srec_cat/ program from <url + url="http://srecord.sourceforge.net/" name="the SRecord tool collection"> + can be used. + + Care must be taken that the <tt/-offset/ and <tt/-execution-start-address/ + options for the <bf/srec_cat/ program correspond to the start address + of the executable. + + Example for converting an executable "hello" file that was built for the + default start address $0200 to an uploadable file "hello.c1p": -For uploading into a real machine over the serial port or into an emulator a -program must be converted to a text file that is understood by the 65V PROM -monitor. For this purpose the srec_cat program from the -<url url="http://srecord.sourceforge.net/" name="SRecord"> -tool collection can be used. + <tscreen><verb> + srec_cat hello -bin -of 0x200 -o hello.c1p -os -esa=0x200 + </verb></tscreen> -Care must be taken that the -offset and -execution-start-address options for the srec_cat -program correspond to the start address of the executable. + <tag/Hybrid/ + The linker can create an alternate format that contains two parts: + <enum> + <item>A text header that is understood by the 65V PROM monitor. + It is a boot loader that reads the second part. + <item>The default binary code that is described above. + </enum> -Example for converting an executable "hello" that was built for the default -start address $0200 to an uploadable file "hello.c1p": + You can make the alternate format by adding the option <tt/-u __BOOT__/ to + <tt/cl65/'s or <tt/ld65/'s command lines. -<tscreen> -srec_cat hello -binary -offset 0x200 -o hello.c1p -Ohio_Scientific -execution-start-address=0x200 -</tscreen> + This format doesn't need to be converted. It is smaller than the text-only + format. But, it cannot be loaded by <url + url="http://www.pcjs.org/docs/c1pjs/" name="C1Pjs">; you must use the + SRecord-produced text-only format with that emulator. + +</descrip> <sect>Memory layout<p> By default programs compiled for the osic1p target are configured for 32 kB RAM. -The RAM size can be configured via the symbol __HIMEM__. +The RAM size can be configured via the symbol <tt/__HIMEM__/. Special locations: <descrip> <tag/Program start address/ The default start address is $0200. The start address is configurable - via the compiler option --start-addr. + via the linker option <tt/--start-addr/. <tag/Stack/ The C runtime stack is located at the top of RAM and growing downwards. - The size is configurable via the symbol __STACKSIZE__. The default + The size is configurable via the symbol <tt/__STACKSIZE__/. The default stack size is $0400. <tag/Heap/ @@ -77,7 +99,7 @@ Special locations: runtime stack. <tag/Video RAM/ - The 1 kB video RAM is located at $D000. On the monitor only a subset + The 1 kB video RAM is located at $D000. On the monitor, only a subset of the available video RAM is visible. The address of the upper left corner of the visible area is $D085 and corresponds to conio cursor position (0, 0). @@ -87,9 +109,9 @@ Special locations: Example for building a program with start address $0300, stack size $0200 and RAM size $2000: -<tscreen> +<tscreen><verb> cl65 --start-addr 0x300 -Wl -D,__HIMEM__=$2000,-D,__STACKSIZE__=$0200 -t osic1p hello.c -</tscreen> +</verb></tscreen> <sect>Linker configurations<p> @@ -112,16 +134,17 @@ To use this config file, assemble with <tt/-t osic1p/ and link with is used, while the latter supplies the actual config. When using <tt/cl65/, use both command line options. -Sample command line for <tt/cl65/: +Sample command lines for <tt/cl65/: <tscreen><verb> -cl65 -o program -t osic1p -C osic1p-asm.cfg source.s +cl65 -t osic1p -C osic1p-asm.cfg -o program source.s +cl65 -t osic1p -C osic1p-asm.cfg -u __BOOT__ -o program.lod source.s </verb></tscreen> <sect>Platform-specific header files<p> -Programs containing Ohio Scientific-specific code may use the <tt/osic1p.h/ -header file. +Programs containing Ohio Scientific-specific code may use the <tt/osic1p.h/ +header file. <sect1>Ohio Scientific-specific functions<p> diff --git a/libsrc/osic1p/bootstrap.s b/libsrc/osic1p/bootstrap.s new file mode 100644 index 000000000..298de8f73 --- /dev/null +++ b/libsrc/osic1p/bootstrap.s @@ -0,0 +1,138 @@ +; +; 2015-03-06, Greg King +; + +; When you want to create a program with the alternate file format, +; add "-u __BOOT__" to the cl65/ld65 command line. Then, the linker +; will import this symbol name; and, link this module at the front +; of your program file. +; + .export __BOOT__:abs = 1 + + .import __RAM_START__, __RAM_SIZE__, __BSS_RUN__ + +; ------------------------------------------------------------------------ + +load_addr := __RAM_START__ +load_size = __BSS_RUN__ - __RAM_START__ +ram_top := __RAM_START__ + __RAM_SIZE__ + + .segment "BOOT" + +.ifdef ASM + + .include "osic1p.inc" + .macpack generic + +load := $08 ; private variables +count := $0A + +GETCHAR := $FFBF ; gets one character from ACIA + +FIRSTVISC = $85 ; Offset of first visible character in video RAM +LINEDIST = $20 ; Offset in video RAM between two lines + + lda #<load_addr + ldx #>load_addr + tay + stx load+1 + lda #<load_size + eor #$FF + sta count ; store (-size - 1) + lda #>load_size + eor #$FF + sta count+1 + +L1: inc count ; pre-count one's-complement upwards + bnz L2 + inc count+1 + bze L3 +L2: jsr GETCHAR ; (doesn't change .Y) + sta (load),y + +; Show that the file is being loaded by rotating an arrow on the screen. +; + tya + lsr a + lsr a + and #8 - 1 + ora #$10 ; eight arrow characters + sta SCRNBASE + FIRSTVISC + 2 * LINEDIST + 11 + + iny + bnz L1 + inc load+1 + bnz L1 ; branch always + +L3: jmp load_addr + +.else + +.mac hex1 h + .lobytes ((h) & $0F) + (((h) & $0F) > 9) * 7 + '0' +.endmac + +.mac hex2 h + hex1 (h) >> 4 + hex1 (h) >> 0 +.endmac + +.mac hex4 h + hex2 >(h) + hex2 <(h) +.endmac + +CR = $0D + + .byte CR, CR + .byte "." ; set an address + hex4 ram_top ; put loader where stack will sit + .byte "/" ; write bytes into RAM + +; ASCII-coded hexadecimal translation of the above assembly code. +; It was copied from the assembler listing. + + .byte "A9", CR + hex2 <load_addr + .byte CR, "A2", CR + hex2 >load_addr + .byte CR, "A8", CR + .byte "86", CR, "09", CR + .byte "A9", CR + hex2 <load_size + .byte CR, "49", CR, "FF", CR + .byte "85", CR, "0A", CR + .byte "A9", CR + hex2 >load_size + .byte CR, "49", CR, "FF", CR + .byte "85", CR, "0B", CR + + .byte "E6", CR, "0A", CR + .byte "D0", CR, "04", CR + .byte "E6", CR, "0B", CR + .byte "F0", CR, "16", CR + .byte "20", CR, "BF", CR, "FF", CR + .byte "91", CR, "08", CR + + .byte "98", CR + .byte "4A", CR + .byte "4A", CR + .byte "29", CR, "07", CR + .byte "09", CR, "10", CR + .byte "8D", CR, "D0", CR, "D0", CR + + .byte "C8", CR + .byte "D0", CR, "E6", CR + .byte "E6", CR, "09", CR + .byte "D0", CR, "E2", CR + + .byte "4C", CR + hex2 <load_addr + .byte CR + hex2 >load_addr + + .byte CR, "." + hex4 ram_top + .byte "G" ; go to address + +.endif -- 2.39.5