Updated Protovision Shop URL.

[cc65] / doc / intro.sgml

diff --git a/doc/intro.sgml b/doc/intro.sgml
index 5ffef7e6905139a938fe8a03cf922759222da412..d92fd1d20f2216d48338a9137a0a93c2a4e4b07d 100644 (file)
--- a/doc/intro.sgml
+++ b/doc/intro.sgml
@@ -6,8 +6,9 @@
 <author>
 <url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
 <url url="mailto:cbmnut@hushmail.com" name="CbmNut">,<newline>
 <author>
 <url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
 <url url="mailto:cbmnut@hushmail.com" name="CbmNut">,<newline>

-<url url="mailto:greg.king5@verizon.net" name="Greg King">
-<date>2014-4-24
+<url url="mailto:greg.king5@verizon.net" name="Greg King">,<newline>
+<url url="mailto:stephan.muehlstrasser@web.de" name="Stephan M&uuml;hlstrasser">
+<date>2015-03-07

 
 <abstract>
 How to use the cc65 C language system -- an introduction.
 
 <abstract>
 How to use the cc65 C language system -- an introduction.


@@ -342,8 +343,8 @@ Available at <url
 url="http://code.google.com/p/oriculator/">:
 
 Emulates Oric-1 and Atmos computers, with sound, disk images,
 url="http://code.google.com/p/oriculator/">:
 
 Emulates Oric-1 and Atmos computers, with sound, disk images,

-scanline-exact NTSC/PAL video, and movie export. Includes monitor.
-Fortunately for all SDL platforms. You will just need the emulator, all
+scanline-exact NTSC/PAL video, and movie export. Includes a monitor.
+Fortunately, for all SDL platforms. You will need just the emulator; all

 ROMs are supplied.
 
 Compile the tutorial with
 ROMs are supplied.
 
 Compile the tutorial with


@@ -353,8 +354,11 @@ cl65 -O -t atmos hello.c text.s -o hello.tap
 </verb></tscreen>
 
 Start the emulator, choose <bf/F1/ and <bf/Insert tape.../, and point to
 </verb></tscreen>
 
 Start the emulator, choose <bf/F1/ and <bf/Insert tape.../, and point to

-the "<bf/hello.tap/" executable. The file has an auto start header meant to
-be loaded directly from tape.
+the "<bf/hello.tap/" executable. After it has finished loading, type
+
+<tscreen><verb>
+RUN
+</verb></tscreen>

 
 On a real Atmos, you would need a tape drive.
 Turn on the computer, type
 
 On a real Atmos, you would need a tape drive.
 Turn on the computer, type


@@ -363,7 +367,11 @@ Turn on the computer, type
 CLOAD""
 </verb></tscreen>
 
 CLOAD""
 </verb></tscreen>
 

-at the BASIC prompt.
+at the BASIC prompt. After it has finished loading, type
+
+<tscreen><verb>
+RUN
+</verb></tscreen>

 
 The emulation, also, supports that method.
 
 
 The emulation, also, supports that method.
 


@@ -513,31 +521,20 @@ directory notePad.  Look at the eight file-positions on each page until you see
 The output is shown in a GEOS dialog box; click <bf/OK/ when you have finished
 reading it.
 
 The output is shown in a GEOS dialog box; click <bf/OK/ when you have finished
 reading it.
 

-<sect1>Ohio Scientific Challenger 1P<p>
-Available at <url url="http://www.pcjs.org/docs/c1pjs/" name="C1Pjs">:
-
-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
-<url url="http://www.pcjs.org/devices/c1p/machine/32kb/" name="here">.

 
 

-In addition the srec_cat program from the
-<url url="http://srecord.sourceforge.net/" name="SRecord">
-tool collection must be installed. Some Linux distributions also provide the
-srecord package that can be installed directly from the distribution's
-repository.
-
-The osic1p runtime library directly 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
+<sect1>Ohio Scientific Challenger 1P<p>
+The <tt/osic1p/ runtime library returns to the boot prompt when the main()
+program exits. Therefore, the C file in the tutorial must be modified
+slightly, 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

 impossible to see the results of running the tutorial program.
 
 impossible to see the results of running the tutorial program.
 

-In addition to that the cc65 target does not yet have support for stdio
+In addition to that, the <tt/osic1p/ target does not yet have support for stdio

 functions. Only the functions from the conio library are available.
 
 functions. Only the functions from the conio library are available.
 

-Therefore modify the main() function in hello.c as follows:
+Therefore, modify the "<tt/hello.c/" source file, as follows:

 
 

