Unicard Repository MZFREPO je programové rozhraní (API) pro komunikaci programu běžícího na Sharp MZ s Unicard a jejími funkcemi. K tomu se používají porty 0x50 (CMDPORT) a 0x51 (DATAPORT). Vyhrazené, avšak zatím bez využití jsou porty 0x52 a 0x53.
| Poslání bytu na CMDPORT se zadává příkaz | Posláním bytu(ů) na DATAPORT se zadávají data příkazu |
| Čtením z CMDPORTu (4x) se čte status | Čtením bytu(ů) z DATAPORTu se získávají data příkazu |
Doporučuji k prostudování soubor emu_MZFREPO.c ze zdrojových kódů, je pěkně komentovaný. Zde je výpis komentářů a definicí – popis Unicard repository MZFREPO ze souboru emu_MZFREPO.c.
/*
*
* Prikazy prijate pres CMD port
* =============================
*
* Prikazy se posilaji na CMD port. Vsechny jsou jednobajtove a pokud
* nevyzaduji dalsi parametr, tak jsou okamzite vykonany.
*
* Pokud je kdykoliv vlozen prikaz, tak se tim automaticky zrusi vykonavani
* predchoziho prikazu (napr. pokud ceka na vstupni parametry,
* nebo na odebrani vystupnich dat).
*
* V pripade vlozeni prikazu STSR se pouze vynuluje ukazatel statusu (viz. nize) a
* nedojde k zadnemu ovlivneni predchoziho prikazu, ani obsahu statusu.
*
*
* Vstup:
*
* Pokud prikaz vyzaduje dalsi parametry, tak jsou ocekavany v
* predem urcenem poradi na DATA portu a prikaz bude vykonan okmzite po
* vlozeni vsech parametru.
*
* Pokud je vstupnim parametrem string, tak za jeho konec je povazovano
* prijeti libovolneho znaku s hodnotou mensi nez 0x20.
*
* Pokud jsou vstupnim parametrem dva retezce, tak za oddelovac je povazovan
* libovolny jeden znak s hodnotou mensi nez 0x20.
*
* Pokud je vstupnim parametrem retezec, tak tento vstup prochazi uvnitr
* unikarty I/O translatorem ASCII.
*
* Pokud je parametrem soubor nebo adresar (string), tak je mozne pouzit
* absolutni cestu, ktera zacina od korene "/". Nebo relativni, ktera zacne od CWD.
* Pouziti relativni cesty neni vhodne u prikazu MOUNT, protoze se pak v teto podobe
* ulozi do konfigurace. Pri startu unikarty se nastavi CWD=/ a relativni cesta k DSK nemusi
* byt platna.
*
*
* Vystup:
*
* Pokud se ocekava, ze vystupem prikazu budou nejake data,
* tak jsou k dispozici na dataportu.
*
* Pokud jsou vystupni hodnotou retezce, tak jsou vzdy oddeleny a ukonceny znakem 0x0d.
*
* Pokud unikarta nema zadne data, ktere by mohla poslat, tak na datovem portu vraci 0x00.
*
* Pokud je vystupnim parametrem retezec, tak tento vystup prochazi uvnitr
* unikarty I/O translatorem ASCII.
*
*
* Pokud je pres OPEN otevren nejaky soubor, tak zapis a cteni dataportu je povazovano
* za pokus o getc() nebo putc().
*
* Pokud je pres OPEN otevren nejaky soubor a vlozime prikaz, ktery ocekava parametry,
* nebo vraci nejaka data, tak tento prikaz ziska prioritu v pristupu na dataport.
* To plati do doby, dokud neni prikaz kompletne vykonan nebo stornovan prikazem STORNO.
*
*
* Ciselne hodnoty WORD (2B) a DWORD (4) jsou predavany od nejnizsiho bajtu k nejvyssimu.
*
* Struktura 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), zakonceno 0x00
* BYTE - 1B, LFN strlen
* TCHAR - 32B, LFN, zakonceno 0x00
*
*
*
* Status kody:
* ============
*
* Status repozitare obsahuje 4 bajty a lze jej kdykoliv ziskat prectenim CMD portu.
*
* Prectenim jednoho bajtu ze statusu se interne zvedne pozice ukazatele na dalsi bajt
* a jakmile jsou precteny vsechny ctyri bajty, tak zustane ukazatel "zaparkovan" a pri dalsim
* cteni vraci unikarta misto statusu 0x00.
*
* Po kazde I/O operaci DATA portu nebo pri zapisu prikazu se vzdy v unikarte aktualizuje
* stav, ktery je sdelovan statusem a zaroven se take vzdy resetuje ukazatel statusu
* na prvni bajt.
*
* Pozici ukazatele lze kdykoliv resetovat prikazem STSR, ktery zaroven jako jediny prikaz
* zadnym zpusobem neovlivnije obsah statusu a ani neprerusi vykonavani jiz aktivniho prikazu.
* Je tedy bezpecne jej kdykoliv pouzit.
*
*
* Vyznam jednotlivych bajtu:
*
* 1. bajt - master status byte:
*
* 0. bit - BUSY/READY - pokud je bit vynulovan, tak to znamena, ze je
* repozitar ve stavu READY
*
* - pokud je nastaven, tak to znamena, ze je repozitar
* ve stavu BUSY - tedy je prave aktivni nejaky prikaz,
* ktery vyzaduje vlozeni dalsich parametru
* pres DATA port
*
* - s vlozenim posledniho parametru nebo pretecenim
* vstupniho zasobniku se tento bit opet vynuluje a repozitar
* prejde do stavu READY (Pokud doslo k preteceni zasobniku,
* tak se zaroven status ERROR.)
*
* - s vlozenim prikazu STORNO prejde repozitar do stavu READY
*
*
*
* 1. bit - CMD_OUTPUT - jestlize je nastaven, tak to znamena, ze mame v zasobniku
* nejaka data, ktera jsou vystupem z posledniho prikazu
*
* - s prectenim posledniho bajtu nebo vlozenim prikazu STORNO
* se tento bit vynuluje
*
*
*
* 2. bit - READDIR - pokud je nastaven, tak to znamena, ze mame otevren
* adresar prikazem READDIR nebo FILELIST a pokud nejsou
* v zasobniku zadna data k vyzvednuti (CMD_OUTPUT), tak
* v tuto chvili ctenim z DATA portu ziskame odpovidajici
* data z otevreneho adresare
*
* - s prectenim posledniho bajtu z posledni polozky adresare
* se tento status bit vynuluje
*
* - pokud je vlozen prikaz NEXT a jiz neni k dispozici
* zadna dalsi polozka adresare, tak se tento bit vynuluje
*
*
*
* 3. bit - READ_FILE - pokud je nastaven, tak to znamena, ze mame otevren
* nejaky soubor pro cteni a pokud nejsou v zasobniku
* zasobniku zadna data k vyzvednuti (CMD_OUTPUT),
* tak v tuto chvili ctenim z DATA portu provedeme
* fget() - precteme bajt z otevreneho souboru
*
*
*
* 4. bit - WRITE_FILE - pokud je nastaven, tak to znamena, ze mame otevren
* nejaky soubor pro zapis a poku je repozitar READY,
* tak zapisem na DATA port provedeme fput() - zapiseme
* bajt do otevreneho souboru
*
*
*
* 5. bit - EOF - pokud mame otevreny nejaky soubor a pozice ukazatele
* se momentalne nachazi na jeho konci, tak se nam nastavi
* tento bit
*
*
* 6. bit - nepouzito
*
*
* 7. bit - ERROR - nastaven, pokud doslo k chybe, coz muze nastat:
*
* - vlozeni prikazu (pripadne vlozenim jeho posledniho
* parametru, cimz je prikaz spusten)
*
* - pretecenim vstupniho bufferu pri vkladani parametru
* typu string
*
* - zapisem/ctenim otevreneho souboru
*
* - prectenim posledniho bajty polozky adresare (to interne
* aktivuje prikaz NEXT pro nacteni dalsi polozky z FAT
* do vystupniho bufferu)
*
* - pri neocekavane I/O operaci na DATA portu
*
*
* Pozn.: Status bity READDIR a READ_FILE/WRITE_FILE se v tuto chvili navzajem vylucuji.
*
*
* 2. bajt - hodnota posledniho aktivniho prikazu
*
* Pozn.: V pripade cteni/zapisu do souboru pres DATA port se zde jako hodnota projevi
* interni prikazy INTGETC a INTPUTC.
*
*
* 3. bajt - v pripade, ze je v prvnim master status bajtu nastaven ERROR, tak zde muze
* byt error kod z unikarty, napr. pri preteceni bufferu, spatne hodnote parametru, atd...
* (v tuto chvili jeste neni implementovano a vraci 0x00)
*
* - v pripade, ze vkladame parametry k prikazu (BUSY) je zde informace o zbyvajici
* velikosti volne pameti ve vstupnim bufferu
*
* - v pripade, ze cteme vystupni data z prikazu, tak je zde zbyvajici pocet
* bajtu ve vystupnim bufferu
*
* - v pripade, ze cteme polozku adresare otevreneho pres READDIR nebo FILELIST,
* tak je zde zbyvajici pocet bajtu aktualni polozky, ktera je ulozena v bufferu
*
* 4. bajt - FatFS result
*
* Zde je ulozen navratovy kod z posledni zavolane FatFS operace. Ma smysl se
* o nej zajimat jen v pripade, ze byl v prvnim master status bajtu nastaven ERROR.
* viz. FatFS - http://elm-chan.org/fsw/ff/en/rc.html
*/
/*
*
* Seznam prikazu repozitare
*
*/
// Prace s repozitarem:
cmdRESET 0x00 // Reset celeho repozitare. Nastaveni ASCII.
// Sync a uzavreni otevrenych souboru.
// Uzavreni otevrenych adresaru. CWD se nastavi na korenovy adresar.
cmdASCII 0x01 // I/O translator nastavime na ASCII.
cmdSHASCII 0x02 // I/O translator nastavime na SharpASCII.
cmdSTSR 0x03 // Ukazatel statusu se nastavi na zacatek.
// Jinym zpusobem se na statusu neprojevi. Aktualni prikaz nebude prerusen.
cmdSTORNO 0x04 // Okamzite ukonceni prave vkladaneho,
// nebo vykonavaneho prikazu (takovy maly reset pro uvolneni data portu).
cmdREV 0x05 // Sdeli revizi firmware v txt tvaru.
//
// Vystup: string
cmdREVD 0x06 // Sdeli revizi firmware v binarnim tvaru.
//
// Vystup: DWORD
cmdBOOT 0x07 // Provede hw reset pocitace.
// Konfigurace a nastaveni unikarty:
cmdMOUNT 0x10 // Nastavi image file pro prislusnou mechaniku a ulozi konfiguraci.
// Pokud uz je v mechanice nejaky DSK, tak provede jeho sync a odpoji se.
//
// Vstup: 1B - cislo mechaniky, 0..3 - FDD, 4 - RAMdisc, 5 - QDisc, 6 - EMMdisc
// string - DSK image path/filename (pokud je parametr prazdny, tak se mechanika odmountuje a zustane prazdna)
cmdINTCALLER 0x11 // Sdeli kdo je volajicim interruptu. Kody volajicich periferii jsou definovany v mzint.h
//
// Vystup: 1B - mzintFLAG
// Prace s filesystemem:
cmdGETFREE 0x20 // Sdeli celkovy pocet a pocet volnych sektoru na disku.
//
// Vystup: DWORD - celkovy pocet sektoru
// DWORD - pocet volnych sektoru
cmdCHDIR 0x21 // Zmena CWD.
//
// Vstup: string - path nebo dirname
cmdGETCWD 0x22 // Sdeli aktualni CWD.
//
// Vystup: string, 0x0d
// Prace se soubory a adresari:
cmdSTAT 0x30 // Informace o souboru nebo adresari.
//
// Vstup: string
// Vystup: binarni struktura FILINFO
cmdUNLINK 0x31 // Smazat soubor nebo adresar.
//
// Vstup: string
cmdCHMOD 0x32 // Zmena atributu souboru nebo adresare.
//
// Vstup: 1B - atributy
// 1B - maska
// string - filename/dirname
//
//
// 0x01 AM_RDO Read only
// 0x02 AM_HID Hidden
// 0x04 AM_SYS System
// 0x20 AM_ARC Archive
//
// Napr. nastavit AM_RDO a smazat AM_ARC (ostatni atributy zustanou nezmeneny):
//
// attr = AM_RDO
// mask = AM_RDO | AM_ARC
//
cmdUTIME 0x33 // Nastaveni casove znacky souboru.
//
// Vstup: 6B - D,M,Y-1980,H,M,S
// string - filename/dirname
cmdRENAME 0x34 // Prejmenovani souboru nebo adresare.
//
// Vstup: string - oldname
// string - newname
// Prace s adresarem:
cmdMKDIR 0x40 // Vytvori adresar.
//
// Vstup: string - dirname
cmdREADDIR 0x41 // Otevre adresar a pripravi na data port binarni vystup pro cteni.
// Pokud byl otevreny nejaky soubor, tak se provede sync() a zavre se.
//
// Vstup: string - dirname
// Vystup: FILINFO - binarni struktura pro kazdou polozku adresare
cmdFILELIST 0x42 // Otevre adresar a pripravi na data port textovy vystup pro cteni.
// Pokud byl otevreny nejaky soubor, tak se provede sync() a zavre se.
//
// Vstup: string - dirname
// Vystup: string filename[/],0x0d,string size,0x0d
cmdNEXT 0x43 // Provede okamzity presun na dalsi polozku adresare v prave
// vykonavanem READDIR nebo FILELIST.
// Prace se souborem:
#define cmdOPEN 0x50 // Otevre soubor v pozadovanem rezimu.
//
// Vstup: 1B - rezim viz. 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 // Zmena pozice v otevrenem souboru.
//
// Vstup: 1B - rezim
// 0x00 - od zacatku
// 0x01 - od konce
// 0x02 - relativne nahoru
// 0x03 - relativne dolu
// DWORD - pocet bajtu o ktere se ma ukazatel posunout
#define cmdTRUNC 0x52 // Zkrati prave otevreny soubor na velikost odpovidajici soucasne pozici ukazatele.
#define cmdSYNC 0x53 // Provede sync() prave otevreneho souboru.
#define cmdCLOSE 0x54 // Provede sync() a zavre prave otevreny soubor.
#define cmdTELL 0x55 // Sdeli pozici ukazatele v prave otevrenem souboru.
//
// Vystup: DWORD
#define cmdSIZE 0x56 // Sdeli velikost prave otevreneho souboru.
//
// Vystup: DWORD
// Prace s RTC:
#define cmdRTCSETD 0x60 // Nastaveni datumu.
//
// Vstup: 3B - D,M,Y-1980
#define cmdRTCSETT 0x61 // Nastaveni casu.
//
// Vstup: 3B - H,M,S
#define cmdRTCGETD 0x62 // Vrati aktualni datum.
//
// Vystup: 3B - D,M,Y-1980
#define cmdRTCGETT 0x63 // Vrati aktualni cas.
//
// Vystup: 3B - H,M,S
// USART:
#define cmdUSHELLON 0x70 // Zapne USARTshell, vypne emu_SIO.
#define cmdUSHELLOFF 0x71 // Vypne USARTshell, zapne emu_SIO.
#define cmdUSARTBPS 0x72 // Nastaveni BPS pro USART1.
//
// Vstup: DWORD - rychlost