From e5171df3d18521393a0d592f9b20237417e3ec45 Mon Sep 17 00:00:00 2001 From: Christopher Mosher Date: Fri, 20 Apr 2012 20:44:14 -0400 Subject: [PATCH] initial import docs, from epple2web subversion project --- doc/80x15.png | Bin 0 -> 697 bytes doc/Makefile | 19 + doc/applesplit.png | Bin 0 -> 1788 bytes doc/building.asciidoc | 128 ++ doc/callouts/1.png | Bin 0 -> 329 bytes doc/callouts/10.png | Bin 0 -> 361 bytes doc/callouts/11.png | Bin 0 -> 565 bytes doc/callouts/12.png | Bin 0 -> 617 bytes doc/callouts/13.png | Bin 0 -> 623 bytes doc/callouts/14.png | Bin 0 -> 411 bytes doc/callouts/15.png | Bin 0 -> 640 bytes doc/callouts/2.png | Bin 0 -> 353 bytes doc/callouts/3.png | Bin 0 -> 350 bytes doc/callouts/4.png | Bin 0 -> 345 bytes doc/callouts/5.png | Bin 0 -> 348 bytes doc/callouts/6.png | Bin 0 -> 355 bytes doc/callouts/7.png | Bin 0 -> 344 bytes doc/callouts/8.png | Bin 0 -> 357 bytes doc/callouts/9.png | Bin 0 -> 357 bytes doc/cards.asciidoc | 263 ++++ doc/cassette.asciidoc | 188 +++ doc/commands.asciidoc | 202 ++++ doc/configuration.asciidoc | 63 + doc/debian.png | Bin 0 -> 552 bytes doc/deploy/80x15.png | Bin 0 -> 697 bytes doc/deploy/applesplit.png | Bin 0 -> 1788 bytes doc/deploy/callouts/1.png | Bin 0 -> 329 bytes doc/deploy/callouts/10.png | Bin 0 -> 361 bytes doc/deploy/callouts/11.png | Bin 0 -> 565 bytes doc/deploy/callouts/12.png | Bin 0 -> 617 bytes doc/deploy/callouts/13.png | Bin 0 -> 623 bytes doc/deploy/callouts/14.png | Bin 0 -> 411 bytes doc/deploy/callouts/15.png | Bin 0 -> 640 bytes doc/deploy/callouts/2.png | Bin 0 -> 353 bytes doc/deploy/callouts/3.png | Bin 0 -> 350 bytes doc/deploy/callouts/4.png | Bin 0 -> 345 bytes doc/deploy/callouts/5.png | Bin 0 -> 348 bytes doc/deploy/callouts/6.png | Bin 0 -> 355 bytes doc/deploy/callouts/7.png | Bin 0 -> 344 bytes doc/deploy/callouts/8.png | Bin 0 -> 357 bytes doc/deploy/callouts/9.png | Bin 0 -> 357 bytes doc/deploy/debian.png | Bin 0 -> 552 bytes doc/deploy/dos310rev0.png | Bin 0 -> 3170 bytes doc/deploy/dos330boot.png | Bin 0 -> 1992 bytes doc/deploy/epple2logo.png | Bin 0 -> 605 bytes doc/deploy/gplv3logo.png | Bin 0 -> 2986 bytes doc/deploy/index.html | 2325 ++++++++++++++++++++++++++++++++++++ doc/deploy/make.png | Bin 0 -> 273 bytes doc/deploy/note.png | Bin 0 -> 2494 bytes doc/deploy/pinkmystery.png | Bin 0 -> 1722 bytes doc/deploy/prodos.png | Bin 0 -> 1768 bytes doc/deploy/redhat.png | Bin 0 -> 1692 bytes doc/deploy/splitcolors.png | Bin 0 -> 2100 bytes doc/deploy/tip.png | Bin 0 -> 2718 bytes doc/deploy/warning.png | Bin 0 -> 3214 bytes doc/deploy/windows.gif | Bin 0 -> 1543 bytes doc/display.asciidoc | 83 ++ doc/dos310rev0.png | Bin 0 -> 3170 bytes doc/dos330boot.png | Bin 0 -> 1992 bytes doc/download.asciidoc | 75 ++ doc/epple2logo.png | Bin 0 -> 605 bytes doc/gplv3logo.png | Bin 0 -> 2986 bytes doc/index.asciidoc | 61 + doc/index.html | 2325 ++++++++++++++++++++++++++++++++++++ doc/keyboard.asciidoc | 61 + doc/make.png | Bin 0 -> 273 bytes doc/note.png | Bin 0 -> 2494 bytes doc/overview.asciidoc | 6 + doc/paddles.asciidoc | 12 + doc/pinkmystery.png | Bin 0 -> 1722 bytes doc/prodos.png | Bin 0 -> 1768 bytes doc/redhat.png | Bin 0 -> 1692 bytes doc/screenshots.asciidoc | 173 +++ doc/speaker.asciidoc | 9 + doc/splitcolors.png | Bin 0 -> 2100 bytes doc/tip.png | Bin 0 -> 2718 bytes doc/usermanual.asciidoc | 17 + doc/warning.png | Bin 0 -> 3214 bytes doc/windows.gif | Bin 0 -> 1543 bytes 79 files changed, 6010 insertions(+) create mode 100644 doc/80x15.png create mode 100644 doc/Makefile create mode 100644 doc/applesplit.png create mode 100644 doc/building.asciidoc create mode 100644 doc/callouts/1.png create mode 100644 doc/callouts/10.png create mode 100644 doc/callouts/11.png create mode 100644 doc/callouts/12.png create mode 100644 doc/callouts/13.png create mode 100644 doc/callouts/14.png create mode 100644 doc/callouts/15.png create mode 100644 doc/callouts/2.png create mode 100644 doc/callouts/3.png create mode 100644 doc/callouts/4.png create mode 100644 doc/callouts/5.png create mode 100644 doc/callouts/6.png create mode 100644 doc/callouts/7.png create mode 100644 doc/callouts/8.png create mode 100644 doc/callouts/9.png create mode 100644 doc/cards.asciidoc create mode 100644 doc/cassette.asciidoc create mode 100644 doc/commands.asciidoc create mode 100644 doc/configuration.asciidoc create mode 100644 doc/debian.png create mode 100644 doc/deploy/80x15.png create mode 100644 doc/deploy/applesplit.png create mode 100644 doc/deploy/callouts/1.png create mode 100644 doc/deploy/callouts/10.png create mode 100644 doc/deploy/callouts/11.png create mode 100644 doc/deploy/callouts/12.png create mode 100644 doc/deploy/callouts/13.png create mode 100644 doc/deploy/callouts/14.png create mode 100644 doc/deploy/callouts/15.png create mode 100644 doc/deploy/callouts/2.png create mode 100644 doc/deploy/callouts/3.png create mode 100644 doc/deploy/callouts/4.png create mode 100644 doc/deploy/callouts/5.png create mode 100644 doc/deploy/callouts/6.png create mode 100644 doc/deploy/callouts/7.png create mode 100644 doc/deploy/callouts/8.png create mode 100644 doc/deploy/callouts/9.png create mode 100644 doc/deploy/debian.png create mode 100644 doc/deploy/dos310rev0.png create mode 100644 doc/deploy/dos330boot.png create mode 100644 doc/deploy/epple2logo.png create mode 100644 doc/deploy/gplv3logo.png create mode 100644 doc/deploy/index.html create mode 100644 doc/deploy/make.png create mode 100644 doc/deploy/note.png create mode 100644 doc/deploy/pinkmystery.png create mode 100644 doc/deploy/prodos.png create mode 100644 doc/deploy/redhat.png create mode 100644 doc/deploy/splitcolors.png create mode 100644 doc/deploy/tip.png create mode 100644 doc/deploy/warning.png create mode 100644 doc/deploy/windows.gif create mode 100644 doc/display.asciidoc create mode 100644 doc/dos310rev0.png create mode 100644 doc/dos330boot.png create mode 100644 doc/download.asciidoc create mode 100644 doc/epple2logo.png create mode 100644 doc/gplv3logo.png create mode 100644 doc/index.asciidoc create mode 100644 doc/index.html create mode 100644 doc/keyboard.asciidoc create mode 100644 doc/make.png create mode 100644 doc/note.png create mode 100644 doc/overview.asciidoc create mode 100644 doc/paddles.asciidoc create mode 100644 doc/pinkmystery.png create mode 100644 doc/prodos.png create mode 100644 doc/redhat.png create mode 100644 doc/screenshots.asciidoc create mode 100644 doc/speaker.asciidoc create mode 100644 doc/splitcolors.png create mode 100644 doc/tip.png create mode 100644 doc/usermanual.asciidoc create mode 100644 doc/warning.png create mode 100644 doc/windows.gif diff --git a/doc/80x15.png b/doc/80x15.png new file mode 100644 index 0000000000000000000000000000000000000000..ed028fed9d6154b10bf73872ea925a9603a352ae GIT binary patch literal 697 zcmV;q0!ICbP)IS55s3f)|36ZE3j`1kui3O3Sz^zwy)&oI?C9tyFE7W`=IZKt>eQ*W?pARLaUfS- zR>9TD_2Y++gWR`3Zvy?xgemdz#mnW3m*es+5bWN)+sw>ta{m+v_ru2zg$0E}C6cjt zc=?hQ!otG1d8z{RS#dfcqu(S9mqI)_N=n9GB6nc z)A0NE?|~$c4HN;28yg$DxVT)qdJSp{6BCe&mVO`r&PA5On%*$k$R^-QrD(PgERUEl ze0%xxr_VtD0NG(-VL%4Z2q4+n*$MRLyLaz^F@NvgJ)kU5@XqZ!@Kg;<? z1Gzvy1H~&UDrU`^g%&65>>U69{Kpf+*lP$_Fe_H@*|00^!fe!_wi^0hKPxYNpxIvK(IfMD=RJ6+|ayr%hn-T4@bvEy?y%z7^QeLmz9;N zs47Ez%g-mUW6O>~?pu7-60rT0nweTzS=rv+j#ZD7v(xqK*9%Gt;OV)4LjP!6dXToI fM_Olz0U*EtDwt)|Le?|v00000NkvXXu0mjf&ay*> literal 0 HcmV?d00001 diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..af6c27d --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,19 @@ +.SUFFIXES: .asciidoc .html + +.asciidoc.html : + asciidoc -b html5 $< + +all : doc + +doc : index.html + +clean : + rm -f index.html + +install : + mkdir -p deploy + cp *.html *.png *.gif deploy + cp -R callouts deploy + +uninstall : + rm -Rf deploy diff --git a/doc/applesplit.png b/doc/applesplit.png new file mode 100644 index 0000000000000000000000000000000000000000..5c6f85a3acf985d4d3d166b2c8ef0fe3551d2874 GIT binary patch literal 1788 zcmbtUYc$kp7=OoKBaF#$8pb7}L}hZX85*~hOB{qSv=uH!E5f6RTK%9L95ja_l!1>$b4Q?7RF`$laOwYB6plxvCjX`@&EGvYtNvh@nr`D?$IxEXC7~D zbAHwoC`?mMo_ebtyoW5v$Xnpjy_Ui^Pu^*AeYd+&Qvex}M*w9gb$WqvxpiU%ij51K zMv65BHi6#lhzv2WPMX2-OH`-PRca-4^Ka8aFwC+f_8zBfC6=6)ADGW5otd&l)K)me(3a=c|1 zN7OKNzY}U$Sqfw9h}2oM;Vm)|Tl{cvUC4b1l1igifLrZ8AwQv19W6e`*YFMQG0Qx;j)3Q`>~{4r8#Qh$7CaDcgaPnB>1m1%zZ z*&az&-EOQ>4Y4edXRZ&S>rts3L8$ z2T7s4#FJ%RT+4#l;a*IVStxGjv+cWo;!!$h5N7OtZqp?|(7^j?P_6i(&^1FsfwqC|c$S*j z{R16dOT0ZrSM7}{EqcliU+!RZo>GS>l1!Somqypg3Z&xUwV#%_@(iD6Avk#NzFGy7 zP7bvgmWb&ft+aJDwu#YM@p)Hk&3uk{;mTm&rO}dzN#Z%H zcx&Ty52v}p`S-t?w%4tQA{!|R6)Tru(>c)6$q2cQxFES~CgapSG#ftk zV=;mIu1Giov$;!JtrvIZnLc&44aDL +cd +mkdir epple2 +cd epple2 +wget http://mosher.mine.nu/epple2/download/epple2-latest.tar.gz # <2> +tar xzvf epple2-1.0.tar.gz +mkdir build # <3> +cd build +../epple2-1.0/configure # <4> +make # <5> +sudo make install # <6> +--------------------------------------------------- +<1> Install dependencies: gcc, make, SDL +<2> Retrieve the latest Epple ][ source distribution +<3> Use this directory for a VPATH-style build +<4> Run one-time configuration script for your system. Use +--help+ for more information. +<5> Compile and link. Program will be +src/epple2+ +<6> Install into standard system directories + + + +=== Windows/MSYS Example + +==== Install MinGW/MSYS + +Install MSYS into +C:\msys\+ + +Install MinGW into +C:\msys\mingw\+ + +For more information on MinGW and MSYS, see http://www.mingw.org/[]. + +==== Install SDL + +At http://www.libsdl.org/[] find the download page. +Download the ``Development Libraries'' for Win32/mingw, for example: + ++SDL-devel-1.2.13-mingw32.tar.gz+ (Mingw32) + +and save it to your MSYS home directory (for example, +C:\msys\home\Administrator+). +Run MSYS, and at the bash prompt, go to your home directory and +untar the SDL archive to your home directory: + +[source,sh] +-------- +$ cd +$ tar xzvf SDL-devel-1.2.13-mingw32.tar.gz +-------- + +Then follow the instructions to install SDL, for example: + +[source,sh] +-------- +$ cd SDL-1.2.13 +$ make native +-------- + +==== Untar Epple ][ Source + +Download the Epple ][ Source Distribution +and save it to your MSYS home directory (for example, +C:\msys\home\Administrator+). +Run MSYS, and at the bash prompt, go to your home directory and +untar the epple2 source distribution tar file. For example: + +[source,sh] +-------- +$ cd +$ tar xzvf epple2-1.0.tar.gz +-------- + +==== Build Epple ][ + +Then build as follows. I recommend doing a VPATH build, +where you build into a different directory than the source +directory. To accomplish this, create a new directory for +building, somewhere, such as: + +[source,sh] +-------- +$ cd +$ mkdir buildepple2 +$ cd buildepple2 +-------- + +Then run +configure+ from there. For the MSYS build to work, +you need some extra parameters to the build, and you could +also add some compiler options to optimize the build. For +example (from the +buildepple2+ directory you just created): + +[source,sh] +-------- +$ ~/epple2/configure --prefix= \ +CXXFLAGS="-I/usr/include -O4 -msse3" \ +CFLAGS="-I/usr/include" \ +LDFLAGS="-L/usr/lib -mconsole -mthreads -mno-cygwin" +$ make +-------- + +If all goes well, it will build without any errors. +If you get errors about not finding +SDL.h+, make sure +SDL is installed, and make sure the configure command +is correct. (If you just run configure without the +options shown above, you will get this error at build time.) +The result of the build (on Windows platform) is + ++installer/epple2.msi+ + +which is an installable file for Windows. To install +epple2, just double-click on this file from Explorer. diff --git a/doc/callouts/1.png b/doc/callouts/1.png new file mode 100644 index 0000000000000000000000000000000000000000..7d473430b7bec514f7de12f5769fe7c5859e8c5d GIT binary patch literal 329 zcmeAS@N?(olHy`uVBq!ia0vp^JRr;gBp8b2n5}^nQC}X^4DKU-G|w_t}fLBA)Suv#nrW z!^h2QnY_`l!BOq-UXEX{m2up>JTQkX)2m zTvF+fTUlI^nXH#utd~++ke^qgmzgTe~DWM4ffP81J literal 0 HcmV?d00001 diff --git a/doc/callouts/10.png b/doc/callouts/10.png new file mode 100644 index 0000000000000000000000000000000000000000..997bbc8246a316e040e0804174ba260e219d7d33 GIT binary patch literal 361 zcmeAS@N?(olHy`uVBq!ia0vp^JRr;gBp8b2n5}^nQWtZ~+OvdJMW|Y+^UT?O-M{rKJsmzxdayJ{ zDCQA!%%@7Jj$q%-wf8e0_jRx8Dqi$}^?K=?6FriQFLv>>oc^CE+aVHhW3=nZ+fQ4!M=ZC7H>3sl|FJr3LwU zC3?yExf6FO?f@F61vV}-Juk7O6lk8Yg;}bFaZ-|HQc7Azopr01?u8M*si- literal 0 HcmV?d00001 diff --git a/doc/callouts/11.png b/doc/callouts/11.png new file mode 100644 index 0000000000000000000000000000000000000000..ce47dac3f52ac49017749a3fea53db57d006993c GIT binary patch literal 565 zcmeAS@N?(olHy`uVBq!ia0vp^JRr=$1SD^YpWXnZI14-?iy0V%N{XE z)7O>#600DeuDZ?5tOl@ql94%{~0TwC?8m~C^ZqJRG}m@H-L1 z5L@scq?{XUcxG{OP9jig5ySQaTl#^*93bKF#G<^+ymW>G($Cs~V(bw8rA5i93}62@ zzlJGu&d<$F%`0K}c4pdspcorSSx9C{PAbEScbC)|7#JBmT^vIy=9KoYUDZ+`aP)jU z&ny=ErrK^#Gw!AcR}pdfMERuV^@&0$@(#^6b8c@rn^6RWX3pUb z4*6@PZ+H0#u=rjsXzS?6n6*sBGbHqGTU%mCsH?n#%j;eD^2}qe=iX*J@VQ3BRpz+u z{PX#N(^9X${`$90+;!pWs>o@z_n8G)7Uo7PJz`jrS+)QE@=PWHmc~UIw=WmUe73o7 z>^bR(M752aYoNg~ozu7U7&{(U>{s!;bn#f?ItjL^o`e{*EOQHqO;ccnz9hLK5@2cAyw@AaPFL~Cp#02|E|4xeQteNtB7waMs QVCXP-y85}Sb4q9e0GRUFb^rhX literal 0 HcmV?d00001 diff --git a/doc/callouts/12.png b/doc/callouts/12.png new file mode 100644 index 0000000000000000000000000000000000000000..31daf4e2f25b6712499ee32de9c2e3b050b691ca GIT binary patch literal 617 zcmeAS@N?(olHy`uVBq!ia0vp^JRr=$1SD^YpWXnZI14-?iy0V%N{XE z)7O>#600De9$%>2LVd81Yeb1-X-P(Y5yQ%LXFPyHJS9LOm(=3qqRfJl%=|nCVNOM5 zpg0#u+&RCXvM4h>ql94%{~0TwC?8m~C^ZqJRG}m@H-L1 z5L@scq?{XUcxG{OP9jig5ySQaTl#^*93bKF#G<^+ymW>G($Cs~V(bw8rA5i93}62@ zzlJGu&d<$F%`0K}c4pdspcorSSx9C{PAbEScbC)|7#JBmT^vIy=Cn>wTzx1(qV@bS z0hYvspf(--lM>otrqbK$7p{3DzJ|+KN8%5ows)AI?zWk_n>jwEHXrTJecpEW_0xL= z?}N`*R`T~d2{AN${y8T#GEn4hUb&52^}Op@TW4{oc)A6)%$5=G}h# z?O{QLj@aRcAIf&y&OiUN=H2gq=_}V|pWfuReDV|{jwXw~>#w)I|9${XE z)7O>#600Dep5bGK9wD%hYeb1-X-P(Y5yQ%LXFPyHJS9LOm(=3qqRfJl%=|nCVNOM5 zpg0#u+&RCXvM4h>ql94%{~0TwC?8m~C^ZqJRG}m@H-L1 z5L@scq?{XUcxG{OP9jig5ySQaTl#^*93bKF#G<^+ymW>G($Cs~V(bw8rA5i93}62@ zzlJGu&d<$F%`0K}c4pdspcorSSx9C{PAbEScbC)|7#JBmT^vIy=Cn>w>~AWNX^a2R zbkveVY|45D7UnZ&JtjPwvdCCscZp0EA*0()#GOw)UH4-^&)y^E*4%UC)*|J}q_Ss;tN`nd8$>x9$_Xb^O2EpX&@C ZI46EzbLxq-voTO7gQu&X%Q~loCIF_C`w;*D literal 0 HcmV?d00001 diff --git a/doc/callouts/14.png b/doc/callouts/14.png new file mode 100644 index 0000000000000000000000000000000000000000..64014b75fe2e84d45ed861974c72462727979360 GIT binary patch literal 411 zcmV;M0c8G(P)!ax*-PXaQ9e~6^e1gu=a6a&KSz}bR`+prYG9ayB$BDjWGfIE;t#wl!+ zR3S(jA%y#i_@eOOedXoc%RQe%L;wH~k+s%ZI~)!<=dD%?4MaplaU9QPGski2q3`>r z(}{j@0a$CLl+)={2vLWml*i-oa5#J}DW$gCZB~Z!(!M#)2St|1_V^0qpmCrBof=Y&NUas@LmfSw=)4B4f;8Fu)(eFsv24 zJzXxBrayquXcR?J{XE z)7O>#600De0j~t#c`vY#Yeb1-X-P(Y5yQ%LXFPyHJS9LOm(=3qqRfJl%=|nCVNOM5 zpg0#u+&RCXvM4h>ql94%{~0TwC?8m~C^ZqJRG}m@H-L1 z5L@scq?{XUcxG{OP9jig5ySQaTl#^*93bKF#G<^+ymW>G($Cs~V(bw8rA5i93}62@ zzlJGu&d<$F%`0K}c4pdspcorSSx9C{PAbEScbC)|7#JBmT^vIy=9Eq_Jl&Ka(%QdX zh{H8O%#_7)Tc@t$mM`p4(Ne7omR*~(>gd8_8AZH{=3ms$Fmzm^yL@_+(#aQQ5>7QW z>3g2fIsH(ugM)!V$x4Rr_+!J_XU%4xbz0aE;^N{m@42Z|@0S@TQ=WbP`TMV5Ok;<| z^Ihv+@6tQ{sciRF9dD7Nr=KobwJJ68zJK$<1Pd9rz%4O)*;}Jzj&~nTGMecz>B%lV zK|`fmIc8mp-h8iSXiGFW=C(L+XH4DRxZQX87^-dLuD>odo6YLT@Sw)dfBEIG)v2@6 zR)%mL7GRj1x-&v&+2q@A%a&h0`Lw7|#(w_!tgT!PoJ|+re`lxaY7e*=hH)_rZeB4|imU1$R#1`!P>&$poQl;nzm}mD5ZFopaX|GsS%q*{P~< z;WtmO%lhToBL0i}yfkaOt?EN=nkLNGuU`ywhI5H)L`iUdT1k0gQ7VIjhO(w-Zen_> zZ(@38a<+nro{^q~f~BRtfrY+-p+a&|W^qZSLvCepNoKNMYO!8QX+eHoiC%Jk?!;Y+ zJAlS%fsM;d&r2*R1)67JkeZlkYGj#gX_9E3W@4U_nw*@Ln38B@k(iuhnUeN2eF0kK0(Y1u|9Rc(19XFPiEBhjaDG}zd16s2gM)^$re|(qda7?? zdS-IAf{C7yo`r&?rM`iMzJZ}aa#3b+Nu@(>WpPPnvR-PjUP@^}eqM=Qa(?c_U5Yz^ z#%Y0#%S_KpEGY$=XJL?(l#*ybuErX#^g`ttQfwn3r>K)tuC)r#2`iJ>Prt42#Ndx#Uc~1)>aw z3jE@Q4|!9Z%lVv}- zc=48cF7H)t`(Ck`^+mtha~Np7bBSw2NpOBzNqJ&XDuaWDvZiNlVtT4?VtQtBwt|VC zk)DNurKP@sg}#BILUK`NaY>~^Ze?*vX0l#tv0h4PL4IC|UUGi!#9fLzfW~Qojmu2W zODrh`nrE42VU(7fm~5G9U~HM3l#*m_WNcxOXkuzEX4g z+-vfUhb0A>b04=Im{6XiQd1v%r%>h0$G8U7E1If8OQ!N~xOYY5h0NDT$p9(iZ?Q&e z18-(+l~J8O`)kc}e&uL$eW&>P-#`~Qm$*ih1m~xflqVLYGB{``YkKA;rl!p+yCFkc(+@-h!Xq*<< zxXkpt#FA2=d1VEBsYynrsitN|Y01eJ$;p;U#>wWX2KP5v&I9V=1L+C? fTFYQ)RAFeOZJ=$?lDoSWD8u0C>gTe~DWM4f^}upZ literal 0 HcmV?d00001 diff --git a/doc/callouts/6.png b/doc/callouts/6.png new file mode 100644 index 0000000000000000000000000000000000000000..0ba694af6c07d947d219b45a629bd32c60a0f5fe GIT binary patch literal 355 zcmeAS@N?(olHy`uVBq!ia0vp^JRr;gBp8b2n5}^nQ*)Bra@SU# zmiz#bR~{$s2si{S(aY|Z}Vd7tb ouUmn-_&~Y>fYve?8dVq?X&Y!8wB+ut1u%w%U~xZhnMEEs6JbBSw2NpOBzNqJ&XDuaWDvZiNlVtT4?VtQtBwt|VC zk)DNurKP@sg}#BILUK`NaY>~^Ze?*vX0l#tv0h4PL4IC|UUGi!#9fLzfW~Qojmu2W zODrh`nrCEbVQgk$XkwI@Y+{_8nv`N>YGIaQkz#0QY@Te9lBQ<)awbq0A4pdK&{_sV bqY6VKZ3AtCmfYR7Kp6&4S3j3^P6u&S`V$cAh@R~F=4@V4jxkzlaQrcFYWK{)(`o5XZnut z=nE4SU2g1ZW%;@@I$>_e3F8a=8WK~|CVXt1DqisQxtIX|`YW_n&?Nh#1gQ}d)$LrYTw(_{nVG)tp2V+#}WG*e^KRLdkoLz7g? qn(IA84Qgo42`r6v<+Hvch>@C7(8A5T-G@yGywn*$#_oy literal 0 HcmV?d00001 diff --git a/doc/callouts/9.png b/doc/callouts/9.png new file mode 100644 index 0000000000000000000000000000000000000000..a0676d26cc2ff1de12c4ecdeefb44a0d71bc6bde GIT binary patch literal 357 zcmeAS@N?(olHy`uVBq!ia0vp^JRr;gBp8b2n5}^nQNRqa;^5&H%t0&v*|C|wdb9$wI zR@+N9#RIowg@Uqn&z-__Tzhhz!sG|vTxA7?=O|Y?u(d4T{!RM9c7chr6d%1?R=i16 z?@Ic{f32YJFJnVhX)qGzOMplv!L->5yAlT#}irms+fsQd*FoSE84k zpF44v;trs3T43Wc)AJHbN`dAXo0u6Hr<$gkq?lM38ycjV7+5A5Sr{ayr5c%-n;95g pF*H#D>f!_G3IJNmU}#ifXryhRZP1dtyA~+J;OXk;vd$@?2>@J{cB%jX literal 0 HcmV?d00001 diff --git a/doc/cards.asciidoc b/doc/cards.asciidoc new file mode 100644 index 0000000..4ea8eb5 --- /dev/null +++ b/doc/cards.asciidoc @@ -0,0 +1,263 @@ +[[cards]] + +=== Peripheral Cards + +==== Disk ][ Controller + +The Disk ][ Controller card emulates the floppy disk controller card and associated +disk drives in the original Apple ][ systems. In the emulator, each card has two +drives attached to it, referred to as drive 1 and drive 2. The floppy disks +themselves are represented by a ``nibble'' image of the contents. The +emulator emulates the hardware, but to be of any use, you will need to provide +the firmware ROM code. + +To use a disk card and drives, add these lines to your epple2.conf file, for example: + +-------- +slot 6 disk +import slot 6 rom 0 /usr/lib/apple2/dos3x/16sector/controller/disk2.ex65 +-------- + +The first line uses the <<_slot,slot>> command to +insert a disk contoller card into slot 6, which is the standard +slot used for disk cards. The next line uses the <<_import,import>> +command to load the card's ROM with the disk controller +firmware. This firmware is known as the ``bootstrap'' or ``P5'' ROM code. +It is seen by the Apple ][ at memory addresses $Cs00-$CsFF, where s is the +slot number (so in the common case of the card being in slot 6, the ROM is +at $C600-$C6FF). The firmware is copyright by Apple, and is available from +the http://mosher.mine.nu/apple2/[Apple II Library]. + +You can also load a floppy disk image (nibble format) into the drive,either by putting +the <<_load,load>> command into the +epple2.conf+ file, or by using the command prompt +in the emulator (+F5+ key). For example, you could load the DOS 3.3 system master into +slot 6, drive 1, with this command + +-------- +load slot 6 drive 1 /usr/lib/apple2/dos3x/16sector/disks/dos330/clean330sysmas.nib +-------- + + + + +==== Language + +The language card emulates an Apple 16K RAM card, commonly called a Language Card. +To use a language card, add this line to your epple2.conf file: + +-------- +slot 0 language +-------- + +Note that DOS and ProDOS will make use of a language card only if it is in slot _zero_. + +The language card has RAM at addresses $E000 through $FFFF, as well as two banks of RAM +at addresses $D000 through $DFFF. A program switches between these RAMs and/or the +motherboard ROM by using the I/O switches at $C080 through $C08F. + +The information area of the Epple ][ will show the current state of the +language card as follows: + +* +R+ Read from card RAM (vs. motherboard ROM) +* +W+ Write to card RAM (vs. write-disabled) +* +B1+ Use $D000 bank 1 +* +B2+ Use $D000 bank 2 + +An overview of the I/O switches that control the language card +is provided by Jim Sather in +http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II], +p. 5-30, Table 5.4, as follows: + +[options="header", style="monospaced"] +|================================================================== +| BANK2 | BANK1 2+| ACTION + +| C080 | C088 .2+| WRTCOUNT = 0*, WRITE DISABLE .2+| READ ENABLE +| C084 | C08C + +| RC081 | RC089 .2+| WRTCOUNT = WRTCOUNT + 1* .2+| READ DISABLE +| RC085 | RC08D + +| WC081 | WC089 .2+| WRTCOUNT = 0* .2+| READ DISABLE +| WC085 | WC08D + +| C082 | C08A .2+| WRTCOUNT = 0*, WRITE DISABLE .2+| READ DISABLE +| C086 | C08E + +| RC083 | RC08B .2+| WRTCOUNT = WRTCOUNT + 1* .2+| READ ENABLE +| RC087 | RC08F + +| WC083 | WC08B .2+| WRTCOUNT = 0* .2+| READ ENABLE +| WC087 | WC08F +|================================================================== + +^*^ Writing to expansion RAM is enabled when WRTCOUNT reaches 2. + + + +==== Firmware + +The firmware card emulates a (modified) Apple Firmware card. +The firmware card is simply an alternate ROM, at addresses +$D000 through $FFFF, that is switched using the I/O switches +at addresses $C080 through $C08F. In order to make use of the +firmware card, you will need to load the ROM with a binary image +from a file on disk. For example, to insert an Integer BASIC +firmware card into the emulator, add these lines to your ++epple2.conf+ file: + +-------- +# Firmware card with Integer BASIC and old Monitor +slot 0 firmware +import slot 0 rombank 1000 /usr/lib/apple2/system/intbasic/intbasic.ex65 +import slot 0 rombank 2425 /usr/lib/apple2/system/other/other.ex65 +import slot 0 rombank 2800 /usr/lib/apple2/system/monitor/apple2/monitor.ex65 +-------- + +For an Applesoft BASIC firmware card, use these: + +-------- +# Firmware card with Applesoft BASIC and Autostart Monitor +slot 0 firmware +import slot 0 rombank 0000 /usr/lib/apple2/system/applesoft/applesoft.ex65 +import slot 0 rombank 2800 /usr/lib/apple2/system/monitor/apple2plus/monitor.ex65 +-------- + +Note that the addresses specified in the +epple2.conf+ file for the +rombank are based on the beginning of the bank ROM itself. For example, specifying ++1000+ (which is 1000 hex) represents the final memory address of $E000, because +the bank ROM is always based at address $D000. + +The idea is that you would load your motherboard with, for +example, Applesoft BASIC and the Autostart Monitor ROM (to emulate +an Apple ][ plus), and then install a firmware card with Integer +BASIC and the old Monitor. Booting with DOS 3.3, then, would allow +you to type +FP+ to use Applesoft BASIC, or +INT+ to switch to Integer BASIC. + +Note that DOS and ProDOS will make use of a firmware card only if it is in slot _zero_. + +Jim Sather, in +http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II], +on pages 6-18 through 6-21, explains +how to modify a firmware card to allow independent switching of the $F800-$FFFF +ROM memory. This area is occupied by the Monitor, so it is primarily +intended to allow the user to switch between the old Monitor and the Autostart +Monitor, independent of switching between Integer and Applesoft BASIC. The EPPLE ][ +firmware card emulates this behavior. + +The information area of the EPPLE ][ will show the current state of the +firmware card as follows: + +* +D+ Read from firmware card $D000-$F7FF (vs. motherboard BASIC ROM) +* +F8+ Read from firmware card $F800-$FFFF (vs. motherboard Monitor ROM) + + + +==== Clock + +The clock card emulates a ProDOS-compatible real-time clock card for the Apple ][. +To use a clock card, you will need to configure the EPPLE ][ to insert one into +a slot, typically slot 4. You will also need to load the card with its ROM code, +which is provided with the emulator in the clock.ex65 file. +For example, add this to your epple2.conf file: + +-------- +slot 4 clock +import slot 4 rom 0 /usr/lib/epple2/cards/clock.ex65 +-------- + +Of course you may need to adjust the path for your particular system. + +To verify that the clock card is working correctly, you can run the following Applesoft +program to retrieve the current time from the clock card and print it. +This program assumes the card is in slot 4. + + +[source,vbs] +------------------------------------------------- +NEW + +10 CALL -15360 : REM $C400 SLOT 4 ENTRY POINT +20 A = 512 : REM $0200 INPUT BUFFER +30 C = PEEK(A) +40 IF C < 160 THEN 99 +50 PRINT CHR$(C); +60 A = A+1 +70 GOTO 30 +99 END + +RUN +------------------------------------------------- + + +The card returns data (into the GETLN input buffer at $200) in +the following format: + ++mm,ww,dd,hh,nn,ss,000,yyyy,Time Zone,v+ + +* +mm+ Month, 01-12 +* +ww+ Weekday, 00=Monday... 06=Saturday +* +dd+ Day, 01-31 +* +hh+ Hour, 00-23 +* +nn+ Minute, 00-59 +* +ss+ Second, 00-61 +* +000+ Milliseconds; always zero +* +yyyy+ Year, e.g., 2008 +* +Time Zone+ time zone string (could contain lower-case characters, + which won't display correctly) +* +v+ Daylight Saving Time in effect, 0=no, 1=yes + +Note that only +mm,ww,dd,hh,nn+ fields are used by ProDOS. The other +fields, +ss,000,yyyy,Time Zone,v+, are an EPPLE ][ extension. Also note +that ProDOS was not designed to work for years past 2007, so +ProDOS will show the incorrect year, but the other fields will be accurate. +I believe patches exist for ProDOS to fix this. + + + +==== Standard Input + +The ``standard input'' card doesn't emulate a real piece of hardware; rather, it +reads characters from standard input (stdin) (of the EPPLE ][ emulator). + +To use a standard input card, add these lines to your +epple2.conf+ file: + +------------------------------------------------- +# IN#2 reads from standard input +slot 2 stdin +import slot 2 rom 0 /usr/lib/epple2/cards/stdin.ex65 +------------------------------------------------- + +That will insert a stdin card into slot 2, and then load its +ROM image into the card. +The stdin ROM is provided with the EPPLE ][ distribution. + +For example, if you have a stdin card installed in slot 2, start +the EPPLE ][ emulator from the command line, and at the Applesoft +prompt, type +IN#2+. Then you can switch back to the +command shell, and whatever you type will be fed into the emulated +Apple. Use RESET or +IN#0+ to go back to normal. + + + +==== Standard Output + +The ``standard output'' card doesn't emulate a real piece of hardware; rather, it acts +similar to a printer card, but instead of sending characters to a printer, it sends +them to standard output (stdout) (of the EPPLE ][ emulator). + +To use a standard output card, add these lines to your +epple2.conf+ file: + +------------------------------------------------- +# PR#1 prints to standard output +slot 1 stdout +import slot 1 rom 0 /usr/lib/epple2/cards/stdout.ex65 +------------------------------------------------- + +This will insert a stdout card into slot 1 (which is the typical +slot for a printer card), and then load its ROM image into the card. +The stdout ROM is provided with the EPPLE ][ distribution. + +For example, if you have a stdout card installed, at the Applesoft +prompt, type +PR#1+. Whatever you type next will be +echoed to standard output. Type +PR#0+ to stop echoing. diff --git a/doc/cassette.asciidoc b/doc/cassette.asciidoc new file mode 100644 index 0000000..8ad770a --- /dev/null +++ b/doc/cassette.asciidoc @@ -0,0 +1,188 @@ +=== Cassette Tape Interface + +The Apple ][ and Apple ][ plus machines had the ability to save and load binary +data to and from cassette tape. The user would attach a standard cassette tape +recorder to the jacks on the back of the Apple ][, and use the monitor +R+ and +W+ +commands, or the Applesoft BASIC commands +LOAD+ and +SAVE+, to read and write data +on the cassette tape. The user would have to press the play and/or record buttons +on the player at the right time. + +The Epple ][ emulates the cassette interface, using a file to hold the +recorded portion of the tape. The file will grow in length as necessary +to hold data that the emulated Apple is writing to the ``tape.'' +The emulator will not overwrite existing data on a tape image. +The emulator will automatically ``press'' the play or record buttons that +would have been necessary when using the original machine. + +==== Commands + ++cassette new + + +This creates a new empty file (on the host computer) that represents a cassette tape image. +The file must not already exist. + ++cassette load + + +This loads an existing file (from the host computer) containing a cassette tape image. +The tape is automatically positioned at its beginning (fully rewound). + ++cassette unload+ + +This removes the file from the cassette tape. Note that you must manually save +the file using the +cassette save+ command (described below). + +[WARNING] +Unloading an unsaved file will lose any changes made to the file, without warning. + ++cassette rewind+ + +This command ``rewinds'' the cassette tape, positioning it at the beginning +of the tape (for subsequent reading). You do not need to rewind the tape +before saving or unloading it, of course. + ++cassette save+ + +This command saves the changed tape to the file. Note that the display will show +an asterisk +*+ next to the file name if there are unsaved changes that need to +be saved. Unsaved changes will be lost without warning if the file is unloaded +or if you quit the program. + +==== Example of Saving to Tape + +Start up the emulator with Applesoft ROMs for this tutorial. +Enter a simple Applesoft program, just as an example, that we +are going to save to a cassette tape image file. + +[source,vbs] +------------------------ +]NEW + +]10 PRINT "HELLO" + +]20 END + +]LIST + +10 PRINT "HELLO" +20 END + +]RUN +HELLO + +] +------------------------ + +We first need to load a tape image file into the cassette machine. +Enter command mode by pressing +F5+, then make a new tape +image file. + +------------------------ +command: cassette new hello.tap +------------------------ + +This will create a new, empty tape file image named +hello.tap+ +in the current default directory. (We could have specified a full path +name for the file if we wanted to place it in a different directory.) +Notice that the emulator now displays the name of the tape image file, +along with the position and length of the tape image, which is now +0/0+. + +Next, we tell Applesoft to save the program to the cassette. For this, +we just use the +SAVE+ command. Note that this is not the +DOS +SAVE+ command; the DOS command has a file name after ++SAVE+. We just use +SAVE+ with no file name. + +------------------------ +]SAVE + +] +------------------------ + +It will take 10 seconds or so for it to save. Notice that the +current position of the tape is counting up as the Apple saves +the program. When it is finished, you need to save the changes +to the file. Press +F5+ and enter the emulator command to save +the tape image file. + +------------------------ +command: cassette save +------------------------ + +We can now unload the file from the emulator (which is like ejecting +the tape from the cassette player). + +------------------------ +command: cassette unload +------------------------ + +==== Example of Loading from Tape + +To load the saved program (from the previous section) into the Apple again, +we will need to first load the tape image file back into the cassette machine. +Press +F5+ to enter command mode and load the image file. + +------------------------ +command: cassette load hello.tap +------------------------ + +This will load hello.tap (in the current default directory). Notice the +emulator now displays the name of the tape image file, along with the +position and length of the tape image, which in this case is +0/33481+. + +Next, we tell Applesoft to load the program from the cassette. For this, +we just use the +LOAD+ command. Note that this is not the +DOS +LOAD+ command; the DOS command has a file name after ++LOAD+. We just use +LOAD+ with no file name. + +------------------------ +]LOAD + +] +------------------------ + +It will take 10 seconds or so for it to load. Notice that the +current position of the tape is counting up as the Apple loads +the program. When it is finished, the program will be loaded. + +[source,vbs] +------------------------ +]LIST + +10 PRINT "HELLO" +20 END + +]RUN +HELLO + +] +------------------------ + +==== Tape Image File Format + +The format of the tape image file is unique to the Epple ][ +It is stored in a low-level format that represents the waveform that the Apple writes +to the cassette tape. + +The file is a binary format. Each byte in the file represents the length of one half of one cycle +(of voltage level variation) written to the tape. The length is in 10-microsecond units. + +For example, a tape image file might have the following binary bytes (in decimal): ++65 65 65 65 65 20 25 50 50 25 25 25 25 50 50+ +Since each byte represents a 10-microsecond unit, these bytes represent the following +half-cycle lengths in microseconds: ++650 650 650 650 650 200 250 500 500 250 250 250 250 500 500+ +The meaning of these half-cycle lengths to the Apple is as follows: + +------------------------ +|-------HEADER------|--sync-|-1-bit-|-0-bit-|-0-bit-|-1-bit-| +| | | | | | | +|650 650 650 650 650|200 250|500 500|250 250|250 250|500 500| +------------------------ + +where +HEADER+ is a header section the Apple writes (to skip any +unrecordable leader section on a real cassette tape); +sync+ is a +synchronization cycle; and the subsequent cycles are the actual +bits of data saved on the tape. A 500-microsecond cycle (which +is stored in the file as two 250 microsecond half-cycles) +represents a *zero* bit, and a 1-millisecond cycle (which is +stored in the file as two 500 microsecond half-cycles) +represents a *one* bit. diff --git a/doc/commands.asciidoc b/doc/commands.asciidoc new file mode 100644 index 0000000..90772ff --- /dev/null +++ b/doc/commands.asciidoc @@ -0,0 +1,202 @@ +=== Commands + ++<<_slot,slot>> <<_import,import>> <<_load,load>> <<_unload,unload>> <<_save,save>> <<_cassette,cassette>> <<_revision,revision>>+ + +==== slot + +The +slot+ command inserts a card into a peripheral slot of the emulated Apple. + +-------- +slot +------- + +++ Slot number, 0 through 7, to insert the card into. + +++ The type of <> to insert into the slot: + +* +language+ +* +firmware+ +* +disk+ +* +clock+ +* +stdout+ +* +stdin+ +* +empty+ + +The +slot+ command inserts a card into a peripheral slot. For example: + +-------- +slot 0 language +-------- + +inserts a language card into slot zero. Use +empty+ to remove a card: + +-------- +slot 0 empty +-------- + +[NOTE] +The emulated Apple should be _powered off_ before inserting or removing cards. + + + +==== import + +The +import+ command imports a binary image file into the emulated Apple's memory. + +-------- +import slot { rom | rom7 | rombank } +import motherboard { rom | ram } +-------- + +++ Slot number, 0 through 7, of peripheral card to import the binary image into. + +++ Base address in hexadecimal within the given memory area at which to start loading the binary image. + +++ Path of the binary image to import. + +The +import+ command reads the binary image byte-for-byte from the given file-path +into an area of memory in the emulated Apple. You can load into either the motherboard or +a card in one of the slots. For the motherboard, you choose the RAM or ROM area. For a card +in a slot, you can choose either the normal ROM, the bank-switched ROM, or the so-called +``seventh ROM'' area. + +You also have to specify the base address within the specific memory +area at which the image file will be loaded. Note that the base address is specified as the offset +within the specific memory area, and not necessarily as the actual memory address as seen +by the Apple. So for motherboard ROM, for example, specifying a base as 2DED will cause the +image to be loaded at offset 2DED in the ROM, which will be addressed by the Apple at +memory address $FDED (because motherboard ROM ``starts'' at address $D000). + +For peripheral cards, the ROM will be seen at locations $Cs00-$CsFF, where s is the slot +number (1 through 7). The ``seventh ROM'' can be seen as locations $C800-$CFFF; Jim Sather +describes this functionality in +http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II], +on page 6-4, section ``The Seventh ROM Chip.'' The EPPLE ][ emulator handles this processing correctly. A card can +also have bank-switched ROM, which will show up at addresses $D000-$FFFF when switched in +(stealing that address range from motherboard ROM... see +http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II], +p. 5-26 ``The 16K RAM Card''). + + + + + +==== load + +The +load+ command loads a (nibble) floppy disk image into one of the emulated disk drives. + + +-------- +load slot drive +-------- + + +++ Slot number, 0 through 7, of Disk ][ controller card to load the nibble image into. + +++ Drive number, 1 or 2, of the disk drive on the controller card to load the nibble image into. + +++ Path of the nibble floppy disk image to import. + +The +load+ command will load a nibble image into a disk drive. Specify the slot that +contains a Disk ][ controller peripheral card, and specify which drive number (1 or 2). + +[NOTE] +The floppy disk image MUST be a NIBBLE DISK IMAGE. +Other formats (for example, DOS order, +.do+, PRODOS order, ++.po+, +.dsk+, or anything else) must first be converted to nibble format. A nibble image contains +all 35 tracks, in order 0-36, each track being 6656 ($1A00) bytes long. Nibble image files +will generally have a filetype of +.nib+. + + +The best floppy disk image conversion tool I've found is http://ciderpress.sourceforge.net/[CiderPress], +for Windows (but it supposedly runs under Wine on Linux, too). Thanks to Andy McFadden. + + + + + +==== unload + +The +unload+ command removes a floppy disk image from one of the emulated disk drives. + +-------- +unload slot drive +-------- + +++ Slot number, 0 through 7, of Disk ][ controller card to which the drive is attached. + +++ Drive number, 1 or 2, of the disk drive on the controller card to remove the floppy disk image from. + +The +unload+ command removes the disk from the specified slot and drive. + +[WARNING] +If the disk has been modified but not saved, the modifications will be DISCARDED. + + + + + +==== save + +The +save+ command saves changes made on an emulated floppy disk back to the original image file. + +-------- +save slot drive +-------- + +++ Slot number, 0 through 7, of Disk ][ controller card to which the drive is attached. + +++ Drive number, 1 or 2, of the disk drive on the controller card to save. + +++ Path of the nibble floppy disk image to import. + +The +save+ command saves any changes that the emulated Apple ][ has made to the floppy +disk image. It is important to note that the emulator operates on the image only in memory, and does +not immediately write changes back to the real file. You need to issue the +save+ command +in order to write changes back to the file. Note that the emulator will display a asterisk +*+ +next to the file-name of a disk image if it has any unsaved changes. + + + + + +==== cassette + +The +cassette+ command performs various operations of the emulated cassette tape. + + +-------- +cassette new +cassette load +cassette unload +cassette rewind +cassette save +-------- + +++ File path of the (special format) cassette tape image file. + +The +cassette+ command allows the user to control the emulated cassette tape player. +See <<_cassette_tape_interface,Cassette>> for more information about operating the emulated +cassette player and cassette tape image files. + + + + + + +==== revision + +The +revision+ command specifies which revision of Apple ][ motherboard to use. + +-------- +revision +-------- + + +++ Revision number of the motherboard. Currently, only two values make any difference in behavior: 0 or 1. + +The +revision+ command chooses which revision of the Apple ][ motherboard to +use. The only revisions that make any difference (for now, at least) are 0 or 1. Zero +is the original (now quite rare) version of the motherboard, that only had two hi-res +colors (green and purple), and always displayed text with green and purple fringes. +Revision 1 and later motherboards are the ones we are more familiar with. diff --git a/doc/configuration.asciidoc b/doc/configuration.asciidoc new file mode 100644 index 0000000..a0b345c --- /dev/null +++ b/doc/configuration.asciidoc @@ -0,0 +1,63 @@ +== Configuration + +The Epple ][ Emulator is most useful when properly configured. +After downloading and installing the Epple ][ Program, some System ROM (demo or real), and +optionally the peripheral card ROMs you want to use, you will need to configure the program. +Configuring is concerned primarily with telling the program what peripheral cards to use, +and where the ROM files are located (and what memory addresses to load them at). + +=== epple2.conf +The default configuration file for +the Epple ][ emulator is: + +--------------------- +/etc/epple2/epple2.conf +--------------------- + +For Windows, the file will be: + +--------------------- +C:\Program Files\Epple2\etc\epple2\epple2.conf +--------------------- + +The configuration file could be in a different location depending upon how +the distribution package is built. + +You can specify a different configuration file for the emulator to use by +specifying its name as the argument when running the epple2 program. + +The format of the configuration file is just lines of <<_commands,commands>>. +Comments begin with a hash +#+ character, and continue to the end of the line. + +=== Firmware + +Firmware, commonly called ROM images or ROMs, will need to be loaded +into the emulated ROM areas of the emulated Apple +in order for it to be able to boot the emulated Apple machine. +The firmware available is described <>. +Once the firmware image +files are installed on your computer, you can use the <<_import,import>> +command in the configuration file to load the image files into the emulator. + +=== Peripheral Cards + +Another primary concern for configuring the Epple ][ is the insertion of +peripheral cards into the Apple's slots. The most useful card is probably the +Disk ][ Controller card; you will need to insert one of these cards if you want +to be able to load floppy disk images into the emulated Apple. The various +types of cards available are described on the <> section. +You can use the <<_slot,slot>> command in the configuration file to insert +them into the Apple's slots. + +=== Sample Configuration Files + +There are a number of configuration files provided with the distribution for +your convenience. They provide various common configurations of machines. +You can use one of these files directly, by specifying its path as the argument +to the program, or as a starting point for you own configuration file. These sample +files are in the same location as the default +epple2.conf+ file. + +The Epple ][ Emulator can actually be run without a configuration file at all. +In this case, you will be able to ``power on'' the Apple and see the low-resolution +graphics display showing random RAM data. The system will not run, because +there is no firmware loaded, but the emulator will otherwise be functional. diff --git a/doc/debian.png b/doc/debian.png new file mode 100644 index 0000000000000000000000000000000000000000..f6e85d87434ba04b222bcda82c604ac2046c7be2 GIT binary patch literal 552 zcmV+@0@wYCP)Px#Gf+%aMFRi_$pALY213&=TiH!>bar!rf`8v=iHwemL;#2d9Y_EG010qNS#tmY3labT z3lag+-G2N4000McNliru*#Qj%4>u0O2Q~lz0bxl*K~y-)m6O}DgD?n16Cf92H2nY9 z9*9ZQPV3C!rB0Wy*?`VnaU^2mD(+h_g7+RYu*&Bv2l`t8qz9$*UnGrQ#l!JIfh6=0 z?lSdGfe%A5my%;MDcDb%^ckzcJQKt?Zv9zHC4<|3$%)kuXELyr-JU+dLx|2*?~Rt3 zHZ7x19PEe6q6vu7*)prQXv%3(B3T6vwN^|y&W?$lD>3I{ZHV_Rn8ZwO=v*$h-fPg2 zsN*4ACzT6BoysUK-<*38Ee=N*jpC9b-A2xyX7Pgw&an}gi`X?_t-~n?MAQ|!J)e!}*p}N} zm{ULH65_g~a1CS2q6ZbP?KkjPZg)_&QntqtLvz1FXHW5kCjfcDTAtpxUNyN_{_)NI qGhf%W_VG2^*vGFZlJpaJzVQd5$qT}AQZ9)A0000_! literal 0 HcmV?d00001 diff --git a/doc/deploy/80x15.png b/doc/deploy/80x15.png new file mode 100644 index 0000000000000000000000000000000000000000..ed028fed9d6154b10bf73872ea925a9603a352ae GIT binary patch literal 697 zcmV;q0!ICbP)IS55s3f)|36ZE3j`1kui3O3Sz^zwy)&oI?C9tyFE7W`=IZKt>eQ*W?pARLaUfS- zR>9TD_2Y++gWR`3Zvy?xgemdz#mnW3m*es+5bWN)+sw>ta{m+v_ru2zg$0E}C6cjt zc=?hQ!otG1d8z{RS#dfcqu(S9mqI)_N=n9GB6nc z)A0NE?|~$c4HN;28yg$DxVT)qdJSp{6BCe&mVO`r&PA5On%*$k$R^-QrD(PgERUEl ze0%xxr_VtD0NG(-VL%4Z2q4+n*$MRLyLaz^F@NvgJ)kU5@XqZ!@Kg;<? z1Gzvy1H~&UDrU`^g%&65>>U69{Kpf+*lP$_Fe_H@*|00^!fe!_wi^0hKPxYNpxIvK(IfMD=RJ6+|ayr%hn-T4@bvEy?y%z7^QeLmz9;N zs47Ez%g-mUW6O>~?pu7-60rT0nweTzS=rv+j#ZD7v(xqK*9%Gt;OV)4LjP!6dXToI fM_Olz0U*EtDwt)|Le?|v00000NkvXXu0mjf&ay*> literal 0 HcmV?d00001 diff --git a/doc/deploy/applesplit.png b/doc/deploy/applesplit.png new file mode 100644 index 0000000000000000000000000000000000000000..5c6f85a3acf985d4d3d166b2c8ef0fe3551d2874 GIT binary patch literal 1788 zcmbtUYc$kp7=OoKBaF#$8pb7}L}hZX85*~hOB{qSv=uH!E5f6RTK%9L95ja_l!1>$b4Q?7RF`$laOwYB6plxvCjX`@&EGvYtNvh@nr`D?$IxEXC7~D zbAHwoC`?mMo_ebtyoW5v$Xnpjy_Ui^Pu^*AeYd+&Qvex}M*w9gb$WqvxpiU%ij51K zMv65BHi6#lhzv2WPMX2-OH`-PRca-4^Ka8aFwC+f_8zBfC6=6)ADGW5otd&l)K)me(3a=c|1 zN7OKNzY}U$Sqfw9h}2oM;Vm)|Tl{cvUC4b1l1igifLrZ8AwQv19W6e`*YFMQG0Qx;j)3Q`>~{4r8#Qh$7CaDcgaPnB>1m1%zZ z*&az&-EOQ>4Y4edXRZ&S>rts3L8$ z2T7s4#FJ%RT+4#l;a*IVStxGjv+cWo;!!$h5N7OtZqp?|(7^j?P_6i(&^1FsfwqC|c$S*j z{R16dOT0ZrSM7}{EqcliU+!RZo>GS>l1!Somqypg3Z&xUwV#%_@(iD6Avk#NzFGy7 zP7bvgmWb&ft+aJDwu#YM@p)Hk&3uk{;mTm&rO}dzN#Z%H zcx&Ty52v}p`S-t?w%4tQA{!|R6)Tru(>c)6$q2cQxFES~CgapSG#ftk zV=;mIu1Giov$;!JtrvIZnLc&44aDLC}X^4DKU-G|w_t}fLBA)Suv#nrW z!^h2QnY_`l!BOq-UXEX{m2up>JTQkX)2m zTvF+fTUlI^nXH#utd~++ke^qgmzgTe~DWM4ffP81J literal 0 HcmV?d00001 diff --git a/doc/deploy/callouts/10.png b/doc/deploy/callouts/10.png new file mode 100644 index 0000000000000000000000000000000000000000..997bbc8246a316e040e0804174ba260e219d7d33 GIT binary patch literal 361 zcmeAS@N?(olHy`uVBq!ia0vp^JRr;gBp8b2n5}^nQWtZ~+OvdJMW|Y+^UT?O-M{rKJsmzxdayJ{ zDCQA!%%@7Jj$q%-wf8e0_jRx8Dqi$}^?K=?6FriQFLv>>oc^CE+aVHhW3=nZ+fQ4!M=ZC7H>3sl|FJr3LwU zC3?yExf6FO?f@F61vV}-Juk7O6lk8Yg;}bFaZ-|HQc7Azopr01?u8M*si- literal 0 HcmV?d00001 diff --git a/doc/deploy/callouts/11.png b/doc/deploy/callouts/11.png new file mode 100644 index 0000000000000000000000000000000000000000..ce47dac3f52ac49017749a3fea53db57d006993c GIT binary patch literal 565 zcmeAS@N?(olHy`uVBq!ia0vp^JRr=$1SD^YpWXnZI14-?iy0V%N{XE z)7O>#600DeuDZ?5tOl@ql94%{~0TwC?8m~C^ZqJRG}m@H-L1 z5L@scq?{XUcxG{OP9jig5ySQaTl#^*93bKF#G<^+ymW>G($Cs~V(bw8rA5i93}62@ zzlJGu&d<$F%`0K}c4pdspcorSSx9C{PAbEScbC)|7#JBmT^vIy=9KoYUDZ+`aP)jU z&ny=ErrK^#Gw!AcR}pdfMERuV^@&0$@(#^6b8c@rn^6RWX3pUb z4*6@PZ+H0#u=rjsXzS?6n6*sBGbHqGTU%mCsH?n#%j;eD^2}qe=iX*J@VQ3BRpz+u z{PX#N(^9X${`$90+;!pWs>o@z_n8G)7Uo7PJz`jrS+)QE@=PWHmc~UIw=WmUe73o7 z>^bR(M752aYoNg~ozu7U7&{(U>{s!;bn#f?ItjL^o`e{*EOQHqO;ccnz9hLK5@2cAyw@AaPFL~Cp#02|E|4xeQteNtB7waMs QVCXP-y85}Sb4q9e0GRUFb^rhX literal 0 HcmV?d00001 diff --git a/doc/deploy/callouts/12.png b/doc/deploy/callouts/12.png new file mode 100644 index 0000000000000000000000000000000000000000..31daf4e2f25b6712499ee32de9c2e3b050b691ca GIT binary patch literal 617 zcmeAS@N?(olHy`uVBq!ia0vp^JRr=$1SD^YpWXnZI14-?iy0V%N{XE z)7O>#600De9$%>2LVd81Yeb1-X-P(Y5yQ%LXFPyHJS9LOm(=3qqRfJl%=|nCVNOM5 zpg0#u+&RCXvM4h>ql94%{~0TwC?8m~C^ZqJRG}m@H-L1 z5L@scq?{XUcxG{OP9jig5ySQaTl#^*93bKF#G<^+ymW>G($Cs~V(bw8rA5i93}62@ zzlJGu&d<$F%`0K}c4pdspcorSSx9C{PAbEScbC)|7#JBmT^vIy=Cn>wTzx1(qV@bS z0hYvspf(--lM>otrqbK$7p{3DzJ|+KN8%5ows)AI?zWk_n>jwEHXrTJecpEW_0xL= z?}N`*R`T~d2{AN${y8T#GEn4hUb&52^}Op@TW4{oc)A6)%$5=G}h# z?O{QLj@aRcAIf&y&OiUN=H2gq=_}V|pWfuReDV|{jwXw~>#w)I|9${XE z)7O>#600Dep5bGK9wD%hYeb1-X-P(Y5yQ%LXFPyHJS9LOm(=3qqRfJl%=|nCVNOM5 zpg0#u+&RCXvM4h>ql94%{~0TwC?8m~C^ZqJRG}m@H-L1 z5L@scq?{XUcxG{OP9jig5ySQaTl#^*93bKF#G<^+ymW>G($Cs~V(bw8rA5i93}62@ zzlJGu&d<$F%`0K}c4pdspcorSSx9C{PAbEScbC)|7#JBmT^vIy=Cn>w>~AWNX^a2R zbkveVY|45D7UnZ&JtjPwvdCCscZp0EA*0()#GOw)UH4-^&)y^E*4%UC)*|J}q_Ss;tN`nd8$>x9$_Xb^O2EpX&@C ZI46EzbLxq-voTO7gQu&X%Q~loCIF_C`w;*D literal 0 HcmV?d00001 diff --git a/doc/deploy/callouts/14.png b/doc/deploy/callouts/14.png new file mode 100644 index 0000000000000000000000000000000000000000..64014b75fe2e84d45ed861974c72462727979360 GIT binary patch literal 411 zcmV;M0c8G(P)!ax*-PXaQ9e~6^e1gu=a6a&KSz}bR`+prYG9ayB$BDjWGfIE;t#wl!+ zR3S(jA%y#i_@eOOedXoc%RQe%L;wH~k+s%ZI~)!<=dD%?4MaplaU9QPGski2q3`>r z(}{j@0a$CLl+)={2vLWml*i-oa5#J}DW$gCZB~Z!(!M#)2St|1_V^0qpmCrBof=Y&NUas@LmfSw=)4B4f;8Fu)(eFsv24 zJzXxBrayquXcR?J{XE z)7O>#600De0j~t#c`vY#Yeb1-X-P(Y5yQ%LXFPyHJS9LOm(=3qqRfJl%=|nCVNOM5 zpg0#u+&RCXvM4h>ql94%{~0TwC?8m~C^ZqJRG}m@H-L1 z5L@scq?{XUcxG{OP9jig5ySQaTl#^*93bKF#G<^+ymW>G($Cs~V(bw8rA5i93}62@ zzlJGu&d<$F%`0K}c4pdspcorSSx9C{PAbEScbC)|7#JBmT^vIy=9Eq_Jl&Ka(%QdX zh{H8O%#_7)Tc@t$mM`p4(Ne7omR*~(>gd8_8AZH{=3ms$Fmzm^yL@_+(#aQQ5>7QW z>3g2fIsH(ugM)!V$x4Rr_+!J_XU%4xbz0aE;^N{m@42Z|@0S@TQ=WbP`TMV5Ok;<| z^Ihv+@6tQ{sciRF9dD7Nr=KobwJJ68zJK$<1Pd9rz%4O)*;}Jzj&~nTGMecz>B%lV zK|`fmIc8mp-h8iSXiGFW=C(L+XH4DRxZQX87^-dLuD>odo6YLT@Sw)dfBEIG)v2@6 zR)%mL7GRj1x-&v&+2q@A%a&h0`Lw7|#(w_!tgT!PoJ|+re`lxaY7e*=hH)_rZeB4|imU1$R#1`!P>&$poQl;nzm}mD5ZFopaX|GsS%q*{P~< z;WtmO%lhToBL0i}yfkaOt?EN=nkLNGuU`ywhI5H)L`iUdT1k0gQ7VIjhO(w-Zen_> zZ(@38a<+nro{^q~f~BRtfrY+-p+a&|W^qZSLvCepNoKNMYO!8QX+eHoiC%Jk?!;Y+ zJAlS%fsM;d&r2*R1)67JkeZlkYGj#gX_9E3W@4U_nw*@Ln38B@k(iuhnUeN2eF0kK0(Y1u|9Rc(19XFPiEBhjaDG}zd16s2gM)^$re|(qda7?? zdS-IAf{C7yo`r&?rM`iMzJZ}aa#3b+Nu@(>WpPPnvR-PjUP@^}eqM=Qa(?c_U5Yz^ z#%Y0#%S_KpEGY$=XJL?(l#*ybuErX#^g`ttQfwn3r>K)tuC)r#2`iJ>Prt42#Ndx#Uc~1)>aw z3jE@Q4|!9Z%lVv}- zc=48cF7H)t`(Ck`^+mtha~Np7bBSw2NpOBzNqJ&XDuaWDvZiNlVtT4?VtQtBwt|VC zk)DNurKP@sg}#BILUK`NaY>~^Ze?*vX0l#tv0h4PL4IC|UUGi!#9fLzfW~Qojmu2W zODrh`nrE42VU(7fm~5G9U~HM3l#*m_WNcxOXkuzEX4g z+-vfUhb0A>b04=Im{6XiQd1v%r%>h0$G8U7E1If8OQ!N~xOYY5h0NDT$p9(iZ?Q&e z18-(+l~J8O`)kc}e&uL$eW&>P-#`~Qm$*ih1m~xflqVLYGB{``YkKA;rl!p+yCFkc(+@-h!Xq*<< zxXkpt#FA2=d1VEBsYynrsitN|Y01eJ$;p;U#>wWX2KP5v&I9V=1L+C? fTFYQ)RAFeOZJ=$?lDoSWD8u0C>gTe~DWM4f^}upZ literal 0 HcmV?d00001 diff --git a/doc/deploy/callouts/6.png b/doc/deploy/callouts/6.png new file mode 100644 index 0000000000000000000000000000000000000000..0ba694af6c07d947d219b45a629bd32c60a0f5fe GIT binary patch literal 355 zcmeAS@N?(olHy`uVBq!ia0vp^JRr;gBp8b2n5}^nQ*)Bra@SU# zmiz#bR~{$s2si{S(aY|Z}Vd7tb ouUmn-_&~Y>fYve?8dVq?X&Y!8wB+ut1u%w%U~xZhnMEEs6JbBSw2NpOBzNqJ&XDuaWDvZiNlVtT4?VtQtBwt|VC zk)DNurKP@sg}#BILUK`NaY>~^Ze?*vX0l#tv0h4PL4IC|UUGi!#9fLzfW~Qojmu2W zODrh`nrCEbVQgk$XkwI@Y+{_8nv`N>YGIaQkz#0QY@Te9lBQ<)awbq0A4pdK&{_sV bqY6VKZ3AtCmfYR7Kp6&4S3j3^P6u&S`V$cAh@R~F=4@V4jxkzlaQrcFYWK{)(`o5XZnut z=nE4SU2g1ZW%;@@I$>_e3F8a=8WK~|CVXt1DqisQxtIX|`YW_n&?Nh#1gQ}d)$LrYTw(_{nVG)tp2V+#}WG*e^KRLdkoLz7g? qn(IA84Qgo42`r6v<+Hvch>@C7(8A5T-G@yGywn*$#_oy literal 0 HcmV?d00001 diff --git a/doc/deploy/callouts/9.png b/doc/deploy/callouts/9.png new file mode 100644 index 0000000000000000000000000000000000000000..a0676d26cc2ff1de12c4ecdeefb44a0d71bc6bde GIT binary patch literal 357 zcmeAS@N?(olHy`uVBq!ia0vp^JRr;gBp8b2n5}^nQNRqa;^5&H%t0&v*|C|wdb9$wI zR@+N9#RIowg@Uqn&z-__Tzhhz!sG|vTxA7?=O|Y?u(d4T{!RM9c7chr6d%1?R=i16 z?@Ic{f32YJFJnVhX)qGzOMplv!L->5yAlT#}irms+fsQd*FoSE84k zpF44v;trs3T43Wc)AJHbN`dAXo0u6Hr<$gkq?lM38ycjV7+5A5Sr{ayr5c%-n;95g pF*H#D>f!_G3IJNmU}#ifXryhRZP1dtyA~+J;OXk;vd$@?2>@J{cB%jX literal 0 HcmV?d00001 diff --git a/doc/deploy/debian.png b/doc/deploy/debian.png new file mode 100644 index 0000000000000000000000000000000000000000..f6e85d87434ba04b222bcda82c604ac2046c7be2 GIT binary patch literal 552 zcmV+@0@wYCP)Px#Gf+%aMFRi_$pALY213&=TiH!>bar!rf`8v=iHwemL;#2d9Y_EG010qNS#tmY3labT z3lag+-G2N4000McNliru*#Qj%4>u0O2Q~lz0bxl*K~y-)m6O}DgD?n16Cf92H2nY9 z9*9ZQPV3C!rB0Wy*?`VnaU^2mD(+h_g7+RYu*&Bv2l`t8qz9$*UnGrQ#l!JIfh6=0 z?lSdGfe%A5my%;MDcDb%^ckzcJQKt?Zv9zHC4<|3$%)kuXELyr-JU+dLx|2*?~Rt3 zHZ7x19PEe6q6vu7*)prQXv%3(B3T6vwN^|y&W?$lD>3I{ZHV_Rn8ZwO=v*$h-fPg2 zsN*4ACzT6BoysUK-<*38Ee=N*jpC9b-A2xyX7Pgw&an}gi`X?_t-~n?MAQ|!J)e!}*p}N} zm{ULH65_g~a1CS2q6ZbP?KkjPZg)_&QntqtLvz1FXHW5kCjfcDTAtpxUNyN_{_)NI qGhf%W_VG2^*vGFZlJpaJzVQd5$qT}AQZ9)A0000_! literal 0 HcmV?d00001 diff --git a/doc/deploy/dos310rev0.png b/doc/deploy/dos310rev0.png new file mode 100644 index 0000000000000000000000000000000000000000..a393a6a0ef0268f59208a8578675f24991d55da5 GIT binary patch literal 3170 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 ZQ@m{#2cnngjsJHRmgcr*^h=(P{{^UHqT~Po literal 0 HcmV?d00001 diff --git a/doc/deploy/epple2logo.png b/doc/deploy/epple2logo.png new file mode 100644 index 0000000000000000000000000000000000000000..ebaf1358066c012e06abbc97701a56e6d97a7f33 GIT binary patch literal 605 zcmeAS@N?(olHy`uVBq!ia0vp^6+kS)!3-n|dpHjQDaPU;cPEB*=VV?2IV%EuLR|m< z{|{s`7(;N{%rj?TBmSo`{GWN|e;QC8h=6*5`py8g00qv>GzKaK z3IcTj-2mhRH37vzGHGc*GtYn|L4ZLh?CV3I`;$Fg978;gKb?BBtjR#2&DTjuQD>9* z7QMB(TetrH_Ame1OvZ^-Po&NfCam#r|J@tYy*q3BEAp#T*WAs}N$R~8Bb9k(+O?N+Z_Hc! zewJ+UQY|Y{hP$7G1?4(wWb@Wc@5r*V{?>Z^in`Uc=Y6v?ZqNRG$~Ua+_1Z7<4By;I z{#v&~n8kzj$f<|+4u4Ahc+3?|1ts@9 z&%Mc4Q}*a=-+I;Yc9!%R*T;`9Z|&=O{4ljAjQiTD8Gp^UuXKDj>rtZlyVq1N*Ak8#_H*SBrML2V*W^!Qa zvDZ-T!secPCeUkniAB-qvbYV*pAQ Mp00i_>zopr0KnQ6fdBvi literal 0 HcmV?d00001 diff --git a/doc/deploy/gplv3logo.png b/doc/deploy/gplv3logo.png new file mode 100644 index 0000000000000000000000000000000000000000..b06e0439d37fa474a344748203ef0930d9cfee9d GIT binary patch literal 2986 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 + + + + +Epple ][ + + + + + +
+
+
+
+
+epple2logo.png +
+
+
+
+
+

Introduction

+
+

Epple ][ is an emulator of the original APPLE ][ and APPLE ][ PLUS +computers from Apple, Inc. It +runs on Windows and Linux platforms, and is released under +GPLv3 + +GPLv3 +

+

It is written in C++ and is designed with cross-platform +portability in mind. It uses the SDL graphics library.

+
+
+
+

Features

+
+
    +
  • +

    +Cycle-accurate: emulates all MOS 6502 CPU cycles including “phantom reads” +

    +
    • +
  • +

    +Video display is synchronized with CPU +

    +
    • +
  • +

    +NTSC video signal emulation: all video quirks emulated accurately +

    +
    • +
  • +

    +Revision 0 motherboard (optional) +

    +
    • +
  • +

    +Multiple display types: monitor and TV emulation +

    +
    • +
  • +

    +Can run full-screen or in a window +

    +
    • +
  • +

    +640x480 resolution +

    +
    • +
  • +

    +Floating data bus, and video scanner +

    +
    • +
  • +

    +Cards: Disk ][, language, firmware, clock +

    +
    • +
  • +

    +Paddles (mouse emulates two paddles) +

    +
    • +
  • +

    +Cassette tape interface +

    +
    • +
  • +

    +PR#1 writes to standard output +

    +
    • +
  • +

    +Accurate keyboard emulation, including the repeat key +

    +
    • +
  • +

    +It even emulates the POWER light! +

    +
    • +
+
+
+
+

Screenshots

+
+
+

DOS 3.3 System Master boot

+
+
+dos330boot.png +
+
+

Here we’ve configured an Apple ][ plus, with a disk +controller in slot 6, and a language card in slot 0. +We’ve booted the DOS 3.3 System Master disk. It correctly +identifies the machine as an Apple ][ plus, and then +loads Integer BASIC into the language card. You can switch +between Applesoft and Integer BASIC by using the FP and +INT commands.

+
+
+

DOS 3.1 System Master on Revision 0 motherboard

+
+
+dos310rev0.png +
+
+

Here we’ve configured an Apple ][ (Integer BASIC ROMs), +with a Revision Zero motherboard, and a disk +controller (with 13-sector ROMs) in slot 6. With a +revision 0 motherboard, when the machine is powered-on, +the CPU doesn’t start actually running until you +manually press the RESET button. Also, the old Monitor +ROMs do not boot from the disk drives automatically; +you need to type C600G to boot. +We’ve booted the DOS 3.1 System Master disk and done a +catalog of it. As you can see, with a revision 0 motherboard, +the text is displayed in green and purple, which are also the +only two HIRES colors. Later revisions +of the motherboard added a “color burst killer” which is +active during text mode, so the text would be strictly white. +Two more HIRES colors, blue and orange, were also added in +later revisions.

+
+
+

PRODOS 1.1.1 boot

+
+
+prodos.png +
+
+

Here we’ve configured an Apple ][ plus with language card +and disk drive. We’re booting a PRODOS 1.1.1 disk.

+
+
+

Bishop’s Apple Split

+
+
+applesplit.png +
+
+

The October 1982 issue of Softalk +featured an article by Bob Bishop entitled +Have an Apple Split, which describes +in some detail the inner workings of the Apple ]['s video processing. Listings 1 and 2 from that +article show a short Applesoft program and assembly language subroutine that allow the Apple ][ +to have a screen split between text and graphics display. To achieve this on the EPPLE ][, +copy the following text and paste it into the emulator (at the Applesoft ] prompt). Since the +EPPLE ][ accurately emulates the video scanning and timing of the original Apple ][s, this +“split screen” technique works successfully. +The rest of the behavior described in the article (the floating data bus) is also emulated +faithfully by the EPPLE ][.

+
+
+
CALL -151
+
+300:8D 52 C0 A9 E0 A2 04 CD 51 C0 D0 F9 CA D0 F8 A9
+310:A0 A2 04 CD 50 C0 D0 F9 CA D0 F8 8D 51 C0 60
+
+E000G
+
+100 HOME
+
+200 FOR K = 0 TO 39
+210   POKE 1448+K, 14*16
+220   POKE 2000+K, 10*16
+230   COLOR = K+4
+240   VLIN 24, 45 AT K
+250 NEXT K
+
+300 VTAB 6 : HTAB 17
+310 PRINT "APPLE II"
+
+400 CALL 768
+500 GOTO 400
+
+RUN
+
+
+

Mysterious Pink Line

+
+
+pinkmystery.png +
+
+

Jim Sather’s book +Understanding the Apple II, +which was the primary +reference for the internal design of the EPPLE ][ emulator, describes the video +generation process of the Apple ][, in great detail, in Chapter 8. +On page 8-21 he shows a simple Applesoft BASIC program (shown below) +that shows an example of one of the hi-res idiosyncrasies on the Apple ][. +The program would logically draw three orange lines, but due to the +video cutoff and extension of half-dot shifted pixels, instead the right +line is brown, and there is a “mysterious pink line” (actually magenta) +on the far left of the screen. The EPPLE ][ faithfully emulates this behavior.

+
+
+
NEW
+
+10 HGR : HCOLOR = 5 : HPLOT 5,159 TO 5,0 TO 279,0 TO 279,159
+
+RUN
+
+
+

Split Screen HIRES/LORES colors

+
+
+splitcolors.png +
+
+

Jim Sather’s book +Understanding the Apple II, +shows an Applesoft BASIC +program and assembly language subroutine on pages 3-16 and 3-17 (reproduced +below) that produce the display shown here. The screen is split between HIRES +and LORES graphics by a timed loop that manipulates the screen switches. +(Press any key repeatedly to move the position of the split.)

+

Notice that the Apple ][ can actually produce more HIRES colors than are +documented in the standard Apple reference manuals. White, black, green, +purple, blue, and orange are normally documented, but by careful manipulation +of the high-bit (half-dot shift indicator) of the HIRES display byte, many +other colors can be produced. The additional colors match some LORES colors. +Also notice that the text at the bottom of the screen is colored green and +purple while in mixed text/graphics mode. This is because the “color +burst killer” circuit is not active while displaying graphics on the +Apple ][ machines.

+
+
+
CALL -151
+1F00:AC 54 C0 A0 27 20 27 1F
+1F08:AC 10 C0 AC 00 C0 30 F3
+1F10:69 01 29 01 AA BC 56 C0
+1F18:A2 08 20 31 1F A0 31 20
+1F20:27 1F 18 90 E6 D0 01 88
+1F28:88 EA D0 F9 60 48 68 EA
+1F30:EA A0 62 20 27 1F EA CA
+1F38:D0 F3 60
+
+E000G
+ 30 HGR : HOME : VTAB 21 : PRINT "1  7  D  2  8  E  B  4  5  A 3 6 C 9 F 8"
+ 40 DIM COLR(39), X(21)
+100 FOR A = 0 TO 39 : READ COLR(A) : COLOR = COLR(A) : VLIN 0, 39 AT A : NEXT A
+200 FOR A = 0 TO 21 : READ COLR(A) : READ X(A) : HCOLOR = COLR(A)
+210 HPLOT X(A), 0 TO X(A), 159 : NEXT A
+220 FOR A = 8319 TO 16383 STEP 128 : POKE A, 64 : NEXT A
+300 CALL 7936
+400 REM  LORES DATA
+410 DATA 1,0,7,7,0,13,13,0,2,2,0,8,8,0,14,14,0,11,11,0
+420 DATA 4,4,0,0,5,0,0,10,0,3,0,6,0,12,0,9,0,15,0,8
+500 REM  HIRES DATA
+510 DATA 4,0,3,20,4,21,3,41,4,42,7,62,7,83,7,104,3,105,7,125,3,126,7,159,3,161
+520 DATA 7,180,3,182,3,206,7,220,3,233,7,247,3,262,3,263,7,279
+
+RUN
+
+
+
+
+

Download

+
+
+ + + +
+Tip +Usable Apple ROMs (proprietary +
[You must respect the fact that the Apple System Software and Apple Disk Operating System (DOS) Software are proprietary software; they are copyright by Apple and/or others. This web page is not providing any advice as to the legality of any copying or downloading you may perform.]
) +are available at the Apple II Library.
+
+

The following software is licensed under +GPLv3.

+

Epple ][ Program: epple2.tar.gz

+

System ROM (Demo): epple2sys.tar.gz

+

Card ROMs (stdin/stdout/clock): epple2cards.tar.gz

+

See Building to build from sources.

+
+
+
+

What To Download

+
+
+

Epple ][ Program—The Hardware (Emulated)

+

The Epple ][ Program package is the emulator itself, which emulates the +Apple ][ or Apple ][ plus hardware, as well as the +peripheral card hardware. This is the main program, so you will +certainly need to download this package. To have a full functioning emulator, +you will also need System ROMs and Card ROMs, as described in the following +sections.

+
+
+

System ROMs—The Main System Firmware (Demo or Real)

+

Since the Epple ][ program emulates only the hardware, you will also need to download some system software +for it to run. This is commonly called “firmware” or “ROMs,” because it is stored in the +read-only memory area of the emulated system. The original system software on the +Apple ][ machines is copyright by Apple, and is proprietary. If you own an actual +Apple ][ or Apple ][ plus machine, you can copy
[disclaimer]
 the firmware +from it ($D000-$FFFF) (into a file on your PC) and use it. Alternatively, you can +download
[disclaimer]
 the firmware images from the Apple II Library.

+

If you do not want to download the proprietary firmware, you can still use the emulator (albeit +in a restricted manner) with the free (GPLv3) System ROM (Demo) package. Download +the file for your platform and +install as appropriate. You can choose either binary format (ready to run), or source if you want +to assemble it yourself (using the xa Assembler). +The Demo System ROM only provides commands to dump or set memory bytes, +or run a program in memory. It is not compatible with any Apple software, nor can it read from disks. +It’s just a free simple demo system to make the emulator do something reasonable.

+
+
+

Card ROMs—The Peripheral Card Firmware

+

If you are going to use the Disk ][ Controller peripheral card (which you almost certainly will, if +you want to read any floppy disk images), you will need to have to original ROMs from Apple. +No demo of the Disk ROMs are provided here; you will need to +use the original ROMs, which can be obtained from an original machine (by copying
[disclaimer]
 +it from $C600-$C6FF into a file on the PC), or by downloading
[disclaimer]
 it +from the Apple II Library. +(And, of course, you will need the real Apple System ROM, as noted in the previous section, +not the Demo System ROM.)

+

If you are using any of the clock, the standard output, or the +standard input peripheral cards, you will need to download their firmware as well, +which are contained in the Card ROMs package. You can choose either binary format +(ready to run) or source format (to assemble it yourself(using the +xa Assembler). +If you are not going to use the stdin, stdout, or clock +cards, then you do not need to download this package.

+
+
+
+
+

Configuration

+
+

The Epple ][ Emulator is most useful when properly configured. +After downloading and installing the Epple ][ Program, some System ROM (demo or real), and +optionally the peripheral card ROMs you want to use, you will need to configure the program. +Configuring is concerned primarily with telling the program what peripheral cards to use, +and where the ROM files are located (and what memory addresses to load them at).

+
+

epple2.conf

+

The default configuration file for +the Epple ][ emulator is:

+
+
+
/etc/epple2/epple2.conf
+
+

For Windows, the file will be:

+
+
+
C:\Program Files\Epple2\etc\epple2\epple2.conf
+
+

The configuration file could be in a different location depending upon how +the distribution package is built.

+

You can specify a different configuration file for the emulator to use by +specifying its name as the argument when running the epple2 program.

+

The format of the configuration file is just lines of commands. +Comments begin with a hash # character, and continue to the end of the line.

+
+
+

Firmware

+

Firmware, commonly called ROM images or ROMs, will need to be loaded +into the emulated ROM areas of the emulated Apple +in order for it to be able to boot the emulated Apple machine. +The firmware available is described above. +Once the firmware image +files are installed on your computer, you can use the import +command in the configuration file to load the image files into the emulator.

+
+
+

Peripheral Cards

+

Another primary concern for configuring the Epple ][ is the insertion of +peripheral cards into the Apple’s slots. The most useful card is probably the +Disk ][ Controller card; you will need to insert one of these cards if you want +to be able to load floppy disk images into the emulated Apple. The various +types of cards available are described on the peripheral cards section. +You can use the slot command in the configuration file to insert +them into the Apple’s slots.

+
+
+

Sample Configuration Files

+

There are a number of configuration files provided with the distribution for +your convenience. They provide various common configurations of machines. +You can use one of these files directly, by specifying its path as the argument +to the program, or as a starting point for you own configuration file. These sample +files are in the same location as the default epple2.conf file.

+

The Epple ][ Emulator can actually be run without a configuration file at all. +In this case, you will be able to “power on” the Apple and see the low-resolution +graphics display showing random RAM data. The system will not run, because +there is no firmware loaded, but the emulator will otherwise be functional.

+
+
+
+
+

User Manual

+
+
+

Overview

+

Epple ][ (the Emulated Apple ][ is a free (as in GPLv3), cross-platform +(Windows, Linux) emulator of the Apple ][ and Apple ][ plus computers +from Apple, Inc. It strives for accurate emulation of the original machines, +with a few extra features added.

+
+
+

Commands

+

slot import load unload save cassette revision

+
+

slot

+

The slot command inserts a card into a peripheral slot of the emulated Apple.

+
+
+
slot <slot> <card>
+
+

<slot> Slot number, 0 through 7, to insert the card into.

+

<card> The type of card to insert into the slot:

+
    +
  • +

    +language +

    +
    • +
  • +

    +firmware +

    +
    • +
  • +

    +disk +

    +
    • +
  • +

    +clock +

    +
    • +
  • +

    +stdout +

    +
    • +
  • +

    +stdin +

    +
    • +
  • +

    +empty +

    +
    • +
+

The slot command inserts a card into a peripheral slot. For example:

+
+
+
slot 0 language
+
+

inserts a language card into slot zero. Use empty to remove a card:

+
+
+
slot 0 empty
+
+
+ + + +
+Note +The emulated Apple should be powered off before inserting or removing cards.
+
+
+
+

import

+

The import command imports a binary image file into the emulated Apple’s memory.

+
+
+
import slot <slot> { rom | rom7 | rombank } <base> <file-path>
+import motherboard { rom | ram } <base> <file-path>
+
+

<slot> Slot number, 0 through 7, of peripheral card to import the binary image into.

+

<base> Base address in hexadecimal within the given memory area at which to start loading the binary image.

+

<file-path> Path of the binary image to import.

+

The import command reads the binary image byte-for-byte from the given file-path +into an area of memory in the emulated Apple. You can load into either the motherboard or +a card in one of the slots. For the motherboard, you choose the RAM or ROM area. For a card +in a slot, you can choose either the normal ROM, the bank-switched ROM, or the so-called +“seventh ROM” area.

+

You also have to specify the base address within the specific memory +area at which the image file will be loaded. Note that the base address is specified as the offset +within the specific memory area, and not necessarily as the actual memory address as seen +by the Apple. So for motherboard ROM, for example, specifying a base as 2DED will cause the +image to be loaded at offset 2DED in the ROM, which will be addressed by the Apple at +memory address $FDED (because motherboard ROM “starts” at address $D000).

+

For peripheral cards, the ROM will be seen at locations $Cs00-$CsFF, where s is the slot +number (1 through 7). The “seventh ROM” can be seen as locations $C800-$CFFF; Jim Sather +describes this functionality in +Understanding the Apple II, +on page 6-4, section “The Seventh ROM Chip.” The EPPLE ][ emulator handles this processing correctly. A card can +also have bank-switched ROM, which will show up at addresses $D000-$FFFF when switched in +(stealing that address range from motherboard ROM… see +Understanding the Apple II, +p. 5-26 “The 16K RAM Card”).

+
+
+

load

+

The load command loads a (nibble) floppy disk image into one of the emulated disk drives.

+
+
+
load slot <slot> drive <drive> <file-path>
+
+

<slot> Slot number, 0 through 7, of Disk ][ controller card to load the nibble image into.

+

<drive> Drive number, 1 or 2, of the disk drive on the controller card to load the nibble image into.

+

<file-path> Path of the nibble floppy disk image to import.

+

The load command will load a nibble image into a disk drive. Specify the slot that +contains a Disk ][ controller peripheral card, and specify which drive number (1 or 2).

+
+ + + +
+Note +The floppy disk image MUST be a NIBBLE DISK IMAGE. +Other formats (for example, DOS order, .do, PRODOS order, +.po, .dsk, or anything else) must first be converted to nibble format. A nibble image contains +all 35 tracks, in order 0-36, each track being 6656 ($1A00) bytes long. Nibble image files +will generally have a filetype of .nib.
+
+

The best floppy disk image conversion tool I’ve found is CiderPress, +for Windows (but it supposedly runs under Wine on Linux, too). Thanks to Andy McFadden.

+
+
+

unload

+

The unload command removes a floppy disk image from one of the emulated disk drives.

+
+
+
unload slot <slot> drive <drive>
+
+

<slot> Slot number, 0 through 7, of Disk ][ controller card to which the drive is attached.

+

<drive> Drive number, 1 or 2, of the disk drive on the controller card to remove the floppy disk image from.

+

The unload command removes the disk from the specified slot and drive.

+
+ + + +
+Warning +If the disk has been modified but not saved, the modifications will be DISCARDED.
+
+
+
+

save

+

The save command saves changes made on an emulated floppy disk back to the original image file.

+
+
+
save slot <slot> drive <drive> <file-path>
+
+

<slot> Slot number, 0 through 7, of Disk ][ controller card to which the drive is attached.

+

<drive> Drive number, 1 or 2, of the disk drive on the controller card to save.

+

<file-path> Path of the nibble floppy disk image to import.

+

The save command saves any changes that the emulated Apple ][ has made to the floppy +disk image. It is important to note that the emulator operates on the image only in memory, and does +not immediately write changes back to the real file. You need to issue the save command +in order to write changes back to the file. Note that the emulator will display a asterisk * +next to the file-name of a disk image if it has any unsaved changes.

+
+
+

cassette

+

The cassette command performs various operations of the emulated cassette tape.

+
+
+
cassette new <file-path>
+cassette load <file-path>
+cassette unload
+cassette rewind
+cassette save
+
+

<file-path> File path of the (special format) cassette tape image file.

+

The cassette command allows the user to control the emulated cassette tape player. +See Cassette for more information about operating the emulated +cassette player and cassette tape image files.

+
+
+

revision

+

The revision command specifies which revision of Apple ][ motherboard to use.

+
+
+
revision <rev>
+
+

<rev> Revision number of the motherboard. Currently, only two values make any difference in behavior: 0 or 1.

+

The revision command chooses which revision of the Apple ][ motherboard to +use. The only revisions that make any difference (for now, at least) are 0 or 1. Zero +is the original (now quite rare) version of the motherboard, that only had two hi-res +colors (green and purple), and always displayed text with green and purple fringes. +Revision 1 and later motherboards are the ones we are more familiar with.

+
+
+
+

Display

+

The orignal Apple ][s didn’t come with a display. The user needed to use either a standard +television, or a monitor, to see the computer’s output. The EPPLE ][ emulates a variety of +displays; you can cycle between the different types using F2. +There are two major types of displays: televisions and monitors. Monitors generally have +higher quality (sharper) displays. The displays show the normal visible area of the NTSC +video signal generated by the emulated Apple ][ machine.

+
+

Monitors

+

The emulator provides a color monitor, and three monochrome monitors (white, green, and orange). +These emulate standard, no-frills NTSC monitors. The most noticeable characteristic of monitors +is the horizontal display of pixels. Monitors react faster than TVs, so two adjacent pixels will +not merge together; both will be distinctly visible, with blackness between them. For example, +type in the following Applesoft command, then cycle through the display types. The monitors +will show thin, vertical, green lines; TVs will show continuous horizontal lines.

+
+
+
GR : COLOR=4 : HLIN 10,20 AT 10
+
+
+
+

Televisions

+

There are two types of television displays, referred to as “old” and “new.” Each has color and +monochrome (commonly known as “black and white”) varieties. Televisions react more slowly to +changes in the incoming video signal than monitors do, and as a result, horizontal pixels will +merge together, forming a more uniform appearance. The “new” color TV display uses the pre-defined +color pallette (described below under “Colors”), and the black and white TV uses the same +pallette, but fully desaturated. The “old” color TV is the most interesting. It emulates the +signal decoding circuitry of a real television. This includes separating out the “chroma” portion +of the incoming NTSC video signal using a filter algorithm, and calculating the color to display. +It does not use the pre-defined colors.

+
+ + + +
+Note +This mode is very CPU intensive, so your computer (that is, the one that EPPLE ][ is running on) +may not be able to run fast enough to run at the speed of the original Apple ][. The Apple ][ CPU +runs at about 1 MHz, but the video generator runs at 14 MHz; so the inner-most loop in the +EPPLE ][ must run 14 million times per second to keep up.
+
+
+
+

Colors

+

The color palatte used for the +color monitor and new color TV is pre-defined, and was determined through observation of a real +Apple ][ machine on a standard TV, the colors being matched by eye. The old color TV, however, +uses algorithms to calculate the colors it displays.

+
+
+

Scan Lines

+

NTSC displays (TVs or monitors) usually receive signals that are interlaced. However, the +Apple ][ doesn’t generate interlaced screens. This causes blank rows between each displayed +row of pixels. The EPPLE ][ emulates this behavior, but also allows you to “fill in” these +black rows with a copy of the row above it, for a more continuous display (vertically). Use +the F4 key to toggle between these two modes.

+
+
+

Resolution

+

The Apple ][s are commonly documented as having a resolution of 280x192 pixels, and to an +extent this is true. Vertically there are 192 pixels, but since there is no interlacing, +it is more accurate to display them with one blank space between each. So the EPPLE ][ has +two times 192, or 384, vertical pixels in its display. Horizontally there are 280 pixels, but +each could also be shifted right one-half dot, allowing for two times 280, or 560, different +horizontal displayable positions. To emulate this, the EPPLE ][ shows each emulated pixel as +two pixels wide, and displays an emulated half-dot shift as an actual one pixel shift. So the +display area of the EPPLE ][ is 560x384. There is an informational area below and to the +right of the emulated display that shows various statistics of the emulator. So the total screen +area used by the EPPLE ][ is a standard 640x480 pixels.

+
+
+

Full Screen

+

The EPPLE ][ can run in either full-screen mode, or within a window. Use the F3 key to toggle +between the two.

+
+
+

Informational Area

+

The area at the bottom and the right of the EPPLE ][ display show various information about +the emulator.

+
    +
  • +

    +POWER light +

    +
    • +
  • +

    +current cards in SLOTS +

    +
    • +
  • +

    +CASSETTE tape information +

    +
    • +
  • +

    +emulated CPU speed (MHz) +

    +
    • +
  • +

    +function-keys help +

    +
    • +
+
+
+
+

Keyboard

+

The EPPLE ][ emulates the original Apple ][ keyboard. The original Apple ][ +keyboard had symbols in different places than current common PC keyboards. For +example, Shift-2 on the Apple ][ produces a double quote, but on a PC keyboard +it produces an at-sign. For ease of typing, the EPPLE ][ emulator does not +mimic the positions of the original keys, but rather mimics the symbols on +the current PC keyboard. So, for example, if you type Shift-2 on the PC +keyboard into the EPPLE ][, it produces an at-sign, as you would normally expect.

+

The Apple ][ keyboard didn’t produce lower-case letters; neither does the emulator. +Also, the Apple couldn’t produce an opening square bracket ([), braces, vertical +bar, backslash. There were no up- or down-arrow keys. You cannot type these into +the emulator, either. There are other, unusual, cases that are emulated correctly, +as well, such as typing Control in conjunction with a number key simply produces +that number. So typing a Control-3 is the same as just typing a 3. Also, typing +Shift-Control-2 produces the NUL character (ASCII $80).

+

The Apple ][ keyboards didn’t automatically repeat typing characters when a +key was held down. Instead, the user would hold down the REPT (“repeat”) key +while holding down the key that was to be repeated. On the EPPLE ][, this +behavior is emulated, and the F10 key is used as the REPT key.

+

The Apple ][ had no keyboard buffer (actually, it had a buffer of one character). +So if you typed several characters on the keyboard before the currently running +program had a chance to read them, they would get lost (only the final character +typed would be remembered). This behavior can be +toggled on or off in the EPPLE ][. By default, the EPPLE ][ will buffer up any +characters you type and deliver them to the emulated machine when it asks for +them. However, the Apple program must be written properly to allow this to work. +Some Apple ][ programs (like maybe some games) may not work correctly in this +respect, so you may want to turn off buffering in these cases. With buffering +turned off, the EPPLE ][ accurately emulates the original Apple ][. Use the F12 +key to toggle the keyboard buffering. Note that pasting from the clipboard (with +the Insert key) will most definitely cause keys to be lost if the keyboard +buffer is turned off. So if you have a big Applesoft program in the clipboard +and you want to paste it into the EPPLE ][ correctly, make sure the keyboard +buffer is on.

+
Special Keys
    +
  • +

    +F1 Emulates the POWER switch on the back of the Apple ][. +

    +
    • +
  • +

    +F2 Cycles among different display types (TV, monitor, etc.). +

    +
    • +
  • +

    +F3 Toggles between full-screen or window display. +

    +
    • +
  • +

    +F4 Toggles between showing scan lines on the display, or duplicating +each scan line to the following line, to fill-in the otherwise black line. +

    +
    • +
  • +

    +F5 Go to “command entry” mode. +

    +
    • +
  • +

    +F10 Emulates the REPT key. +

    +
    • +
  • +

    +F11 Toggles between running the emulator at authentic speed +(1.02 MHz CPU), or as fast as possible. +

    +
    • +
  • +

    +F12 Toggles the keyboard buffer. +

    +
    • +
  • +

    +Break Emulates the RESET key. +

    +
    • +
  • +

    +Insert Pastes characters from the clipboard into the emulated Apple +(as if they had been typed on the keyboard). +

    +
    • +
  • +

    +Print Screen Save a bitmap file of the current EPPLE ][ screen. +The file will be in the default directory, named ep2_YYYYMMDDHHMMSS.bmp. +

    +
    • +
  • +

    +End Quit the EPPLE ][ program, immediately! +

    +
    • +
+
+ + + +
+Warning +If you have modification to any floppy images or cassette images, and you +press the End key, you will LOSE all those changes, unless you +save them first. See Commands for the save command.
+
+
+
+

Peripheral Cards

+
+

Disk ][ Controller

+

The Disk ][ Controller card emulates the floppy disk controller card and associated +disk drives in the original Apple ][ systems. In the emulator, each card has two +drives attached to it, referred to as drive 1 and drive 2. The floppy disks +themselves are represented by a “nibble” image of the contents. The +emulator emulates the hardware, but to be of any use, you will need to provide +the firmware ROM code.

+

To use a disk card and drives, add these lines to your epple2.conf file, for example:

+
+
+
slot 6 disk
+import slot 6 rom 0 /usr/lib/apple2/dos3x/16sector/controller/disk2.ex65
+
+

The first line uses the slot command to +insert a disk contoller card into slot 6, which is the standard +slot used for disk cards. The next line uses the import +command to load the card’s ROM with the disk controller +firmware. This firmware is known as the “bootstrap” or “P5” ROM code. +It is seen by the Apple ][ at memory addresses $Cs00-$CsFF, where s is the +slot number (so in the common case of the card being in slot 6, the ROM is +at $C600-$C6FF). The firmware is copyright by Apple, and is available from +the Apple II Library.

+

You can also load a floppy disk image (nibble format) into the drive,either by putting +the load command into the epple2.conf file, or by using the command prompt +in the emulator (F5 key). For example, you could load the DOS 3.3 system master into +slot 6, drive 1, with this command

+
+
+
load slot 6 drive 1 /usr/lib/apple2/dos3x/16sector/disks/dos330/clean330sysmas.nib
+
+
+
+

Language

+

The language card emulates an Apple 16K RAM card, commonly called a Language Card. +To use a language card, add this line to your epple2.conf file:

+
+
+
slot 0 language
+
+

Note that DOS and ProDOS will make use of a language card only if it is in slot zero.

+

The language card has RAM at addresses $E000 through $FFFF, as well as two banks of RAM +at addresses $D000 through $DFFF. A program switches between these RAMs and/or the +motherboard ROM by using the I/O switches at $C080 through $C08F.

+

The information area of the Epple ][ will show the current state of the +language card as follows:

+
    +
  • +

    +R Read from card RAM (vs. motherboard ROM) +

    +
    • +
  • +

    +W Write to card RAM (vs. write-disabled) +

    +
    • +
  • +

    +B1 Use $D000 bank 1 +

    +
    • +
  • +

    +B2 Use $D000 bank 2 +

    +
    • +
+

An overview of the I/O switches that control the language card +is provided by Jim Sather in +Understanding the Apple II, +p. 5-30, Table 5.4, as follows:

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BANK2 BANK1 ACTION

C080

C088

WRTCOUNT = 0*, WRITE DISABLE

READ ENABLE

C084

C08C

RC081

RC089

WRTCOUNT = WRTCOUNT + 1*

READ DISABLE

RC085

RC08D

WC081

WC089

WRTCOUNT = 0*

READ DISABLE

WC085

WC08D

C082

C08A

WRTCOUNT = 0*, WRITE DISABLE

READ DISABLE

C086

C08E

RC083

RC08B

WRTCOUNT = WRTCOUNT + 1*

READ ENABLE

RC087

RC08F

WC083

WC08B

WRTCOUNT = 0*

READ ENABLE

WC087

WC08F

+

* Writing to expansion RAM is enabled when WRTCOUNT reaches 2.

+
+
+

Firmware

+

The firmware card emulates a (modified) Apple Firmware card. +The firmware card is simply an alternate ROM, at addresses +$D000 through $FFFF, that is switched using the I/O switches +at addresses $C080 through $C08F. In order to make use of the +firmware card, you will need to load the ROM with a binary image +from a file on disk. For example, to insert an Integer BASIC +firmware card into the emulator, add these lines to your +epple2.conf file:

+
+
+
# Firmware card with Integer BASIC and old Monitor
+slot 0 firmware
+import slot 0 rombank 1000 /usr/lib/apple2/system/intbasic/intbasic.ex65
+import slot 0 rombank 2425 /usr/lib/apple2/system/other/other.ex65
+import slot 0 rombank 2800 /usr/lib/apple2/system/monitor/apple2/monitor.ex65
+
+

For an Applesoft BASIC firmware card, use these:

+
+
+
# Firmware card with Applesoft BASIC and Autostart Monitor
+slot 0 firmware
+import slot 0 rombank 0000 /usr/lib/apple2/system/applesoft/applesoft.ex65
+import slot 0 rombank 2800 /usr/lib/apple2/system/monitor/apple2plus/monitor.ex65
+
+

Note that the addresses specified in the epple2.conf file for the +rombank are based on the beginning of the bank ROM itself. For example, specifying +1000 (which is 1000 hex) represents the final memory address of $E000, because +the bank ROM is always based at address $D000.

+

The idea is that you would load your motherboard with, for +example, Applesoft BASIC and the Autostart Monitor ROM (to emulate +an Apple ][ plus), and then install a firmware card with Integer +BASIC and the old Monitor. Booting with DOS 3.3, then, would allow +you to type FP to use Applesoft BASIC, or INT to switch to Integer BASIC.

+

Note that DOS and ProDOS will make use of a firmware card only if it is in slot zero.

+

Jim Sather, in +Understanding the Apple II, +on pages 6-18 through 6-21, explains +how to modify a firmware card to allow independent switching of the $F800-$FFFF +ROM memory. This area is occupied by the Monitor, so it is primarily +intended to allow the user to switch between the old Monitor and the Autostart +Monitor, independent of switching between Integer and Applesoft BASIC. The EPPLE ][ +firmware card emulates this behavior.

+

The information area of the EPPLE ][ will show the current state of the +firmware card as follows:

+
    +
  • +

    +D Read from firmware card $D000-$F7FF (vs. motherboard BASIC ROM) +

    +
    • +
  • +

    +F8 Read from firmware card $F800-$FFFF (vs. motherboard Monitor ROM) +

    +
    • +
+
+
+

Clock

+

The clock card emulates a ProDOS-compatible real-time clock card for the Apple ][. +To use a clock card, you will need to configure the EPPLE ][ to insert one into +a slot, typically slot 4. You will also need to load the card with its ROM code, +which is provided with the emulator in the clock.ex65 file. +For example, add this to your epple2.conf file:

+
+
+
slot 4 clock
+import slot 4 rom 0 /usr/lib/epple2/cards/clock.ex65
+
+

Of course you may need to adjust the path for your particular system.

+

To verify that the clock card is working correctly, you can run the following Applesoft +program to retrieve the current time from the clock card and print it. +This program assumes the card is in slot 4.

+
+
+
NEW
+
+10 CALL -15360 : REM $C400 SLOT 4 ENTRY POINT
+20 A = 512 : REM $0200 INPUT BUFFER
+30 C = PEEK(A)
+40 IF C < 160 THEN 99
+50 PRINT CHR$(C);
+60 A = A+1
+70 GOTO 30
+99 END
+
+RUN
+

The card returns data (into the GETLN input buffer at $200) in +the following format:

+

mm,ww,dd,hh,nn,ss,000,yyyy,Time Zone,v

+
    +
  • +

    +mm Month, 01-12 +

    +
    • +
  • +

    +ww Weekday, 00=Monday… 06=Saturday +

    +
    • +
  • +

    +dd Day, 01-31 +

    +
    • +
  • +

    +hh Hour, 00-23 +

    +
    • +
  • +

    +nn Minute, 00-59 +

    +
    • +
  • +

    +ss Second, 00-61 +

    +
    • +
  • +

    +000 Milliseconds; always zero +

    +
    • +
  • +

    +yyyy Year, e.g., 2008 +

    +
    • +
  • +

    +Time Zone time zone string (could contain lower-case characters, + which won’t display correctly) +

    +
    • +
  • +

    +v Daylight Saving Time in effect, 0=no, 1=yes +

    +
    • +
+

Note that only mm,ww,dd,hh,nn fields are used by ProDOS. The other +fields, ss,000,yyyy,Time Zone,v, are an EPPLE ][ extension. Also note +that ProDOS was not designed to work for years past 2007, so +ProDOS will show the incorrect year, but the other fields will be accurate. +I believe patches exist for ProDOS to fix this.

+
+
+

Standard Input

+

The “standard input” card doesn’t emulate a real piece of hardware; rather, it +reads characters from standard input (stdin) (of the EPPLE ][ emulator).

+

To use a standard input card, add these lines to your epple2.conf file:

+
+
+
# IN#2 reads from standard input
+slot 2 stdin
+import slot 2 rom 0 /usr/lib/epple2/cards/stdin.ex65
+
+

That will insert a stdin card into slot 2, and then load its +ROM image into the card. +The stdin ROM is provided with the EPPLE ][ distribution.

+

For example, if you have a stdin card installed in slot 2, start +the EPPLE ][ emulator from the command line, and at the Applesoft +prompt, type IN#2. Then you can switch back to the +command shell, and whatever you type will be fed into the emulated +Apple. Use RESET or IN#0 to go back to normal.

+
+
+

Standard Output

+

The “standard output” card doesn’t emulate a real piece of hardware; rather, it acts +similar to a printer card, but instead of sending characters to a printer, it sends +them to standard output (stdout) (of the EPPLE ][ emulator).

+

To use a standard output card, add these lines to your epple2.conf file:

+
+
+
# PR#1 prints to standard output
+slot 1 stdout
+import slot 1 rom 0 /usr/lib/epple2/cards/stdout.ex65
+
+

This will insert a stdout card into slot 1 (which is the typical +slot for a printer card), and then load its ROM image into the card. +The stdout ROM is provided with the EPPLE ][ distribution.

+

For example, if you have a stdout card installed, at the Applesoft +prompt, type PR#1. Whatever you type next will be +echoed to standard output. Type PR#0 to stop echoing.

+
+
+
+

Cassette Tape Interface

+

The Apple ][ and Apple ][ plus machines had the ability to save and load binary +data to and from cassette tape. The user would attach a standard cassette tape +recorder to the jacks on the back of the Apple ][, and use the monitor R and W +commands, or the Applesoft BASIC commands LOAD and SAVE, to read and write data +on the cassette tape. The user would have to press the play and/or record buttons +on the player at the right time.

+

The Epple ][ emulates the cassette interface, using a file to hold the +recorded portion of the tape. The file will grow in length as necessary +to hold data that the emulated Apple is writing to the “tape.” +The emulator will not overwrite existing data on a tape image. +The emulator will automatically “press” the play or record buttons that +would have been necessary when using the original machine.

+
+

Commands

+

cassette new <file-path>

+

This creates a new empty file (on the host computer) that represents a cassette tape image. +The file must not already exist.

+

cassette load <file-path>

+

This loads an existing file (from the host computer) containing a cassette tape image. +The tape is automatically positioned at its beginning (fully rewound).

+

cassette unload

+

This removes the file from the cassette tape. Note that you must manually save +the file using the cassette save command (described below).

+
+ + + +
+Warning +Unloading an unsaved file will lose any changes made to the file, without warning.
+
+

cassette rewind

+

This command “rewinds” the cassette tape, positioning it at the beginning +of the tape (for subsequent reading). You do not need to rewind the tape +before saving or unloading it, of course.

+

cassette save

+

This command saves the changed tape to the file. Note that the display will show +an asterisk * next to the file name if there are unsaved changes that need to +be saved. Unsaved changes will be lost without warning if the file is unloaded +or if you quit the program.

+
+
+

Example of Saving to Tape

+

Start up the emulator with Applesoft ROMs for this tutorial. +Enter a simple Applesoft program, just as an example, that we +are going to save to a cassette tape image file.

+
+
+
]NEW
+
+]10 PRINT "HELLO"
+
+]20 END
+
+]LIST
+
+10  PRINT "HELLO"
+20  END
+
+]RUN
+HELLO
+
+]
+

