PicoDOS Release & Revision Notes


Monday, August 23, 1999

Revision History

The printed version of this document that ships with Persistors truncates the release history at the end of the eighth page. If you're interested in the complete change history, the version on diskette and the web completes the story. Note that diskettes and release notes shipped with Persistor orders may not contain the most recent versions - keep an eye on our web page for the latest developments.

Most of these revisions are the direct result of a customer telling us what we did wrong, or what we could do better. We are very grateful to these folks and encourage all PicoDOS users to let us know what you need. Odds are, other users need the same things.

After 1.41

CFExec Interactions with buffered serial I/O (XS, XR, YS, YR, DATE, TIME, CAPTURE, CCC)
This should be fixed once and for all. You no longer need to perform any explicit setup or cleanup between calls to execstr or CFExec.

fopen() update mode problem fixed
Our apologies to Aztec for pushing the blame for this one on them. It actually was a PicoDOS bug that was masked by CodeWarriors larger standard I/O buffer sizes. Ed Boss from Sigma Solutions created an example program that let us isolate and fix this long standing problem that only affected update mode ("r+", "w+", "a+") and we've now fixed it. 

Sub-optimum Optimizations
Archie T. Morrison III from McLane Research passed along two problems with optimized Aztec code that may benefit other developers. First, specify the -sa option (two pass assembly) if you use the -mc and -md memory models (standard for TT8) or you may get "jsr greater than 32K" errors. Note that -so (all optimizations on -- TT8 default) enables -sa. Second, the -sr (automatic weighted register usage) appears to sometimes corrupt variables after subroutine calls. Since this is included in the -so (all optimizations on -- the TT8 default), he has taken to explicitly selecting individual optimization options in his makefiles.

After 1.40

Y2K ok
The DATE and TIME commands in PicoDOS ignored all but the last two digits of the entered year and always assumed 1900 as the base date. The DATE and TIME commands in PicoDOS 1.41 now work correctly for two digit and four digit entries, such that "00" to "69" evaluates to 2000 to 2070, "70" to "99" evaluates to 1970 to 1999, and four digit entries that parse to a number greater than 99 are accepted literally. Thanks for the nudge Jeff.

fopen() update mode with Aztec, not so ok
We were recently shown that opening a file in update mode "a+" or "ab+" using any version of the Aztec C compiler would fail on reads after writing and rewinding the file. These same operations work properly with the Metrowerks CodeWarrior compiler and both depend on the same low-level seek operations in PicoDOS. This problem appears to be buried deep in the Aztec's buffered I/O library, and while we do not have a fix, a viable workaround is to close and reopen the file in order to reposition and read.

Bigger Cards, More Files
Until this release, PicoDOS limited you to a maximum of 512 files. With 1.41, the size of the root directory increases with the capacity of the card in the following fashion:

Size:      Files:    Dir Size:
to 32MB      512        16KB
>= 32MB     1024        32KB
>= 64MB     2048        64KB
>= 128MB    4096       128KB

Dungeon Example in Aztec C
We mentioned in the "After 1.30" notes that this works fine when compiled and run from the Metrowerks system, but crashes with an illegal instruction error after running for a while, or if you ask for help or info. We never did find it, but John Bartholomew from Sandia National Labs was less willing to let it drop and spent a fair bit of time working through the problem. He traced it down to declarations of "const static" variables which either do not get properly stored, or do not get properly referenced at runtime with Aztec. We don't have a fix, but be warned that const static variables may give you similar problems.

DIR to Memory
The After 1.34 had errant example code so we're reprinting it here with the repaired code suggested by Cleo Zani. We also a problem where using the DIR to memory option with an odd value for the maximum number of bytes would cause an exception.

Added an optional /M flag to the DIR command to vector the output to memory for use from within your running programs with the execstr() function. To use this, you must provide a pointer to your own local storage area (malloc or static array) and optionally a maximum length parameter. Both of the parameters follow the file specifier mask and the /M switch in the form of hexadecimal strings as shown below:

dir *.* \m 2c0000 40

After which, the image left in memory has the following format:

