Notes on Opus EDOS Greg Cook, 1 November 2024 Opus EDOS is a double density disc filing system by Alan Williams, which is compatible with DDOS. EDOS is written for Opus' WD2791 expansion board, which is fitted in place of the Intel 8271 controller chip in IC78. This document refers to the original EDOS, dated 1984. EDOS 1.51 (see below) fixes many bugs and provides enhancements. EDOS offers: - Acorn DFS: 200 KiB SD, 31 files per side, 0.5 KiB catalogue - Opus DDOS: 360 KiB DD, 248 files per side, 4.5 KiB catalogue - EDOS SD-4: 200 KiB SD, 124 files per side, 2.5 KiB catalogue - EDOS DD-0: 360 KiB DD, 31 files per side, 0.5 KiB catalogue - Plus 10 unique formats: SD-1 to SD-3, DD-1 to DD-7 - Double stepping in software; use 40 track discs in 80 track drives - Direct saving from paged ROM, loading and saving to/from paged RAM - Reduced memory usage (OSHWM = &1700) - Decoded disc error messages - Tube support - Built-in disc tools - *ENABLE or prompt confirmation - Clean ASCII dialogue suitable for use over serial links. To make full use of EDOS, the Opus Challenger manual is recommended reading. The Challenger extensions apply, not the DDOS ones. Operation is as documented in the manual, except as follows: - *CONFIG, and the Challenger hardware features, are unavailable. - The *VOLGEN command is renamed, and track allocations are given on the command line: *CATGEN[ ]{ } E.g. *CATGEN 2 A30 B30 F10 - OSGBPB supports calls with A=4 (read data using internal pointer). A=3 should be documented as 'Set the file pointer to P, then as for A=4.' The carry flag is undefined on exit. Errors are signalled by BRK instructions or, if A<5 or A>7, by L being non-zero. - The correct form of the 8271 Read ID command is as follows: OSWORD A=&7F XY+0 Drive XY+1..4 Address of block to contain ID bytes XY+5 3 = Number of parameters XY+6 &5B = Command XY+7 Track number XY+8 0 = Not used by EDOS XY+9 Number of ID fields to read XY+10 Result - The 8271 Format command is supported, entry conditions as follows: OSWORD A=&7F XY+0 Drive XY+1..4 Address (I) of CHRN values XY+5 5 = Number of parameters XY+6 &63 = Command XY+7 Track number XY+8 &12 = Gap3 length (&FF/&4E part only) XY+9 &2A b7..5 = Sector size (see Read ID documentation) b4..0 = Number of sectors on track XY+10 0 = Gap5 length (not used on mini-floppy discs) XY+11 &12 = Gap1 length (&FF/&4E part only) I+0 0 = Logical track number for first sector (C) I+1 0 = Logical head number for first sector (H) I+2 0 = Logical record number for first sector (R) I+3 1 = Length of first sector (N) (see Read ID documentation) I+4 0 = Logical track number for second sector (C) I+5 0 = Logical head number for second sector (H) I+6 1 = Logical record number for second sector (R) I+7 1 = Length of second sector (N) ... + The above parameters will format track 0 of an Acorn DFS disc. A catalogue must then be written to this track, please see chapter 9, Disc formats, and the Write Sector documentation. + EDOS's implementation of this command does not support sector sizes other than 256 bytes. + Gap3 is a sequence of bytes written between sectors. It will need adjusting for different formats. Opus DDOS discs should be formatted with Gap3 = &1B. + If 16 or more sectors are to be written (XY+9 b4 = 1) then EDOS will format the track in double density. Otherwise it will format in single density. Opus DDOS discs have 18 sectors per track. + Gap1 is a sequence of bytes written between the index pulse and the first sector. It will need adjusting for different formats. Opus DDOS discs should be formatted with Gap1 = &24. + When formatting DFS or DDOS discs the logical track number (C) should match the physical track number going from 0 to 39 or 0 to 79. The logical head number (H) should be 0, or 1 if the volume is on the upper surface of the disc. The logical record number (R) should run from 0 to 9 or 0 to 17 within each track. + When formatting in double density, EDOS, for reasons of space-saving, discards the H values in the ID block and writes the C values as both logical track number and logical head number. - The volume size field in each catalogue is 11 bits long (offset &0106 has the form %00bb0nnn.) If and only if the volume is 256 KiB or larger, the length and start address fields of each file take an extra bit (offset &10E+8n will have the form %ellldsss.) - Offset &04 of the disc catalogue contains the actual number of tracks, not the number of tracks - 1. This is confirmed in Opus DDOS 3.45 and Opus EDOS 0.4, which write values &20 and &00 respectively in the version byte, at offset &00 of the disc catalogue. - Eight pages of absolute memory and one page of private memory are claimed, so PAGE=&1700 on booting. - If a sector with a Deleted Data Address Mark is met when reading, this is detected after the fact. The pointer is reduced by 256 bytes (regardless of the sector size) and the read operation is restarted at the next sector to overwrite the deleted data. - The OSWORD &7F implementation is vulnerable to buffer overflow, as the number of bytes transferred is determined by the N values (record lengths) of the sector(s) used, not by the record length given in the OSWORD &7F control block. An attacker may use a disc formatted with larger-than-expected sectors to capture, or overwrite, data beyond the end of the buffer. - All OSFILE transfers are done using whole sectors, and are subject to a further buffer overflow in addition to the one described above. Some information not included in the manual: - *DISC I (capital i) invokes the disc filing system if necessary, and immediately boots from the disc in the current drive. - The *FORMAT command accepts parameters for drive, tracks, density and optional outstep. Outstep (also known as track skew) adjusts where sector 0 of each track is located relative to sector 0 of the previous track, for reduced latency while reading long files. All tracks are written with 1:1 interleave. Syntax: *FORMAT [ O] where = S | D = 40 | 80 | 40-80 = 0..9 (single density) | 0..17 (double density) 40-80 will format a 40 track disc in an 80 track drive. It must not be used with 40 track drives. *OPT 8 will need to be set correctly to verify the newly formatted disc. - *OPT 1 enables monitoring of system calls as well as files. Usage: *OPT 1 , where is the sum of the desired values: 1 Display *INFO of files being accessed by SAVE, *SAVE, OPENIN, OPENOUT or OPENUP (or the equivalent calls to OSFILE and OSFIND.) 2 Monitor paged ROM calls. 4 Monitor internal OSFSC calls and calls to OSARGS, OSBGET, OSBPUT, OSFILE, OSFIND and OSGBPB. 8 Monitor OSWORD &7F calls. 128 Pause for 1.3 seconds after each monitoring message. - *OPT 5 displays the current *OPT settings plus a summary of their meanings. - *OPT 7 sets the number of volumes in the catalogue track of a multi-volume disc. Single density Double density 0 Selects Acorn DFS format. Selects DDOS format (DD-8). 1 Reads and writes SD-1. Reads and writes DD-1. *FORMAT fails with "Volume .. unavailable". *CATGEN with any argument forces the single volume to occupy the whole disc. 2 to 4 Selects SD-2 to SD-4. Selects DD-2 to DD-4. 5 to 8 Fails with "Seek error". Selects DD-5 to DD-8. 9 to 127 Fails with "Seek error". Fails with "Seek error". 128 to 255 Selects Acorn DFS format. Selects DD-0. + If equals 2, 3 or 4, then EDOS will cease to recognise Acorn DFS discs. Instead, single density discs will be accessed and formatted in multiple volumes. These are the 'EDOS single density formats' (SD-2, SD-3 and SD-4), which are incompatible with other filing systems. Of these three, =4 results in the recommended format. To read these discs, the value of must be the same as when the disc was formatted. + Values of between 2 and 7 inclusive, when in double density, each produce an incompatible variant of the DDOS format (DD-2 to DD-7). To read these discs, the value of must be the same as when the disc was formatted. + If is 128 or greater, then double density discs will be accessed and formatted in a single volume, in the style of Acorn DFS. There will be no catalogue track. This is the 'EDOS double density format' (DD-0) which is incompatible with other filing systems. NB: DDOS discs will be corrupted with this setting. - On entry to OSGBPB 5..7 (get disc attributes) it is recommended to set XY+5=&00000001, XY+9=&00000000. - Watford DDFS Manual, p.95. - If the address field of an OSWORD &7F command is unused, the recommended default is XY+1=&FFFFFFFF. - The Micro User, February 1986, p.123. - FDC command values should lie in the range &40 to &7F, except &35 Initialise. - Acorn User, July 1986, p.179. - The result byte should be preset to &FF so that unimplemented OSWORD &7F is shown as an error. - EDOS supports a subset of the 8271 command set: &53 Read data &4B Write data &69 Seek &5F Verify data &57 Read data and deleted data &4F Write deleted data &5B Read ID &63 Format track &6C Read drive status &7A Write special registers &7D Read special registers Unlike DDOS, it offers three undocumented pseudo-commands to access the functions of the 1770 chip: &64 Write track (with one parameter: track number) &65 Read track (with one parameter: track number) &36 Force interrupt DDOS supports this 8271 command which EDOS ignores: &35 Initialise - When reading or writing foreign disc formats, EDOS will not automatically detect the density. However, calling *OPT 6 followed by *CAT sets the density flag for the current drive to . While *OPT 6 is set to automatic density selection, the *CAT command will toggle the density flag if no Acorn DFS or DDOS catalogue is found. Remember that there are two density flags per double-sided disc. - Disc tracks start on the outside and work inwards. Side 0 is on the bottom of the floppy disc. - Many of the routines employ an elegant 'microcode' whereby an action byte is shifted right at several decision points, as an encoding of which code segments to execute or skip. - *HELP HELP displays an extra message. (EDOSPAT changes this to *HELP E and displays its version number and the target floppy disc controller. EDOS 1.51 responds to *HELP EDOS with an expanded message including the workspace memory type. *HELP E. matches either of the new keywords.) - Setting PTR# >= EXT# does not extend the file until the next BPUT# or PRINT#. - When a sequential file is extended, only the sector containing the PTR# is initialised to zero. Example output >*HELP OPUS EDOS 0.4 DFS UTILS OS 1.20 >*HELP DFS OPUS EDOS 0.4 ACCESS afsp L BACKUP src drv dest drv CATGEN drv vol specs COMPACT vol COPY src vol dest vol afsp DELETE fsp DESTROY afsp DIR dir DRIVE drv ENABLE FCOPY old fsp new entry name FORMAT drv S D 40 80 40-80 Oo INFO afsp LIB dir LOCK afsp RENAME old fsp new entry name SCOPY src vol dest vol afsp TITLE title UNLOCK afsp VERIFY drv VOL vol WIPE afsp OS 1.20 >*HELP UTILS OPUS EDOS 0.4 BUILD fsp DISC I DISK I DUMP fsp LIST fsp TYPE fsp OS 1.20 >*OPT 5 *opt 1 monitor = 0 *opt 6 density = 0 *opt 7 volumes = 0 *opt 8 tracks = 0 *opt 9 saverom = 0 >*CAT Seek error on drive 0.0.16 >*CAT Seek error on drive 0.0.0 >*CAT 2 Defs :0A.$.!boot Lib :0A.$ Drive 2 80 tracks Density 1 Not DT 2.24R (29) 770free/800 EXEC !BOOT 423TEST AUTODSK L A.DTXASM L >*INFO :2.*.* $.!BOOT 0000 0000 0037 02 $.AUTODSK L 31900 38023 02CC 04 A.DTXASM L 31B00 38023 14B0 15 $.423TEST 31700 38023 028B 97 >REM Inserted a DDOS formatted disc >*CATGEN Drive 0 Volume Tracks Sectors K bytes Cat 1 18 4.5 A 46 828 207 B 33 594 148.5 > Checksums of the EDOS 0.4 ROM 1245836096 16384 edos04 2ac7dbe50d87301c7ce79e7630cf6202 *edos04 $.EDOS04 FFFF8000 FFFF8000 4000 CRC=5523 EDOS 1.51 A reassembly of EDOS is available, incorporating updates made by the long-running EDOSPAT patch programme. EDOS 1.51 offers the following bug fixes and improvements: - Provides apparent compatibility with Xfer 5.3, ADE plus 1.0d and HADFS 6.10 (when keyboard link 1 is made). - Passes Tom Seddon's filing system tests. - EDOS can be reassembled to run on many WD1770 or WD279x based floppy disc controllers (Acorn, Opus, Watford) and the Opus Challenger 3-in-1 plug-in unit. - A version for the BBC Master controller is available, and EDOS 1.51 can be assembled to use the Master's HAZEL extended memory. A BooBip.com OS RAM module may be present on the Model A or B, and the workspace may be placed there. On all BBC models EDOS workspace can reside in sideways RAM, where fitted, or main memory. Use of Challenger extended memory for workspace or RAM discs is not implemented. - *DRIVE accepts volume letters, for compatibility with DDOS applications. - *FORMAT can now produce the SD-1 and DD-1 formats when *OPT 7 1 is set. - *EX is implemented, and Master computers can call *INFO. - A new *ADDRESS command sets the load and execution addresses of files. - Handling of double-quoted command parameters matches DFS, MOS built-ins. - Commands that produce tabulated output (such as *CAT) work reliably when the output is not displayed on the screen. Line breaks make the output compatible with Xfer. - EDOS vacates the shared workspace when claimed by flushing the sector buffers as well as copying its workspace to its private page. - Wherever possible OSGBPB will carry out reads and writes direct to/from memory rather than via the file buffer, giving much faster access times. Where a write operation is interrupted to extend the file's allocation on disc, one of the sectors is written from the file buffer and the operation takes approximately 2 seconds longer than a continuous write operation. - On attempting to read past end-of-file, OSGBPB will return with C=1 and the number of bytes still to be read, in XY+5..8. C will be cleared otherwise. - OSFILE transfers only the bytes in the file to or from user memory. - OSFILE can unlock locked files and change their catalogue information. - OSFILE calls up to A=24 have been implemented, or aliased to one of the existing calls. When deleting a file or reading its catalogue infor- mation, OSFILE returns A=0 if the file is not found. - OSARGS calls A=4..5, Y=0 (read volume used space, read volume free space), and A=3..6, Y>0 (set extent, read allocated length, read EOF state, ensure allocated length) have been implemented. - The pointer is constrained to be less than or equal to the extent at all times. All appended bytes of a random access file not otherwise defined are set to zero. - OSGBPB returns A=0 if it recognises the command. Similarly OSARGS changes A, returning for the most part the same values as Acorn DFS. - OSWORD calls &71 (get free space on current volume), &7D (get catalogue version number of current volume) and &7E (get size of current volume) have been implemented. These end the ROM service call, if EDOS owns the shared workspace; otherwise like OSWORD calls >=&80, they are passed to lower priority ROMs. - OSWORD &7F uses only the memory areas EDOS currently owns. The user may make keyboard link 1 to override shared workspace protection so that HADFS can call EDOS for disc access. - The floppy drive controller's sector register is available as special register &06. - The NMI service routines have been reassembled to ignore INTRQ requests. - EDOS waits for the non-accepting state { NotReady } to clear before issuing a non-Type I command to the floppy disc controller. - The extended EDOS commands in OSWORD &7F are renumbered to fit the paradigm of other Intel 8271 commands: force interrupt is now command &30, write track is &65, and read track is &71. - System call monitors take less CPU time when inactive. - Internal register-saving and memory copy routines are faster and more stack-efficient. Acknowledgements Sincere thanks to J.G.Harston for compiling extensive documentation on OSARGS and OSGBPB, for helping improve compatibility with HADFS and for his correspondence tabulating the return values of OSARGS which provided inspiration. Thanks to Steve Bass for his investigation and sample code for the Master controller and a fix for the Acorn 1770 target. References Opus Challenger Manual http://archive.retro-kit.co.uk/bbc.nvg.org/doc/OpusDDOS.zip WE DFS Manual http://archive.retro-kit.co.uk/bbc.nvg.org/doc/WatfordDFS-Manual.zip OSARGS and OSGBPB from BeebWiki http://beebwiki.mdfs.net/OSARGS http://beebwiki.mdfs.net/OSGBPB Filing system tests by Tom Seddon https://github.com/tom-seddon/beeb-fstest Author Greg Cook debounce@yahoo.co.uk http://regregex.bbcmicro.net/ -END-