We first need to load a tape image file into the cassette machine. +Enter command mode by pressing F5, then make a new tape +image file.

+
+
+
command: cassette new hello.tap
+
+

This will create a new, empty tape file image named hello.tap +in the current default directory. (We could have specified a full path +name for the file if we wanted to place it in a different directory.) +Notice that the emulator now displays the name of the tape image file, +along with the position and length of the tape image, which is now 0/0.

+

Next, we tell Applesoft to save the program to the cassette. For this, +we just use the SAVE command. Note that this is not the +DOS SAVE command; the DOS command has a file name after +SAVE. We just use SAVE with no file name.

+
+
+
]SAVE
+
+]
+
+

It will take 10 seconds or so for it to save. Notice that the +current position of the tape is counting up as the Apple saves +the program. When it is finished, you need to save the changes +to the file. Press F5 and enter the emulator command to save +the tape image file.

+
+
+
command: cassette save
+
+

We can now unload the file from the emulator (which is like ejecting +the tape from the cassette player).

+
+
+
command: cassette unload
+
+
+
+

Example of Loading from Tape

+

To load the saved program (from the previous section) into the Apple again, +we will need to first load the tape image file back into the cassette machine. +Press F5 to enter command mode and load the image file.

+
+
+
command: cassette load hello.tap
+
+