AUTOEXEC.BAT       623\0
PD8R132.HEX     292736\0

The file name is left justified in a 12 character field, and the file length is right justified in the next 11 characters, then terminated with a zero. There are no embedded linefeeds. The final entry begins with a zero. You can parse the information by stepping through in increments of 24 bytes, or with a structure approach as shown ahead. The above command string demonstrates the syntax, but is not how you would normally use this. In your program, you might have something like the following:

typedef struct
	char name[12];
	char lenstr[11];
	char zterm;
	} DirStrEntry;
DirStrEntry	*dirlist;
char dircmd[40];
long maxlen = 400;
	dirlist = malloc(maxlen);
	sprintf(dircmd, "dir *.* /m %lX %lX", dirlist, maxlen);
	while (dirlist->name[0])
		puts((char *) (dirlist++));

PicoDOS extensions now built into TxBASIC
Onset has incorporated the TxBASIC extensions described in the PicoDOS software manual into their 4.10 distribution of TxBASIC as a convenience to their customers. You no longer need to load a special version of TxBASIC to take advantage of the CF8 or AT8 functionality in your BASIC programs.

CFExec Interactions with buffered serial I/O (XS, XR, YS, YR, DATE, TIME, CAPTURE, CCC)
Previous PicoDOS releases have alluded to fixing buffered serial I/O problems when using C's execstr or TxBASIC's CFExec extension, but they keep coming back. If you use buffered (interrupt driven) serial I/O, you'll need to make the following accommodations to call these PicoDOS functions from within your programs.

From TxBASIC use something like the following:

        extension SerBuffered
        SerBuffered(0)  // turn off buffered serial (PicoDOS installs its own)
        CFExec("XS test.tst")
        SerBuffered(1)  // turn buffered serial back on