-<tscreen>
+<tscreen><code>

 #include <conio.h>
 #include <stdlib.h>
 
 #include <conio.h>
 #include <stdlib.h>
 


@@ -545,43 +542,106 @@ extern const char text[];       /* In text.s */
 
 int main (void)
 {
 
 int main (void)
 {

-    clrscr();
-    cprintf ("%s\r\nPress <RETURN>\r\n", text);
-    cgetc();
+    clrscr ();
+    cprintf ("%s\r\nPress <RETURN>.\r\n", text);
+    cgetc ();

     return EXIT_SUCCESS;
 }
     return EXIT_SUCCESS;
 }

-</tscreen>
+</code></tscreen>

 
 Compile the tutorial with
 
 
 Compile the tutorial with
 

+<tscreen><verb>
+cl65 -O -t osic1p -u __BOOT__ -o hello.lod hello.c text.s
+</verb></tscreen>
+
+The program is configured for a Challenger 1P computer with, at least, 32 kB
+of RAM. See the <url url="osi.html"
+name="Ohio Scientifc-specific documentation"> 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 "<bf/BREAK/" key, to display the boot prompt; then, tap the "<tt/M/"
+key, to enter the 65V PROM monitor. Tap the "<tt/L/" key. Either start the
+cassette player (with a tape of the program), or start a transfer of the
+program file "<tt/hello.lod/" from the PC. After a while, you should see the
+following text on the screen:
+
+<tscreen><verb>
+Hello world!
+Press <RETURN>.
+</verb></tscreen>
+
+(Stop the cassette player.) After hitting the RETURN key, you should see the
+boot prompt again.
+
+<sect2>WinOSI<p>
+Available at <url
+url="http://osi.marks-lab.com/#Emulator">:
+
+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 "<tt/M/" key, to enter the 65V PROM monitor; then,
+tap the "<tt/L/" key. If you had configured WinOSI to ask for a file when it
+starts to read data from the serial port, then you will see a file dialog box;
+otherwise, you must tap your host keyboard's F10 function key. Select the file
+"<tt/hello.lod/". After a moment, you should see the following text on the
+screen:
+
+<tscreen><verb>
+Hello world!
+Press <RETURN>.
+</verb></tscreen>
+
+After hitting the RETURN key, you should see the boot prompt again.
+
+<sect2>C1Pjs<p>
+Available at <url
+url="http://www.pcjs.org/docs/c1pjs/">:
+
+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
+<url url="http://www.pcjs.org/devices/c1p/machine/32kb/" name="here">.
+
+In addition to cc65, the <bf/srec_cat/ program from <url
+url="http://srecord.sourceforge.net/" name="the SRecord tool collection">
+must be installed. Some Linux distributions also provide srecord directly as
+an installable package.
+
+Compile the tutorial with this command line:
+

 <tscreen><verb>
 cl65 -O -t osic1p hello.c text.s
 </verb></tscreen>
 
 <tscreen><verb>
 cl65 -O -t osic1p hello.c text.s
 </verb></tscreen>
 

-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:

 
 <tscreen><verb>
 srec_cat hello -binary -offset 0x200 -o hello.c1p -Ohio_Scientific -execution-start-address=0x200
 </verb></tscreen>
 
 
 <tscreen><verb>
 srec_cat hello -binary -offset 0x200 -o hello.c1p -Ohio_Scientific -execution-start-address=0x200
 </verb></tscreen>
 

-Open the URL <url url="http://www.pcjs.org/devices/c1p/machine/32kb/" name="http://www.pcjs.org/devices/c1p/machine/32kb/">
-in your browser and wait until the emulator is loaded. Click on the BREAK
-button to display the boot prompt, then press the M key to enter the
-65V PROM monitor. Press the "Choose File" button and select the 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 "<bf/BREAK/" button to display the boot prompt;
+then, press the "<tt/M/" key to enter the 65V PROM monitor. Click the
+"<bf/Browse.../" button; and, select the file "<tt/hello.c1p/" that was
+created as the output of the above invocation of the "<tt/srec_cat/" command.
+Press the "<bf/Load/" button. You should see the following text on the screen:

 
 <tscreen><verb>
 Hello world!
 
 <tscreen><verb>
 Hello world!

-Press <RETURN>
+Press <RETURN>.

 </verb></tscreen>
 
 </verb></tscreen>
 

-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.

 
 <sect1>Contributions wanted<p>
 
 
 <sect1>Contributions wanted<p>