home *** CD-ROM | disk | FTP | other *** search
/ Computer Club Elmshorn Atari PD / CCE_PD.iso / pc / 0600 / CCE_0665.ZIP / CCE_0665.PD / HSMODA01 / SERSOFST.TXT < prev    next >
Text File  |  1993-11-20  |  34KB  |  776 lines
  1. Festlegung einer Softwareschnittstelle, die eine vollständig
  2. hardwareunabhängige Nutzung serieller Interfaces ermöglicht
  3. ============================================================
  4.  
  5. Definition of a software interface, providing a fully hardware independend 
  6. use of serial interfaces
  7. ============================================================
  8. (This file contains the english version too, begin to search at the 
  9. middle of the text.)
  10.  
  11.  
  12. Text von: Harun Scheutzow, Dresdener Straße 83, D-10179 Berlin
  13. Internet-Email: Harun_Scheutzow@B.maus.de
  14. letzte Änderung: 12.11.1993
  15.  
  16.  
  17. Es sollen möglichst alle Funktionen definiert werden, die ein 
  18. Terminalprogramm, ein Übertragungsprotokoll oder z.B. ein Faxprogramm 
  19. benötigt. Diese Funktionen sollen ein hardwareunabhängiges Interface für 
  20. Programme darstellen.
  21.  
  22. Dieser Vorschlag ist Eric Smith bekannt. Es ist (noch?) KEIN 
  23. offizieller Atari-Standard. Eric findet den Vorschlag gut (nur die 
  24. Callbacks hält er bezüglich Memory Protection für nicht so toll) und 
  25. meint: Es ist besser, einen inoffiziellen Standard zu haben, als gar 
  26. keinen. Originalton im englischen Teil.
  27.  
  28. MiNT oder TOS oder ein nachzuladender Treiber sollen möglichst viele der 
  29. hier beschriebenen Funktionen unterstützen, soweit es die Hardware zuläßt. 
  30. Es muß aber jede Soft damit rechnen, daß eine Funktion nicht existiert 
  31. (Rückmeldung EINVFN, -32). Verhindert dies die Arbeit der Soft, so muß der 
  32. Nutzer darüber informiert werden.
  33.  
  34. Dies hier ist ein Standardisierungsversuch für das Interface, daß 
  35. Nutzerprogramme vorfinden. Über die Interna der Treiberimplementation soll 
  36. nichts geschrieben werden. Bei allen Funktionen und Vorschlägen muß aber 
  37. daran gedacht werden, daß diese auch auf einem 68000 mit 8MHz bei 38400Bd 
  38. über den MFP (also ohne FIFO) realisierbar sind. Die steigende Leistung der 
  39. CPUs ist kein Argument, da die gewünschte Datentransferrate auch ständig 
  40. steigt.
  41.  
  42.  
  43. Fopen, Fread, Fwrite, Fclose dürften als normale GEMDOS-Funktionen jedem
  44. bekannt sein. Fcntl ist die im MiNT (und in HSMODEM) vorhandene GEMDOS-Funktion
  45. $104, mit LONG Fcntl( WORD filehandle, LONG special, WORD subfunction). Fcntl
  46. liefert meist eine 0 als OK-Meldung, oder sonst einen Fehlercode. Irgendwelche
  47. abgefragten Werte werden üblicherweise nicht als Returncode von Fcntl
  48. geliefert, sondern auf einer Speicherstelle, auf die special zeigt.
  49.  
  50. Die Reservierung einer Schnittstelle will ich über den Öffnungsmodus von Fopen 
  51. realisieren.
  52.  
  53.  
  54. ########################################################################
  55.  
  56. Ich werde noch eine deutsche Beschreibung der vorhandenen Fcntl-Funktionen für
  57. serielle Schnittstellen zusammenstellen, für HSMODEM1 muβ ich das sowieso. 
  58. Hier ein Versuch der Dokumentation, was MiNT bereits bieten soll (nicht 
  59. alle Funktionen funktionieren (ganz so wie sie sollen)):
  60.  
  61.  
  62. Manche Zeilen sind C, manche Kommentar. Bei den angegebenen 
  63. Funktionsaufrufen handelt es sich wirklich um Musteraufrufe, und nicht etwa 
  64. um mißgestaltete Prototypen.
  65.  
  66.  
  67.  
  68. Ermittlung, wieviel Byte nichtblockierend übertragen werden können
  69. ------------------------------------------------------------------
  70. #define FIONREAD  (('F'<< 8) | 1)
  71. #define FIONWRITE (('F'<< 8) | 2)
  72. Fcntl( handle, &count, FIONREAD)
  73. Fcntl( handle, &count, FIONWRITE)
  74. In count wird als 32Bit-Wert die Anzahl der Byte hinterlassen, die beim 
  75. nächsten Fread/Fwrite mindestens gelesen/geschrieben werden können. Da aber 
  76. möglicherweise mehrere Programme auf einen Port schreiben könnten, sollte 
  77. man nur den Returnwert von Fread/Fwrite für voll nehmen.
  78.  
  79.  
  80. Setzen und Rücksetzen von Break
  81. -------------------------------
  82. #define TIOCCBRK (('T'<< 8) | 20)
  83. #define TIOCSBRK (('T'<< 8) | 21)
  84. Fcntl( handle, dummy, TIOCSBRK); /* Break aktivieren */
  85. Fcntl( handle, dummy, TIOCCBRK); /* Break löschen */
  86.  
  87.  
  88. Setzen/Abfragen der Eingabegeschwindigkeit und Steuerung der DTR-Leitung
  89. ------------------------------------------------------------------------
  90. #define TIOCIBAUD (('T'<< 8) | 18)
  91. Fcntl( handle, &speed, TIOCIBAUD);
  92. Setze die Eingabegeschwindigkeit der Schnittstelle. In speed steht ein 
  93. 32Bit-Wert, der die gewünschte Geschwindigkeit unkodiert in Bit pro Sekunde 
  94. angibt. speed = 19200 würde auf 19200bps setzen. In speed wird die 
  95. Geschwindigkeit vor dem Aufruf von TIOCIBAUD zurückgegeben. Ist sie 
  96. unbekannt, wird -1 geliefert. Ist beim Aufruf speed = -1, so wird nur die 
  97. Geschwindigkeit erfragt. Ist speed = 0, so wird das DTR-Signal auf inaktiv 
  98. gebracht (gelöscht), ohne die Geschwindigkeit zu beeinflussen. Bei 
  99. geschwindigkeitssetzendem Aufruf wird DTR automatisch aktiviert. 
  100. Rückgabewert ist ERANGE wenn die Geschwindigkeit nicht einstellbar ist. 
  101. Dann wird als "Ausnahme" in speed die nächstniedrigere mögliche 
  102. Geschwindigkeit geliefert. Gibt es keine nächstniedrige, so wird die 
  103. kleinstmögliche zurückgegeben.
  104.  
  105.  
  106. Setzen/Abfragen der Ausgabegeschwindigkeit und Steuerung der DTR-Leitung 
  107. ------------------------------------------------------------------------
  108. #define TIOCOBAUD (('T'<< 8) | 19) Fcntl( handle, &speed, TIOCOBAUD);
  109. Setze die Ausgabegeschwindigkeit der Schnittstelle. Die 
  110. Funktionsbeschreibung ist identisch zu TIOCIBAUD. Unterstützt eine 
  111. Schnittstelle getrennte Ein- und Ausgabegeschwindigkeit nicht, so 
  112. beeinflußt jeder Aufruf beide Geschwindigkeiten.
  113.  
  114.  
  115. Übertragungsprotokolleinstellungen erfragen
  116. -------------------------------------------
  117. #define TIOCGFLAGS (('T'<< 8) | 22)
  118. Fcntl( handle, &flags, TIOCGFLAGS);
  119. Liefert in flags einen 16Bit-Wert der eingestellten Parameter, die eine 
  120. ODER-Verknüpfung der folgenden Werte darstellen. Alle anderen Bit sind 
  121. reserviert. Bei TIOCGFLAGS sollte man sie ignorieren. Sinnvollerweise 
  122. erfragt man mit TIOCGFLAGS, modifiziert die bekannten Werte, und setzt dann 
  123. per TIOCSFLAGS.
  124.  
  125. /* Anzahl der Stoppbits */
  126. #define TF_STOPBITS 0x0003
  127. /* 0x0000  nicht erlaubt
  128. ERWEITERUNGSVORSCHLAG: So wird der Synchronmode aktiviert. Die restlichen 
  129. Parameter erhalten im Synchronmode andere Bedeutungen. Diese sind später 
  130. noch festzulegen. */
  131. #define TF_1STOP   0x0001 /* 1 Stoppbit */
  132. #define TF_15STOP  0x0002 /* 1.5 Stoppbit */
  133. #define    TF_2STOP   0x0003 /* 2 Stoppbit */
  134.  
  135. /* Anzahl der Bits pro Zeichen */
  136. #define TF_CHARBITS 0x000C
  137. #define TF_8BIT    0x0 /* 8 Bit */
  138. #define TF_7BIT    0x4
  139. #define TF_6BIT    0x8
  140. #define TF_5BIT    0xC /* 5 Bit */
  141.  
  142. /* Handshakemodi und Parität */
  143. #define TF_FLAG  0xF000
  144. #define T_TANDEM 0x1000 /* XON/XOFF (=^Q/^S) Flußkontrolle aktiv */
  145. #define T_RTSCTS 0x2000 /* RTS/CTS Flußkontrolle aktiv */
  146. #define T_EVENP  0x4000 /* even (gerade) Parität aktiv */
  147. #define T_ODDP   0x8000 /* odd (ungerade) Parität aktiv */
  148. /* even und odd schließen sich gegenseitig aus */
  149.  
  150.  
  151. Übertragungsprotokolleinstellungen setzen
  152. -----------------------------------------
  153. #define TIOCSFLAGS (('T'<< 8) | 23)
  154. Fcntl( handle, &flags, TIOCSFLAGS);
  155. Setzt die Einstellungen, Beschreibung dieser bei TIOCGFLAGS. Rückgabewert 
  156. ist ERANGE bei illegaler / nicht unterstützer Kombination in flags.
  157.  
  158.  
  159. Ende der Dokumentattion der mir bekannten und verständlichen Funktionen in 
  160. MiNT.
  161.  
  162. ########################################################################
  163.  
  164. Es folgen die neuen Vorschläge:
  165.  
  166.  
  167. Leeren der seriellen Puffer
  168. ---------------------------
  169. #define TIOCFLUSH (('T'<< 8) | 8)
  170. (ist doch im Mint "/* BUG: this should flush the input/output buffers */")
  171. Auswählbar über den special-Parameter werden die seriellen Puffer 
  172. unterschiedlich geleert:
  173. special  Funktion
  174. 0
  175.          Der Sendepuffer soll komplett gesendet werden. Die Funktion kehrt 
  176.          erst zurück, wenn der Puffer leer ist (return E_OK, =0) oder ein 
  177.          systeminterner Timeout abgelaufen ist (return EDRVNR, =-2). Der 
  178.          Timeout wird vom System sinnvoll bestimmt.
  179. 1
  180.          Der Empfangspuffer wird gelöscht.
  181. 2
  182.          Der Sendepuffer wird gelöscht.
  183. 3
  184.          Empfangspuffer und Sendepuffer werden gelöscht.
  185. -tout
  186.          Ein negativer Parameter funktioniert wie 0, aber tout (man 
  187.          beachte, tout selbst ist positiv) gibt den Timeout in 1/200 
  188.          Sekunden vor.
  189.  
  190.  
  191. Stoppen des Empfangs
  192. --------------------
  193. #define TIOCSTOP (('T'<< 8) | 9)
  194. Ist nur in den Handshakemodi verfügbar und teilt dem Kommunikationspartner 
  195. mit, daß der Rechner nichts empfangen möchte. Die Funktion wartet eine 
  196. sinnvolle Zeitspanne, um in der Übertragung befindliche Zeichen 
  197. einzusammeln. Dann geht sie davon aus, daß der Partner schweigt und kehrt 
  198. zurück. (Anwendungsbeispiel: Ein 8MHz-ST kann nicht gleichzeitig DMA und 
  199. 57600Bd-Empfang über den MFP.)
  200.  
  201.  
  202. Starten des Empfangs
  203. --------------------
  204. #define TIOCSTART (('T'<< 8) | 10)
  205. Hebt die Wirkung von TIOCSTOP auf.
  206.  
  207.  
  208. Erfragen/Setzen der Puffereinstellungen
  209. ---------------------------------------
  210. #define TIOCBUFFER (('T'<<8) | 128)
  211. special zeigt beim Aufruf auf eine Struktur:
  212. LONG   Größe des Eingabepuffers in Byte
  213. LONG   untere Wassermarke des Eingabepuffers in Byte
  214. LONG   obere Wassermarke des Eingabepuffers in Byte
  215. LONG   Größe des Ausgabepuffers in Byte
  216. Soll ein Wert nur erfragt bzw. nicht geändert werden, so ist anstelle des 
  217. Wertes eine -1 anzugeben. Wird anstelle eines Wertes -1 zurückgegeben, so 
  218. wird diese Funktion nicht unterstützt. Werden Werte gesetzt, so sollte man 
  219. auch den Rückgabewert prüfen, da der Treiber bei ihm nicht passenden 
  220. Vorgaben die nächstliegenden ihm passenden Werte einsetzt und benutzt. 
  221. (Hinweis: Es ist allein Sache des Treibers, den Speicher irgendwo zu 
  222. reservieren oder freizugeben. Das kann man auch unter TOS programmieren.)
  223.  
  224.  
  225. Erfragen der I/O-Leitungen und Signalisierungsfähigkeiten
  226. ---------------------------------------------------------
  227. #define TIOCCTLMAP (('T'<<8) | 129)
  228. special ist Zeiger auf eine Struktur aus 6 LONGs, die durch den Treiber 
  229. ausgefüllt wird. In jedem LONG wird für jede vorhandene 
  230. Steuer/Melde-Leitung oder Fähigkeit das Bit auf 1 gesetzt.
  231. 1.LONG: Leitung über TIOCCTL(GET/SET) abfrag/beieinflußbar
  232. 2.LONG: Reaktion (Routinenaufruf) bei Eintreten des Zustandes möglich.
  233. 3.LONG: Reaktion (Routinenaufruf) bei Beendigung des Zustandes möglich.
  234. 4.LONG: reserviert für zukünftige Erweiterungen, bis dahin 0
  235. 5.LONG: reserviert für zukünftige Erweiterungen, bis dahin 0
  236. 6.LONG: reserviert für zukünftige Erweiterungen, bis dahin 0
  237. Die Zuordnung der Bits zu den "Leitungen" lautet:
  238. #define TIOCM_LE   0x0001 /* line enable output, Ausgang */
  239. #define TIOCM_DTR  0x0002 /* data terminal ready, Ausgang */
  240. #define TIOCM_RTS  0x0004 /* ready to send, hat heute andere Bedeutung,
  241. Ausgang */
  242. #define TIOCM_CTS  0x0008 /* clear to send, hat heute andere Bedeutung,
  243. Eingang */
  244. #define TIOCM_CAR  0x0010 /* data carrier detect, Eingang */
  245. #define TIOCM_CD   TIOCM_CAR /* alternativer Name */
  246. #define TIOCM_RNG  0x0020 /* ring indicator, Eingang */
  247. #define TIOCM_RI   TIOCM_RNG /* alternativer Name */
  248. #define TIOCM_DSR  0x0040 /* data set ready, Eingang */
  249. #define TIOCM_LEI  0x0080 /* line enable input, Eingang */
  250. #define TIOCM_TXD  0x0100 /* Sendedatenleitung, Ausgang */
  251. #define TIOCM_RXD  0x0200 /* Empfangsdatenleitung, Eingang */
  252. #define TIOCM_BRK  0x0400 /* Break erkannt, Pseudo-Eingang */
  253. #define TIOCM_TER  0x0800 /* Sendefehler, Pseudo-Eingang */
  254. #define TIOCM_RER  0x1000 /* Empfangsfehler, Pseudo-Eingang */
  255. #define TIOCM_TBE  0x2000 /* Hardware-Sendepuffer leer, Pseudo-Eingang */
  256. #define TIOCM_RBF  0x4000 /* Hardware-Empfangspuffer voll, Pseudo-Eingang */
  257.  
  258. Nichtdefinierte Bits sollten ignoriert werden.
  259.  
  260. Einige TIOCM_* haben Besonderheiten, die hier erklärt werden:
  261.  
  262. TIOCM_TER, TIOCMRER
  263. Der Routine wird in D0.b ein Byte übergeben, das den Fehler genauer angibt:
  264. Byte Fehler
  265. 0    allgemeiner, nicht genauer spezifizierbarer Fehler
  266. 1    Hardware-Empfangspufferüberlauf
  267. 2    Software-Empfangspufferüberlauf
  268. 3    Paritätsfehler
  269. 4    Rahmenfehler
  270.  
  271. TIOCM_TBE
  272. Der Routine wird in D0.w -1 übergeben, falls im Software-Sendepuffer kein 
  273. Byte mehr ist. Andernfalls wird ein Byte aus dem Software-Sendepuffer 
  274. gelesen und in D0.b übergeben, D0.bit15 ist dann =0. Die Routine gibt in 
  275. D0.w -1 zurück, falls nichts gesendet werden soll. Sie gibt D0.bit15 =0 und 
  276. in D0.b das Byte zurück, falls es gesendet werden soll. Diese Routine wird 
  277. ebenfalls aufgerufen, wenn ein Byte neu in den Software-Sendepuffer 
  278. geschrieben wurde, und der Sendepuffer schon lange leer ist. Gibt diese 
  279. Routine ein selbst erzeugtes -1 zurück und stehen noch Daten im 
  280. Software-Sendepuffer, so wird sie spätestens nach einer Sekunde erneut 
  281. aufgerufen.
  282.  
  283. TIOCM_RBF
  284. Der Routine wird in D0.b das empfangene Byte übergeben. Sie gibt in D0.w -1 
  285. zurück, falls nichts in den Software-Empfangspuffer geschrieben werden 
  286. soll. Andernfalls gibt sie D0.bit15 =0 und in D0.b das Byte zurück, das in 
  287. den Software-Empfangspuffer geschrieben werden soll.
  288.  
  289.  
  290. Abfragen der I/O-Leitungen und Signalisierungen
  291. -----------------------------------------------
  292. #define TIOCCTLGET (('T'<<8) | 130)
  293. liefert auf der durch special angegebenen Speicherstelle ein LONG, in dem 
  294. die aktuellen Zustände der CTLleitungen abgelegt werden, Kodierung wie bei 
  295. TIOCCTLMAP. Auf special wird auch ein Parameter hin übergeben: Ist er -1, 
  296. so werden alle CTLleitungen erfragt, ist er <>-1, so darf nur ein Bit 
  297. gesetzt sein, und es wird nur diese CTLleitung erfragt. Der Treiber darf 
  298. trotzdem auch die Werte der anderen Leitungen zu liefern. Das geschieht aus 
  299. Geschwindigkeitsgründen. Unsinnig gesetzte Bits werden ignoriert.
  300.  
  301.  
  302. Setzen der I/O-Leitungen und Signalisierungen
  303. -----------------------------------------------
  304. #define TIOCCTLSET (('T'<<8) | 131)
  305. special zeigt auf eine Struktur:
  306. LONG ctlmaske
  307. LONG ctlvalues
  308. Es werden die in ctlmaske gesetzten Bit (Kodierung wie bei TIOCCTLMAP) auf 
  309. die in ctlvalues vorhandenen Werte gesetzt. In ctlmaske darf man natürlich 
  310. nur Bits setzen, deren Funktion man kennt. Eingabeleitungen lassen sich 
  311. nicht beeinflussen, solche Setzversuche werden wie unsinnige Bits 
  312. ignoriert.
  313.  
  314.  
  315. Konzept der Callback-Funktionen
  316. -------------------------------
  317. Ein Programm kann Funktionen anmelden, die beim Eintreten bestimmter 
  318. Zustände sehr schnell aufgerufen werden. Angemeldet wird die Funktion durch 
  319. Übergabe ihrer Adresse in procadr. Dabei ist Bit0 immer 0. Abgemeldet wird 
  320. durch den gleichen Aufruf, aber mit gesetzem Bit0 (also =1) in procadr, 
  321. also einer ungeraden Adresse! Bit31-1 müssen genau wie ctlline den gleichen 
  322. Wert wie beim Installieren aufweisen. Wenn bei den einzelnen Funktionen 
  323. nichts anderes steht, gelten folgende Grundsätze:
  324. - Nur Register D0 und A0 dürfen verändert werden.
  325. - Sie muβ extrem kurz sein, mehr als 20 "normale" Assemblerbefehle sind
  326.   unzulässig (ein MOVEM.L D1-D7/A1-A6,... oder DIV ist nicht als "normal"). 
  327.   Anders ausgedrückt: die Laufzeit der Routine sollte auf einer CPU MC68000 
  328.   200 Takte nicht überschreiten.
  329. - Aufruf erfolgt im Supervisormode.
  330. - Der aktuelle InterruptPriorityLevel ist unbestimmt.
  331. - Ende mit RTS.
  332.  
  333. Es ist denkbar, daβ mehrere Programme gleichzeitig eine Leitung überwachen. 
  334. Man muβ die Routine abmelden, bevor sie durch eine nichtresidente 
  335. Beendigung des Programms aus dem Speicher fliegt. Es ist egal, welcher 
  336. Filehandle zur An-/Abmeldung benutzt wird, wenn er auf das entsprechende 
  337. Device paßt (z.B. Fopen, Fcntl(...,TIOCCTLSFAST) /*Anmeldung*/, Fclose, 
  338. ... Fopen, Fcntl(...,TIOCCTLSFAST) /*Abmeldung*/, Fclose).
  339.  
  340. Manche Funktionen werden nur bei bestimmten Handshakemodi existieren und 
  341. können nur unter diesen Modi angemeldet, aber unter jedem Modus abgemeldet 
  342. werden. Sie werden beim Umschalten des Handshakes automatisch aktiviert und 
  343. deaktiviert, solange sie angemeldet sind.
  344.  
  345.  
  346. Anmelden/Abmelden schneller Callback-Funktionen
  347. -----------------------------------------------
  348. #define TIOCCTLSFAST (('T'<<8) | 132)
  349. Anmelden und Abmelden von Routinen, die bei Statusänderung der CTLleitungen
  350. aufgerufen werden. special ist ein Zeiger auf Struktur:
  351. LONG ctlline
  352. LONG procadr
  353. Die Routine wird möglichst (siehe dazu TIOCCTLMAP) bei jeder Flanke auf der 
  354. in ctlline (dort darf nur ein Bit gesetzt sein, siehe TIOCCTLMAP) 
  355. angegebenen Leitung aufgerufen. Der dabei angenommene neue Pegel der 
  356. Leitung wird in D0.b übergeben: 0 inaktiv (bei DSR wäre es TTL-High-Pegel) 
  357. und $FF für aktiv.
  358. Returnwerte der Funktion:
  359. E_OK    alles OK
  360. 1       Routine installiert, aber sie ist nicht die einzige. So langsam wird
  361.         es zeitkritisch, das Programm sollte wenn möglich die Routine wieder
  362.         deinstallieren. (Das ist nur eine Empfehlung)
  363. EINVFN  diese Überwachungsmöglichkeit gibt es nicht
  364. EACCDN  Routine kann nicht mehr installiert werden.
  365.  
  366.  
  367. Anmelden/Abmelden langsamer Callback-Funktionen
  368. -----------------------------------------------
  369. #define TIOCCTLSSLOW (('T'<<8) | 133)
  370. fast identisch zu CTLSIGFAST, mit einem Unterschied: Die Routine darf fast 
  371. beliebig lang sein.
  372.  
  373.  
  374. Erfragen der Anzahl noch nicht gesendeter Byte
  375. ----------------------------------------------
  376. #define TIONOTSEND (('T'<<8) | 134)
  377. Fcntl( handle, &count, TIONOTSEND)
  378. In count wird als 32Bit-Wert die Anzahl der Byte hinterlassen, die noch 
  379. nicht gesendet wurden. Es wird versucht, im Rahmen der Möglichkeiten 
  380. (Hardware-FIFOs), möglichst genau zu bestimmen, wieviel nichtgesendete 
  381. Zeichen im Rechner sind.
  382.  
  383.  
  384. Einstellung des Verhaltens bei Fehlern
  385. --------------------------------------
  386. #define TIOCERROR (('T'<<8) | 135)
  387. Fcntl( handle, &errmode, TIOCERROR);
  388. errmode ist ein LONG. Ist errmode -1, wird in errmode nur die aktuelle 
  389. Einstellung geliefert. Ist errmode >=0, so werden die Einstellungen gesetzt 
  390. und die vorigen Werte geliefert. In Bit7..0 von errmode wird ein Zeichen 
  391. übergeben. Bit8 =1 schaltet das Einfügen dieses Zeichens in den 
  392. Empfangspuffer bei einem Empfangsfehler ein. Normalerweise ist Bit8 =0, bei 
  393. einem Fehler wird kein Zeichen in den Puffer geschrieben. Bit9 =1 schaltet 
  394. das Löschen des Empfangspuffers bei Empfang von Break ein, normalerweise 
  395. ist Bit9 =0 und es erfolgt keine Pufferlöschung bei Break. Rückgabewert ist 
  396. E_OK, bei nicht unterstützten Einstellungen ERANGE.
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404. Definition of a software interface, providing a fully hardware independend 
  405. use of serial interfaces
  406. ============================================================
  407.  
  408. written by: Harun Scheutzow, Dresdener Straße 83, D-10179 Berlin
  409. Internet-Email: Harun_Scheutzow@B.maus.de
  410. last change: 12.11.1993
  411. translated into english: 12.11.1993
  412.  
  413. It should be defined (if possible) all functions, a terminal program, a 
  414. transfer protocol such as ZMODEM or eg. a fax program will need. This 
  415. functions realize a hardware independent interface for programs.
  416.  
  417. This proposal is known to Eric Smith. He wrote to me last:
  418. "Note that I can't say that this will be an 'official' Atari standard 
  419. right now; we haven't had time to review it completely and make it 
  420. official. But it seems OK to me, and it's better to have an 
  421. unofficial standard than no standard at all, I think."
  422. (Only the callbacks he likes not so much, because of possible problems 
  423. with memory protection).
  424.  
  425. MiNT or TOS or a loaded driver should support as much as possible of the 
  426. functions described here, if the hardware allows it. But every software has 
  427. to consider, that a function could not exist and only return the error 
  428. EINVFN (-32). If the absence of a function prevents the proper work of the 
  429. software, the user must be informed about this fact by this software.
  430.  
  431. This is a attemp to standardize the interface found by user programms. 
  432. About the interna of driver implementation nothing should be written. All 
  433. functions and suggestions should be implementable on an 68000 with 8MHz and 
  434. 38400Bd transfer by the MFP (68901, without hardware-FIFO). The rising 
  435. performance of the CPUs is no argument, because the demanded data transfer 
  436. rate rises permanently too.
  437.  
  438.  
  439. Everybody should know Fopen, Fread, Fwrite, Fclose as normal 
  440. GEMDOS-functions. Fcntl is the GEMDOS-function $104, with LONG Fcntl( WORD 
  441. filehandle, LONG special, WORD subfunction), existing in MiNT (and in 
  442. HSMODEM). Fcntl returns mostly a 0 as OK-message, or otherwise a error 
  443. code. Any requested values are used to return in a memory cell the 
  444. parameter special is pointing to, and not as return code of Fcntl.
  445.  
  446. Reserving of a Interface I like to realize about the opening mode of Fopen.
  447.  
  448.  
  449. ########################################################################
  450.  
  451. The description of the following functions is a modified copy from same 
  452. files included in a MiNT distribution.
  453.  
  454.  
  455. Some lines are C, some comment. The function calls are really examples and 
  456. not prototypes.
  457.  
  458.  
  459. How many bytes may be transfered nonblocking?
  460. ---------------------------------------------
  461. #define FIONREAD  (('F'<< 8) | 1)
  462. #define FIONWRITE (('F'<< 8) | 2)
  463. Fcntl( handle, &count, FIONREAD)
  464. Fcntl( handle, &count, FIONWRITE)
  465. count is a 32Bit-value in which the function returns the number of bytes, 
  466. which can be at least read / written during the next Fread/Fwrite. Because 
  467. more than one program could write to a interface, nobody should rely on 
  468. this. Only Fread/Fwrite return, how much byte are really transfered.
  469.  
  470.  
  471. Set and Reset Break
  472. -------------------
  473. #define TIOCCBRK (('T'<< 8) | 20)
  474. #define TIOCSBRK (('T'<< 8) | 21)
  475. Fcntl( handle, dummy, TIOCSBRK); /* aktivate Break */
  476. Fcntl( handle, dummy, TIOCCBRK); /* clear Break */
  477.  
  478.  
  479. Set/Inquire the input speed and DTR-line control
  480. ------------------------------------------------
  481. #define TIOCIBAUD (('T'<< 8) | 18)
  482. Fcntl( handle, &speed, TIOCIBAUD);
  483. Set the input speed of the interface. speed is a 32Bit-value, which 
  484. contains the requested speed uncoded in bits per second. speed = 19200 
  485. would set the speed to 19200bps. The old (real) input speed is returned in 
  486. speed. If the old speed is unknown, -1 is returned. If speed = -1 as input 
  487. parameter of TIOCIBAUD, only the input speed is returned. If speed = 0, the 
  488. DTR-line will be inaktivated (cleared, dropped), without influence on the 
  489. real speed. Every TIOCIBAUD-call which sets the speed, aktivates 
  490. automatically DTR. Returnvalue is ERANGE if the requested speed is not 
  491. available. In this case (as exception) the next lowest legal speed is 
  492. returned in speed. If a next lowest speed is unavailable too, the lowest 
  493. legal speed is returned.
  494.  
  495.  
  496. Set/Inquire the output speed and DTR-line control
  497. -------------------------------------------------
  498. #define TIOCOBAUD (('T'<< 8) | 19) Fcntl( handle, &speed, TIOCOBAUD);
  499. Set output speed of the interface. The function description is identical 
  500. with TIOCIBAUD. If a device does not support different input and output 
  501. speed, TIOCIBAUD and TIOCOBAUD affects both speeds.
  502.  
  503.  
  504. Inquire protocol settings
  505. -------------------------
  506. #define TIOCGFLAGS (('T'<< 8) | 22)
  507. Fcntl( handle, &flags, TIOCGFLAGS);
  508. Get the terminal control flags bits. 16 bit flag word flags is set to 
  509. reflect the current terminal state. It is a OR-connection of bits and bit 
  510. combinations. Not defined bits should be ignored. A 
  511. program should read the flags with TIOCGFLAGS, modify the interesting, and 
  512. set the new value with TIOCSFLAGS.
  513.  
  514. /* Number of stopbits */
  515. #define TF_STOPBITS 0x0003
  516. /* 0x0000  illegal
  517. extension proposal: This aktives the synchron mode. The remaining bits will 
  518. have other meanings in synchron mode, which must be defined in future. */
  519. #define TF_1STOP   0x0001 /* 1 Stopbit */
  520. #define TF_15STOP  0x0002 /* 1.5 Stopbit */
  521. #define    TF_2STOP   0x0003 /* 2 Stopbit */
  522.  
  523. /* Bits per character */
  524. #define TF_CHARBITS 0x000C
  525. #define TF_8BIT    0x0 /* 8 Bit */
  526. #define TF_7BIT    0x4
  527. #define TF_6BIT    0x8
  528. #define TF_5BIT    0xC /* 5 Bit */
  529.  
  530. /* Handshake and parity */
  531. #define TF_FLAG  0xF000
  532. #define T_TANDEM 0x1000 /* XON/XOFF (=^Q/^S) flow control aktiv */
  533. #define T_RTSCTS 0x2000 /* RTS/CTS flow control aktiv */
  534. #define T_EVENP  0x4000 /* even parity aktiv */
  535. #define T_ODDP   0x8000 /* odd parity aktiv */
  536. /* even and odd are mutually exclusive */
  537.  
  538.  
  539. Set protocol settings
  540. ---------------------
  541. #define TIOCSFLAGS (('T'<< 8) | 23)
  542. Fcntl( handle, &flags, TIOCSFLAGS);
  543. Set the settings, description see TIOCGFLAGS. Returnvalue is ERANGE if a 
  544. illegal or not support combination occurs in flags.
  545.  
  546.  
  547. End of documentation of existing MiNT functions.
  548.  
  549. ########################################################################
  550.  
  551. New proposals follow:
  552.  
  553.  
  554. Flush serial buffers
  555. --------------------
  556. #define TIOCFLUSH (('T'<< 8) | 8)
  557. (in MiNT "/* BUG: this should flush the input/output buffers */")
  558. Selected by the special-parameter the buffers are flushed in different 
  559. ways:
  560. special  function
  561. 0
  562.          Send the transmit buffer. The function returns, if the transmit 
  563.          buffer is empty (return E_OK, =0) or if a internal timeout occurs 
  564.          (return EDRVNR, =-2). The system takes a reasonable timeout.
  565. 1
  566.          Clear the receive buffer.
  567. 2
  568.          Clear the transmit buffer.
  569. 3
  570.          Clear receive and transmit buffer.
  571. -tout
  572.          A negative parameter works as 0, but tout (hint: tout is positive) 
  573.          gives the timeout in 1/200 seconds.
  574.  
  575.  
  576. Stop receive
  577. ------------
  578. #define TIOCSTOP (('T'<< 8) | 9)
  579. is only available in the handshake modi and signals the communication 
  580. partner, that the computer wants to receive nothing. The function waits a 
  581. reasonable time for collecting characters already in transmission. Then it 
  582. returns, thinking, the partner stopped transmission. (Example for use: an 
  583. 8MHz-ST is unable to do simultaneously DMA and 57600Bd-receive by MFP.)
  584.  
  585.  
  586. Start receive
  587. -------------
  588. #define TIOCSTART (('T'<< 8) | 10)
  589. Eliminates effects of TIOCSTOP.
  590.  
  591.  
  592. Inquire/Set buffer settings
  593. ---------------------------
  594. #define TIOCBUFFER (('T'<<8) | 128)
  595. special points to a structure:
  596. LONG   input buffer size in byte
  597. LONG   low water mark in byte
  598. LONG   high water mark in byte
  599. LONG   output buffer size in byte
  600. If a value should inquired only, use a -1 instead of the value. Is a -1 
  601. returned instead of a value, this function is not supported. If values are 
  602. set, the returned values should be examined, because the driver may use not 
  603. the given ones, but the next values the driver founds suitable. (Hint: The 
  604. driver has to allocate an free the memory. That is implementable under 
  605. plain TOS too.)
  606.  
  607.  
  608. Inquire I/O-lines and signaling capabilities
  609. --------------------------------------------
  610. #define TIOCCTLMAP (('T'<<8) | 129)
  611. special is a pointer to a structur of 6 LONGs which is filled out by the 
  612. driver. In every LONG the corresponding bit is set to 1 for a existing 
  613. control line or capability.
  614. 1.LONG: line inquire-/setable with TIOCCTL(GET/SET)
  615. 2.LONG: aktion (routine call) possible at start of condition
  616. 3.LONG: aktion (routine call) possible at end of condition
  617. 4.LONG: reserved for future extension, till then 0
  618. 5.LONG: reserved for future extension, till then 0
  619. 6.LONG: reserved for future extension, till then 0
  620. corresponding bits and "lines":
  621. #define TIOCM_LE   0x0001 /* line enable output, output */
  622. #define TIOCM_DTR  0x0002 /* data terminal ready, output */
  623. #define TIOCM_RTS  0x0004 /* ready to send, today other meaning, output */
  624. #define TIOCM_CTS  0x0008 /* clear to send, today other meaning, input */
  625. #define TIOCM_CAR  0x0010 /* data carrier detect, input */
  626. #define TIOCM_CD   TIOCM_CAR /* alternative name */
  627. #define TIOCM_RNG  0x0020 /* ring indicator, input */
  628. #define TIOCM_RI   TIOCM_RNG /* alternative name */
  629. #define TIOCM_DSR  0x0040 /* data set ready, input */
  630. #define TIOCM_LEI  0x0080 /* line enable input, input */
  631. #define TIOCM_TXD  0x0100 /* transmit data line, output */
  632. #define TIOCM_RXD  0x0200 /* receive data line, input */
  633. #define TIOCM_BRK  0x0400 /* Break detected, pseudo-input */
  634. #define TIOCM_TER  0x0800 /* transmit error, pseudo-input */
  635. #define TIOCM_RER  0x1000 /* receive error, pseudo-input */
  636. #define TIOCM_TBE  0x2000 /* hardware-transmitter buffer empty, 
  637. pseudo-input */
  638. #define TIOCM_RBF  0x4000 /* hardware-receiver buffer full, pseudo-input */
  639.  
  640. Undefined bits should be ignored.
  641.  
  642. Some TIOCM_* have special features, described here:
  643.  
  644. TIOCM_TER, TIOCMRER
  645. The routine gets in D0.b a byte, describing the error in detail:
  646. Byte Error
  647. 0    no more information available about this error
  648. 1    hardware-receiver buffer overflow
  649. 2    software-receiver buffer overflow
  650. 3    parity error
  651. 4    framing error
  652.  
  653. TIOCM_TBE
  654. The routine gets in D0.w -1, if the software-transmit buffer is empty. 
  655. Otherways it gets a byte read out from the software-transmit buffer in 
  656. D0.b, D0.bit15 is =0 in this case. The routine returns in D0.w -1, if 
  657. nothing should be sent. It returns D0.bit15 =0 and in D0.b the byte, if the 
  658. byte should be sent. The routine is called too, if a new byte is written 
  659. into the software-transmit buffer and the buffer was empty before. If the 
  660. routine returns a self generated -1 and there are bytes available in the 
  661. software-transmit buffer, the routine is called again latest after one 
  662. second.
  663.  
  664. TIOCM_RBF
  665. The routine gets in D0.b the received byte. The routine returns in D0.w -1, 
  666. if nothing should be written into the software-receive buffer. Otherwise it 
  667. returns D0.bit15 =0 and in D0.b the Byte zurück, which should be written 
  668. into the software-receive buffer.
  669.  
  670.  
  671. Inquire I/O-lines and signals
  672. -----------------------------
  673. #define TIOCCTLGET (('T'<<8) | 130)
  674. returns a LONG in the memory cell special points to, which contains the 
  675. actual conditions of the CTLlines, coding see TIOCCTLMAP. On special is 
  676. given a parameter to this function too: If -1, all CTLlines are inquired, 
  677. if <>-1, only one bit has to be set, and only this CTLline is inquired. The 
  678. driver may provide never the less the values of the other lines, because of 
  679. speed reasons. Senceless set bits are ignored.
  680.  
  681.  
  682. Set I/O-lines and signals
  683. -------------------------
  684. #define TIOCCTLSET (('T'<<8) | 131)
  685. special points to a structur:
  686. LONG ctlmaske
  687. LONG ctlvalues
  688. The bits which are set in ctlmaske (coding see TIOCCTLMAP), are set to the 
  689. values in ctlvalues. A software should only set bit(s) in ctlmaske, if it 
  690. knows its functions. Input lines are unchangable, such bits are ignored as 
  691. senceless bits.
  692.  
  693.  
  694. concept of callback-functions
  695. -----------------------------
  696. A programm can install functions, which are called nearly immediately if a 
  697. condition occurs. A function becomes installed by giving its address in 
  698. procadr. During this installation Bit0 is always 0. A function becomes 
  699. uninstalled by the same call, but with set bit0 (=1) in procadr, with a odd 
  700. address! Bit31-1 and ctlline must have the same value as during 
  701. installation. If there are no special remarks for outstanding functions, 
  702. the following basic rules apply:
  703. - Only register D0 and A0 may be changed.
  704. - It must be extremly short, more than 20 "normal" assembler instructions
  705.   are not allowed (a MOVEM.L D1-D7/A1-A6,... or DIV is not "normal"). The 
  706.   rum time of the routine should not exceed 200 clocks on a CPU MC68000.
  707. - Call is made in supervisormode.
  708. - The actual InterruptPriorityLevel is unknown.
  709. - End with RTS.
  710.  
  711. It is possible, that several programs watch one line simultaneously. The 
  712. routine must be uninstalled, before it leaves the memory because a non 
  713. resident program termination. It is unimportant, which file handle is used 
  714. for (un-/)registration, if it matches the device (e.g. Fopen, 
  715. Fcntl(...,TIOCCTLSFAST) /*installation*/, Fclose, ... Fopen, 
  716. Fcntl(...,TIOCCTLSFAST) /*uninstallation*/, Fclose).
  717.  
  718. Some functions exist only under special handshake modi and can only 
  719. installed if this mode is activ, but uninstalled under every mode. Such 
  720. functions are automatically activated and deaktivated, as long as they are 
  721. installed.
  722.  
  723.  
  724. Install/Uninstall fast callback-functions
  725. -----------------------------------------
  726. #define TIOCCTLSFAST (('T'<<8) | 132)
  727. Installation and uninstallation of routines, which are called if changes on 
  728. the CTLlines occur. special is a pointer to a structur:
  729. LONG ctlline
  730. LONG procadr
  731. The routine is called on every transition (if possible, see TIOCCTLMAP) on 
  732. the line marked in ctlline (only one bit should be set, see TIOCCTLMAP). 
  733. The new level of the line is given in D0.b: 0 inaktiv (on the DSR line 
  734. inaktiv means TTL-high-level, for example) and $FF aktiv.
  735. Returnvalues of TIOCCTLSFAST:
  736. E_OK    everything OK
  737. 1       routine installed, but it is not the only one. It becomes time
  738.         critic, if possible, the programm should uninstall the routine. 
  739.         This is only a recommendation.
  740. EINVFN  this watch capability does not exist
  741. EACCDN  routine can not be installed.
  742.  
  743.  
  744. Install/Uninstall slow callback-functions
  745. -----------------------------------------
  746. #define TIOCCTLSSLOW (('T'<<8) | 133)
  747. nearly identical to TIOCCTLSFAST, with one difference: The routine may be 
  748. (nearly) as long as it likes to be.
  749.  
  750.  
  751. Inquire number of unsent bytes
  752. ------------------------------
  753. #define TIONOTSEND (('T'<<8) | 134)
  754. Fcntl( handle, &count, TIONOTSEND)
  755. The function returns in count as a 32bit-value the number of bytes, which 
  756. are not sent at this moment. The function tries, limited by the hardware 
  757. (hardware-FIFOs), exactly to find out how much unsent characters in the 
  758. computer are.
  759.  
  760.  
  761. Set error behavior
  762. ------------------
  763. #define TIOCERROR (('T'<<8) | 135)
  764. Fcntl( handle, &errmode, TIOCERROR);
  765. Errmode is a 32bit value. If errmode is -1 as input parameter, in errmode 
  766. is only the actual setting returned. If errmode >=0, the error behavior 
  767. will be set and the old setting is returned in errmode. In Bit7..0 of 
  768. errmode is a character. Bit8 =1 switchs on the insert of this character 
  769. into the receive buffer if a receive error occurs. Normally is Bit8 =0, and 
  770. no character is inserted during a error. Bit9 =1 switchs on the clearance 
  771. of receive buffer if break is received, normally is Bit9 =0 and the buffer 
  772. is not influenced by break. Returnvalue is E_OK, or ERANGE for not 
  773. supported settings.
  774.  
  775.  
  776.