The Unicard repository MZFREPO is a programming interface (API) for communication between a program running on the Sharp MZ with the Unicard and its functions. For this it uses ports 0x50 (CMDPORT) and 0x51 (DATAPORT). Reserved, but not yet used are ports 0x52 and 0x53.
|Sending a byte on the CMDPORT inputs a command||Sending a byte(s) on the DATAPORT inputs the command data|
|Reading from the CMDPORT (4x) reads the status||Reading byte(s) from the DATAPORT gives the command data|
I recommend for study the file emu_MZFREPO.c from the source codes, it is well commented on. Here is the list of comments and definitions – a description of the Unicard repository MZFREPO from the file emu_MZFREPO.c.
/* * * Commands received through the CMD port * ============================= * * The commands are being sent on the CMD port. They all have one byte and if they do not require a parameter, they are executed instantly. * * If at any point a command is entered. it will automatically cancel the processing of the previously input command * (for example, if it is waiting for parameter input, * or waiting for removal of output data). * * When entering the command STSR, it will only reset the status indicator (see below) and * the previous command or the contents of the status will not be affected at all. * * * Input: * * If a command requires additional parameters, they are expected to be in a set order on the DATA port * and the command will be executed instantly * after all the parameters are input. * * If the input parameter is a string, then any character with * a value less than 0x20 will be considered as its end. * * If the input parameters are two chains, then any character with * a value less than 0x20 will be considered as its separator. * * If the input parameter is a chain, then this input runs through * the Unicard's I/O translator ASCII. * * If the parameter is a file or folder (string), it is possible to set * an absolute path, which starts from the root "/", or a relative path, which starts from CWD. * THe use of a relative path is not ideal for the command MOUNT, because it will be saved in this form * into the configuration. When starting the Unicard, CWD=/ will be set and the relative path may not * be valid. * * * Output: * * If any data is expected to be the outup of the command, * it will be available on the data port. * * If the output values are chans, they will always be separated and ended with the 0x0d character. * * If the Unicard has no data to send, it will return 0x00 on the data port. * * If the output parameter is a chain, then this output runs through * the Unicard's I/O translator ASCII. * * * If a file is opened through OPEN, then reading and writing of the dataport is considered to be an a * attempt to getc() or putc(). * * If a file is opened through OPEN and we enter a command, that expects parameters * or returns some data, then this command gains priority in accessing the dataport. * This applies until the command is completely finished, or is cancelled using the STORNO command. * * * Number values WORD (2B) and DWORD (4) are relayed from the lowest byte to the highest. * * Structure of FILINFO: * * DWORD - 4B, File size * WORD - 2B, Last modified date * WORD - 2B, Last modified time * BYTE - 1B, Attribute * TCHAR - 13B, Short file name (8.3 format), ended with 0x00 * BYTE - 1B, LFN strlen * TCHAR - 32B, LFN, ended with 0x00 * * * * Status codes: * ============ * * Status of the repository contains 4 bytes and ca be displayed at any time by reading the CMD port. * * By reading one byte of the status the position of the indicator will internally shift to the next byte * and as soon as all four bytes are read, the indicator will stay "parked" and with the next * reading the Unicard will return 0x00 instead of the status. * * After every I/O operation of the DATA port or when writing a command the Unicard will always * update the status, which is relayed by the status and at the same time the status indicator always resets * to the first byte. * * The position of the indicator can always be rest using the STSR command, which is also the only command * that does not in any way affect the contents of the status nor does it interrupt the execution of an already active command. * It is therefore safe to use it at any time. * * * The meaning of each individual byte: * * 1. byte - master status byte: * * 0. bit - BUSY/READY - if the bit is annulled, it means that the * repository is in the READY status. * * - if it is set, it means that the repository * is in a BUSY state - meaning there is currently a command being processed, * which requires parameters * through the DATA port * * - when the last parameter is entered or the input stack is read * this bit is annulled again and the repository * changes to a READY status (if the stack was read, * it will also display an ERROR status.) * * - by inputing a STORNO command the repository will change to the READY status * * * * 1. bit - CMD_OUTPUT - if it is set, it means that there is some data * in the stack, which is the output of the last command * * - by reading the last byte or by entering a STORNO command *this bit will be annulled * * * * 2. bit - READDIR - if it is set it means a folder is opened * by a READDIR or FILELIST command and if there is no data in * the stack to be collected (CMD_OUTPUT), then * at this moment reading from the DATA port gives the appropriate * data from the folder * * - by reading the last byte from the last item of the folder * this status is annulled * * - if a NEXT command is used and there are no more * folder items available, then this bit will be annulled * * * * 3. bit - READ_FILE - if it is set it means a file is opened * for reading and if there is no data in * the stack to be collected (CMD_OUTPUT), * then at this moment reading from the DATA port executes * fget() - reads the last byte of the opened file * * * * 4. bit - WRITE_FILE - if it is set it means a file is opened * for writing and if the repository is READY, * then by writing in the DATA port we execute fput() - write * the byte into the opened file * * * * 5. bit - EOF - if there is a file opened and the position of the indicator * is currently located at its end, then this * bit is set * * * 6. bit - unused * * * 7. bit - ERROR - is set when an error occurred, which can happen when: * * - a command is entered (or by entering its last parameter * which executes the command) * * - the input buffer is read when entering parameters * of the string type * * - writing/reading and opened file * * - by reading the last byte of a folder item (this internally * activates the NEXT command for loading the next item from FAT *to the output buffer) * * - an unexpected I/O operation executes on the DATA port * * * Note: The status bits READDIR and READ_FILE/WRITE_FILE are mutually exclusive at this point. * * * 2. byte - the value of the last active command * * Note: When reading/writing a file through the DATA port, internal commands INTGETC and INTPUTC will show as values here. * * * 3. bajt - when ERROR is set in the first master status bite, a Unicard error code * can be here, for example, when the buffer overflows, when the parameter has a wrong value etc... * (Is not iplemented yet and returns 0x00) * * - when inputting parameters to the (BUSY) command, there is an information here * about the remaining size of memory in the input buffer * * - when reading the output data from the command, there is the remaining number of bytes in the output buffer here * * * - when reading a folder item open through READDIR or FILELIST, * there is the remaining number of bytes of the current item which is saved in the buffer here * * 4. byte - FatFS result * * Here is the return code from the last called FatFS operation. You only have to worry about this * in case ERROR was set in the first master status byte. * see FatFS - http://elm-chan.org/fsw/ff/en/rc.html */ /* * * List of repository commands * */ // Working with the repository: cmdRESET 0x00 // Resets the entire repository. Sets the ASCII. // Syncs and closes open files. // Closes open folders. CWD is set to the root folder. cmdASCII 0x01 // I/O translator is set to ASCII. cmdSHASCII 0x02 // I/O translator is set to SharpASCII. cmdSTSR 0x03 // The status indicator is set to the beginning. // Does not affect the status in any other way. The current command will not be interrupted. cmdSTORNO 0x04 // Instantly ends the currently input or // executed command (a sort of small reset for freeing the data port). cmdREV 0x05 // Displays firmware revision in txt format. // // Output: string cmdREVD 0x06 // Displays firmware version in a binary format. // // Vystup: DWORD cmdBOOT 0x07 // Resets the computer hw. // Configuration and settings of the Unicard: cmdMOUNT 0x10 // Sets the image file for the appropriate drive and saves the configuration. // If there is already a DSK in the drive, it syncs it and disconnects. // // Input: 1B - number of the drive, 0..3 - FDD, 4 - RAMdisc, 5 - QDisc, 6 - EMMdisc // string - DSK image path/filename (if the parameter is empty, the drive unmounts and remains empty) cmdINTCALLER 0x11 // Displays the caller of the interrupt. Codes of the caller peripherals are defined in mzint.h // // Output: 1B - mzintFLAG // Working with file system: cmdGETFREE 0x20 // Displays the total number of sectors and free sectors on the disk. // // Output: DWORD - total number of sectors // DWORD - number of free sectors cmdCHDIR 0x21 // Change of CWD. // // Input: string - path or dirname cmdGETCWD 0x22 // Displays current CWD. // // Output: string, 0x0d // Working with files and folders: cmdSTAT 0x30 // Information about the file or folder. // // Input: string // Output: binary structure FILINFO cmdUNLINK 0x31 // Delete file or folder. // // Input: string cmdCHMOD 0x32 // Change the attribute of file or folder. // // Input: 1B - attributes // 1B - mask // string - filename/dirname // // // 0x01 AM_RDO Read only // 0x02 AM_HID Hidden // 0x04 AM_SYS System // 0x20 AM_ARC Archive // // For example to set AM_RDO and delete AM_ARC (other attributes remain unchanged): // // attr = AM_RDO // mask = AM_RDO | AM_ARC // cmdUTIME 0x33 // Sets the time stamp of the file. // // Input: 6B - D,M,Y-1980,H,M,S // string - filename/dirname cmdRENAME 0x34 // Renaming the file or folder. // // Input: string - oldname // string - newname // Working with the folder: cmdMKDIR 0x40 // Creates a folder. // // Input: string - dirname cmdREADDIR 0x41 // Opens the folder and prepares a binary output for reading on the data port. // If a file was open, sync() is done and then it is closed. // // Input: string - dirname // Output: FILINFO - binary structure of each item in the folder cmdFILELIST 0x42 // Opens the folder and prepares a text output for reading on the data port. // If a file was open, sync() is done and then it is closed. // // Input: string - dirname // Output: string filename[/],0x0d,string size,0x0d cmdNEXT 0x43 // Instantly moves to the next item in the folder // in the currently executed READDIR or FILELIST. // Working with a file: #define cmdOPEN 0x50 // Opens the file in the requested mode. // // Input: 1B - mode, see FatFS // string - filename // // 0x00 FA_OPEN_EXISTING // 0x01 FA_READ // 0x02 FA_WRITE // 0x04 FA_CREATE_NEW // 0x08 FA_CREATE_ALWAYS // 0x10 FA_OPEN_ALWAYS // 0x20 FILE_SHASCII_CNV // #define cmdSEEK 0x51 // Changes the position in the open file. // // Input: 1B - mode // 0x00 - from the beginning // 0x01 - from the end // 0x02 - relatively up // 0x03 - relatively down // DWORD - number of bytes the indicator should move by #define cmdTRUNC 0x52 // Shortens the currently open file to a size corresponding to the current position of the indicator. #define cmdSYNC 0x53 // Executes sync() of the currently open file. #define cmdCLOSE 0x54 // Executes sync() and closes the currently open file. #define cmdTELL 0x55 // Displays the position of the indicator in the currently open file. // // Output: DWORD #define cmdSIZE 0x56 // Dsiplays the size of the currently open file. // // Output: DWORD // Working with RTC: #define cmdRTCSETD 0x60 // Sets the date. // // Input: 3B - D,M,Y-1980 #define cmdRTCSETT 0x61 // Sets the time. // // Input: 3B - H,M,S #define cmdRTCGETD 0x62 // Displays current date. // // Output: 3B - D,M,Y-1980 #define cmdRTCGETT 0x63 // Displays current time. // // Output: 3B - H,M,S // USART: #define cmdUSHELLON 0x70 // Turns on USARTshell, turns off_SIO. #define cmdUSHELLOFF 0x71 // Turns off USARTshell, turns on emu_SIO. #define cmdUSARTBPS 0x72 // Sets the BPS for USART1. // // Input: DWORD - speed