This will load hello.tap (in the current default directory). Notice the +emulator now displays the name of the tape image file, along with the +position and length of the tape image, which in this case is 0/33481.

+

Next, we tell Applesoft to load the program from the cassette. For this, +we just use the LOAD command. Note that this is not the +DOS LOAD command; the DOS command has a file name after +LOAD. We just use LOAD with no file name.

+
+
+
]LOAD
+
+]
+
+

It will take 10 seconds or so for it to load. Notice that the +current position of the tape is counting up as the Apple loads +the program. When it is finished, the program will be loaded.

+
+
+
]LIST
+
+10  PRINT "HELLO"
+20  END
+
+]RUN
+HELLO
+
+]
+
+
+

Tape Image File Format

+

The format of the tape image file is unique to the Epple ][ +It is stored in a low-level format that represents the waveform that the Apple writes +to the cassette tape.

+

The file is a binary format. Each byte in the file represents the length of one half of one cycle +(of voltage level variation) written to the tape. The length is in 10-microsecond units.

+

For example, a tape image file might have the following binary bytes (in decimal): +65 65 65 65 65 20 25 50 50 25 25 25 25 50 50 +Since each byte represents a 10-microsecond unit, these bytes represent the following +half-cycle lengths in microseconds: +650 650 650 650 650 200 250 500 500 250 250 250 250 500 500 +The meaning of these half-cycle lengths to the Apple is as follows:

+
+
+
|-------HEADER------|--sync-|-1-bit-|-0-bit-|-0-bit-|-1-bit-|
+|                   |       |       |       |       |       |
+|650 650 650 650 650|200 250|500 500|250 250|250 250|500 500|
+
+

where HEADER is a header section the Apple writes (to skip any +unrecordable leader section on a real cassette tape); sync is a +synchronization cycle; and the subsequent cycles are the actual +bits of data saved on the tape. A 500-microsecond cycle (which +is stored in the file as two 250 microsecond half-cycles) +represents a zero bit, and a 1-millisecond cycle (which is +stored in the file as two 500 microsecond half-cycles) +represents a one bit.

+
+
+
+

Paddles

+

The Epple ][ provides two paddles to the Apple ][ machine. +One paddle is controlled by moving the mouse left and right; the other +paddle is controlled by moving the mouse up and down. The paddle buttons +are emulated by the mouse buttons (left and right click).

+

In +Understanding the Apple II, +on page 7-33, Jim Sather describes soldering fixed resistors across a game connector +to create two real-time clock references. This is emulated by the Epple ][. Paddle timers 2 and 3 +are 100-microsecond and 1-millisecond references, respectively.

+
+
+

Speaker

+

The Apple ][ could generate sound via a speaker that generated square wave +audio. A program could read memory location $C030 to toggle the speaker and +generate a “click” sound.

+

The Epple ][ emulator will generate sounds from the emulated Apple and +send them to the audio device. It generates 8-bit mono sound, with a 22,050 Hz +sampling rate.

+
+
+
+
+

Building From Source

+
+

The Epple ][ Emulator is written in C++, and can be built +using the standard make program.

+

The primary dependency is +Simple DirectMedia Layer (SDL). +Your linux distribution may provide a package. Or else +you can download it directly from SDL’s web site. In +either case, be sure to install the “Development Libraries” +for your particular platform.

+
+

Debian Linux Example

+
+
+
sudo apt-get install build-essential libsdl1.2-dev  # 1
+cd
+mkdir epple2
+cd epple2
+wget http://mosher.mine.nu/epple2/download/epple2-latest.tar.gz  # 2
+tar xzvf epple2-1.0.tar.gz
+mkdir build  # 3
+cd build
+../epple2-1.0/configure  # 4
+make  # 5
+sudo make install  # 6
+
+ + + + + + +
1 +Install dependencies: gcc, make, SDL +
2 +Retrieve the latest Epple ][ source distribution +
3 +Use this directory for a VPATH-style build +
4 +Run one-time configuration script for your system. Use --help for more information. +
5 +Compile and link. Program will be src/epple2 +
6 +Install into standard system directories +
+
+
+

Windows/MSYS Example

+
+

Install MinGW/MSYS

+

Install MSYS into C:\msys\

+

Install MinGW into C:\msys\mingw\

+

For more information on MinGW and MSYS, see http://www.mingw.org/.

+
+
+

Install SDL

+

At http://www.libsdl.org/ find the download page. +Download the “Development Libraries” for Win32/mingw, for example:

+

SDL-devel-1.2.13-mingw32.tar.gz (Mingw32)

+

and save it to your MSYS home directory (for example, C:\msys\home\Administrator). +Run MSYS, and at the bash prompt, go to your home directory and +untar the SDL archive to your home directory:

+
+
+
$ cd
+$ tar xzvf SDL-devel-1.2.13-mingw32.tar.gz
+

Then follow the instructions to install SDL, for example:

+
+
+
$ cd SDL-1.2.13
+$ make native
+
+
+

Untar Epple ][ Source

+

Download the Epple ][ Source Distribution +and save it to your MSYS home directory (for example, C:\msys\home\Administrator). +Run MSYS, and at the bash prompt, go to your home directory and +untar the epple2 source distribution tar file. For example:

+
+
+
$ cd
+$ tar xzvf epple2-1.0.tar.gz
+
+
+

Build Epple ][

+

Then build as follows. I recommend doing a VPATH build, +where you build into a different directory than the source +directory. To accomplish this, create a new directory for +building, somewhere, such as:

+
+
+
$ cd
+$ mkdir buildepple2
+$ cd buildepple2
+

Then run configure from there. For the MSYS build to work, +you need some extra parameters to the build, and you could +also add some compiler options to optimize the build. For +example (from the buildepple2 directory you just created):

+
+
+
$ ~/epple2/configure --prefix= \
+CXXFLAGS="-I/usr/include -O4 -msse3" \
+CFLAGS="-I/usr/include" \
+LDFLAGS="-L/usr/lib -mconsole -mthreads -mno-cygwin"
+$ make
+

If all goes well, it will build without any errors. +If you get errors about not finding SDL.h, make sure +SDL is installed, and make sure the configure command +is correct. (If you just run configure without the +options shown above, you will get this error at build time.) +The result of the build (on Windows platform) is

+

installer/epple2.msi

+

which is an installable file for Windows. To install +epple2, just double-click on this file from Explorer.

+
+

Copyright © 2009,2012, by +Christopher A. Mosher, +Shelton CT, USA.

+

+Creative Commons Attribution-Noncommercial-Share Alike 3.0 USA License +

+

This web site is licensed under the +Creative Commons Attribution-Noncommercial-Share Alike 3.0 USA License.

+
+
+
+
+
+
+ + + diff --git a/doc/deploy/make.png b/doc/deploy/make.png new file mode 100644 index 0000000000000000000000000000000000000000..a995a8077438062d9e79da0be6542aa116aa6fb9 GIT binary patch literal 273 zcmeAS@N?(olHy`uVBq!ia0vp^%0Mj3!VDxYwV&7yq!^2X+?^QKos)S9XIP8U}p>AGsd7C`Gi|xo0vIWUG51^ Sp1B(6PzFy|KbLh*2~7aphiw1= literal 0 HcmV?d00001 diff --git a/doc/deploy/note.png b/doc/deploy/note.png new file mode 100644 index 0000000000000000000000000000000000000000..7c1f3e2fa7ef8897bb55ee0e0dda088dc49d6408 GIT binary patch literal 2494 zcmV;v2|@OWP)Dn;hlg!sWaK|u z738H>q0O5&+vt7wuzAz%lqL_6pE$;`=_$TGUSZXTKE{?UTV#Q4eNlNy5f~X6vC;eP zVar?IL^}QqvwNN<9++V9)D&M@mNI(ZJ=}l){r{0jyrc*W4-ebj%iAbbjxqbUooH}4 zuZUNi7mlaxe8H{Yp@$wSHWB%^MdKw!V8@OfbY&U!zwaWH1ECZMSs=**Axr2VTE>nY zJBTp?U=3MN%Nye7^JNh+5usEnkslf-lmqG&b&3m$`XUlKILOS*6L|lEeL0JH(vmpIP@3Z^}f3}I(e8SSttw+1qk&H*S&}e3GMAA ze*25>uxL>y9qlEuEJammu}RJZ5CH{IL<&-v!LqCF#LVnM6r2|T?>)7XyLk5G&`*lKvIwdGy#_(nzjI3(5CqS2q6%0s89LCN8ZARpWMe?PmD9V?HShd%D^46n-da~Q0bB!|EBq>kbB>Eu-+5C=y+<^lE)vp=*IvDh z&wTt&rcO=q;MU#j89PizM@H}-Rga;VI;Lj~b&!c7sK&G4*;xL@AYv=42@Ky5Lkv(r``>09+Sn36l=6 z84v~GqWqsXfEXi~07CEyNgBxW6tgmEaLm=~L<2=p=SYIbsghVP_0%`Ra6A$gv2LUnu6t|!IS4XAcz)5gy2b%K$<2%qgy+N3n``vNcr^Q zmN%H6A>=IzEhvB(BZ#2Rkw+mU4vPUNDKQ4}7*SQ6I$|_XE%HVk!F!HZs!SX_&UNe8 zV*mzw_wDD{i7DQ&ZY_yR5m5{S?2-V?s}HCuqD8fE!Q(XHcTbKIP5Il?2N)Zlp}ni0 za%UfZ+;xO+eeXBy-2EKRC+t6XlI=Ujd1TvD?EA+dL=(RI{a^Cj{$q4^cJkf(9z?V- zy=Zh7FQM}W(AiN&)T2Jd`+%zF=0aLf|5ja=Oj3vEYJhk@_ zcieg%Z{4_#y<_|N!;^pK%{N|)i16Nb-pC`5Zs*$9E@RE=6|KR{@N{=|@#U}mkozBa zj9YHH9ytHdc0QR`4!oEwUD8c=cYEu3QFjMp&rY!6`ZX<(dEW4(%~6}32H?SmA7lON zR&w3Ct9g3QKbfn~0`2E6ziF8+3;xuMO6%lbHX&cK1 zdW%z5qc3DxiJNa&2Ph%Hrs124#YGz`7*fm{3t91PH2%;Sh14O&014#tFeAXyE|BL>6|K8yg#=x3{Y}v$mQ|(ef=8&(R{e zL9_a)N)Z7RXqL$0RL7Y$UOcE4&XC3=YFzLj)09gtqt8D33|9;d6d^{yIQ_RMW=f2X zJSurEg~sANv%)wU9tJ56E=`rjI*mptS^!FtWMKeo-MZDbZTmI1-F7=51=pLSuF;4{ zF{zqqL#5?pYt9WczAK7ZY-vG5hcpI7K^jBj#pRMHG%+#32i|iVi98n4YW;xYr_3{riW@h)^doN%7{9V+h zk6;!#cyN-uUgNL3_Aq(mIDg$ehQ&xndmCL{ZLD10&oygSAp(N~y+srn0E~zbkyt-# zpQs+SIn0db4jg3nt}!Z=%7OqWPF0rk)D zr>8l2s>1lB@$ff)#?*sGJVnVz0zW@d(3twxNo#p`CGHJ_WD_uk{2YrQse z#LSqPnK|p?*UYHb>#ak)bB-iQNRot7sf73b^6y4fwdLW$YlU&m+vcV=Lw@G-xp$l1 z`?IJaBE%S5qeD}ZB)L2a{V&M>_pg-y4e|OV literal 0 HcmV?d00001 diff --git a/doc/deploy/pinkmystery.png b/doc/deploy/pinkmystery.png new file mode 100644 index 0000000000000000000000000000000000000000..85274daf23a74fff77c7655d849e1d70dc7add8e GIT binary patch literal 1722 zcmbVNdo+}382@H6?D-_Bv8Yfwaw*NwVOfT@HDwIa%ou70U&pfKl1=VprVi06Z7a7W zolWD^xRWH4uTBxENXX2%olc9!G+zydY0T{KM|I9>&z^n$_`R3s`906?dH#6c9ABRU zI^ZS{00145hdTuT&@2Ezjccq?-*l?(52+Va9Ob}1pyt_@Y4u@)uNRG|Ub(;?)_y=0 z1|Yq@DwPVW&7lH-CY|K|11*U!9$_32c<5>ND#NBQJ@haK_>4g>?v|=Lx0R77VA*7c zOe)sp*cN5~c*Ao;#qX4-W2!C(6$fihsjyQx2@l?>&_yF?h;)62-yIjBtEN{&SFixo zNYa9ej{}k__{CdEBtdW3Xxs+%jo#M1Ec7P;1emH*M%+MuOwvw>xYL|+w+@3Oz;8TH z@^%;k5-uEJkU*4QFe&mU^y)`Y4b@}-h1OWfvdRXt>|cR@30lPkE~otrUoY?_cR|Qf z0V`5|T9#t@3BIQ8OY-L!UqD@M1(v6>N>i)T^tRe92V+0MSBJ7H|NpAhGy3PK#!UfB zv;Sf?{$F&b&j=4-}+qc2M>)n799oeuBJ7Qw$0z?ClVb z@GYKC-_`C$*4<@{^aameNVmfB+Gh#98cr6bb><`k|Cz`an>#f?3eTSD!v#SM7 zA+-}SO7@5!+ZboTN}PpVp2JZVu6CJZPZFx+LA!Dw z1h_Do5uGrB&upi$BVjo#n0M^O-qT0Y8Eg(x$%+Td`L(UuwJBGv(vZC+!!i_~Epgpw zo2eV5E}{#RJm>_xC$14L_SIXJdQF7rPcdI%l{(hFScgngOi^*MT8}hX9V(HqIdxVu z%!S40?p_mT2)$TWARPQd?Ir`~vRBN*bG?;r4zsYOirhwQ%HZdB`coNr+ZZOQF~6u* z`7lz&xM4W;J@ig?LTiS+G{8NpUsp>=)`l|X^M`8S^>u4;bIJgA^rJ31Ne5}3Q_8K` zeOC;oAE7G2ssu8I(@+c3Vz_Xr@*>#7^SebfH-N*3>O_?$=6RP-GIVDm!wLqqgEt{A z`$dP{ZeGq8P#&i@)U-SM%MowUamRsSCO;r&(3tT4-8-J|ETRol zy*pdZ%{GL_hfa%2UL;q^UOG>`l|D`1NMFj)^@@7@_Q@;n{8t$Am7A*Wrg< zV}g_gc1zyk#pEmEerCD|Y0<@`u_(@{y<;O(VFUHB>eW5QI(kO2 zZqb@qywMMDua){ixS4oNjCJ_ozQn+v4{<=@{D>C10BcGc4~3;*t`PO46-^Bq`bA!a z{%HL|bd3Dbe((u}EqHId9ZGS>_z>_N$EzowUU=F1tVZjvprGWLtT-GaW&C7ri)Jae zabPsy{vJqD%z$6{LAhl$V**8Nc+MC^m|xSlSg@#Qid$+liWi5!lfV9WW;`^kBj#-D zY)aGxO-?IAK5{)IYx=!3PO`9AzSgq5v?bWNyhXWS66<8KJ0kTGJ)uyC-yFr6iigwY zg9_;a+;k_(je%3~1+{^;IgRDJnWNISRIxQOGk1iS?AI@5hRWK1edzLBs%Q=nTP#-Y z#Ake%KT&5_c)+v!E+{-*W;}7Z!P(J7_k4ehU0$9{rPxM~zqbYDqKEIcxvMmX7l0_0 zJmy|AH&+BkQCparTgDnv_B&sE-+yTN5wKUS+14`@ZT6TsqW*UP64A%KW*>C=Z}d8| A+yDRo literal 0 HcmV?d00001 diff --git a/doc/deploy/prodos.png b/doc/deploy/prodos.png new file mode 100644 index 0000000000000000000000000000000000000000..4e6f59a757df7673c87b20175fe95518e32b6790 GIT binary patch literal 1768 zcmah}X*3&%7LG{7Qp?nc)N3fG)7qDo5iwP1Esci6)`)#8+MCB+rQ0RVs``j(j; z004Xp00_+ig-<89*!mHtAQWb2c>_>6aDMf)IfKJEn4jVa0I)TLJ2^Sg2o2W)07R0} zW+;cqsr3TuU>@>k3$aM3=$s<*(N^MPCa5KOgV_P8QrTj?R~PlQy5Q1i$^`9dt662q zeJ-h-`rUfq-cMf!2bQt>=_*=Jy6Vi%ig6PSE6#eK;ULD#+c_K>n1&gVqNU}gpa1|T zj<-?b2!Ra9b>~8UMk?Hs00thyH&qhjP8xhk-g4;pXz6 zEH1iSzEhAnS)|f0kzjOPK7rhi`Xt@_aenSM`V*O!QB*zlQm>}+H#(suBu(bX03vV? zpbP!jF*k^_lwNblnY{34?W;WoU)eeHdr#e-nsNV#=va#?E$4+wv|6d+71B|u!N`KA zcHaX%M3f&?%2^Oq`)z&>>qngJ#bsuX8yw^lTvhy+JW2eoFn#>Oct=`!j17cQ{(*Wu zqw_YT-=D!b+9bH-OEjvN*&o+vDe{Fys{fYo&sP7RVIrH&P1?y!Uua1@uKu+z>w&-Q z%Uq&QtlJ-qu>8!cn|#56%V4Qh#l$`5P9)vm{c7BHOrb`G?Ck2~f?ynD*V-yBj zY!6?IyY=N-?;1@Zc}^*s?3F5V$f4O-t|O!hQ-~$y8afNuQhS4b(*={rH8tk4Fapu% ziG&*6Ic%ivXl6a38qoQ@{)GH@++->_r+;F%#7dRKu}tLHO?i#xQWU8rcUmw>tX` zE5q`@G#R%ERo(x}B)CN7O?37H3&g{Ni`y4n57^VsU8gjw?c-w*>*`k5j4NNg1#-zwbptC&EL7DY~dPoH7(lgcTZjSp>% z;-a4wxAzXdW1yCOpeq@4HDgtG_%oAVswhU+DPs72_VFmD&*O8$QEM7K9o%)a?i7AD ze}nvVnBx@}=@TCnetXb61yyx<3M=(!8&!A6o&D1h())c^kr2~4{sg@dTibB(HfOk^ zA9$|#`$~}B=~dU6Co4x5MHd_|EM%;wV#)grhg&x=2kI;RN|kC6_O$8e{M7Ca6j(8( zn-uTW;IqmACyR%pYTB6#8>cZgGacj8>kM-)wo$1wb91S~93>sZ%Et~)S{;3!ZYp2_ zBfh+hRTimdE6r|G+9+Mdeiad%q@?>ag;!-#*fA4$@~g#!J#hY_pgfjrRVT=)Lj}2DG@zGHI?j%S@Pk!;6Yi< z(E{qyzMhhEaIv<(+rpI(?-vzxksjj~9IOm$seO)oIwc+OH34PL@}fXaxK2xDYG z5UCpJumM)Y+@9oIWLtXnl{!HDftMl8^S6j)2o_IXicF;{lSes~2-wYvBg60qt&~W) zm7YXiNOCvqjE%5*s+bjnlVcJ8+V^0CWpEeDdP4wPk#PEJp#{jJltqe5w}4i6Tzsw# zQ+82DGj%isJwW{TmYvj7t5tyq1BG@kEUdX@D1H8^`B#M|`7FzLqYP`-x-$zeilW_I zcwuT7+%!F{6bx->nT%*NVVgYHpGAP3NFnO>f0;MQdMIgdB}qN?-bPC3;8@?g2QsFj zRSg8_4LC@`al&b}6ZfA*WVPEzTz2zIcT0Qz;~?P3;VN4+Q^U)L03X$O&*7+2F5&Pr gxY{FOz!2y}C=KQ)1#uk){`h!ka~reD8=eXO1MBECivR!s literal 0 HcmV?d00001 diff --git a/doc/deploy/redhat.png b/doc/deploy/redhat.png new file mode 100644 index 0000000000000000000000000000000000000000..a98a44ba6ca5afd19e8dbb55716d18e277daf626 GIT binary patch literal 1692 zcmV;N24ne&P)X1^@s6S>%lC00006VoOIv0RI60 z0RN!9r;`8x010qNS#tmY2Mz!L2Mz&_1aeUT000McNliru*9-*|EH|rSUI_pI1}RBI zK~zY`rI%f(9aj~{e{1hOGw0kh_a-+t$t2CyNNlSm*0$0rsY0t33f2cf#0Q^>;Kz%C z3gVj&iV8yCM2Zw2M5ONp5ua@lw9*QV{jh01lvCRzO*-eCnZ5T~KFql{x3NiX>W0nC znZud&+iS1?f3G9l#AupEfCIoW;Fvf2P@VHf3e!8CaTr*Ab+hd>bhRp$m!SL8dV$jP9_{0kJwjLjEVxhCy9_mFu<9C$TpCgvBx=XH!G$o z-T!(Buhn(^eA~7++`e#~)ZP7lq^zJBMTl}`CNr`VOdURF0zxH1x!k^B#%FU1 z=TiFl`4FB1{`#IXv^JSMbVBnN?g+)OYBfw1a)z9doKaPh84;L?&^n<7`WWeQBAQYd zR4J{T4PmWZUHyIAw()vE?i%$2aQprpHIgu*DbbXy8O;eFd#bKuv{*3e7KGRnO<4d@ zjikeGZ&hWp?;in9+$clt8qZ4y$M%>KbpR=sN>aNLEUFQ803;?t*E5DON^t}SDRjNlSAlmTKRuiT3tcE}x0)=xp5d^RurJ8J5z;GSFlNkq9*`MO4 zo2I#a*EQ5MjbE+n4_2z*KA6%Y_c~XVPRItGD%p&}4VfyPqjHYQJ4Vh^I7c#No^=}{ z+i*>0FaVCvRMpu@T|eEn?e$gGG|fJN?`(G6SMM@CbeD6~ArQButi~c|+MHPNfsq@M ztH3NLF2=|_XL?n-<#h{WJBDgl9j8Yxh44Gz>@|(CX_}9%ru2*Z`tH65%F@-rGZRP1 z88IarOMe-%WX3x@C)-dB*HPWkcVVR+wD-|G%aM^pFD=Yp2 z9MmkIn9u4xIelv3{Ab+S+N+bgKHavh0{FGb3|3< zfDTyXOy70e+Xt|xEIFWh<#@`O6PGWo*P4HHa=cPDP4kmbnC=^i&@WY#%@B-ReBd%d zxkD|^42R*>a5?krtYxlO0`3gHa}?flFa$nn%Apwlr-+ZwW~CzEdww!`C3Mcce7^7R zSzF3`3u+_xlrAwZ3e<-|O{&bzxRf(zQ>0hBQotg^1e^#C7<iylM^uE2S*mCQ(?7vfGmNIc!kh_79 zck!XCKW~jJ!pq~8#cNgdQx7ny>(_hd{`BtxuB*EYaUD!$4+x-hj!Qo9pR!2*Dyx$hLwG8RJPw?i zPN#aqCLcH|aQ{g4bK{&(Y{dS+dW@5C&aPaxsD7)b9<;yx!o2Lc=g!;AyZMDsv=>7- z|F-vkUO4v@@C_lE_y?-T( myb7EF&H*n?r_+nqi}hc9T-2A-C70>|0000I_1%xyEeXO zuS+d;cTCh&5b}|NirR`RzBboV36xY=b5+*zRR~8jyEpgO{eSnJ`95d9pYQ9B@9oHo zp;juW75DuX(Mm~ zi1y>01%M1=JI-iK0ysrRBZpTa1pwni-9)5O2^ft=G5Jj`09dqzhn$Yinq5^YOBF*% z^9lN$_A8!vnx*w0gJ(Y8`PoMQ*v${ho4>oC;&`9a7;vko59e#xUvk(DR`J8`;X*T; zMb1~K$3W7Qo#6w|*V^8ggNF59ceqg`^2m;l-`O@cdFU0r1BLp{YOOrCcQ0+0u-8hU zev(0!tfidP%C}3Rtos2EG3KK z;-h;~Z#2DQ15N?g!y*5P@o%vI14I7n~ZAfNO2a&(OLC%`6or2PwU+0wu$SYESve= zBIR{$#XE*t@@`R+KAKbLEXhWh@6-U>k6vWhKI+I-2Kf7*nob1_VbUq(lBDP57`!$1 z%5bhjo%i#KzB`R=lh!sI0p!33|D8$`&{QV{Q}#ND65;lwBq~CddM!e@SDEg+nss*H zXoj^##OjYJLw&5P?!)aq=y&ZdQ+4)at^*~|0bVALDM+B!l3bk-1ndx<;nxFRxx0rX z#9(dF+ts^$$Z7lhD94VZQ0SmYywYFY13!9G1h1R9&3%z$=@EJ_eQhdx4`i_rh0{Q#HV)-qr#}L7?o|i2!~Q3rl-4ovqqhks8_k3`W%3!t`y&Z?~vJ}bafMa z{h`#2BA&m_a;%5X!FMnM9BIdeqR7P#3+SjSdk9VKihod^gT)2v24bB})!$cfHGybN ze65&UP_@#38pYy+Nv4*tr=hR!y8^1WBzI%C(<9cIxp@# z*uqakP;%(i0ut8&A4p7aOnv;%&gf$efJS`wM01UqW<#Q%qQ2ZhPFuxQeCbS#ri5*O zMzQP-gYqT{8{^lA+f@2}xf}gX=A3s+QF-~WFp{MZqjC(W+cS=D87IgxSMIV{InL8cuvMw ztq7Tzl+R|~9zX;P(!`19Xkm-2Yt0;?eBZRFkh2;r#63`l)-*UdWC8Y}%F#`v-2IIp zpvc*QHy&5;lY+Lcj{Xb%%Bdu@))D=cKc(s!F}y5>VsYqC(3IyDkY_jZ2WI|ki9(ho zcjAxTh&jEG*E1Q=*o}=KueyRf3NvfL&p}@9Xc?@GhdeY0D^PYWw85Hc!tfm)9x?(x z5jv(|thMV)5-Dq}2V{0D87tfMlmwX%63Ie~HTTbh%(t|8QPLomM=kw46v5dn^S2nu zhm9yp`B-daPqF^P0vU@rEFOCMbhoCs=T+Tfexa}9IKwlc%B=X*2`_qm+is9JV0k4q zNYzXlcq8``bjukRy)ddJyJ7)Vy0!7qeAb1aZrzIZb$WafDbo&3ZfZL@%Yu1XNd7=J zJX?roL~MM=Ci(H1%s0g7`R}shyVEXDF5S=kg^l_?7+XA$$P`sSiH)U5rb?@uM$*Dz zX_vSeE%_%T|2XI>Q#Pa#GBv5py=v@Yc;z^Msu(=7Tt#AAp%XyyV_t8QJLP`O(rAG+ s79~O{nTsL(Pbs(l1zhxK-2eap literal 0 HcmV?d00001 diff --git a/doc/deploy/tip.png b/doc/deploy/tip.png new file mode 100644 index 0000000000000000000000000000000000000000..f087c73b7aef4ae1e4e30df11debe4cd25a73b48 GIT binary patch literal 2718 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 AfdBvi literal 0 HcmV?d00001 diff --git a/doc/deploy/windows.gif b/doc/deploy/windows.gif new file mode 100644 index 0000000000000000000000000000000000000000..626108d430ab37bd45ae9b0c3223eccb8fcaa8dc GIT binary patch literal 1543 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 ZQ@m{#2cnngjsJHRmgcr*^h=(P{{^UHqT~Po literal 0 HcmV?d00001 diff --git a/doc/download.asciidoc b/doc/download.asciidoc new file mode 100644 index 0000000..eef1548 --- /dev/null +++ b/doc/download.asciidoc @@ -0,0 +1,75 @@ +== Download + +[TIP] +Usable Apple ROMs (proprietary +footnoteref:[disclaimer,You must +respect the fact that the Apple +System Software and +Apple Disk Operating System (DOS) Software are +_proprietary_ software; they are copyright by Apple and/or others. This web page is not +providing any advice as to the legality of any copying or downloading you may perform. +]) +are available at the http://mosher.mine.nu/apple2/[Apple II Library]. + +The following software is licensed under +http://www.gnu.org/licenses/gpl-3.0-standalone.html[GPLv3]. + +Epple ][ Program: http://mosher.mine.nu/epple2/download/epple2-latest.tar.gz[epple2.tar.gz] + +System ROM (Demo): http://mosher.mine.nu/epple2/download/epple2sys-latest.tar.gz[epple2sys.tar.gz] + +Card ROMs (stdin/stdout/clock): http://mosher.mine.nu/epple2/download/epple2cards-latest.tar.gz[epple2cards.tar.gz] + +See <<_building_from_source,Building>> to build from sources. + + + +== What To Download + +=== Epple ][ Program—The Hardware (Emulated) + +The _Epple ][ Program_ package is the emulator itself, which emulates the +Apple ][ or Apple ][ plus _hardware_, as well as the +<> hardware. This is the main program, so you will +certainly need to download this package. To have a full functioning emulator, +you will also need System ROMs and Card ROMs, as described in the following +sections. + +[[firmware]] +=== System ROMs—The Main System Firmware (Demo or Real) + +Since the Epple ][ program emulates only the hardware, you will also need to download some _system software_ +for it to run. This is commonly called ``firmware'' or ``ROMs,'' because it is stored in the +read-only memory area of the emulated system. The original system software on the +Apple ][ machines is copyright by Apple, and is proprietary. If you own an actual +Apple ][ or Apple ][ plus machine, you can copy footnoteref:[disclaimer] the firmware +from it ($D000-$FFFF) (into a file on your PC) and use it. Alternatively, you can +download footnoteref:[disclaimer] the firmware images from the http://mosher.mine.nu/apple2/[Apple II Library]. + +If you do not want to download the proprietary firmware, you can still use the emulator (albeit +in a restricted manner) with the free (GPLv3) _System ROM (Demo)_ package. Download +the file for your platform and +install as appropriate. You can choose either binary format (ready to run), or source if you want +to assemble it yourself (using the http://www.floodgap.com/retrotech/xa/[xa Assembler]). +The Demo System ROM only provides commands to dump or set memory bytes, +or run a program in memory. It is not compatible with any Apple software, nor can it read from disks. +It's just a free simple demo system to make the emulator do something reasonable. + +=== Card ROMs—The Peripheral Card Firmware + +If you are going to use the Disk ][ Controller peripheral card (which you almost certainly will, if +you want to read any floppy disk images), you will need to have to original ROMs from Apple. +No demo of the Disk ROMs are provided here; you will need to +use the original ROMs, which can be obtained from an original machine (by copying footnoteref:[disclaimer] +it from $C600-$C6FF into a file on the PC), or by downloading footnoteref:[disclaimer] it +from the http://mosher.mine.nu/apple2/[Apple II Library]. +(And, of course, you will need the real Apple System ROM, as noted in the previous section, +not the Demo System ROM.) + +If you are using any of the clock, the standard output, or the +standard input <>, you will need to download their firmware as well, +which are contained in the _Card ROMs_ package. You can choose either binary format +(ready to run) or source format (to assemble it yourself(using the +http://www.floodgap.com/retrotech/xa/[xa Assembler]). +If you are _not_ going to use the stdin, stdout, or clock +cards, then you do not need to download this package. diff --git a/doc/epple2logo.png b/doc/epple2logo.png new file mode 100644 index 0000000000000000000000000000000000000000..ebaf1358066c012e06abbc97701a56e6d97a7f33 GIT binary patch literal 605 zcmeAS@N?(olHy`uVBq!ia0vp^6+kS)!3-n|dpHjQDaPU;cPEB*=VV?2IV%EuLR|m< z{|{s`7(;N{%rj?TBmSo`{GWN|e;QC8h=6*5`py8g00qv>GzKaK z3IcTj-2mhRH37vzGHGc*GtYn|L4ZLh?CV3I`;$Fg978;gKb?BBtjR#2&DTjuQD>9* z7QMB(TetrH_Ame1OvZ^-Po&NfCam#r|J@tYy*q3BEAp#T*WAs}N$R~8Bb9k(+O?N+Z_Hc! zewJ+UQY|Y{hP$7G1?4(wWb@Wc@5r*V{?>Z^in`Uc=Y6v?ZqNRG$~Ua+_1Z7<4By;I z{#v&~n8kzj$f<|+4u4Ahc+3?|1ts@9 z&%Mc4Q}*a=-+I;Yc9!%R*T;`9Z|&=O{4ljAjQiTD8Gp^UuXKDj>rtZlyVq1N*Ak8#_H*SBrML2V*W^!Qa zvDZ-T!secPCeUkniAB-qvbYV*pAQ Mp00i_>zopr0KnQ6fdBvi literal 0 HcmV?d00001 diff --git a/doc/gplv3logo.png b/doc/gplv3logo.png new file mode 100644 index 0000000000000000000000000000000000000000..b06e0439d37fa474a344748203ef0930d9cfee9d GIT binary patch literal 2986 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 +:icons: +:iconsdir: . +:toclevels: 3 +:toc2: + +image::epple2logo.png[] + +== Introduction + +Epple ][ is an emulator of the original APPLE ][ and APPLE ][ PLUS +computers from http://www.apple.com/[Apple, Inc.] It +runs on Windows and Linux platforms, and is released under +http://www.gnu.org/licenses/gpl-3.0-standalone.html[GPLv3] +image:gplv3logo.png[GPLv3] + +It is written in C++ and is designed with cross-platform +portability in mind. It uses the http://www.libsdl.org/[SDL] graphics library. + + + +== Features + +* Cycle-accurate: emulates all MOS 6502 CPU cycles including ``phantom reads'' +* Video display is synchronized with CPU +* NTSC video signal emulation: all video quirks emulated accurately +* Revision 0 motherboard (optional) +* Multiple display types: monitor and TV emulation +* Can run full-screen or in a window +* 640x480 resolution +* Floating data bus, and video scanner +* Cards: Disk ][, language, firmware, clock +* Paddles (mouse emulates two paddles) +* Cassette tape interface +* PR#1 writes to standard output +* Accurate keyboard emulation, including the repeat key +* It even emulates the POWER light! + +include::screenshots.asciidoc[] + +include::download.asciidoc[] + +include::configuration.asciidoc[] + +include::usermanual.asciidoc[] + +include::building.asciidoc[] + + +'''' + +[small]#Copyright (C) 2009,2012, by +mailto:chris-keyword-epple2.4a8db3@mosher.mine.nu[Christopher A. Mosher], +Shelton CT, USA.# + +image:80x15.png[Creative Commons Attribution-Noncommercial-Share Alike 3.0 USA License] + +[small]#This web site is licensed under the +http://creativecommons.org/licenses/by-nc-sa/3.0/us/[Creative Commons Attribution-Noncommercial-Share Alike 3.0 USA License].# diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..98a2127 --- /dev/null +++ b/doc/index.html @@ -0,0 +1,2325 @@ + + + + + +Epple ][ + + + + + +
+
+
+
+
+epple2logo.png +
+
+
+
+
+

Introduction

+
+

Epple ][ is an emulator of the original APPLE ][ and APPLE ][ PLUS +computers from Apple, Inc. It +runs on Windows and Linux platforms, and is released under +GPLv3 + +GPLv3 +

+

It is written in C++ and is designed with cross-platform +portability in mind. It uses the SDL graphics library.

+
+
+
+

Features

+
+
    +
  • +

    +Cycle-accurate: emulates all MOS 6502 CPU cycles including “phantom reads” +

    +
    • +
  • +

    +Video display is synchronized with CPU +

    +
    • +
  • +

    +NTSC video signal emulation: all video quirks emulated accurately +

    +
    • +
  • +

    +Revision 0 motherboard (optional) +

    +
    • +
  • +

    +Multiple display types: monitor and TV emulation +

    +
    • +
  • +

    +Can run full-screen or in a window +

    +
    • +
  • +

    +640x480 resolution +

    +
    • +
  • +

    +Floating data bus, and video scanner +

    +
    • +
  • +

    +Cards: Disk ][, language, firmware, clock +

    +
    • +
  • +

    +Paddles (mouse emulates two paddles) +

    +
    • +
  • +

    +Cassette tape interface +

    +
    • +
  • +

    +PR#1 writes to standard output +

    +
    • +
  • +

    +Accurate keyboard emulation, including the repeat key +

    +
    • +
  • +

    +It even emulates the POWER light! +

    +
    • +
+
+
+
+

Screenshots

+
+
+

DOS 3.3 System Master boot

+
+
+dos330boot.png +
+
+

Here we’ve configured an Apple ][ plus, with a disk +controller in slot 6, and a language card in slot 0. +We’ve booted the DOS 3.3 System Master disk. It correctly +identifies the machine as an Apple ][ plus, and then +loads Integer BASIC into the language card. You can switch +between Applesoft and Integer BASIC by using the FP and +INT commands.

+
+
+

DOS 3.1 System Master on Revision 0 motherboard

+
+
+dos310rev0.png +
+
+

Here we’ve configured an Apple ][ (Integer BASIC ROMs), +with a Revision Zero motherboard, and a disk +controller (with 13-sector ROMs) in slot 6. With a +revision 0 motherboard, when the machine is powered-on, +the CPU doesn’t start actually running until you +manually press the RESET button. Also, the old Monitor +ROMs do not boot from the disk drives automatically; +you need to type C600G to boot. +We’ve booted the DOS 3.1 System Master disk and done a +catalog of it. As you can see, with a revision 0 motherboard, +the text is displayed in green and purple, which are also the +only two HIRES colors. Later revisions +of the motherboard added a “color burst killer” which is +active during text mode, so the text would be strictly white. +Two more HIRES colors, blue and orange, were also added in +later revisions.

+
+
+

PRODOS 1.1.1 boot

+
+
+prodos.png +
+
+

Here we’ve configured an Apple ][ plus with language card +and disk drive. We’re booting a PRODOS 1.1.1 disk.

+
+
+

Bishop’s Apple Split

+
+
+applesplit.png +
+
+

The October 1982 issue of Softalk +featured an article by Bob Bishop entitled +Have an Apple Split, which describes +in some detail the inner workings of the Apple ]['s video processing. Listings 1 and 2 from that +article show a short Applesoft program and assembly language subroutine that allow the Apple ][ +to have a screen split between text and graphics display. To achieve this on the EPPLE ][, +copy the following text and paste it into the emulator (at the Applesoft ] prompt). Since the +EPPLE ][ accurately emulates the video scanning and timing of the original Apple ][s, this +“split screen” technique works successfully. +The rest of the behavior described in the article (the floating data bus) is also emulated +faithfully by the EPPLE ][.

+
+
+
CALL -151
+
+300:8D 52 C0 A9 E0 A2 04 CD 51 C0 D0 F9 CA D0 F8 A9
+310:A0 A2 04 CD 50 C0 D0 F9 CA D0 F8 8D 51 C0 60
+
+E000G
+
+100 HOME
+
+200 FOR K = 0 TO 39
+210   POKE 1448+K, 14*16
+220   POKE 2000+K, 10*16
+230   COLOR = K+4
+240   VLIN 24, 45 AT K
+250 NEXT K
+
+300 VTAB 6 : HTAB 17
+310 PRINT "APPLE II"
+
+400 CALL 768
+500 GOTO 400
+
+RUN
+
+
+

Mysterious Pink Line

+
+
+pinkmystery.png +
+
+

Jim Sather’s book +Understanding the Apple II, +which was the primary +reference for the internal design of the EPPLE ][ emulator, describes the video +generation process of the Apple ][, in great detail, in Chapter 8. +On page 8-21 he shows a simple Applesoft BASIC program (shown below) +that shows an example of one of the hi-res idiosyncrasies on the Apple ][. +The program would logically draw three orange lines, but due to the +video cutoff and extension of half-dot shifted pixels, instead the right +line is brown, and there is a “mysterious pink line” (actually magenta) +on the far left of the screen. The EPPLE ][ faithfully emulates this behavior.

+
+
+
NEW
+
+10 HGR : HCOLOR = 5 : HPLOT 5,159 TO 5,0 TO 279,0 TO 279,159
+
+RUN
+
+
+

Split Screen HIRES/LORES colors

+
+
+splitcolors.png +
+
+

Jim Sather’s book +Understanding the Apple II, +shows an Applesoft BASIC +program and assembly language subroutine on pages 3-16 and 3-17 (reproduced +below) that produce the display shown here. The screen is split between HIRES +and LORES graphics by a timed loop that manipulates the screen switches. +(Press any key repeatedly to move the position of the split.)

+

Notice that the Apple ][ can actually produce more HIRES colors than are +documented in the standard Apple reference manuals. White, black, green, +purple, blue, and orange are normally documented, but by careful manipulation +of the high-bit (half-dot shift indicator) of the HIRES display byte, many +other colors can be produced. The additional colors match some LORES colors. +Also notice that the text at the bottom of the screen is colored green and +purple while in mixed text/graphics mode. This is because the “color +burst killer” circuit is not active while displaying graphics on the +Apple ][ machines.

+
+
+
CALL -151
+1F00:AC 54 C0 A0 27 20 27 1F
+1F08:AC 10 C0 AC 00 C0 30 F3
+1F10:69 01 29 01 AA BC 56 C0
+1F18:A2 08 20 31 1F A0 31 20
+1F20:27 1F 18 90 E6 D0 01 88
+1F28:88 EA D0 F9 60 48 68 EA
+1F30:EA A0 62 20 27 1F EA CA
+1F38:D0 F3 60
+
+E000G
+ 30 HGR : HOME : VTAB 21 : PRINT "1  7  D  2  8  E  B  4  5  A 3 6 C 9 F 8"
+ 40 DIM COLR(39), X(21)
+100 FOR A = 0 TO 39 : READ COLR(A) : COLOR = COLR(A) : VLIN 0, 39 AT A : NEXT A
+200 FOR A = 0 TO 21 : READ COLR(A) : READ X(A) : HCOLOR = COLR(A)
+210 HPLOT X(A), 0 TO X(A), 159 : NEXT A
+220 FOR A = 8319 TO 16383 STEP 128 : POKE A, 64 : NEXT A
+300 CALL 7936
+400 REM  LORES DATA
+410 DATA 1,0,7,7,0,13,13,0,2,2,0,8,8,0,14,14,0,11,11,0
+420 DATA 4,4,0,0,5,0,0,10,0,3,0,6,0,12,0,9,0,15,0,8
+500 REM  HIRES DATA
+510 DATA 4,0,3,20,4,21,3,41,4,42,7,62,7,83,7,104,3,105,7,125,3,126,7,159,3,161
+520 DATA 7,180,3,182,3,206,7,220,3,233,7,247,3,262,3,263,7,279
+
+RUN
+
+
+
+
+

Download

+
+
+ + + +
+Tip +Usable Apple ROMs (proprietary +
[You must respect the fact that the Apple System Software and Apple Disk Operating System (DOS) Software are proprietary software; they are copyright by Apple and/or others. This web page is not providing any advice as to the legality of any copying or downloading you may perform.]
) +are available at the Apple II Library.
+
+

The following software is licensed under +GPLv3.

+

Epple ][ Program: epple2.tar.gz

+

System ROM (Demo): epple2sys.tar.gz

+

Card ROMs (stdin/stdout/clock): epple2cards.tar.gz

+

See Building to build from sources.

+
+
+
+

What To Download

+
+
+

Epple ][ Program—The Hardware (Emulated)

+

The Epple ][ Program package is the emulator itself, which emulates the +Apple ][ or Apple ][ plus hardware, as well as the +peripheral card hardware. This is the main program, so you will +certainly need to download this package. To have a full functioning emulator, +you will also need System ROMs and Card ROMs, as described in the following +sections.

+
+
+

System ROMs—The Main System Firmware (Demo or Real)

+

Since the Epple ][ program emulates only the hardware, you will also need to download some system software +for it to run. This is commonly called “firmware” or “ROMs,” because it is stored in the +read-only memory area of the emulated system. The original system software on the +Apple ][ machines is copyright by Apple, and is proprietary. If you own an actual +Apple ][ or Apple ][ plus machine, you can copy
[disclaimer]
 the firmware +from it ($D000-$FFFF) (into a file on your PC) and use it. Alternatively, you can +download
[disclaimer]
 the firmware images from the Apple II Library.

+

If you do not want to download the proprietary firmware, you can still use the emulator (albeit +in a restricted manner) with the free (GPLv3) System ROM (Demo) package. Download +the file for your platform and +install as appropriate. You can choose either binary format (ready to run), or source if you want +to assemble it yourself (using the xa Assembler). +The Demo System ROM only provides commands to dump or set memory bytes, +or run a program in memory. It is not compatible with any Apple software, nor can it read from disks. +It’s just a free simple demo system to make the emulator do something reasonable.

+
+
+

Card ROMs—The Peripheral Card Firmware

+

If you are going to use the Disk ][ Controller peripheral card (which you almost certainly will, if +you want to read any floppy disk images), you will need to have to original ROMs from Apple. +No demo of the Disk ROMs are provided here; you will need to +use the original ROMs, which can be obtained from an original machine (by copying
[disclaimer]
 +it from $C600-$C6FF into a file on the PC), or by downloading
[disclaimer]
 it +from the Apple II Library. +(And, of course, you will need the real Apple System ROM, as noted in the previous section, +not the Demo System ROM.)

+

If you are using any of the clock, the standard output, or the +standard input peripheral cards, you will need to download their firmware as well, +which are contained in the Card ROMs package. You can choose either binary format +(ready to run) or source format (to assemble it yourself(using the +xa Assembler). +If you are not going to use the stdin, stdout, or clock +cards, then you do not need to download this package.

+
+
+
+
+

Configuration

+
+

The Epple ][ Emulator is most useful when properly configured. +After downloading and installing the Epple ][ Program, some System ROM (demo or real), and +optionally the peripheral card ROMs you want to use, you will need to configure the program. +Configuring is concerned primarily with telling the program what peripheral cards to use, +and where the ROM files are located (and what memory addresses to load them at).

+
+

epple2.conf

+

The default configuration file for +the Epple ][ emulator is:

+
+
+
/etc/epple2/epple2.conf
+
+

For Windows, the file will be:

+
+
+
C:\Program Files\Epple2\etc\epple2\epple2.conf
+
+

The configuration file could be in a different location depending upon how +the distribution package is built.

+

You can specify a different configuration file for the emulator to use by +specifying its name as the argument when running the epple2 program.

+

The format of the configuration file is just lines of commands. +Comments begin with a hash # character, and continue to the end of the line.

+
+
+

Firmware

+

Firmware, commonly called ROM images or ROMs, will need to be loaded +into the emulated ROM areas of the emulated Apple +in order for it to be able to boot the emulated Apple machine. +The firmware available is described above. +Once the firmware image +files are installed on your computer, you can use the import +command in the configuration file to load the image files into the emulator.

+
+
+

Peripheral Cards

+

Another primary concern for configuring the Epple ][ is the insertion of +peripheral cards into the Apple’s slots. The most useful card is probably the +Disk ][ Controller card; you will need to insert one of these cards if you want +to be able to load floppy disk images into the emulated Apple. The various +types of cards available are described on the peripheral cards section. +You can use the slot command in the configuration file to insert +them into the Apple’s slots.

+
+
+

Sample Configuration Files

+

There are a number of configuration files provided with the distribution for +your convenience. They provide various common configurations of machines. +You can use one of these files directly, by specifying its path as the argument +to the program, or as a starting point for you own configuration file. These sample +files are in the same location as the default epple2.conf file.

+

The Epple ][ Emulator can actually be run without a configuration file at all. +In this case, you will be able to “power on” the Apple and see the low-resolution +graphics display showing random RAM data. The system will not run, because +there is no firmware loaded, but the emulator will otherwise be functional.

+
+
+
+
+

User Manual

+
+
+

Overview

+

Epple ][ (the Emulated Apple ][ is a free (as in GPLv3), cross-platform +(Windows, Linux) emulator of the Apple ][ and Apple ][ plus computers +from Apple, Inc. It strives for accurate emulation of the original machines, +with a few extra features added.

+
+
+

Commands

+

slot import load unload save cassette revision

+
+

slot

+

The slot command inserts a card into a peripheral slot of the emulated Apple.

+
+
+
slot <slot> <card>
+
+

<slot> Slot number, 0 through 7, to insert the card into.

+

<card> The type of card to insert into the slot:

+
    +
  • +

    +language +

    +
    • +
  • +

    +firmware +

    +
    • +
  • +

    +disk +

    +
    • +
  • +

    +clock +

    +
    • +
  • +

    +stdout +

    +
    • +
  • +

    +stdin +

    +
    • +
  • +

    +empty +

    +
    • +
+

The slot command inserts a card into a peripheral slot. For example:

+
+
+
slot 0 language
+
+

inserts a language card into slot zero. Use empty to remove a card:

+
+
+
slot 0 empty
+
+
+ + + +
+Note +The emulated Apple should be powered off before inserting or removing cards.
+
+
+
+

import

+

The import command imports a binary image file into the emulated Apple’s memory.

+
+
+
import slot <slot> { rom | rom7 | rombank } <base> <file-path>
+import motherboard { rom | ram } <base> <file-path>
+
+

<slot> Slot number, 0 through 7, of peripheral card to import the binary image into.

+

<base> Base address in hexadecimal within the given memory area at which to start loading the binary image.

+

<file-path> Path of the binary image to import.

+

The import command reads the binary image byte-for-byte from the given file-path +into an area of memory in the emulated Apple. You can load into either the motherboard or +a card in one of the slots. For the motherboard, you choose the RAM or ROM area. For a card +in a slot, you can choose either the normal ROM, the bank-switched ROM, or the so-called +“seventh ROM” area.

+

You also have to specify the base address within the specific memory +area at which the image file will be loaded. Note that the base address is specified as the offset +within the specific memory area, and not necessarily as the actual memory address as seen +by the Apple. So for motherboard ROM, for example, specifying a base as 2DED will cause the +image to be loaded at offset 2DED in the ROM, which will be addressed by the Apple at +memory address $FDED (because motherboard ROM “starts” at address $D000).

+

For peripheral cards, the ROM will be seen at locations $Cs00-$CsFF, where s is the slot +number (1 through 7). The “seventh ROM” can be seen as locations $C800-$CFFF; Jim Sather +describes this functionality in +Understanding the Apple II, +on page 6-4, section “The Seventh ROM Chip.” The EPPLE ][ emulator handles this processing correctly. A card can +also have bank-switched ROM, which will show up at addresses $D000-$FFFF when switched in +(stealing that address range from motherboard ROM… see +Understanding the Apple II, +p. 5-26 “The 16K RAM Card”).

+
+
+

load

+

The load command loads a (nibble) floppy disk image into one of the emulated disk drives.

+
+
+
load slot <slot> drive <drive> <file-path>
+
+

<slot> Slot number, 0 through 7, of Disk ][ controller card to load the nibble image into.

+

<drive> Drive number, 1 or 2, of the disk drive on the controller card to load the nibble image into.

+

<file-path> Path of the nibble floppy disk image to import.

+

The load command will load a nibble image into a disk drive. Specify the slot that +contains a Disk ][ controller peripheral card, and specify which drive number (1 or 2).

+
+ + + +
+Note +The floppy disk image MUST be a NIBBLE DISK IMAGE. +Other formats (for example, DOS order, .do, PRODOS order, +.po, .dsk, or anything else) must first be converted to nibble format. A nibble image contains +all 35 tracks, in order 0-36, each track being 6656 ($1A00) bytes long. Nibble image files +will generally have a filetype of .nib.
+
+

The best floppy disk image conversion tool I’ve found is CiderPress, +for Windows (but it supposedly runs under Wine on Linux, too). Thanks to Andy McFadden.

+
+
+

unload

+

The unload command removes a floppy disk image from one of the emulated disk drives.

+
+
+
unload slot <slot> drive <drive>
+
+

<slot> Slot number, 0 through 7, of Disk ][ controller card to which the drive is attached.

+

<drive> Drive number, 1 or 2, of the disk drive on the controller card to remove the floppy disk image from.

+

The unload command removes the disk from the specified slot and drive.

+
+ + + +
+Warning +If the disk has been modified but not saved, the modifications will be DISCARDED.
+
+
+
+

save

+

The save command saves changes made on an emulated floppy disk back to the original image file.

+
+
+
save slot <slot> drive <drive> <file-path>
+
+

<slot> Slot number, 0 through 7, of Disk ][ controller card to which the drive is attached.

+

<drive> Drive number, 1 or 2, of the disk drive on the controller card to save.

+

<file-path> Path of the nibble floppy disk image to import.

+

The save command saves any changes that the emulated Apple ][ has made to the floppy +disk image. It is important to note that the emulator operates on the image only in memory, and does +not immediately write changes back to the real file. You need to issue the save command +in order to write changes back to the file. Note that the emulator will display a asterisk * +next to the file-name of a disk image if it has any unsaved changes.

+
+
+

cassette

+

The cassette command performs various operations of the emulated cassette tape.

+
+
+
cassette new <file-path>
+cassette load <file-path>
+cassette unload
+cassette rewind
+cassette save
+
+

<file-path> File path of the (special format) cassette tape image file.

+

The cassette command allows the user to control the emulated cassette tape player. +See Cassette for more information about operating the emulated +cassette player and cassette tape image files.

+
+
+

revision

+

The revision command specifies which revision of Apple ][ motherboard to use.

+
+
+
revision <rev>
+
+

<rev> Revision number of the motherboard. Currently, only two values make any difference in behavior: 0 or 1.

+

The revision command chooses which revision of the Apple ][ motherboard to +use. The only revisions that make any difference (for now, at least) are 0 or 1. Zero +is the original (now quite rare) version of the motherboard, that only had two hi-res +colors (green and purple), and always displayed text with green and purple fringes. +Revision 1 and later motherboards are the ones we are more familiar with.

+
+
+
+

Display

+

The orignal Apple ][s didn’t come with a display. The user needed to use either a standard +television, or a monitor, to see the computer’s output. The EPPLE ][ emulates a variety of +displays; you can cycle between the different types using F2. +There are two major types of displays: televisions and monitors. Monitors generally have +higher quality (sharper) displays. The displays show the normal visible area of the NTSC +video signal generated by the emulated Apple ][ machine.

+
+

Monitors

+

The emulator provides a color monitor, and three monochrome monitors (white, green, and orange). +These emulate standard, no-frills NTSC monitors. The most noticeable characteristic of monitors +is the horizontal display of pixels. Monitors react faster than TVs, so two adjacent pixels will +not merge together; both will be distinctly visible, with blackness between them. For example, +type in the following Applesoft command, then cycle through the display types. The monitors +will show thin, vertical, green lines; TVs will show continuous horizontal lines.

+
+
+
GR : COLOR=4 : HLIN 10,20 AT 10
+
+
+
+

Televisions

+

There are two types of television displays, referred to as “old” and “new.” Each has color and +monochrome (commonly known as “black and white”) varieties. Televisions react more slowly to +changes in the incoming video signal than monitors do, and as a result, horizontal pixels will +merge together, forming a more uniform appearance. The “new” color TV display uses the pre-defined +color pallette (described below under “Colors”), and the black and white TV uses the same +pallette, but fully desaturated. The “old” color TV is the most interesting. It emulates the +signal decoding circuitry of a real television. This includes separating out the “chroma” portion +of the incoming NTSC video signal using a filter algorithm, and calculating the color to display. +It does not use the pre-defined colors.

+
+ + + +
+Note +This mode is very CPU intensive, so your computer (that is, the one that EPPLE ][ is running on) +may not be able to run fast enough to run at the speed of the original Apple ][. The Apple ][ CPU +runs at about 1 MHz, but the video generator runs at 14 MHz; so the inner-most loop in the +EPPLE ][ must run 14 million times per second to keep up.
+
+
+
+

Colors

+

The color palatte used for the +color monitor and new color TV is pre-defined, and was determined through observation of a real +Apple ][ machine on a standard TV, the colors being matched by eye. The old color TV, however, +uses algorithms to calculate the colors it displays.

+
+
+

Scan Lines

+

NTSC displays (TVs or monitors) usually receive signals that are interlaced. However, the +Apple ][ doesn’t generate interlaced screens. This causes blank rows between each displayed +row of pixels. The EPPLE ][ emulates this behavior, but also allows you to “fill in” these +black rows with a copy of the row above it, for a more continuous display (vertically). Use +the F4 key to toggle between these two modes.

+
+
+

Resolution

+

The Apple ][s are commonly documented as having a resolution of 280x192 pixels, and to an +extent this is true. Vertically there are 192 pixels, but since there is no interlacing, +it is more accurate to display them with one blank space between each. So the EPPLE ][ has +two times 192, or 384, vertical pixels in its display. Horizontally there are 280 pixels, but +each could also be shifted right one-half dot, allowing for two times 280, or 560, different +horizontal displayable positions. To emulate this, the EPPLE ][ shows each emulated pixel as +two pixels wide, and displays an emulated half-dot shift as an actual one pixel shift. So the +display area of the EPPLE ][ is 560x384. There is an informational area below and to the +right of the emulated display that shows various statistics of the emulator. So the total screen +area used by the EPPLE ][ is a standard 640x480 pixels.

+
+
+

Full Screen

+

The EPPLE ][ can run in either full-screen mode, or within a window. Use the F3 key to toggle +between the two.

+
+
+

Informational Area

+

The area at the bottom and the right of the EPPLE ][ display show various information about +the emulator.

+
    +
  • +

    +POWER light +

    +
    • +
  • +

    +current cards in SLOTS +

    +
    • +
  • +

    +CASSETTE tape information +

    +
    • +
  • +

    +emulated CPU speed (MHz) +

    +
    • +
  • +

    +function-keys help +

    +
    • +
+
+
+
+

Keyboard

+

The EPPLE ][ emulates the original Apple ][ keyboard. The original Apple ][ +keyboard had symbols in different places than current common PC keyboards. For +example, Shift-2 on the Apple ][ produces a double quote, but on a PC keyboard +it produces an at-sign. For ease of typing, the EPPLE ][ emulator does not +mimic the positions of the original keys, but rather mimics the symbols on +the current PC keyboard. So, for example, if you type Shift-2 on the PC +keyboard into the EPPLE ][, it produces an at-sign, as you would normally expect.

+

The Apple ][ keyboard didn’t produce lower-case letters; neither does the emulator. +Also, the Apple couldn’t produce an opening square bracket ([), braces, vertical +bar, backslash. There were no up- or down-arrow keys. You cannot type these into +the emulator, either. There are other, unusual, cases that are emulated correctly, +as well, such as typing Control in conjunction with a number key simply produces +that number. So typing a Control-3 is the same as just typing a 3. Also, typing +Shift-Control-2 produces the NUL character (ASCII $80).

+

The Apple ][ keyboards didn’t automatically repeat typing characters when a +key was held down. Instead, the user would hold down the REPT (“repeat”) key +while holding down the key that was to be repeated. On the EPPLE ][, this +behavior is emulated, and the F10 key is used as the REPT key.

+

The Apple ][ had no keyboard buffer (actually, it had a buffer of one character). +So if you typed several characters on the keyboard before the currently running +program had a chance to read them, they would get lost (only the final character +typed would be remembered). This behavior can be +toggled on or off in the EPPLE ][. By default, the EPPLE ][ will buffer up any +characters you type and deliver them to the emulated machine when it asks for +them. However, the Apple program must be written properly to allow this to work. +Some Apple ][ programs (like maybe some games) may not work correctly in this +respect, so you may want to turn off buffering in these cases. With buffering +turned off, the EPPLE ][ accurately emulates the original Apple ][. Use the F12 +key to toggle the keyboard buffering. Note that pasting from the clipboard (with +the Insert key) will most definitely cause keys to be lost if the keyboard +buffer is turned off. So if you have a big Applesoft program in the clipboard +and you want to paste it into the EPPLE ][ correctly, make sure the keyboard +buffer is on.

+
Special Keys
    +
  • +

    +F1 Emulates the POWER switch on the back of the Apple ][. +

    +
    • +
  • +

    +F2 Cycles among different display types (TV, monitor, etc.). +

    +
    • +
  • +

    +F3 Toggles between full-screen or window display. +

    +
    • +
  • +

    +F4 Toggles between showing scan lines on the display, or duplicating +each scan line to the following line, to fill-in the otherwise black line. +

    +
    • +
  • +

    +F5 Go to “command entry” mode. +

    +
    • +
  • +

    +F10 Emulates the REPT key. +

    +
    • +
  • +

    +F11 Toggles between running the emulator at authentic speed +(1.02 MHz CPU), or as fast as possible. +

    +
    • +
  • +

    +F12 Toggles the keyboard buffer. +

    +
    • +
  • +

    +Break Emulates the RESET key. +

    +
    • +
  • +

    +Insert Pastes characters from the clipboard into the emulated Apple +(as if they had been typed on the keyboard). +

    +
    • +
  • +

    +Print Screen Save a bitmap file of the current EPPLE ][ screen. +The file will be in the default directory, named ep2_YYYYMMDDHHMMSS.bmp. +

    +
    • +
  • +

    +End Quit the EPPLE ][ program, immediately! +

    +
    • +
+
+ + + +
+Warning +If you have modification to any floppy images or cassette images, and you +press the End key, you will LOSE all those changes, unless you +save them first. See Commands for the save command.
+
+
+
+

Peripheral Cards

+
+

Disk ][ Controller

+

The Disk ][ Controller card emulates the floppy disk controller card and associated +disk drives in the original Apple ][ systems. In the emulator, each card has two +drives attached to it, referred to as drive 1 and drive 2. The floppy disks +themselves are represented by a “nibble” image of the contents. The +emulator emulates the hardware, but to be of any use, you will need to provide +the firmware ROM code.

+

To use a disk card and drives, add these lines to your epple2.conf file, for example:

+
+
+
slot 6 disk
+import slot 6 rom 0 /usr/lib/apple2/dos3x/16sector/controller/disk2.ex65
+
+

The first line uses the slot command to +insert a disk contoller card into slot 6, which is the standard +slot used for disk cards. The next line uses the import +command to load the card’s ROM with the disk controller +firmware. This firmware is known as the “bootstrap” or “P5” ROM code. +It is seen by the Apple ][ at memory addresses $Cs00-$CsFF, where s is the +slot number (so in the common case of the card being in slot 6, the ROM is +at $C600-$C6FF). The firmware is copyright by Apple, and is available from +the Apple II Library.

+

You can also load a floppy disk image (nibble format) into the drive,either by putting +the load command into the epple2.conf file, or by using the command prompt +in the emulator (F5 key). For example, you could load the DOS 3.3 system master into +slot 6, drive 1, with this command

+
+
+
load slot 6 drive 1 /usr/lib/apple2/dos3x/16sector/disks/dos330/clean330sysmas.nib
+
+
+
+

Language

+

The language card emulates an Apple 16K RAM card, commonly called a Language Card. +To use a language card, add this line to your epple2.conf file:

+
+
+
slot 0 language
+
+

Note that DOS and ProDOS will make use of a language card only if it is in slot zero.

+

The language card has RAM at addresses $E000 through $FFFF, as well as two banks of RAM +at addresses $D000 through $DFFF. A program switches between these RAMs and/or the +motherboard ROM by using the I/O switches at $C080 through $C08F.

+

The information area of the Epple ][ will show the current state of the +language card as follows:

+
    +
  • +

    +R Read from card RAM (vs. motherboard ROM) +

    +
    • +
  • +

    +W Write to card RAM (vs. write-disabled) +

    +
    • +
  • +

    +B1 Use $D000 bank 1 +

    +
    • +
  • +

    +B2 Use $D000 bank 2 +

    +
    • +
+

An overview of the I/O switches that control the language card +is provided by Jim Sather in +Understanding the Apple II, +p. 5-30, Table 5.4, as follows:

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BANK2 BANK1 ACTION

C080

C088

WRTCOUNT = 0*, WRITE DISABLE

READ ENABLE

C084

C08C

RC081

RC089

WRTCOUNT = WRTCOUNT + 1*

READ DISABLE

RC085

RC08D

WC081

WC089

WRTCOUNT = 0*

READ DISABLE

WC085

WC08D

C082

C08A

WRTCOUNT = 0*, WRITE DISABLE

READ DISABLE

C086

C08E

RC083

RC08B

WRTCOUNT = WRTCOUNT + 1*

READ ENABLE

RC087

RC08F

WC083

WC08B

WRTCOUNT = 0*

READ ENABLE

WC087

WC08F

+

* Writing to expansion RAM is enabled when WRTCOUNT reaches 2.

+
+
+

Firmware

+

The firmware card emulates a (modified) Apple Firmware card. +The firmware card is simply an alternate ROM, at addresses +$D000 through $FFFF, that is switched using the I/O switches +at addresses $C080 through $C08F. In order to make use of the +firmware card, you will need to load the ROM with a binary image +from a file on disk. For example, to insert an Integer BASIC +firmware card into the emulator, add these lines to your +epple2.conf file:

+
+
+
# Firmware card with Integer BASIC and old Monitor
+slot 0 firmware
+import slot 0 rombank 1000 /usr/lib/apple2/system/intbasic/intbasic.ex65
+import slot 0 rombank 2425 /usr/lib/apple2/system/other/other.ex65
+import slot 0 rombank 2800 /usr/lib/apple2/system/monitor/apple2/monitor.ex65
+
+

For an Applesoft BASIC firmware card, use these:

+
+
+
# Firmware card with Applesoft BASIC and Autostart Monitor
+slot 0 firmware
+import slot 0 rombank 0000 /usr/lib/apple2/system/applesoft/applesoft.ex65
+import slot 0 rombank 2800 /usr/lib/apple2/system/monitor/apple2plus/monitor.ex65
+
+

Note that the addresses specified in the epple2.conf file for the +rombank are based on the beginning of the bank ROM itself. For example, specifying +1000 (which is 1000 hex) represents the final memory address of $E000, because +the bank ROM is always based at address $D000.

+

The idea is that you would load your motherboard with, for +example, Applesoft BASIC and the Autostart Monitor ROM (to emulate +an Apple ][ plus), and then install a firmware card with Integer +BASIC and the old Monitor. Booting with DOS 3.3, then, would allow +you to type FP to use Applesoft BASIC, or INT to switch to Integer BASIC.

+

Note that DOS and ProDOS will make use of a firmware card only if it is in slot zero.

+

Jim Sather, in +Understanding the Apple II, +on pages 6-18 through 6-21, explains +how to modify a firmware card to allow independent switching of the $F800-$FFFF +ROM memory. This area is occupied by the Monitor, so it is primarily +intended to allow the user to switch between the old Monitor and the Autostart +Monitor, independent of switching between Integer and Applesoft BASIC. The EPPLE ][ +firmware card emulates this behavior.

+

The information area of the EPPLE ][ will show the current state of the +firmware card as follows:

+
    +
  • +

    +D Read from firmware card $D000-$F7FF (vs. motherboard BASIC ROM) +

    +
    • +
  • +

    +F8 Read from firmware card $F800-$FFFF (vs. motherboard Monitor ROM) +

    +
    • +
+
+
+

Clock

+

The clock card emulates a ProDOS-compatible real-time clock card for the Apple ][. +To use a clock card, you will need to configure the EPPLE ][ to insert one into +a slot, typically slot 4. You will also need to load the card with its ROM code, +which is provided with the emulator in the clock.ex65 file. +For example, add this to your epple2.conf file:

+
+
+
slot 4 clock
+import slot 4 rom 0 /usr/lib/epple2/cards/clock.ex65
+
+

Of course you may need to adjust the path for your particular system.

+

To verify that the clock card is working correctly, you can run the following Applesoft +program to retrieve the current time from the clock card and print it. +This program assumes the card is in slot 4.

+
+
+
NEW
+
+10 CALL -15360 : REM $C400 SLOT 4 ENTRY POINT
+20 A = 512 : REM $0200 INPUT BUFFER
+30 C = PEEK(A)
+40 IF C < 160 THEN 99
+50 PRINT CHR$(C);
+60 A = A+1
+70 GOTO 30
+99 END
+
+RUN
+

The card returns data (into the GETLN input buffer at $200) in +the following format:

+

mm,ww,dd,hh,nn,ss,000,yyyy,Time Zone,v

+
    +
  • +

    +mm Month, 01-12 +

    +
    • +
  • +

    +ww Weekday, 00=Monday… 06=Saturday +

    +
    • +
  • +

    +dd Day, 01-31 +

    +
    • +
  • +

    +hh Hour, 00-23 +

    +
    • +
  • +

    +nn Minute, 00-59 +

    +
    • +
  • +

    +ss Second, 00-61 +

    +
    • +
  • +

    +000 Milliseconds; always zero +

    +
    • +
  • +

    +yyyy Year, e.g., 2008 +

    +
    • +
  • +

    +Time Zone time zone string (could contain lower-case characters, + which won’t display correctly) +

    +
    • +
  • +

    +v Daylight Saving Time in effect, 0=no, 1=yes +

    +
    • +
+

Note that only mm,ww,dd,hh,nn fields are used by ProDOS. The other +fields, ss,000,yyyy,Time Zone,v, are an EPPLE ][ extension. Also note +that ProDOS was not designed to work for years past 2007, so +ProDOS will show the incorrect year, but the other fields will be accurate. +I believe patches exist for ProDOS to fix this.

+
+
+

Standard Input

+

The “standard input” card doesn’t emulate a real piece of hardware; rather, it +reads characters from standard input (stdin) (of the EPPLE ][ emulator).

+

To use a standard input card, add these lines to your epple2.conf file:

+
+
+
# IN#2 reads from standard input
+slot 2 stdin
+import slot 2 rom 0 /usr/lib/epple2/cards/stdin.ex65
+
+

That will insert a stdin card into slot 2, and then load its +ROM image into the card. +The stdin ROM is provided with the EPPLE ][ distribution.

+

For example, if you have a stdin card installed in slot 2, start +the EPPLE ][ emulator from the command line, and at the Applesoft +prompt, type IN#2. Then you can switch back to the +command shell, and whatever you type will be fed into the emulated +Apple. Use RESET or IN#0 to go back to normal.

+
+
+

Standard Output

+

The “standard output” card doesn’t emulate a real piece of hardware; rather, it acts +similar to a printer card, but instead of sending characters to a printer, it sends +them to standard output (stdout) (of the EPPLE ][ emulator).

+

To use a standard output card, add these lines to your epple2.conf file:

+
+
+
# PR#1 prints to standard output
+slot 1 stdout
+import slot 1 rom 0 /usr/lib/epple2/cards/stdout.ex65
+
+

This will insert a stdout card into slot 1 (which is the typical +slot for a printer card), and then load its ROM image into the card. +The stdout ROM is provided with the EPPLE ][ distribution.

+

For example, if you have a stdout card installed, at the Applesoft +prompt, type PR#1. Whatever you type next will be +echoed to standard output. Type PR#0 to stop echoing.

+
+
+
+

Cassette Tape Interface

+

The Apple ][ and Apple ][ plus machines had the ability to save and load binary +data to and from cassette tape. The user would attach a standard cassette tape +recorder to the jacks on the back of the Apple ][, and use the monitor R and W +commands, or the Applesoft BASIC commands LOAD and SAVE, to read and write data +on the cassette tape. The user would have to press the play and/or record buttons +on the player at the right time.

+

The Epple ][ emulates the cassette interface, using a file to hold the +recorded portion of the tape. The file will grow in length as necessary +to hold data that the emulated Apple is writing to the “tape.” +The emulator will not overwrite existing data on a tape image. +The emulator will automatically “press” the play or record buttons that +would have been necessary when using the original machine.

+
+

Commands

+

cassette new <file-path>

+

This creates a new empty file (on the host computer) that represents a cassette tape image. +The file must not already exist.

+

cassette load <file-path>

+

This loads an existing file (from the host computer) containing a cassette tape image. +The tape is automatically positioned at its beginning (fully rewound).

+

cassette unload

+

This removes the file from the cassette tape. Note that you must manually save +the file using the cassette save command (described below).

+
+ + + +
+Warning +Unloading an unsaved file will lose any changes made to the file, without warning.
+
+

cassette rewind

+

This command “rewinds” the cassette tape, positioning it at the beginning +of the tape (for subsequent reading). You do not need to rewind the tape +before saving or unloading it, of course.

+

cassette save

+

This command saves the changed tape to the file. Note that the display will show +an asterisk * next to the file name if there are unsaved changes that need to +be saved. Unsaved changes will be lost without warning if the file is unloaded +or if you quit the program.

+
+
+

Example of Saving to Tape

+

Start up the emulator with Applesoft ROMs for this tutorial. +Enter a simple Applesoft program, just as an example, that we +are going to save to a cassette tape image file.

+
+
+
]NEW
+
+]10 PRINT "HELLO"
+
+]20 END
+
+]LIST
+
+10  PRINT "HELLO"
+20  END
+
+]RUN
+HELLO
+
+]
+

