Update README.md

demos/sdcard/README.md

@@ -1,29 +1,105 @@
-# SD CARD COMMANDS
+# SD CARD
 
-## I/O
-READ,WRITE for pure binaries,
-LOAD,BSAVE,RUN for basic/prodos format and .PRG
-TYPE
-DUMP
+- all numbers must be provided in hexadecimal format unless specified
+- arguments in `[]` brackets means they are optional
+- nested paths are allowed with the `/` character, e.g. `/`, `/foder1/foo`
+- no path given implies current working directory
 
-## FILE
-DEL
-REN
-COPY
+## TAGGED FILE NAMES
 
-## DIR
-DIR
-LS
-CD
-MKDIR
-RMDIR
+File names containing a tag `#` character have a special meaning: the part after the `#` 
+indicates the file type (two characters) and the hex loading address (4 characters).
 
-## MISC
-HELP
-JMP
-BAS
-STAT
-MOUNT
-TIME
-EXIT
+`#06` for plain binary files
+`#F1` for BASIC programs
+
+E.g.:
+`BASIC#06E000` is binary file named `BASIC` that loads at address `$E000`.
+`STARTREK#F10300` is a BASIC program named `STARTREK` that loads at address `$0300`.
+
+Tagged file names are used by the `LOAD`, `RUN`, `SAVE` and `DIR` commands to simplify working with files. For example to execute the above files, it's enough to type:
+
+```
+LOAD BASIC
+RUN STARTREK
+```
+
+## COMMANDS
+
+`READ filename startaddress`
+
+   Reads a binary file from the SD card and loads it in memory at the specified address. 
+
+`WRITE filename startaddress endaddress`
+
+   Writes the memory range from `startaddress` to `endaddress` (inclusive) in a file on the SD card.
+
+`TYPE filename`
+
+   Reads the specified ASCII file from the SD card and prints it on the screen. Press any key to stop the printing and return to the command prompt.
+
+`DUMP filename [start] [end]`
+
+   Reads the specified binary file from the SD card and prints it on the screen in hexadecimal format. `start` and `end` are optional and are used to print a smaller portion of the file. Press any key to stop the printing and return to the command prompt.
+
+`LOAD filename`
+
+   Loads a file from the SD card. `filename` refers to a "tagged file name" described above. For convenience, `filename` can be partially given, the first matching file will be loaded.
+   
+`SAVE filename start end`
+
+   Saves a file to the SD card. If `start` and `end` are specified, a binary file with tag `#06` will be created with the memory content from the address range `start`-`end` (included).
+   If `start` and `end` are not specified, the BASIC program currently loaded in memory will be created with the corresponding `#F1` tag.
+
+`RUN filename`
+
+   Same as `LOAD` but runs the file after loading it. Binary files are exectuted at the starting address specified in the file name tag; BASIC files are `RUN` from the BASIC interpreter.
+
+`DEL filename`
+`RM filename`
+
+   Deletes a file from the SD card.
+
+`DIR [path]`
+`LS [path]`
+
+   Lists the files from the specified directory, or from the current directory if no path is given. `LS` has a shorter but quicker output format. Press any key to stop the file listing and return to the command prompt.
+
+`CD path`
+
+   Changes the current working directory to the specified path. The current directory is also shown in the command prompt.
+
+`MD path`
+`MKDIR path`
+
+   Creates the specified directory.
+
+`RD path`
+`RMDIR path`
+
+   Removes the specified directory. The directory to remove must be empty (no files or directories within).
+
+`PWD`
+
+   Prints on the screen the current working directory.
+
+`BAS`
+
+   Prints `LOMEM` and `HIMEM` pointers from the BASIC program currently loaded in memory.
+
+`JMP address`
+
+   Makes the CPU jump at the specified address.
+
+`TIME value`
+
+   Set the internal timeout value used in the I/O operations with the SD cards.
+
+`TEST`
+
+   Internal test.
+
+`EXIT`
+
+   Exits to the WOZ monitor