~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ FUNNELWEB - PROGRAM SERVICES for ASSEMBLY USAGE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Version 4.40 ------------- The FUNNELWEB system is held together by a reference block at the top of high memory. This has grown somewhat haphazardly over the years, but at this stage of the history of the TI 99/4a computer, plans for complete tidying up and revision have been shelved although almost all functional improvements, and more, previously intended for that grand revision have now been incorporated in Vn 4.40 of FUNNELWEB. The information and facilities available include BLWP vectors for a variety of services, indirect BL routine pointers, and various data, pointer, and flag words and bytes. Specifications of various useful BLWP and BL routines and associated data/flag items follow. Some others, mostly data and flags, are specified in FWDOC/REPT. The XOP instruction is poorly supported on the 99/4a, and is left for application programs to use. (A) BLWP UTILITY ROUTINE VECTORS ~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ (1) DSRLNK EQU >FFD4 --- ----------------- This provides a bare-bones DSRLNK function equivalent to that in the TI-Writer Editor but corrected to be compatible with multiple RS232 cards. It is for file access only and does NOT take a following DATA 8 or DATA >A instruction. This seemed like a good idea in pre-historic times when FUNNELWEB was only a TI-Writer interface and has stuck for reasons of consistency ever since. Never mind, this sort of thing happens all the time - MS-DOS still smells like CP/M and Intel's i486 microprocessor still suffers gigantic hangovers fron the 8080. After the usual setup of a PAB in VDP and PAB pointer in PAD, call the DSRLNK as BLWP @DSRLNK JEQ error handler .. Further error trapping from the PAB error bits and GPL status is up to the programmer. FUNNELWEB utilities regularly use this DSRLNK for subprogram access by the code sequence DSRTYP EQU >7A MOV @DSRLNK+2,R11 INCT @DSRTYP(R11) BLWP @DSRLNK JEQ DSERR DECT @DSRTYP(R11) success exit DSERR DECT @DSRTYP(R11) failure exit The offset value DSRTYP will be maintained at this value. All exits must restore the offset value correctly. (2) KSCANA EQU >FFD0 --- ----------------- This is an enhanced KSCAN routine which may be used in place of the normal E/A utility. It provides some extra functions transparently by setting processor status bits, which may then be tested by various conditional Jump instructions as required. There are 6 condition bits available, and the tests check these separately. BLWP @KSCANA JNC -->> --> Jump JOP -->> --> Jump JNO -->> --> Jump JEQ -->> --> Jump JGT -->> --> Jump JH -->> --> Jump (New key only) senses both and , and checks both and . Finally an unconditional JMP may be used to loop on the keyscan after one or more other tests. (3) FILENT EQU >FFCC --- ----------------- This provides a single line Editor typically used for entry of file and device names, and may be used in text mode as well from Vn 4.40 onwards. The flashing cursor has auto-repeat with acceleration, and the timing parameters are set on entry to FUNNELWEB. Editing keys are as described for filename entry. FILENT waits on entry until the previous key is released. Typical calling sequence is BLWP @FILENT DATA BYTE BYTE The initial offset gives the initial position of the cursor in the entry window, with null being the first position. The CPU buffer is assigned after entry to the routine, immediately following the workspace. The workspace is at >8302 in the PAD area, so the maximum buffer length can extend at most to the end of the DSR transient area. A calling sequence that allows another workspace/buffer area to be assigned is BLWP @FWFILN DATA DATA .. FILNT EQU $ MOV @FILENT+2,R11 FILENT code pointer in R11 RT Return via FILENT RTWP FWFILN DATA FEWSP,FILNT User "FILENT" BLWP vector FEWSP BSS >20 New workspace FILBFR BSS Follows new workspace This is a lot simpler than writing your own routine, and may be necessary if you are already using the PAD area. Several auxiliary flag locations are associated with use of FILENT. LOWCAS EQU >FF22 Lower case allowed HEXDIG EQU >FF24 HEX digits only ESFLAG EQU >FF60 flag/pointer When LOWCAS is null, the normal condition, all entries are converted to upper case as in the Editor SF/LF. FILENT always resets LOWCAS to null on exit. SETO of LOWCAS before calling FILENT allows lower case alpha characters to slip through. If HEXDIG is set before entry only valid hex digits can be entered and deletes produce "0" instead of blanks. Write a valid hex entry on the screen first as this is not checked. If ESFLAG is null then the key is ignored internally and the key value passed out. SETO of ESFLAG is reserved for internal purposes. Any other value is treated as an address pointer. First instruction in the routine should be a LWPI as the sensing occurs in the internal CURSOR (see later) routine and will exit with the FILENT registers set. (4) DELSPR EQU >FFC8 --- ----------------- This one just writes byte >D0 to VDP memory at >300 to shut off the sprite list in Graphics mode I with normal E/A table positions. It is useful in quick cleanups after switching back from Text mode. Just call as is. (5) VMBWD EQU >FFBA --- ----------------- VMBWD gives a VMBW function from in-line data, which saves program space when using fixed value data. Null length is just ignored. Call as BLWP @VMBWD DATA DATA DATA The primary FUNNELWEB workspace is at >FF7C, and R9 of this workspace always points to VMBWD so that it may be called from this workspace as BLWP *R9 making a 4 word total call. (6) VMBRD EQU >FFB6 --- ----------------- This is the VDP read version and is essentially similar to VMBWD. (7) VSBRD EQU >FFB2 --- ----------------- The calling sequence for this is BLWP @VSBRD DATA and it returns the byte in VDP memory at to the MSB of R0 (not the usual R1 in E/A code). (8) VFILL EQU >FFAE --- ----------------- This fills a block of VDP RAM with the byte value in the MSB of R0. The FUNNELWEB main workspace FWREGS EQU >FF7C maintains R8 as a pointer to this so that it may be called as BLWP *R8 etc. Standard calling sequence is LI R0, BLWP @VFILL DATA DATA (9) VMBWR EQU >FED4 (10) VMBRR EQU >FED0 (11) VSBWR EQU >FECC (12) VSBRR EQU >FEC8 ---- ----------------- This bunch of VDP utilities is equivalent to the standard E/A utility set in usage. The VM routines check for and ignore null length values in R2. (13) VSTRW EQU >FEC4 ---- ----------------- This writes the body of a string with leading length byte to VDP. Call as LI R0, BLWP @VSTRW DATA If the length byte of the string is null then the call is ignored. (14) CURSOR EQU >FEC0 ---- ----------------- The CURSOR routine is called internally by FILENT, but may also be called externally. The calling sequence is LI R6, BLWP @CURSOR CURSOR flashes at the screen position specified in the calling R6, and returns the key-value in the MSB of the calling R2, and this is left in raw state at console KEYRT (>8375) . See FILENT for a discussion of . Normally CURSOR provides the up-case function for FILENT, so the LOWCAS flag is effective here also. It is not cleared however except by the path. If you want to use CURSOR externally with hex digit validation, you will need to supply your own validation routine. A table of hex digits "01..EF" is provided at HXTAB EQU >FEA4 The cursor flash rate and auto-delays are slaved indirectly to the VDP vertical interrupt rate. On entry to FUNNELWEB the number of console keyscans that occur in an interval of 14 vertical interrupts is counted and stored at REPETS EQU >FEE4 This does not account for the difference between PAL and NTSC consoles, but this will be minor compared to possible Geneve to 99/4a difference. (14) DSRREN EQU >FEBC ---- ----------------- DSRREN is intended to give a direct DSR re-entry from saved values, as is done in the E/A object loader, or more comprehensively in LINEHUNTER. It re-enters the last DSR ROM at the same entry point directly without having to search for it. All PAB information necessary after this DSR entry must be supplied as normal. It is used in DiskReview (80-col) as the new speedup for Vn 4.40 of the Myart file viewer. It is of course not necessary to set the DSRTYP again for sub-program (eg sector read) re-entry as this is only needed to find the entry point in the original search. The relevant DSR values are stored in a 4 word block starting at SAVENT EQU >FF46 on every full DSRLNK call. (15) QDCODE EQU >FEB8 ---- ----------------- This is mostly of use internally after the AID key has been detected in the path with SETO of ESFLAG (>FF60). It checks the value at AIDFL (>FF3A) and if null returns directly, else it branches to the address pointed to by AIDFL. Usually this is a QD test/load/branch routine. (16) SETGRD EQU >FEB4 ---- ----------------- This sets the GROM address using the system GROM pointer in GPL R13, so that Module Library banking is supported. Call as LI R0, BLWP @SETGRD (B) INDIRECT BL ROUTINE POINTERS ~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ All of these routines are conveniently called by MOV @BLPTR,R11 BL *R11 together with whatever register and/or in-line data is appropriate for the particular BL call. (1) CFILE# EQU >FFA6 Uses R0,R1 --- ----------------- This takes a trailing DATA item >0n00 where "n" is the number of file buffers to be set aside in VDP as would be done with CALL FILES(n) from BASIC. The routine is compatible with V-9938 based systems, and rewrites MAXMEM (>8370) to suit. A new VDP header is written for TI/CorComp disk controllers and VDP cleared above that to the top of the disk DSR area. No range checking is done on "n". (2) KEY EQU >FFA4 Uses R2 --- ----------------- This keyloop enables interrupts, follows the previous prescription for and ESFLAG (>FF60), and calls QDCODE if AID is pressed. The key return is placed in the MSB of R2 and left unchanged at KEYRT (>8375). (3) RESTR EQU >FFA2 Uses R0.R1,R15 --- ----------------- This does various housekeeping tasks to set up the E/A Graphics I mode for the FUNNELWEB Central Menu screen. It resets the VDP registers to E/A default, rewrites the color table, clears the screen, calls DELSPR, restores the CHR(>81) pattern to underline, and restores the key-unit to 5. (4) RDDEV EQU >FFA0 Uses R0,R1,R2,R3 --- ----------------- The RDDEV routine handles the details after screen entry of a file or device name, saving the device name to CPU RAM, and building a PAB in VDP for DSRLNK. RDDEV is called externally as MOV @RDDEV,R11 Get pointer BL *R11 Go to routine DATA Entry pointer on screen DATA CPU RAM buffer for name DATA VDP address for PAB DATA PAB data storage address .. The first data item is the VDP pointer for the filename as entered on screen. RDDEV parses this up to the first space and enters it with leading length byte at the CPU RAM buffer pointed to by the second data item. It then builds a PAB in VDP at the address in the third data item, using PAB data in CPU RAM pointed to by the fourth data item. The CPU RAM buffer may well be a continuation of the PAB data, but need not be. While at it RDDEV clears the GPL status byte (>837C) and loads SCNAME (>8356) for DSRLNK. (5) QDLOAD EQU >FF3C Uses R0,R1,R2,R10,R12 --- ------------------ System files with 2 character filenames in E/A program file format may be loaded without executing by QDLOAD. A typical calling sequence is MOV @QDLOAD,R11 Get pointer BL *R11 Execute DATA 'UL' 2-char filename DATA ULPOS Load position in CPU DATA ULLEN Load length JMP .. Successful loads step over the error branch. The normal E/A header is ignored in favor of the load target position and length. The maximum file length allowed is >1100 which is long enough for QD or QF. The file is loaded from the FUNNELWEB boot path as for other system files. (4) FILCLN EQU >FEDC Uses R0,R1,R10,R14 --- ------------------ This routine cleans up the mailbox (>A000 - >A050) area, supplying the Utility pathname if nothing starting like a valid filename is found. (C) DATA POINTERS ~~~ ~~~~~~~~~~~~~ Other BL routines, data, code fragments, and pointers are for internal system use and may be subject to change in function or auxiliary conditions. Some not already mentioned which may be useful are NAMBUF EQU >FF62 The space from NAMBUF to FWREGS (>FF7C) is used a filename buffer by the various loaders. It is long enough to accomodate length byte and 25 character name (DSK.volname.filename or whatever else fits). Increase in this was the one change that would have forced major incompatibilities with previous versions, and so it has been left as is for better or for worse. BTLN EQU >FF58 This points to the length byte of the boot pathname and all references to system filenames are by offsets from this value. The Editor printer device name, as a survival from much earlier versions, though part of this block has its own pointer at EDPRNT EQU >FF1E. All these path/file and device names are stored with leading length byte, unlike the workfile name in the mailbox at >A000 which is stored without length byte as required by the Editor. INCOL EQU >FF26 The word value here is an index, range 0-9, into the 10 byte table of color bytes for use in VReg #7, and pointed to by COLRS EQU >FF1C. Standard Funnelweb system practice is always to use this table as the source of color combinations, and to use INCOL as index. This helps avoid unexpected and jarring color changes on return. CPUDEL EQU >FEE2 The value here estimates CPU speed as seen from normal expansion RAM by counting a loop against the VDP interrupt timer. It is handy as a value for CPU delay timing of beeps and bloops. Use REPETS (see earlier) for keyloop timings. ΋ՀˋՀ