We first need to load a tape image file into the cassette machine. +Enter command mode by pressing F5, then make a new tape +image file.

+
+
+
command: cassette new hello.tap
+
+

This will create a new, empty tape file image named hello.tap +in the current default directory. (We could have specified a full path +name for the file if we wanted to place it in a different directory.) +Notice that the emulator now displays the name of the tape image file, +along with the position and length of the tape image, which is now 0/0.

+

Next, we tell Applesoft to save the program to the cassette. For this, +we just use the SAVE command. Note that this is not the +DOS SAVE command; the DOS command has a file name after +SAVE. We just use SAVE with no file name.

+
+
+
]SAVE
+
+]
+
+

It will take 10 seconds or so for it to save. Notice that the +current position of the tape is counting up as the Apple saves +the program. When it is finished, you need to save the changes +to the file. Press F5 and enter the emulator command to save +the tape image file.

+
+
+
command: cassette save
+
+

We can now unload the file from the emulator (which is like ejecting +the tape from the cassette player).

+
+
+
command: cassette unload
+
+
+
+

Example of Loading from Tape

+

To load the saved program (from the previous section) into the Apple again, +we will need to first load the tape image file back into the cassette machine. +Press F5 to enter command mode and load the image file.

+
+
+
command: cassette load hello.tap
+
+

