Peersoft v1.5 - Page personnelle de Benoît Gilon
Contents
1. Check the option box labeled Enable hard disk controller in slot 7 and click on the Select HDD 1 action button A choose file dialog box would open Navigate to your download directory and select the file Click OK A message box could then pop up advising you that AppleWin will reboot due to change in connected bootable devices configuration Configuration 2 The emulator needs to restart as the hardware configuration has changed Harddiskts have been plugged funplugged This change will not take effect until the next tine you restart the emulator Would vou like to restart the emulator now Annuler Operation of the Shrinking procedure Once the emulator has restarted then the screen below should pop up Monday April 29 2013 Page 7 RETURN Select TAB Chg Vol ESC Back Quit U Unshrink Extract A Add to Archive L List Archive C Catalog F Format Device Erase Device Copy Files Delete Files T Type Files Create Directory Zero Probo Disk About ShrinkIT Drag and drop the D33Merlin Peersoftv15 do disk image icon on the drive 1 box with the panel at the right side of the window And select the Shrink option Copyright 1988 89 by Andrew E Nicholas D i Files ISK Quit List Archive C Catalog F Format Device Erase Device Copy Files Delete Files T Type Files Create Directory Zero Proli2. From 8388608 to 8388607 I DEFLNG32_ 32bits integer From 2147483648 to 2147483647 l Therefore the program text can be smaller in size by using default typed variables Using new integer types can make array variables use less memory than plain 16bits integer or FP arrays The support for new integer types means that o Some utilities which worked great for plain vanilla Applesoft and its support for the four kind of variables integer FP string and user defined functions might not work anymore with Peersoft given the fact that the way to discriminate integer variables is based upon examining the value of the INTTYP page zero location after a call to PTRGET subroutine 80 for 16bits integer type 81 for 8bits integer type 83 for 24bits integer type and 84 for 32bits integer type o New subroutines are provided for direct arithmetic operations implied by the four and operators see below for introduction to those new statements o The three new integer subtypes are now allowed for types of integer variables used within FOR NEXT loops with native arithmetic operations within NEXT statement handling e Anew syntax scheme for setting variable values based upon the result from an arithmetic operation LET lt variableName gt lt value gt or LET lt variableName gt lt value gt or LET lt variableName gt lt value gt or LET lt variableName gt lt value gt If specified variable is of
3. J SS and I are looked up first from then on e Use of the pseudo variable in order to avoid additional references lookups to simple variables 1 J and to array A and relevant computations Just press any key to go to next screen a Enhanced Apple e Emulator TV CONCURRENT SUBROUTINES WITHIN PEERSOFT SOURCE LISTING Ih 11 127 1 127 REM ARRAYS i CONTEXT STORAGE REM PHYS ICAL REORG OF SIMPLE VARIABLES 4 1T ii 0 0 1200 12 00 13 ACTIVATE NT KER ie 86 PRINT PROGRAM COMPLETED END 1188 GOSUB 2100 FOR 1246 GOSUB 2100 FOR 1368 GOSUB 2100 FOR RINT JO 1T NEAT JA GOSUB 2000 RETURN RINT J1 Z IT NEAT Ji 2000 RETURN RINT J2 Z IT NEAT J2 GOSUB 2000 RETURN TED RETURN 0 RETURN TU PAS A T 2 1 70 4 TO 6 T COMP T ENTE sl J i 2000 PRINT SUBROUTINE 2100 PRINT SUBROUTINE PRESS ANY KEY TO CONTINUES I L R p E Here is minimalist segment of code to illustrate the use of routines within Peersoft innovative feature indeed The first few lines listed set up the environment And the latter lines form the body of the co routines and subroutines called from within the co routines To show what is displayed on the screen resulting from running the activation just press a key as usual Monday April 29 2013 Page 13 Enhanced ane
4. 1 4 disk depending on whether you have an emulator or a real hardware on hand The relevant disk image is DOS 3 3 bootable insert it in drive 6 slot 1 and reboot your emulator computer The screen appearing should be similar to the one below bo ER JH 10 j Depending upon the CPU detected on your host environment more or less choices could be available At this prompt you can opt to bypass the Peersoft installation by using the usual lt CTRL gt lt C gt keystroke But for the time being suppose that you selected option 2 to install the Peersoft version which can benefit from the richer instruction set of the 65C02 CPU The mention that Peersoft has been installed pops up FLAVOUR TO LAUNCH There is an Applesoft named TF which allowed the user to check that the latest build Peersoft showed no regression In addition it shows up every implemented feature to interested parties either programmers themselves or end users Monday April 29 2013 Page 11 Just issue the RUN TF command from the prompt This leads to screen below The TF program can make use of the Apple gs clock chip or of a Thunderclock peripheral card as supported by the Virtual emulator under Mac OS X to measure time elapsed Enhanced Apple e Emulator Ok S Oo eH LI in oO 4 r ume TI Mag Aas TITI FII mn pa a a T mT T Just press a
5. POKE 40154 0 1102 RETURN 1199 REM PRINT A CONTEXT CONTENT JT 1200 IF PEEK AD JT 8 lt 255 AND JT lt gt IT THEN JF 1201 OF PEEK AD JT 8 256 PEEK AD JT XV IT 1 GOSUB 5010 CALL 777 OF JTe GOSUB 5000 1202 RETURN 1999 REM SECOND CONTEXT PROCESS SOME KEYBOARD INPUT FROM USER 2000 BSS CHRS 8 CUS CHRS 127 BSS POKE 49168 0 ONERR GOTO 2900 2001 GOSUB 5010 PRINT SPC 6O DIVISION EXEMPLE GOSUB 5000 LY XV IT FOR 01 0 TO 1 STEP 0 0 J ra TAIT 2002 XH IT 1 XV TT LY GOSUB 5010 CALL 958 PRINT ENTER NUMERATOR C US GOSUB 2801 ON MS GOTO 2004 VN VAL MS 2003 GOSUB 5010 PRINT ENTER DIVISOR CUS lt GOSUB 2801 ON MS lt gt GOTO 2005 2004 J1 1 2005 ON Jl 1 GOTO 2007 VD VAL MS VR FN AR VN VD GOSUB 5010 PRINT RESULT VR lt RET gt TO PROCEED CUS GOSUB 2851 ON XC 1 OR ES 1 GOTO 20 04 GOTO 2007 2006 POKE 40154 128 VTAB 24 HTAB 1 PRINT MOS 2007 NEXT RETURN 2800 REM INPUT SUBROUTINE 2801 GOSUB 5000 MS LM Q ES O FOR JS 0 TO 1 STEP 2802 GOSUB 2861 ON ES 0 AND XC 0 GOTO 2803 MS LM 0 GOTO 2809 Monday April 29 2013 Page 23 2803 ON JS 1 GOTO 2809 ON A lt gt 8 OR LM O GOTO 2804 LM 1 MS LEFTS MS LM LM 0 PRINT ASAS CUS ON LM gt GOTO 2804 MS wr 2804 ON A lt 31 GOTO 2809 LM 1 MS AS PRINT AS CUS 2809 GOSUB 5000 NEXT 2810 GOSUB 50
6. Unshrink system files this disk image will grab the DOS 3 3 disk images and put them into a ProDOS 8 archive file In case you do cannot put your hand on such disk image you can get the one from my site URL bgilon free fr apple2 Shrinklt 2mg e Anemulator for running the NuFX Shrinkit program on your modern computer To illustrate this am using the AppleWin 1 22 Win32 emulator e The CiderPress Win32 program in order to put the NuFX archive files onto a compact memory e The CFFA Compact Flash memory disk drive for Apple e or gs mine is CFFA 2 0 but a newer version has since been released with the ability to directly read po and do disk images Monday April 29 2013 Page 6 Other paths are available for performing the same tasks dealing with serial communication interfaces between a modern computer and the Apple Configuration of Apple Win 1 22 After having downloaded the disk image containing a bootable ProDOS 8 and the Shrinklt system file open the Configuration window by pressing the F8 function key AppleWin Configuration Configuration Input Sound Disk Advanced Floppy Disk Drives Disk access speed Enhanced Speed ka Select Disk 1 D34Peersofty 14 do Select Disk2 Hard Disk Drives Select HDD 1 Shrinkit 2ma Path to CiderPress C Program Files FaddenSoft CiderPress C
7. and professional business aspects of my life would suggest to not hold your breath Feature s implemented Estimated delivery date Generalized user defined functions DEF FN more args 1 5 31 04 2013 EE allowed and arg Variables of any type not just FP Support for remaining utility routines to reorganize the 1 31 04 2013 Applesoft variables areas both simple and array pon 6 Merge with Bananasoft utility using similar technology but f i feat ther than performance the name of ocusing on features ra p 08 09 2013 resulting software could be fruit salad but still quite unsure about this Generalized integer arithmetic for expression evaluation i e 1 the sub expression A 1 will be evaluated using integer 08 09 2013 arithmetic first and only reverting to FP operation in case an overflow occurs Monday April 29 2013 Page 4 Feature s implemented Estimated delivery date Compilation of Applesoft user defined functions to convert 1 7 them to machine code callable with USR lt n gt functions 31 12 2013 provided by Bananasoft n from 0 to 9 Peersoft physical package description Peersoft consists of a zip archive Peersoftv1 5 zip containing e One disk archive with the do suffix DOS 3 3 sector order providing a complete Merlin 8 environment DOS 3 3 version 2 47 by Glen Bredon from Roger Wagner Publishing and full assembly source code to build Peersoft T PEERINTEGARITH Peersoft P
8. 10 CALL 868 PRINT GOSUB 5000 RETURN 2850 REM GET RETURN SUBROUTINE 23851 GOSUB 5000 ES 0 FOR JS D TO 1 STEP 0 2852 GOSUB 2861 JS ES 1 OR XC 1 OR A 13 GOSUB 5000 NEXT GOSU B 5010 CALL 868 GOSUB 5000 RETURN 2860 REM GET KEYBOARD ENTRY 2861 ON PEEK 49152 gt 127 OR XC 1 GOTO 2862 POKE 40155 1 GOTO 2861 2862 GOSUB 5010 IF XC THEN GET AS A ASC AS 2863 ON XC 0 GOTO 2864 PRINT ABORTED 7 JS 1 2664 ON A lt gt 27 GOTO 2865 PRINT lt ESCAPEDS JUS LESS 1 2865 ON A lt gt 13 GOTO 2866 JS 1 2866 RETURN 2900 ON PEEK 222 lt gt 255 GOTO 2902 2901 XC 1 49 CHRS 3 tA Se PRINT CHRS 22 RESUME 2502 ON PEEK 222 lt gt 133 GOTO 2903 EL FN DR 218 ON EL lt gt 2005 GOTO 2 903 MOS DIVIDE BY ZERO ERROR J1 1 CALL 3288 GOTO 2006 2903 PRINT CHRS 7 7 GOTO 4003 2998 REM 3RD CONTEXT MAIN ROUTINE JUST PRINT SOME STAR CHARACTERS 2998 REM 3RD CONTEXT MAIN ROUTINE JUST PRINT SOME STAR CHARACTERS 2999 REM AS A BACKGROUND ACTIVITY 3000 FOR J2 0 TO 1 STEP 0 J2 J1 GOSUB 3008 3001 PRINT T gt GOSUB 50002 NEXT 3002 FOR J2 1 TO 4 GOSUB 3008 PRINT MIDS OVER J2 1 GOSUB 5000 NEXT RE TURN 3008 XV IT INT RND 1 15 6 XH IT INT RND 1 40 1 GOSUB 50102 RETURN 4000 IF PEEK 40156 lt 128 THEN VTAB 23 HTAB 1 CALL 771 END 4001 ON PEEK 222 255 GOTO 2901 4003 XH IT 1 XV IT 23 GOSUB 5010 CALL 771 GOSUB 5000 CALL
9. DOS 3 3 sector order providing a bootable DOS 3 3 image with the binary exe files from Peersoft either machine code or Apple soft sample files File name on disk HELLO Boot program displaying a menu and prompting the user to select a valid Perrsoft program version to load according to CPU detected purpose is to detect host CPU flavour PEERSOFTV15_ 6502 One binary executable file per CPU each file results PEERSOFTV15_65C02 from assembly from PEEROFTV14 S source files with PEERSOFTV15_ 65802 different setting for the KOPT and KOPT16 macros features currently included within Peersoft TCPRECON Object file loaded by TF program which deals with peripheral clock chip detection and time elapsed measurements Thunder clock and gs internal battery clock chip SMTRECON Object file loaded by TF program which deals with peripheral clock chip detection and time elapsed measurements NoSlotClock device chip mechanism of co routines in some unusual ways Auxiliary machine code routines loaded at address 0300 Currently only serves to toggle the speaker as a coroutine is swaped in swaped out e Peersoft documentation in the form of a PDF file you are currently reading How to transfer the two disk archives to real 5 1 4 disks on an Apple hardware In order to transfer the content of both disks to a native hardware Apple computer We will use the components below e A pre formatted disk image with ProDOS2 0 3 and NuFX Shrink
10. Disk About ShrinklT ee i Select the Shrink Disk option Monday April 29 2013 Page 8 Monday April 29 2013 Volume Name 0g F Format Device Erase Device Copy Files Delete Files T Type Files Create Directory Zero Probo Disk About ShrinkIT Copyright 1988 89 by Andrew E Nicholas 1 2 k 1 oi a mi ESS o gt D i qf YO wo x EN BNI 1820 B Enter the label for this backup within the archive Here SOURCES D33 Now enter the name of the ProDOS file which will contain the backup you are about to initiate Here have entered the filename PEERSOFTV15 SHK Once the RETURN key has been pressed the progression bar for the shrinking advises you of the progress so far Enhanced Apple e Emulator TV S 5hrink SOURCES D33 r ss elete Files T Type Files Create Directory Zero Proli Disk About ShrinkIT The next step would be to reiterate the procedure above for the D34Peersoftv14 do disk image Checking that everything is OK at the end of this step can be done by listing the content of the archive which is an option available from the main menu Enhanced Apple e Emulator TV isk 148k Ho Datel sk 140k No Datel Monday April 29 2013 Page 10 Peersoft user manual Peersoft executable files come within the D34Peersoft14 do archive or real 5
11. Emulator TV T T L te gt ROUTINE 6 COMPLETED BROUT INE 1 COMPLETED Wap m u 1 H S jak j iT mz Fe COMPLETED ac a A ii I 1 1 be tft P 1 Every co routine is entered and completed and the allocation of CPU to each thread follows a round robin model till all subroutines complete thus triggering the end of program The co routine feature is thoroughly described in a subsequent chapter Monday April 29 2013 Page 14 Peersoft reference manual Variable default typing DEFINT A I N Z To specify the scope of variables involved by every DEF lt type gt instruction you just have to list first characters either alone or as part of a range In the sample above every variable simple or array which first character is A K C M N or Z will have a default type of integer The involved statements are DEFINT DEFSNG DEFSTR DEFBYTE DEFLNG24 and DEFLNG32 the three latter being added with release of version 1 5 DEF lt type gt statements can appear anywhere within a program text and be run at anytime within the program flow At program start or when a RUN CLEAR Applesoft statement is run within the program flow then all variables inherit the Floating point type default However an explicit type specifier 5 or the new used for floating point variables
12. L P C B Peersoft v1 5 An Applesoft extension Benoit GILON 28 02 2013 Peersoft is an Applesoft extension which focuses mainly on performance issues rather than features Currently it is to be considered as a complement to the Bananasoft utility already released attempting among other features to enrich the Applesoft interpreter by adding new keywords found in other flavors of Microsoft Basic Anintroduction to Peersoft Peersoft is an Applesoft BASIC extension which aims to provide to the Applesoft programmer features in addition to those offered by plain vanilla Applesoft interpreter alone Currently in its present incarnation Peersoft runs on DOS 3 3 only but a ProDOS version could see the day in months to come if demand level is high enough However three versions of Peersoft exist depending on the CPU detected within the Apple 2 host either 6502 65C02 or 65802 16 with relevant code optimizations for the two latter CPUs The focus has been put on performance aspects while authoring this software Here are the main features delivered with this release of Peersoft e New instructions for defining a default variable type per name s first character Tableau 1 New statements for specifying a variable s default type N Suffi Type of variable Magnitude a statement character DEFBYTE From 128 to 127 DEFINT 16bits integer From 32768 to 32767 DEFSNG Floating point 5 bytes SS DEFLNG24 24bitsinteger
13. OUTINE IT 7 ABOUT TO QUIT RETURN 1 TO 4 PRINT J1 ITS NEXT 1 TO 6 PRINT J2 1T NEXT Address 40160 contains a pointer to the general utility routine within Peersoft The arguments are described in the table below Table 2 Arguments for activating the MT kernel h ie routines defined by parm values It is the name of the Applesoft variable must be simple integer type variable which will hold the current thread index value from 0 to NumCoRoutines 1 Peersoft updates this value upon every context switch Name of the integer type array which will contain the context storage for the 1 co routine structure of this array is given in a section below This parameter defines whether the co routine has a private error handling routine of its own This parameter should be considered as a bit string here where for our purpose only the two lsb interest use Three values are possible here 0 implies that no error handling at all while the co routine is the one run by CPU That means that no segment exists in the context dealing specifically with the error handling making its size smaller and its store and retrieval faster Whenever the context is restored a zero is stored in the ERRFLG flag page zero location 1 Private error handling which instructs Peersoft to cater for dedicated error handling segment within stored context for this co routine The co routine should however execute an ONERR GOTO nnn in
14. RE 5 4998 REM STORE CURSOR POSITION INTO CONTEXT AND RELEASE CONTROL TO MT 4999 REM EXPECTS TO BE CALLED WHILE CONTEXT SWITCHES INHIBITED 5000 XH IT PEEK 36 1 XV IT PEEK 37 1 POKE 40155 1 POKE 40154 0 RETURN 5009 REM INHIBIT CONTEXT SWITCH AND RESTORE CURSOR POSITION FROM STORED CONTEXT 5010 POKE 40154 128 VTAB XV IT HTAB XH IT RETURN Monday April 29 2013 Page 24 Sommaire AIL odu tornio6PoOaSsS0t uuu u u EEE 2 PCS zl PEI ISIS sss ss 4 Peersoft physical package description n 5 How to transfer the two disk archives to real 5 1 4 disks on an Apple hardware 6 Configuration of Apple Win 1 22 uu 7 Operation of the Shrinking procedure r 7 Peer oku ermana uu u uuu sus 11 Peer ort PETEFENCe Monal E E 15 Vee dele ome 121 Wt DINE u ern eC Ee ee ee 15 New syntax scheme for altering Variables values cccccccssseccecesecceceescceeeeseceeeueceeeeeeceeseuseeetsenecss 15 OP euo Vil pi u uuu uuu unu usss 15 Integer variables as loop variables within FOR NEXT loops r 16 Some Applesoft statements pro
15. UT file handling the integer arithmetic routines handling the and for integer variables as well as the loop variable increment whenever that loop variable is integer NEXT statement CRECON S Assembly source file for handling CPU recognition upon Peersoft boot see HELLO Applesoft program from other disk object installs as a 0300 subroutine and thus helping launching the proper Peersoft executable file TCPRECON S Assembly source file for detecting a thunder clock peripheral card or a gs clock chip both can be used to measure time spent by Applesoft subroutines within the TF Applesoft program Object file is loaded as a 0300 subroutine from TF BASIC program SMTRECON S Assembly source file for detecting a NoSlotClock device within an Apple e or c and making use of it TUTMC S Assembly source file for monitoring context switches as used by the TUTORIAL Applesoft program which serves as a demo for the co routines features Here only a speaker toggle is applied thus routines are rather short HELLO MERLIN ASM 1 Files originating from a Merlin 8 standard distribution ASM 2 ED 16 ED XREF v2 47 DOS3 3 flavor FORMATER XREF A KEYMAC S KEYMAC T MACRO LIBRARY T SEND MSG T FPMACROS MON 65C0O2 SOURCEROR LABELS S LABELS PRINTFILER S PRINTFILER T ROCKWELL MACROS T PRDEC T OUTPUT MAKE DUMP S EDMAC S EDMAC Monday April 29 2013 Page 5 e One disk archive with the do suffix
16. a variable is proportional to the number of variables of same kind i e simple or array that have been defined i e referred to from BASIC program text for simple variables before the time the current variable looked up for has been created The order of definition of variables within the program flow seldom follows an order with which most used referred to variables or arrays are created first We tend to define some constant variables suchas DS CHRS 4 atthe very beginning albeit the fact that such variable will be much less frequently used than for instance a loop variable from an inner loop The goal of the provided utility routines is to optimize variable Monday April 29 2013 Page 3 access after variables have been created and thus their memory storage address defined Two alternative approaches have been supplied o Physical re organization of array simple variables areas where actual variable slot are actually moved within the area o Cache based variable referencing here the variables storage slots are kept at the same original place within memory Instead Peersoft manages a small memory area to keep some variable names and addresses in a safe place Such variables are looked up for at first place when a reference to some variable need to be returned and thus lookups for such variables are the fastest e Availability of co routines within an Applesoft program this is a new paradigm for every Applesoft program author N
17. cessing busgfixes rr 17 I l S j GIO usu nu un uu bunu D 17 RETURN and POP SLISteme tSu u uuu u u uu u u uu sssssapakasspusaskakapaukasasaywayakaakukasusakaykasanaukipa 17 COrTpiuli eswitpinPeerSsgu u uu uuu 2 u aS usus 17 Activating he CO PO UNS u ul u u u uuu k L 17 Deac vatine the Co uuu uuu u uuu rE re ee 19 Peersoft data structures and hints for performing usual tasks from Applesoft programs relating EO WO K S u E E ai au u 5 ns 19 Peersoft co routines tutorial sccececcscscscsccceccscecscctestececesecseseecetescscecesescsescecersscecececesceescesevessecs 22
18. ebraic highest possible value an integer variable can be bound to This is because as the last iteration the loop variable being equal to the final value completes the first operation the NEXT statement does is to increment the loop variable s value here 32767 with the STEP value default 1 this add operation causes an overflow within the 6502 and thus the overflow exception is raised to the Applesoft environment itself raising an OVERFLOW ERROR for the Applesoft program The same limitation exists for a final value as 32768 when the STEP value is 1 Some Applesoft statements processing bugfixes Every bug fix provided here is an obvious code update to bugs raised as part of the Web resource already mentioned http www txbobsc com scsc scdocumentor ONERR statement The current Applesoft implementation for the ONERR statement processing erroneously skip the whole physical line after processing instead of just up to next end of instruction marker This is fixed within this Peersoft release RETURN and POP statements Co routines within Peersoft A word of advice this section describes the working of co routines features within the 1 4 release of Peersoft Future releases might expose other API to the external entities in case this interface evolves or others appear then this section will be updated accordingly within the document you are currently reading From now on an Applesoft program should be considered a
19. ext for the co routine 18 and 19 OLDTEXT OLDTEXT 1 Text pointer of last instruction parsed by interpreter exec loop Local Error handling segment optional see value at offset 8 Monday April 29 2013 Page 21 20 and 21 TXTPSV SF4 TXTPSV 1 Points to the first character of line as ONERR GOTO statement is parsed 22 and 23 CURLSV SF6 CURLSV 1 Line where the ONERR GOTO is located ERRNUM SDE branch back to the faulty statement RESUME could branch back to the faulty statement 28 and 29 ERRPOS SDC ERRPOS 1 TXTPTR pointer of the statement raising the error ERRFLG 508 Only bit 7 is meaningful here Stack segment variable size lt ValueAt Offset 7 gt and above N A in page zero within From private stack pointer to global environment stack hardware page 1 pointer value Peersoft co routines tutorial Within the Applesoft program listing below e The arrays 1 and 12 serve as context storage areas useful for switching between co routines e The arrays XH and XV serve as memory place where to store screen cursor locations horizontal for XH and vertical for XV for every co routine implemented here the number of them being 3 Monday April 29 2013 Page 22 e Variable XC serve as an indicator that the user issued a Ctrl C keystroke while the program was running Therefore it is set to a non zero value at line 2901 part of the shared general error handling routine begin
20. in a previous section An alternate way is to get the vector stored at 40159 1 40159 2 and calling it directly cf sample Applesoft above 40158 S9CDE Peersoft version byte currently a 15 value is stored at this location meaning 1 5 10 setup whenever Peersoft is loaded from disk 40156 S9CDC Bit 7 set iif the MT kernel is active A call to CALL RE 4 will set it up This flag is reset whenever the MT kernel is terminated usually as the last co routine returns to the global environment Monday April 29 2013 Page 19 40155 S9CDB Number of ticks that the currently running co routine will last before next context switch At every context switch Peersoft copies the S9CDD slot into this slot upon running an Applesoft instruction the context switch occurs only if the value from this slot decremented by one reaches zero 40154 S9CDA Bit 7 set if context switch temporarily inhibited while a critical section of code is run by the current co routine What happens when the co routines are established A GOSUB stack frame is created in the stack segment of every co routine s context This GOSUB frame indicates that the return points to just after the CALL RE 4 Applesoft statement Obviously the stack pointer for every established co routine is decremented by the frame size 5 bytes including the GOSUB token Peersoft marks a co routine as being completed when as this co routine is being run by the CPU the cur
21. la Applesoft interpreter all that is returned is a SYNTAX ERROR message FOR I 1 TO 10 PRINT 1 NEXT I believed that the use of integer arithmetic for processing the increment and test for final value as part of the NEXT statement processing would greatly offer benefits in performance terms H las in French in the text by the time the loop variable appears in the loop body then all benefits disappear because handling of integer variables is much more costly than of floating point variables just by the fact that the retrieved integer value needs to be converted to floating point whatever the context OK now with Peersoft installed you can have integer variables as loop variables but wouldn t tell you more about it until September this year cf section Peersoft roadmap for further details on future developments Ah yes be advised that Applesoft is bugged in its integer variable handling too Have you ever tried toissuea AS 32768 only to get bounced witha ILLEGAL QUANTITY ERROR message Users curious about this state of things could study the excellent Web resource already mentioned in this document http www txbobsc com scsc scdocumentor Suffice to say that AS 32767 5 works well and provides the same expected result Monday April 29 2013 Page 16 Another limitation to warn the reader about is that the final value of such loop using integer variables cannot be 32767 which is the alg
22. ning at line 4000 see ONERR statement at line 2 and part also of the dedicated i e private error handling for co routine 1 beginning at line 2900 e RE holds the address where to call the Peersoft general utility routine with appropriate parameters I CLEAR DEFINT DIM T104 0127 110127 124127 7X 2 yXV 12 2 PRINT CHRS 4 TEXT HOME XC ONERR GOTO 4000 3 PRINT CHRS 4 BLOAD VTAB 12 HTAB 15 PRINT TUTORIAL 2 4 XH 0 1 XV 0 2 XH 1 1 XV 1 21 XH 2 1 XV 2 6 DEF FN DR A PEEK A 256 PEEK A 1 DEF FN AR CX INT CX 100 01 5 RE FN DR 40160 POKE 40157 4 REM OF APPLESOFT INSTRUCTIONS RUN BETWEEN TWO SWITCHES 6 CALL RE 4y17 10 2 0 0 1000 LLL L 68 gt 774 20004 12 27 474 165 3000 7 VTAB 1 HTAB 1 PRINT PROGRAM ENDED PRESS ANY KEY GET AS HOME END 999 REM FIRST COROUTINE MONITOR EVERY CONTEXT INCLUDING ITSELF 1000 AD FN DR 40152 O0OF O NT 0 SO PEEK AD 17 SL O LX 1 GOS UB 5010 PRINT RUNNING TASKS STATUS SO 7 gt GOSUB 5000 xXH XH IT XV XV IT 1002 FOR JT 0 TO 7 ON PEEK AD 8 JT lt 255 GOTO 1003 NT JT 1 JT 7 1003 NEXT JT FOR JO 0 TO 1 STEP O GOSUB 1100 JF 1 1004 FOR JT TO NT GOSUB 1200 NEXT JT 1005 JO JF NEXT JO RETURN 1099 REM 1100 ON PEEK 40157 LX GOTO 1102 POKE 40154 128 HTAB XH VTAB XV LX PE EK 20157 1101 PRINT LX 72 CALL 868 POKE 40155 1
23. ny key on your keyboard to proceed Enhanced Apple e Emulator TV DEFC INT SNG STR AND t l 3 _DEFIHT A DEFSTR _ S BON Pe S HELLO w l LIL 1 E 4 4 i e This screen shows some new features available by using Peersoft as e Anew way to concatenate strings e Default typing for Applesoft variables using the DEFSTR DEFINT and DEFSNG statements e Some new syntax schemes for altering values of variables Just press any key on your keyboard to proceed Monday April 29 2013 Page 12 Enhanced Apple e Emulator TV i II U rie 4 mtin ii z 1 i IT H H Ll r Ue T gt Am m gri SCI OT Mo ra II ll et k Sa iT Hour or m ee le We e B loins F oe a ma Y iG 1T gt TI Lota iS Ee um gt lt MI T COHTIHLIE Here no clock was detected no support from the AppleWin emulator is provided thus the only mention the program delivers is meaningless and the user should have a convenient external medium for time measurement this time The features that are showed within this screen are e Use ofa utility routine to physically reorganize the simple variables memory area so that the variables
24. on variable particularly when dealing with multi dimensions array variables So the idea of implementing the pseudo variable was born Anytime an expression is evaluated then the Applesoft interpreter will use some constant locations within page zero as main and auxiliary accumulators large enough to contain an integer a floating point value or a string descriptor The pseudo variable is the simplest in its processing code All it does is a RTS actually it s a bit more than that but only by a small amount cf source code for further details this would imply that the returned value will come unchanged from what it was during the last factor evaluation Beyond the sample code showing up in the previous section Peersoft user manual the could also refer to any content of any type PRINT RIGHTS AS LEN 4 will print the AS current value with its first 4 characters removed Use of the pseudo variable as the first term evaluated within an expression thus possibly referencing the result from a previous statement expression is not recommended especially from within a co routine cf section named Co routines within Peersoft for details upon what a co routine is in author s mind Integer variables as loop variables within FOR NEXT loops was worried that Integer variables be banned from being used as loop variables within FOR NEXT loop constructs If you try the statement below under plain vanil
25. or Peersoft usage 5 and 6 Value of first and last dimension Constant segment general use Offset to stack segment always populated Operation mode for context BOb1 provides an indication whether the local error handling is in use or not In case local error handling is in N A use whether the global environment is used for such context or not B2b7 provides options for additional context switch operations The one being shown within the tutorial is the display cursor backup restore operations Constant segment for monitoring context switches Address of machine language routine to be called whenever the co routine is paged in This routine must 9 and 10 N A not alter register values from the calling environment unless pushed on stack and must return with a RTS after possible Pull from stack instructions High byte is SFF if no routine registered Address of machine language routine to be called whenever the co routine is paged out This routine must Ina is N A not alter register values from the calling environment unless pushed on stack and must return with a RTS after possible Pull from stack instructions High byte is SFF if no routine registered Core segment always populated 13 REMSTK SD8 Current stack pointer for this pointer only byte at offset 8 is meaningful 14 and 15 CURLIN CURLIN 1 Current Applesoft line for the co routine 1Gandi7 XTPTR SB8 TXTPTR 1 Current text pointer within program t
26. or the u n new T and for alternate integer types as a variable name s suffix overrides its default type currently defined Thus the statement sequence CLEAR DEFINT I I 1 PRINT I will print on screen New syntax scheme for altering variables values A 3 Peersoft will simplify variable value alterations by providing a new syntax scheme The new A 3 being a shortcut forA A 3 All four basic operations can be part of the new syntax scheme For instance A 3 is a shortcut forA A 3andB 4isashortcutforB B 4 The new syntax scheme can be included in every context where a variable has its value set within program text This includes the FOR NEXT loop construct FOR I 5 TO 10isashortcutforFOR I I 5 TO 10 Whenever the variable type is integer then arithmetic operation applied is of the integer kind too Also the syntax scheme is also valid for string concatenation whenever the variable is a character string S BONJOUR SS HELLO PRINT S will print BONJOUR HELLO onto the output display Pseudo variable Having written quite a number of applications myself and studied the code from other authors as well I ve found out that one pattern that emerge quite often is the use of the same sub expression variable multiple times within an expression Sometimes there is a cost in term of Monday April 29 2013 Page 15 performance to lookup some sub expressi
27. ow he is able to design his programs as if they run under a multi tasking environment The application could be considered as an assembly of phases where the kernel is active co routines active and running concurrently and where kernel is inactive the kernel is inactive only one flow is processed by the Applesoft interpreter Beyond what follows an subsequent entire chapter has been dedicated to describe its configuration and operation within this document o Because the switch between co routines will occur at known and arbitrary locations within the interpreter loop then the context can be kept rather small compared to true multi tasking monitors o Unlike true multi tasking monitors no hardware generated external signal IRQ is used and thus Peersoft co routines run equally well on the whole Apple 2 range from the Apple II standard with Autostart ROM to Apple gs and every emulator environment I currently know of Peersoft roadmap The features described in the previous section are actually implemented in the Peersoft current release However not all the features envisioned from the start have already been implemented Some are yet to be developed from scratch in order to meet the author s original requirements The table below provides some hints about what additional features will be developed and candidate release dates However as this project is founded upon the time left only as am idle on both the other i e family
28. rent stack pointer reaches the original stack pointer value taken as the CALL RE 4 Applesoft statement was parsed Hints and tips How to release control to other threads from the current co routine Just use the POKE statement POKE 40155 1 just before the location where you want to release control While parsing the next statement Peersoft will decrement this value to 0 and thus a context switch will be triggered saving the current context and restoring the next active co routine declared within the kernel Be advised that this could be the same co routine as the current one in case no other is still active How to temporarily disable the context switch While a critical section of Applesoft code is being run within the current co routine no context switch should occur in order to let this section of code appear as being atomic A simple way to fit this requirement is to inserta POKE 40154 128 statement at the beginning of your critical section code In order to reinstate switches for giving a chance for other co routine to flow normally then use the POKE 40154 0 statement at the conclusion of this section Also as the decrement operation is not processed while the switching is inhibited it is a good idea to inserta POKE 40155 low value just in the vicinity of the former POKE statement as did in my tutorial example Applesoft programs Having private variable sets no collision between co routines The current solution propo
29. s a sequence of consecutives phases some with active co routines flows of control running in and on different parts of the program text and inactive co routines when a unique flow of control exists and determines the program behavior Except when you previously installed another multi tasking environment in your Apple 2 then every Applesoft application has to be considered as a purely sequential unit of flow on time before the adoption of Peersoft in its current incarnation Peersoft provides two ways of doing for both transitions one for from purely sequential to active co routines and the other for the other way round Activating the co routines simplistic sample For activating the MT short for multi threading kernel and the co routines which come along then a unique way of doing this is given below minimal sample o DIM 10 LA yz 12 LO 10 RE PEEK 40160 256 PEFK 40161 20 PRINT ACTIVE CO ROUTINES PHASE ABOUT TO BEGIN ON LINES 1000 2000 AND 3000 Monday April 29 2013 Page 17 30 CALL RE 4 IT I10 0 0 0 1000 11 0 0 0 2000 I2 0 0 0 3000 40 PRINT ACTIVE CO ROUTINES PHASE ENDED END 1000 GOSUB 5000 FOR J0 1 TO 2 PRINT J0 IT NEXT 1010 GOSUB 5010 RETURN Z000 lt GOSUB 5000s FOR Jiz 2001 GOSUB 5010 RETURN 3000 GOSUB 5000 FOR J2 3001 GOSUB 5010 RETURN 5000 PRINT CO ROUTINE 7 1IT ENTERED RETURN 5010 PRINT CO R
30. se is to get arrays of variables with at least one dimension indexed by the context index value In the tutorials from the disk used two arrays XH and XV to store cursor data line and column where cursor lies in two dedicated integer arrays and all PRINT statements or cursor position setting statements being run in critical sections of code Committing suicide or assassination of other threads Beyond the usual way to mark a thread as completed i e using RETURN or POP instructions in order for the stack pointer to reach its initial value an alternate and more intrusive way would be to force a specific byte from Peersoft memory to SFF value thus Peersoft will consider the relevant co routine as completed Here is the code segment which performs just that action Monday April 29 2013 Page 20 AD PEEK 40152 256 PEEK 40153 POKE AD 8 IT 255 Where IT being the current context index implies suicide and IT being unequal to current context index but still between 0 and 7 meaning assassination Structure of the context storage Every context is stored within a dedicated integer type array variable one dimension which layout is described in the table below Table 4 Context Storage layout Offset Header for housekeeping by Applesoft Oand 1 Name of the array two bytes Offset from the beginning of this array to next array 2 and 3 N A variable or to end of memory area Number of dimensions must be 1 f
31. struction in its own flow of control 2 The co routine relies on the status of the global environment ie error handling status as the CALL RE 4 is run a context segment for dealing with error handling is created iif the ERRFLG page zero location SD8 meaning an ONERR handler is active is set upon the CALL RE 4 is processed by Peersoft The role of other bits b2b7 from the value are described in a subsequent section This parameter is the address of a machine language subroutine ending with a RTS instruction called whenever the co routine is about to be active gain the 6502 CPU The sub routine must not change any register value cf Push and Pull 6502 instructions This parameter is the address of a machine language subroutine ending with a RTS instruction called whenever the co routine is Monday April 29 2013 Page1l8 April 29 2013 Page 18 1 co routine about to release control and the corresponding context be stored in the context storage area see array 10 description above The sub routine must not change any register value cf Push and Pull 6502 instructions This is the co routine starting Applesoft BASIC line number Consider that internally the CALL RE 4 does a GOSUB to this line number upon co routine activation Arguments descriptions for 2 and 3 co routines are similar in their description as the ones for the 1 co routine s arguments Up to 8 co routines can be active a
32. t the same time Activating the co routines Not so simplistic approach Now suppose that a particular co routine needs to have a dedicated environment for text cursor positioning The context segment representative of text cursor positioning could be summarized within the table below WNDLFT WNDWDTH WNDTOP WNDHGHT for text window setting on the display screen and CH CV BASL BASL 1 for cursor location within the window Deactivating the co routines Beyond the natural and normal way of returning to a single flow for the Applesoft application let every co routine return to the statement following the CALL RE 4 instruction by using a combination of RETURN POP statements themselves The fastest way is based upon a new reason code for the Peersoft general utility CALL RE 5 is the instruction to insert within the code of a co routine including its error handling procedure dedicated or shared Such statement must be run as the MTK is active Peersoft data structures and hints for performing usual tasks from Applesoft programs relating to co routines For reference by assembly language programmers here is the structure of the Peersoft global page and of every integer type array variable used by Peersoft for context storage purposes Table 3 Peersoft global page Address Address Description decimal hexadecimal 40159 S9CDF A call to this address will branch to the Peersoft general utility routine already described
33. type integer then used arithmetic is of type integer too also the syntax scheme can be applied to string variables as well The main benefit beyond using integer arithmetic when adequate is to minimize the number of variables references Monday April 29 2013 Page 2 compared to a syntax as inthe statement LET lt variableName gt lt variableName gt lt operator gt lt value gt particularly when variableName is a multi dimensional array with index values equals e Before the release of Peersoft v1 5 an array element from array named A could only be referred to by using the expression A lt expression gt lt expression gt presuming that the array A was defined as having two dimensions with a DIM statement this is the common way of using array variables from within the program text But now with Peersoft v1 5 the same element could be referred to by using only one dimension specification The two code extracts below 10 DIM A 4 5 5 0 FOR I 0 TO 4 FOR J 0 TO 5 5 Mi yt NEXT J I 10 DIM A 4 5 S 0 FOR I 0 TO 29 S A I NEXT I Will both compute the sum of every element value into the S variable This new way of authoring code will simplify some computations upon arrays and thus enhance performance of such computations Also within the original Applesoft interpreter there was a limitation that an expression value for giving a dimension must be less than 32768 At the time Applesoft was authored this
34. was sensible as the smallest size element type was integer and takes 2 bytes for storage given the hardware limitation of 64K for 8bits architectures now this limitation was increased to 65535 thus addressing up to 65536 1 byte elements such as bytes within 64Kb e Anew pseudo variable usable in arithmetic expressions and which replicates the value currently stored in the Applesoft floating point accumulator For instance the statement S 0 FOR T 0 TO 9 FOR J 0 TO 975 A ti J Ff NEXT 2 1 will compute the sum of squared elements from matrix A You will notice that the code only refer to every element of matrix A just once and that the operator between a value and itself is known to be and actually is faster than the concurrent expression A I J 2 e Integer variables now allowed as loop variables of FOR NEXT loops also arithmetic operations comparisons when running a NEXT statements is of integer type whenever the loop variable is of type integer itself e Fixes to some of the Applesoft instructions processing ONERR RETURN and POP if you get a look at the Applesoft disassembly listing generated by S C Documentor and commented by Bob Sander Cederlof http www txbobsc com scsc scdocumentor then you ll find out that Applesoft has many bugs buried in its code e Utility routines provided to optimize access to Applesoft variables For either simple or array variable kinds time spent to get a reference to
Download Pdf Manuals
Related Search