From C, enable buffered serial the same way you normally do, but turn it off temporarily with:

        SerSetInBuf(0, 0);  // turn off buffered serial (PicoDOS installs its own)
        execstr("XS test.tst");
        SerSetInBuf( ... // whatever is appropriate

After 1.39

PicoLog Example
Lots of customers have requested an example program that demonstrates how to perform continuous high speed sampling while streaming the data on to the card. Now there's PicoLog. Check out the HTML description in the examples folder or up on the periph.com web site.

Atmel Flash Loads from PicoDOS
Fixed a bug in PicoDOS that slipped in with version 1.37 and caused .AHX loads to the Atmel flash to quietly fail, and then crash when the application would next run from a reset. We also took this opportunity to add a second phase of verification to the burn to prevent any future occurrence.

Sixteen Command Line Arguments
We needed more than the previous limit of ten command line arguments to make the new PicoLog example work.

Ten Open Files
We've always said you could have ten open files, but PicoDOS was actually refusing to open more than seven. We also found this out while creating PicoLog.

After 1.37

Updated Onset Libraries
Onset has released updated versions of the Model 8 libraries which are compatible with the Persistors, and these, along with updated header files are included on the PicoDOS diskette. Contact Onset if you want a complete update package.

Fixed BOOT Command Bug
Code changes in 1.36 exposed a long standing but dormant bug that could cause the BOOT command to reset to the TOM8 monitor on completion.

After 1.36

Faster File System Operations
The standard C file system and DOS file system compatibility add a great deal of overhead to flash card operations, and for writing, the overhead increased as the card filled up. This was almost unnoticeable for 2MB cards, a little annoying with 15MB cards, but downright intolerable with new and bigger PCMCIA cards that work with the Persistor AT8. PicoDOS 1.37 uses some new algorithms that level the write speeds such that writing to a near full card operates as fast as to an empty card.

512 Files Maximum
This has always been the maximum number of files supported by PicoDOS, but it was not declared in the software manual or earlier release notes. Now that we can have cards with up to 300MB capacity, this limitation has more impact on the design of your logger experiment. If you need to write huge numbers of small files, consider writing to a single file using append mode and inserting identifiable delimiters, or write a second log file containing offsets to the start of each small data segment.

Format from PicoDOS
Format your cards from PicoDOS, and not from Windows. When you buy flash cards from Peripheral Issues, they come preformatted in the manner preferred by PicoDOS. If you buy cards from other vendors, make sure to format them at least once from PicoDOS before using them with your Persistor. If you have not been doing this, don't worry as PicoDOS can deal with just about any DOS compatible format, but future versions of PicoDOS will likely include optimizations that rely on PicoDOS formatting, and though they will still work with non-PicoDOS formats, there will not be able to take advantage of these enhancements.

ERASE *.* (or DEL *.*)
PicoDOS still does not support wildcards for the erase operation, but it will accept "*.*" to perform a clean wipe of the card. This is the preferred way to prepare and clean a card for a new experiment.

After 1.35

Persistor AT8 PCMCIA Compatibility
PicoDOS 1.36 has been tested for operation with both the Persistor CF8 for CompactFlash cards and Persistor AT8 for Type I/II/III PCMCIA ATA flash cards from Peripheral Issues (or SanDisk SDP3B).

No Media Startup
Changed the initialization search criteria such that the first Persistor found in the search order CS2, CS1, CS10 is the default card whether or not a flash card is installed. This fixed a problem with the last 1.35 initialization code that failed the search when it didn't find a populated card. PicoDOS would report a very confusing "No Persistor hardware found" instead of "No media detected", because that was what it found at CS10.

After 1.34

20MB and 24MB Cards
We finally got our hands on some of these new high capacity cards, and as expected, they work just fine with PicoDOS.

CCC Command Extended
The CCC (Cooperative Card Change) command now accepts an optional chip select values of 1, 2, or 10 corresponding to the jumper selection on the Persistor, and like the Persistor, it defaults to CS2. If you have multiple stacked Persistors, you can use this command to select the active card. This is also available from within your programs using the execstr() function, and you can use the optional /Q (quiet) flag to skip the prompts and messages. We still don't have documentation on the mechanics of stacking Persistors, so contact us before attempting this on your own.

DIR to Memory
(See After 1.40 for a corrected description and example)

Fixed a bug where the YMODEM send function (YS) was truncating files larger than 65536 to length modulo 65536.

XMODEM execstr() Return Code
These were added with 1.33, but until now, returned incorrect values.

pdcfinfo() - Important Notes
There's been some confusion on how to use the pointer arguments with this function, and also some surprise that the call can take several hundred milliseconds to complete (it has to scan the directory). The example below demonstrates its use:

long    cfsize, cffree;
pdcfinfo("A:", &cfsize, &cffree);

After 1.33

Really changed the name of the installer program from PD8Rnnnr.HEX to PD8Rnnnr.RHX (alleged to have done that in 1.30), and fixed all pertinent references of .HEX to .RHX in the software manual and release notes.

Batch files
1. Fixed a bug where batch files which invoked .RUN files were no passing their parameters to the .RUN files properly.

2. Setting the baud rate inside AUTOEXEC.BAT with a BAUD /Q XXXXX now leaves the selected baud in effect even after entering the PicoDOS command shell.

Buffered Serial/PicoDOS Interactions
(See the updated information in After 1.40) Model 8 programs that explicitly enabled buffered (interrupt driven) serial input used to fail in execstr() calls to PicoDOS functions that performed serial I/O. The old workaround was to turn buffered input off (SerSetInBuf(0,0)) before calling execstr() for the and of the XMODEM functions, as well as Format, Capture, and Baud. This is now handled transparently inside PicoDOS.

RUN Command with Arguments
This is the same as the GO command, but accepts a command line to pass to the running program which must still call initargs(). This is a great way to test command line arguments from RAM based programs before committing to a flash burn, and only made it into PicoDOS because one of my customers was smart enough to think of it and make the request. Thanks Jeff.

XMODEM execstr() Return Code
The XMODEM commands now return an error flag to indicate success (zero) or failure (non-zero) when called from the execstr() function. These are currently the only command that may return non-zero failure codes.

Date and Time
1. Added recognition of command line arguments for DATE and TIME (mostly for execstr()). Typing DATE or TIME with no arguments prompts for a date/time string just like before, but if a date/time string is passed as an argument, the prompt is suppressed.

2. Fixed a cosmetic problem with the DATE and TIME commands which were not returning the PicoDOS prompt to beginning of next line.

1MB Model 8s
Modified the .RUN launcher and the CAPTURE command to work correctly with both 256KB and 1MB flash TT8s by calling library function GetRamInfo for the load address.

TYPE Command
Added optional /N /N flag to the TYPE command to force linefeeds after carriage returns.

One customer requested the ability to use the auxiliary TPU UART with the built-in XMODEM functions. I had to bail out when it turned out to be much more difficult than first appeared. Now I'm soliciting input from other customers on how useful this capability would be, and what memory/complexity compromises would be acceptable.

After 1.32

Installation from diskette
Yet another change attempting to unify installation, whether from disk or ftp (soon). All PC files are now shipped as self extracting ZIP archives and a batch installer (INSTALL.BAT) puts all of the files in the proper place.

Software Manual - Revision 7
The software manual has been updated to contain all of the pertinent information from the release notes. If you are a new user, you can safely ignore the remainder of this document.

TxBASIC Support
PicoDOS now supports TxBASIC with extensions to read and write datafiles to CompactFlash, and to access the built-in commands using the CFExec extension See the updated software manual for details.

No more PDOS!
We tripped over another company selling a product called PDOS on the web, and since this was just an abbreviation for us, we decided to proactively eliminate any future tradename collisions. We've renamed one header file and a few function calls, but we've kept placeholders files and macros with the old names to allow earlier code to compile and run. You should use the new names in new projects, and gradually migrate older code to the new names.

-- 0ld --    -- New --
   <pDOS8.h>      <PicoDCF8.h>
ResetToPDOS8   ResetToPicoDOS
pdosver        picodosver
pdospro        pdcfpro

pdcfinfo() - Return card size and current capacity
We've had a lot of requests for a function to tell a running program the size of the CompactFlash card, and the amount of free space remaining. The prototype for the new function is shown below. It returns zero if the operation was successful, or a non-zero error code. Pass the string "A:" for the drive parameter, and pointers to longs to hold the size (max) of the card and the free space.

short pdcfinfo(char *drive, long *size, long *free);

Fixed a problem with batch files refusing to execute file level commands. Try them again.

PicoDOS programs on no PicoDOS TT8's
The call to InitCF8() now correctly handles the error condition where no PicoDOS image exists in high flash. You still need to check the global errno variable for non-zero and take the appropriate action to prevent a future crash from calling nonexistent software.

BAUD Command has optional /Q switch
Adding -Q or /Q to the BAUD command now inhibits the message and query to allow better automated use, especially with batch files.

XMODEM et al
See After 1.40 notes. No longer installs its own serial interrupt handlers if the UART is already running from interrupts.

BOOT "P..." or "T..."
The boot command now only looks at the first character of the first argument. P followed by anything boots PicoDOS, and T followed by anything boots the TOM8 monitor.

Changed picodosver() function
This call now returns a string defining the PicoDOS target, serial number, and version number in the form "TTT#SSSS-V.RR", where TTT is the Persistor type (CF8), SSSS is the serial number, V is the PicoDOS version, and RR is the current release. Note that beta releases of PicoDOS may have a single character appended to the release number. This current version of PicoDOS for Persistor CF8 serial number 124 would be: "CF8#0124-1.33".

After 1.31

Pre 5.2C Aztec fixes
Earlier versions of Aztec C didn't like the // comments we had in PICODCF8.H and the updated version of TT8LIB.H. We changed all of these to /* ... */ pairs. There may be other problems with older versions, and you should update to the most recent as we only test our software releases with the most current versions of the Aztec software (5.2C).

Fixed time stamps for CF8 files
Programs compiled with Aztec C were not showing the correct times in directory listings due to a base time_t difference between the Aztec and Metrowerks (which builds PicoDOS) compilers. The latest version conforms to the Aztec 1/1/1970 as do the new libraries for the MotoCross/Metrowerks release 11. Aztec users need do nothing, and MotoCross users need be concerned only if they do non-standard operations on time_t types.

Fixed execstr() not executing intrinsic PicoDOS commands
Somewhere along the way (probably 1.30), PicoDOS lost the ability to execute intrinsic commands like "DIR" and "ERA" from the execstr() function. They're back to working now.

New picodosver() function
This new call returns a string defining the PicoDOS target and version number in the form "TTT-V.RR". This current version of PicoDOS for the Persistor CF8 is "CF8-1.32".

DUMP command now accepts offset range parameters
This little known dump command now lets you specify a starting offset (hexadecimal) into the file and an optional end offset (,end) or range (:range), and the filename specification.

PicoDOS Pro support
PicoDOS now has hooks to allow support of an optional future PicoDOS Pro library that will expand card access capabilities to include much faster read/write speeds through the use of cache buffers, power tailoring, and sequential only file access, as well as convenience features like direct access to xmodem transfers, formatting, directory information, and low level sector operations. Contact us if you're interested in beta testing.

After 1.30

We changed the filenames and directory structure to simplify installation both from diskette and the online ZIP files. A complete PicoDOS installation from diskette to a standard C:\TT8 and C:\Aztec hard disk installation can now be performed with a single XCOPY command and the various update files end up in the proper directories.The PicoDOS kernel installer, which was called PD8Rnnnr.HEX now has the extension .RHX for consistency with other Model 8 RAM applications and the Tattletale documentation.

COM Files
There were several problems getting .RUN files loaded from the PC to run under PicoDOS and a number of users questioned the wisdom of providing what appear to DOS and Windows as executables, but are in fact 68000 programs. For that reason, PicoDOS no longer recognizes .COM for executables, and instead expects the extension .RUN, which is what we get from the standard TT8 make utilities. Users with earlier versions of PicoDOS will need to rename their .COM files to .RUN.

We fixed the problem with XMODEM loaded.RUN files not running and also made it easier to get .RUN executables onto the CF card. From the PicoDOS prompt, use CrossCut's Load S Records command just as you would to run a RAM application. Instead on typing "G" on completion, type "SAVE FILENAME.RUN" (FILENAME being whatever is appropriate) and PicoDOS takes care of moving the image from RAM to card. FILENAME is now ready to run any time you type FILENAME at the PicoDOS prompt.

Dungeon Example in Aztec C
(See the updated information in the After 1.40 section) Works fine when compiled and run from the Metrowerks system, but crashes with an illegal instruction error after running for a while, or if you ask for help or info. It is repeatable, so we'll find it and post an update, but it is fairly low on the priority list.

Low Power Idle
The PicoDOS monitor drops into a power saving mode while waiting for commands. Though it can't get to the lowest power since it can't make any assumptions about floating TPU and port lines, it should be about one tenth the normal power drain.

After 1.29

There's a new 3.1 release that corrects several problems, see <tt8lib.h> for details.

Lets you continue to operate with reduced functionality even without a CF8 installed.

Was not allowing repeat commands with just return.

Is a little more intelligent in dealing with card changes.

After 1.26

Fixed a bug in all the send routines that prepended a 512 byte block to the beginning of the file.

fopen("name", "r+")
Fixed a bug that wasn't allowing read access to files opened with this mode.

After 1.25

The XMODEM functions are working properly and now support options to change the default protocol and offer quiet mode for calls from within programs. XS and XR default to XMODEM 1k, but can be forced to first try original XMODEM with the -X or /X option, or XMODEM 128CRC with the -C or /C option. YS and YR default to normal YMODEM batch, but can be forced to YMODEMG (no error checking/recovery) with the -G or /G option. -Q inhibits the routines from emitting messages.

XS [-Q] [-X] [-C] filename.ext
XS [-Q] [-X] [-C] [filename.ext]
YS [-Q] [-G] filename.ext [,filename.ext...]
YR [-Q] [-G]

There's a new ResetToPDOS() inline function defined in pDOS8.h that allows a running program to exit directly to pDOS.

This now supports calls into pDOS intrinsic commands such as XS, XR, DIR, REN. There are probably many bugs in this arrangement so please report any problems or anomalies.

Now accepts PDOS as well as the longer PDOS8.