This will load hello.tap (in the current default directory). Notice the +emulator now displays the name of the tape image file, along with the +position and length of the tape image, which in this case is 0/33481.

+

Next, we tell Applesoft to load the program from the cassette. For this, +we just use the LOAD command. Note that this is not the +DOS LOAD command; the DOS command has a file name after +LOAD. We just use LOAD with no file name.

+
+
+
]LOAD
+
+]
+
+

It will take 10 seconds or so for it to load. Notice that the +current position of the tape is counting up as the Apple loads +the program. When it is finished, the program will be loaded.

+
+
+
]LIST
+
+10  PRINT "HELLO"
+20  END
+
+]RUN
+HELLO
+
+]
+
+
+

Tape Image File Format

+

The format of the tape image file is unique to the Epple ][ +It is stored in a low-level format that represents the waveform that the Apple writes +to the cassette tape.

+

The file is a binary format. Each byte in the file represents the length of one half of one cycle +(of voltage level variation) written to the tape. The length is in 10-microsecond units.

+

For example, a tape image file might have the following binary bytes (in decimal): +65 65 65 65 65 20 25 50 50 25 25 25 25 50 50 +Since each byte represents a 10-microsecond unit, these bytes represent the following +half-cycle lengths in microseconds: +650 650 650 650 650 200 250 500 500 250 250 250 250 500 500 +The meaning of these half-cycle lengths to the Apple is as follows:

+
+
+
|-------HEADER------|--sync-|-1-bit-|-0-bit-|-0-bit-|-1-bit-|
+|                   |       |       |       |       |       |
+|650 650 650 650 650|200 250|500 500|250 250|250 250|500 500|
+
+

where HEADER is a header section the Apple writes (to skip any +unrecordable leader section on a real cassette tape); sync is a +synchronization cycle; and the subsequent cycles are the actual +bits of data saved on the tape. A 500-microsecond cycle (which +is stored in the file as two 250 microsecond half-cycles) +represents a zero bit, and a 1-millisecond cycle (which is +stored in the file as two 500 microsecond half-cycles) +represents a one bit.

+
+
+
+

Paddles

+

The Epple ][ provides two paddles to the Apple ][ machine. +One paddle is controlled by moving the mouse left and right; the other +paddle is controlled by moving the mouse up and down. The paddle buttons +are emulated by the mouse buttons (left and right click).

+

In +Understanding the Apple II, +on page 7-33, Jim Sather describes soldering fixed resistors across a game connector +to create two real-time clock references. This is emulated by the Epple ][. Paddle timers 2 and 3 +are 100-microsecond and 1-millisecond references, respectively.

+
+
+

Speaker

+

The Apple ][ could generate sound via a speaker that generated square wave +audio. A program could read memory location $C030 to toggle the speaker and +generate a “click” sound.

+

The Epple ][ emulator will generate sounds from the emulated Apple and +send them to the audio device. It generates 8-bit mono sound, with a 22,050 Hz +sampling rate.

+
+
+
+
+

Building From Source

+
+

The Epple ][ Emulator is written in C++, and can be built +using the standard make program.

+

The primary dependency is +Simple DirectMedia Layer (SDL). +Your linux distribution may provide a package. Or else +you can download it directly from SDL’s web site. In +either case, be sure to install the “Development Libraries” +for your particular platform.

+
+

Debian Linux Example

+
+
+
sudo apt-get install build-essential libsdl1.2-dev  # 1
+cd
+mkdir epple2
+cd epple2
+wget http://mosher.mine.nu/epple2/download/epple2-latest.tar.gz  # 2
+tar xzvf epple2-1.0.tar.gz
+mkdir build  # 3
+cd build
+../epple2-1.0/configure  # 4
+make  # 5
+sudo make install  # 6
+
+ + + + + + +
1 +Install dependencies: gcc, make, SDL +
2 +Retrieve the latest Epple ][ source distribution +
3 +Use this directory for a VPATH-style build +
4 +Run one-time configuration script for your system. Use --help for more information. +
5 +Compile and link. Program will be src/epple2 +
6 +Install into standard system directories +
+
+
+

Windows/MSYS Example

+
+

Install MinGW/MSYS

+

Install MSYS into C:\msys\

+

Install MinGW into C:\msys\mingw\

+

For more information on MinGW and MSYS, see http://www.mingw.org/.

+
+
+

Install SDL

+

At http://www.libsdl.org/ find the download page. +Download the “Development Libraries” for Win32/mingw, for example:

+

SDL-devel-1.2.13-mingw32.tar.gz (Mingw32)

+

and save it to your MSYS home directory (for example, C:\msys\home\Administrator). +Run MSYS, and at the bash prompt, go to your home directory and +untar the SDL archive to your home directory:

+
+
+
$ cd
+$ tar xzvf SDL-devel-1.2.13-mingw32.tar.gz
+

Then follow the instructions to install SDL, for example:

+
+
+
$ cd SDL-1.2.13
+$ make native
+
+
+

Untar Epple ][ Source

+

Download the Epple ][ Source Distribution +and save it to your MSYS home directory (for example, C:\msys\home\Administrator). +Run MSYS, and at the bash prompt, go to your home directory and +untar the epple2 source distribution tar file. For example:

+
+
+
$ cd
+$ tar xzvf epple2-1.0.tar.gz
+
+
+

Build Epple ][

+

Then build as follows. I recommend doing a VPATH build, +where you build into a different directory than the source +directory. To accomplish this, create a new directory for +building, somewhere, such as:

+
+
+
$ cd
+$ mkdir buildepple2
+$ cd buildepple2
+

Then run configure from there. For the MSYS build to work, +you need some extra parameters to the build, and you could +also add some compiler options to optimize the build. For +example (from the buildepple2 directory you just created):

+
+
+
$ ~/epple2/configure --prefix= \
+CXXFLAGS="-I/usr/include -O4 -msse3" \
+CFLAGS="-I/usr/include" \
+LDFLAGS="-L/usr/lib -mconsole -mthreads -mno-cygwin"
+$ make
+

If all goes well, it will build without any errors. +If you get errors about not finding SDL.h, make sure +SDL is installed, and make sure the configure command +is correct. (If you just run configure without the +options shown above, you will get this error at build time.) +The result of the build (on Windows platform) is

+

installer/epple2.msi

+

which is an installable file for Windows. To install +epple2, just double-click on this file from Explorer.

+
+

Copyright © 2009,2012, by +Christopher A. Mosher, +Shelton CT, USA.

+

+Creative Commons Attribution-Noncommercial-Share Alike 3.0 USA License +

+

This web site is licensed under the +Creative Commons Attribution-Noncommercial-Share Alike 3.0 USA License.

+
+
+
+
+
+
+ + + diff --git a/doc/keyboard.asciidoc b/doc/keyboard.asciidoc new file mode 100644 index 0000000..351dc3b --- /dev/null +++ b/doc/keyboard.asciidoc @@ -0,0 +1,61 @@ +=== Keyboard + +The EPPLE ][ emulates the original Apple ][ keyboard. The original Apple ][ +keyboard had symbols in different places than current common PC keyboards. For +example, Shift-2 on the Apple ][ produces a double quote, but on a PC keyboard +it produces an at-sign. For ease of typing, the EPPLE ][ emulator does not +mimic the positions of the original keys, but rather mimics the symbols on +the current PC keyboard. So, for example, if you type Shift-2 on the PC +keyboard into the EPPLE ][, it produces an at-sign, as you would normally expect. + +The Apple ][ keyboard didn't produce lower-case letters; neither does the emulator. +Also, the Apple couldn't produce an opening square bracket ([), braces, vertical +bar, backslash. There were no up- or down-arrow keys. You cannot type these into +the emulator, either. There are other, unusual, cases that are emulated correctly, +as well, such as typing Control in conjunction with a number key simply produces +that number. So typing a Control-3 is the same as just typing a 3. Also, typing +Shift-Control-2 produces the NUL character (ASCII $80). + +The Apple ][ keyboards didn't automatically repeat typing characters when a +key was held down. Instead, the user would hold down the REPT (``repeat'') key +while holding down the key that was to be repeated. On the EPPLE ][, this +behavior is emulated, and the F10 key is used as the REPT key. + +The Apple ][ had no keyboard buffer (actually, it had a buffer of one character). +So if you typed several characters on the keyboard before the currently running +program had a chance to read them, they would get lost (only the final character +typed would be remembered). This behavior can be +toggled on or off in the EPPLE ][. By default, the EPPLE ][ will buffer up any +characters you type and deliver them to the emulated machine when it asks for +them. However, the Apple program must be written properly to allow this to work. +Some Apple ][ programs (like maybe some games) may not work correctly in this +respect, so you may want to turn off buffering in these cases. With buffering +turned off, the EPPLE ][ accurately emulates the original Apple ][. Use the F12 +key to toggle the keyboard buffering. Note that pasting from the clipboard (with +the Insert key) will most definitely cause keys to be lost if the keyboard +buffer is turned off. So if you have a big Applesoft program in the clipboard +and you want to paste it into the EPPLE ][ correctly, make sure the keyboard +buffer is on. + +.Special Keys +* +F1+ Emulates the POWER switch on the back of the Apple ][. +* +F2+ Cycles among different display types (TV, monitor, etc.). +* +F3+ Toggles between full-screen or window display. +* +F4+ Toggles between showing scan lines on the display, or duplicating +each scan line to the following line, to fill-in the otherwise black line. +* +F5+ Go to ``command entry'' mode. +* +F10+ Emulates the REPT key. +* +F11+ Toggles between running the emulator at authentic speed +(1.02 MHz CPU), or as fast as possible. +* +F12+ Toggles the keyboard buffer. +* +Break+ Emulates the RESET key. +* +Insert+ Pastes characters from the clipboard into the emulated Apple +(as if they had been typed on the keyboard). +* +Print Screen+ Save a bitmap file of the current EPPLE ][ screen. +The file will be in the default directory, named +ep2_YYYYMMDDHHMMSS.bmp+. +* +End+ Quit the EPPLE ][ program, immediately! + +[WARNING] +If you have modification to any floppy images or cassette images, and you +press the +End+ key, you will LOSE all those changes, unless you +save them first. See <<_commands,Commands>> for the +save+ command. diff --git a/doc/make.png b/doc/make.png new file mode 100644 index 0000000000000000000000000000000000000000..a995a8077438062d9e79da0be6542aa116aa6fb9 GIT binary patch literal 273 zcmeAS@N?(olHy`uVBq!ia0vp^%0Mj3!VDxYwV&7yq!^2X+?^QKos)S9XIP8U}p>AGsd7C`Gi|xo0vIWUG51^ Sp1B(6PzFy|KbLh*2~7aphiw1= literal 0 HcmV?d00001 diff --git a/doc/note.png b/doc/note.png new file mode 100644 index 0000000000000000000000000000000000000000..7c1f3e2fa7ef8897bb55ee0e0dda088dc49d6408 GIT binary patch literal 2494 zcmV;v2|@OWP)Dn;hlg!sWaK|u z738H>q0O5&+vt7wuzAz%lqL_6pE$;`=_$TGUSZXTKE{?UTV#Q4eNlNy5f~X6vC;eP zVar?IL^}QqvwNN<9++V9)D&M@mNI(ZJ=}l){r{0jyrc*W4-ebj%iAbbjxqbUooH}4 zuZUNi7mlaxe8H{Yp@$wSHWB%^MdKw!V8@OfbY&U!zwaWH1ECZMSs=**Axr2VTE>nY zJBTp?U=3MN%Nye7^JNh+5usEnkslf-lmqG&b&3m$`XUlKILOS*6L|lEeL0JH(vmpIP@3Z^}f3}I(e8SSttw+1qk&H*S&}e3GMAA ze*25>uxL>y9qlEuEJammu}RJZ5CH{IL<&-v!LqCF#LVnM6r2|T?>)7XyLk5G&`*lKvIwdGy#_(nzjI3(5CqS2q6%0s89LCN8ZARpWMe?PmD9V?HShd%D^46n-da~Q0bB!|EBq>kbB>Eu-+5C=y+<^lE)vp=*IvDh z&wTt&rcO=q;MU#j89PizM@H}-Rga;VI;Lj~b&!c7sK&G4*;xL@AYv=42@Ky5Lkv(r``>09+Sn36l=6 z84v~GqWqsXfEXi~07CEyNgBxW6tgmEaLm=~L<2=p=SYIbsghVP_0%`Ra6A$gv2LUnu6t|!IS4XAcz)5gy2b%K$<2%qgy+N3n``vNcr^Q zmN%H6A>=IzEhvB(BZ#2Rkw+mU4vPUNDKQ4}7*SQ6I$|_XE%HVk!F!HZs!SX_&UNe8 zV*mzw_wDD{i7DQ&ZY_yR5m5{S?2-V?s}HCuqD8fE!Q(XHcTbKIP5Il?2N)Zlp}ni0 za%UfZ+;xO+eeXBy-2EKRC+t6XlI=Ujd1TvD?EA+dL=(RI{a^Cj{$q4^cJkf(9z?V- zy=Zh7FQM}W(AiN&)T2Jd`+%zF=0aLf|5ja=Oj3vEYJhk@_ zcieg%Z{4_#y<_|N!;^pK%{N|)i16Nb-pC`5Zs*$9E@RE=6|KR{@N{=|@#U}mkozBa zj9YHH9ytHdc0QR`4!oEwUD8c=cYEu3QFjMp&rY!6`ZX<(dEW4(%~6}32H?SmA7lON zR&w3Ct9g3QKbfn~0`2E6ziF8+3;xuMO6%lbHX&cK1 zdW%z5qc3DxiJNa&2Ph%Hrs124#YGz`7*fm{3t91PH2%;Sh14O&014#tFeAXyE|BL>6|K8yg#=x3{Y}v$mQ|(ef=8&(R{e zL9_a)N)Z7RXqL$0RL7Y$UOcE4&XC3=YFzLj)09gtqt8D33|9;d6d^{yIQ_RMW=f2X zJSurEg~sANv%)wU9tJ56E=`rjI*mptS^!FtWMKeo-MZDbZTmI1-F7=51=pLSuF;4{ zF{zqqL#5?pYt9WczAK7ZY-vG5hcpI7K^jBj#pRMHG%+#32i|iVi98n4YW;xYr_3{riW@h)^doN%7{9V+h zk6;!#cyN-uUgNL3_Aq(mIDg$ehQ&xndmCL{ZLD10&oygSAp(N~y+srn0E~zbkyt-# zpQs+SIn0db4jg3nt}!Z=%7OqWPF0rk)D zr>8l2s>1lB@$ff)#?*sGJVnVz0zW@d(3twxNo#p`CGHJ_WD_uk{2YrQse z#LSqPnK|p?*UYHb>#ak)bB-iQNRot7sf73b^6y4fwdLW$YlU&m+vcV=Lw@G-xp$l1 z`?IJaBE%S5qeD}ZB)L2a{V&M>_pg-y4e|OV literal 0 HcmV?d00001 diff --git a/doc/overview.asciidoc b/doc/overview.asciidoc new file mode 100644 index 0000000..17a90cf --- /dev/null +++ b/doc/overview.asciidoc @@ -0,0 +1,6 @@ +=== Overview + +Epple ][ (the Emulated Apple ][ is a free (as in GPLv3), cross-platform +(Windows, Linux) emulator of the Apple ][ and Apple ][ plus computers +from Apple, Inc. It strives for accurate emulation of the original machines, +with a few extra features added. diff --git a/doc/paddles.asciidoc b/doc/paddles.asciidoc new file mode 100644 index 0000000..e2c07f7 --- /dev/null +++ b/doc/paddles.asciidoc @@ -0,0 +1,12 @@ +=== Paddles + +The Epple ][ provides two paddles to the Apple ][ machine. +One paddle is controlled by moving the mouse left and right; the other +paddle is controlled by moving the mouse up and down. The paddle buttons +are emulated by the mouse buttons (left and right click). + +In +http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II], +on page 7-33, Jim Sather describes soldering fixed resistors across a game connector +to create two real-time clock references. This is emulated by the Epple ][. Paddle timers 2 and 3 +are 100-microsecond and 1-millisecond references, respectively. diff --git a/doc/pinkmystery.png b/doc/pinkmystery.png new file mode 100644 index 0000000000000000000000000000000000000000..85274daf23a74fff77c7655d849e1d70dc7add8e GIT binary patch literal 1722 zcmbVNdo+}382@H6?D-_Bv8Yfwaw*NwVOfT@HDwIa%ou70U&pfKl1=VprVi06Z7a7W zolWD^xRWH4uTBxENXX2%olc9!G+zydY0T{KM|I9>&z^n$_`R3s`906?dH#6c9ABRU zI^ZS{00145hdTuT&@2Ezjccq?-*l?(52+Va9Ob}1pyt_@Y4u@)uNRG|Ub(;?)_y=0 z1|Yq@DwPVW&7lH-CY|K|11*U!9$_32c<5>ND#NBQJ@haK_>4g>?v|=Lx0R77VA*7c zOe)sp*cN5~c*Ao;#qX4-W2!C(6$fihsjyQx2@l?>&_yF?h;)62-yIjBtEN{&SFixo zNYa9ej{}k__{CdEBtdW3Xxs+%jo#M1Ec7P;1emH*M%+MuOwvw>xYL|+w+@3Oz;8TH z@^%;k5-uEJkU*4QFe&mU^y)`Y4b@}-h1OWfvdRXt>|cR@30lPkE~otrUoY?_cR|Qf z0V`5|T9#t@3BIQ8OY-L!UqD@M1(v6>N>i)T^tRe92V+0MSBJ7H|NpAhGy3PK#!UfB zv;Sf?{$F&b&j=4-}+qc2M>)n799oeuBJ7Qw$0z?ClVb z@GYKC-_`C$*4<@{^aameNVmfB+Gh#98cr6bb><`k|Cz`an>#f?3eTSD!v#SM7 zA+-}SO7@5!+ZboTN}PpVp2JZVu6CJZPZFx+LA!Dw z1h_Do5uGrB&upi$BVjo#n0M^O-qT0Y8Eg(x$%+Td`L(UuwJBGv(vZC+!!i_~Epgpw zo2eV5E}{#RJm>_xC$14L_SIXJdQF7rPcdI%l{(hFScgngOi^*MT8}hX9V(HqIdxVu z%!S40?p_mT2)$TWARPQd?Ir`~vRBN*bG?;r4zsYOirhwQ%HZdB`coNr+ZZOQF~6u* z`7lz&xM4W;J@ig?LTiS+G{8NpUsp>=)`l|X^M`8S^>u4;bIJgA^rJ31Ne5}3Q_8K` zeOC;oAE7G2ssu8I(@+c3Vz_Xr@*>#7^SebfH-N*3>O_?$=6RP-GIVDm!wLqqgEt{A z`$dP{ZeGq8P#&i@)U-SM%MowUamRsSCO;r&(3tT4-8-J|ETRol zy*pdZ%{GL_hfa%2UL;q^UOG>`l|D`1NMFj)^@@7@_Q@;n{8t$Am7A*Wrg< zV}g_gc1zyk#pEmEerCD|Y0<@`u_(@{y<;O(VFUHB>eW5QI(kO2 zZqb@qywMMDua){ixS4oNjCJ_ozQn+v4{<=@{D>C10BcGc4~3;*t`PO46-^Bq`bA!a z{%HL|bd3Dbe((u}EqHId9ZGS>_z>_N$EzowUU=F1tVZjvprGWLtT-GaW&C7ri)Jae zabPsy{vJqD%z$6{LAhl$V**8Nc+MC^m|xSlSg@#Qid$+liWi5!lfV9WW;`^kBj#-D zY)aGxO-?IAK5{)IYx=!3PO`9AzSgq5v?bWNyhXWS66<8KJ0kTGJ)uyC-yFr6iigwY zg9_;a+;k_(je%3~1+{^;IgRDJnWNISRIxQOGk1iS?AI@5hRWK1edzLBs%Q=nTP#-Y z#Ake%KT&5_c)+v!E+{-*W;}7Z!P(J7_k4ehU0$9{rPxM~zqbYDqKEIcxvMmX7l0_0 zJmy|AH&+BkQCparTgDnv_B&sE-+yTN5wKUS+14`@ZT6TsqW*UP64A%KW*>C=Z}d8| A+yDRo literal 0 HcmV?d00001 diff --git a/doc/prodos.png b/doc/prodos.png new file mode 100644 index 0000000000000000000000000000000000000000..4e6f59a757df7673c87b20175fe95518e32b6790 GIT binary patch literal 1768 zcmah}X*3&%7LG{7Qp?nc)N3fG)7qDo5iwP1Esci6)`)#8+MCB+rQ0RVs``j(j; z004Xp00_+ig-<89*!mHtAQWb2c>_>6aDMf)IfKJEn4jVa0I)TLJ2^Sg2o2W)07R0} zW+;cqsr3TuU>@>k3$aM3=$s<*(N^MPCa5KOgV_P8QrTj?R~PlQy5Q1i$^`9dt662q zeJ-h-`rUfq-cMf!2bQt>=_*=Jy6Vi%ig6PSE6#eK;ULD#+c_K>n1&gVqNU}gpa1|T zj<-?b2!Ra9b>~8UMk?Hs00thyH&qhjP8xhk-g4;pXz6 zEH1iSzEhAnS)|f0kzjOPK7rhi`Xt@_aenSM`V*O!QB*zlQm>}+H#(suBu(bX03vV? zpbP!jF*k^_lwNblnY{34?W;WoU)eeHdr#e-nsNV#=va#?E$4+wv|6d+71B|u!N`KA zcHaX%M3f&?%2^Oq`)z&>>qngJ#bsuX8yw^lTvhy+JW2eoFn#>Oct=`!j17cQ{(*Wu zqw_YT-=D!b+9bH-OEjvN*&o+vDe{Fys{fYo&sP7RVIrH&P1?y!Uua1@uKu+z>w&-Q z%Uq&QtlJ-qu>8!cn|#56%V4Qh#l$`5P9)vm{c7BHOrb`G?Ck2~f?ynD*V-yBj zY!6?IyY=N-?;1@Zc}^*s?3F5V$f4O-t|O!hQ-~$y8afNuQhS4b(*={rH8tk4Fapu% ziG&*6Ic%ivXl6a38qoQ@{)GH@++->_r+;F%#7dRKu}tLHO?i#xQWU8rcUmw>tX` zE5q`@G#R%ERo(x}B)CN7O?37H3&g{Ni`y4n57^VsU8gjw?c-w*>*`k5j4NNg1#-zwbptC&EL7DY~dPoH7(lgcTZjSp>% z;-a4wxAzXdW1yCOpeq@4HDgtG_%oAVswhU+DPs72_VFmD&*O8$QEM7K9o%)a?i7AD ze}nvVnBx@}=@TCnetXb61yyx<3M=(!8&!A6o&D1h())c^kr2~4{sg@dTibB(HfOk^ zA9$|#`$~}B=~dU6Co4x5MHd_|EM%;wV#)grhg&x=2kI;RN|kC6_O$8e{M7Ca6j(8( zn-uTW;IqmACyR%pYTB6#8>cZgGacj8>kM-)wo$1wb91S~93>sZ%Et~)S{;3!ZYp2_ zBfh+hRTimdE6r|G+9+Mdeiad%q@?>ag;!-#*fA4$@~g#!J#hY_pgfjrRVT=)Lj}2DG@zGHI?j%S@Pk!;6Yi< z(E{qyzMhhEaIv<(+rpI(?-vzxksjj~9IOm$seO)oIwc+OH34PL@}fXaxK2xDYG z5UCpJumM)Y+@9oIWLtXnl{!HDftMl8^S6j)2o_IXicF;{lSes~2-wYvBg60qt&~W) zm7YXiNOCvqjE%5*s+bjnlVcJ8+V^0CWpEeDdP4wPk#PEJp#{jJltqe5w}4i6Tzsw# zQ+82DGj%isJwW{TmYvj7t5tyq1BG@kEUdX@D1H8^`B#M|`7FzLqYP`-x-$zeilW_I zcwuT7+%!F{6bx->nT%*NVVgYHpGAP3NFnO>f0;MQdMIgdB}qN?-bPC3;8@?g2QsFj zRSg8_4LC@`al&b}6ZfA*WVPEzTz2zIcT0Qz;~?P3;VN4+Q^U)L03X$O&*7+2F5&Pr gxY{FOz!2y}C=KQ)1#uk){`h!ka~reD8=eXO1MBECivR!s literal 0 HcmV?d00001 diff --git a/doc/redhat.png b/doc/redhat.png new file mode 100644 index 0000000000000000000000000000000000000000..a98a44ba6ca5afd19e8dbb55716d18e277daf626 GIT binary patch literal 1692 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 s79~O{nTsL(Pbs(l1zhxK-2eap literal 0 HcmV?d00001 diff --git a/doc/tip.png b/doc/tip.png new file mode 100644 index 0000000000000000000000000000000000000000..f087c73b7aef4ae1e4e30df11debe4cd25a73b48 GIT binary patch literal 2718 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 AfdBvi literal 0 HcmV?d00001 diff --git a/doc/windows.gif b/doc/windows.gif new file mode 100644 index 0000000000000000000000000000000000000000..626108d430ab37bd45ae9b0c3223eccb8fcaa8dc GIT binary patch literal 1543 zcmV+i2Kf0$Nk%w1VI%+`0O$VzCswXETB<8wvpQz8MPsNgY`P?JzTY<`HFCP#Ix9eP zwpDGY{`h^WN8nTMpIqM@Up!k=7z$UVxQP^F}twxe{Yq?Z4Q zJO7O>z@%Y@$UlV0OZ|;Ri^oU*k2m6?BHg4Xy{T@FuGguno~Wv)hO^XwwBWp|bkV3v zk;+4#tHpb_>G_mUtgwytnMAUxqyLvX|C%hrt!uZhg08Eun9D`~nl#a{K)bVT>8%s3 zudK4Lo4Bu*{+>0M%~JW9W0%TlkGSCanqKLyBG9m1)wMmYv$dkbhK;=Gvb3?tw0OU; ztM;FA@}7gXwXBH2?Eb1W;kzlqxr&*-;PtFZ@wpQJsy(a5k+-?FmBQoExp1(;o3Odj z*{+_pyS~G^py6_s;;t#=`W{0sPJcr_k)(zqJ3oX7|t?|Iz@_#l^7D z?dH){$;-$8zk>YP0RGk#``8uC&ddG3n#<7Axz+9e*C)f@sQlU~(9+J+(#ib9s{GqF z^2ojX+d=r=LB-kZ_{y`@*VOpmOa0wT+1uFG;LF?H+WXbQ-{IZZ>cZmW;pXG$<>%!7 z7h7DEmcCkGR+SaX2H2r+@3$dHHbXv8FEb+bDtmMg*DneXf z;7pdSoe1w~$}5q9%$Gz96(AtM0&jd$OEOMK(FG)gkRe40FsxC@EaTWy5IHSGA&fAFBymCo1_(gF z6JZp=g(uq-(~2XGOd^OPAs$E%Z3G36aWAORwz-#9