home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / DC-POS24.LZX / pOS / pOS_RKRM.lzx / pOS_RKRM / _Txt / Dev.txt < prev    next >
Encoding:
Text File  |  1997-03-18  |  8.0 KB  |  277 lines
  1.  
  2. Hintergrundwissen zu den Devices:
  3. -----------------------------------
  4.  
  5. Das pOS-Device ist eine erweiterte Library. Speziell zur
  6. Kommuntikation ausgelegte Mechanismem sind Bestandteil der Devices.
  7. Der pExec-Kernel stellt IO-Funktionen bereit.
  8. pOS_DoIO, pOS_SendIO, pOS_BeginIO, pOS_AbortIO, pOS_CheckIO, pOS_WaitIO.
  9.  
  10. Von Sicht des Anwenderprogramms aus ist ein Device ein IO-Pool. Eine Aktion
  11. kann mittels pOS_DoIO vollständig bearbeitet werden. Mit pOS_SendIO und
  12. pOS_BeginIO kann die Aktion asynchron zum Anwenderprogramm erfolgen.
  13. Ein so gestarteter IO kann jederzeit mit pOS_AbortIO abgebrochen werden.
  14. Sollte der IO beim Aufruf von pOS_AbortIO schon fertig sein, so hat
  15. der Abort keine Auswirkung und der IO ist korrekt beendet. Ein laufender
  16. IO kann jederzeit auf seinen Status geprüft werden. Die Funktion
  17. pOS_CheckIO ermittelt, ob der IO abgeschlossen ist oder ob der IO noch
  18. bearbeitet wird. Zur nachträglichen Synchronisation dient die pOS_WaitIO-
  19. Funtion, die solange wartet, bis der IO bearbeitet ist.
  20.  
  21. Das pOS definiert einige Kommandos (CMD) für die Device-Handhabung.
  22.   (enum pOS_IOReqCommands) : io_Command
  23.  
  24. CMD_INVALID
  25.  Nicht definiertes Kommando, das Device antwortet immer mit IOERR_NoCMD.
  26.  
  27. CMD_RESET
  28.  Das Device wird in den Grundzustand (Einschaltzustand) zurückgesetzt.
  29.  Alle IOs werden abgebrochen und mit IOERR_Aborted gekennzeichnet.
  30.  Sämtliche Puffer werden zurückgesetzt.
  31.  
  32. CMD_READ
  33.  io_Data zeigt auf den Puffer, der mit Daten gefüllt werden soll. Die Puffergröße
  34.  wird in io_Length vermerkt. Nach Vollendung der Aktion steht in io_Actual die
  35.  beschriebene Puffergröße. Der Anwender muß jeden Request mittels io_Error
  36.  und io_Actual prüfen.
  37.  Durch die Device-Bearbeitung wird nur io_Flags, io_Actual, io_Error verändert.
  38.  
  39. CMD_WRITE
  40.  Der Puffer von io_Data wird geschrieben. Die Puffergröße befindet sich in
  41.  io_Length.
  42.  Durch die Device-Bearbeitung wird nur io_Flags, io_Actual, io_Error verändert.
  43.  
  44. CMD_UPDATE
  45.  Sämtliche gepufferte Daten werden auf den Datenträger geschrieben.
  46.  
  47. CMD_CLEAR
  48.  Sämtliche Datenpuffer werden geleert.
  49.  
  50. CMD_STOP
  51.  Das Device wird angehalten. Durch CMD_START kann das Device wieder aktiviert
  52.  werden.
  53.  
  54. CMD_START
  55.  siehe CMD_STOP
  56.  
  57. CMD_FLUSH
  58.  Alle noch ausstehenden IOs werden abgebrochen und als IOERR_Aborted gekennzeichnet.
  59.  Nur der aktuell bearbeitete IO ist nicht betroffen und wird normal weiterbearbeitet.
  60.  
  61. CMD_NONSTD
  62.  Platzhalter, ab dieser Position können device-eigene Kommandos folgen.
  63.  
  64.  
  65.  
  66. Jeder Aufruf von pOS_DoIO, pOS_SendIO, pOS_BeginIO, pOS_WaitIO löscht und setzt
  67. den neuen io_Error. Die restlichen Device-IO-Funktionen verändert den io_Error
  68. nicht direkt. Es ist aber denkbar, daß parallel zum Anwender-Task der io_Error
  69. verändert wird. Deshalb darf der io_Error erst nach Vollendung des IO's ausgelesen
  70. werden.
  71. Das pOS definiert in io_Error Standard-Errors mit <0, wie folgt:
  72.  (enum pOS_IOReqErrors) : io_Error
  73.  
  74. IOERR_None = 0
  75.  Es liegt kein Fehler vor.
  76.  
  77. IOERR_OpenFail
  78.  pOS_OpenDevice ist fehlgeschlagen. Der 'Error' wird in io_Error gesetzt und
  79.  von pOS_OpenDevice zurückgegeben.
  80.  
  81. IOERR_Aborted
  82.  Der IO wurde durch pOS_AbortIO oder durch CMD_RESET, CMD_FLUSH vorzeitig
  83.  abgebrochen. Die Grunddefinition besagt, daß io_Actual immer den aktuell
  84.  gültigen Bearbeitungs-Stand anzeigt. Hieraus darf aber beim Abort nicht
  85.  auf eine eventuelle Teilbearbeitung geschlossen werden.
  86.  
  87. IOERR_NoCMD
  88.  Das Kommando io_Command ist dem Device nicht bekannt.
  89.  
  90. IOERR_BadLength
  91.  Die Bearbeitungslänge io_Length ist falsch.
  92.  
  93. IOERR_BadAddress
  94.  Die Pufferadresse io_Data ist falsch.
  95.  
  96. IOERR_UnitBusy
  97.  Kann eine Unit nicht ge-shared geöffnet werden, wird bei jedem
  98.  weiteren pOS_OpenDevice dieser Fehler gesetzt.
  99.  Z.B. "pserial.device"
  100.  
  101. IOERR_Selftest
  102.  Hardware führt zur Zeit einen Selbsttest durch.
  103.  
  104. IOERR_NoMem
  105.  Allgemeiner Speichermangel.
  106.  
  107. IOERR_NoSubCMD
  108.  Unbekanntes Unterkommando.
  109.  
  110.  
  111. Im pOS sind folgende Device-Funktionen implementiert:
  112.  
  113. pOS_OpenDevice
  114.  Device öffnen. Bevor ein Device eingesetzt werden kann, muß es geöffnet
  115.  und auf einen IO 'eingebrant' werden. Ein Fehler kann in io_Error
  116.  ausgelesen werden.
  117.  
  118. pOS_CloseDevice
  119.  Konnte ein Device mittels pOS_OpenDevice erfolgreich geöffnet werden, so
  120.  muß es am Ende wieder geschlossen werden.
  121.  
  122. pOS_DoIO
  123.  Das io_Command wird synchron ausgeführt und ein eventuell aufgetretener
  124.  Error kann in io_Error ausgelesen werden. Vor dem Start wird immer das
  125.  IOREQF_Quick-Flag gelöscht.
  126.  
  127. pOS_SendIO
  128.  Wie pOS_DoIO, jedoch wird das Kommando asynchron zum Anwenderprogramm ausgeführt.
  129.  Vor dem Start wird immer das IOREQF_Quick-Flag gesetzt.
  130.  Jeder asynchrone IO MUSS mit pOS_WaitIO bzw. pOS_GetMsg vom ReplyPort
  131.  entfert werden.
  132.  
  133. pOS_BeginIO
  134.  Wie pOS_SendIO, aber das IOREQF_Quick-Flag wird nicht verändert.
  135.  
  136. pOS_AbortIO
  137.  Ein asynchroner IO wird abgebrochen. Ist der IO zum Zeitpunkt vom Aufruf von
  138.  pOS_AbortIO bereits vollendet, so ist der Abort wirkungslos. Wurde ein IO
  139.  abgebrochen, muß wie im Normalfall pOS_WaitIO bzw. GetMsg verwendet werden.
  140.  Der Abort modifiziert io_Error.
  141.  pOS_Abort darf nur zwischen pOS_SendIO/pOS_BeginIO und pOS_WaitIO eingesetzt
  142.  werden.
  143.  
  144. pOS_CheckIO
  145.  Prüft, ob der IO bereits vollendet ist. pOS_CheckIO liefert nur nach
  146.  pOS_SendIO/pOS_BeginIO und vor pOS_WaitIO einen sinnvollen Status.
  147.  
  148. pOS_WaitIO
  149.  Wartet bis der IO vollendet ist bzw. entfernt den IO vom ReplyPort.
  150.  
  151.  
  152. Wie wird ein Device verwendet:
  153. ------------------------------
  154.  
  155. {
  156.   pOS_MsgPort  ReplyPort;
  157.   pOS_SerialIO *IO;
  158.  
  159. /*\
  160. *** Zur Intertask-Kommunikation mit dem Device wird ein MsgPort benötigt.
  161. *** Alle IOs werden nach Vollendung bzw. nach Abort an den ReplyPort gesendet.
  162. \*/
  163.   pOS_ConstructMsgPort(&ReplyPort);
  164.  
  165. /*\
  166. *** Die eigentliche Kommunikation erfolgt über die IORequest-Stuktur, die
  167. *** oft als 'IO' bezeichnet wird. Das Device setzt seine privaten Daten
  168. *** in pOS_OpenDevice und aktuallisiert den IO bei der Bearbeitung.
  169. \*/
  170.   IO=(pOS_SerialIO*)pOS_CreateIORequest(&ReplyPort,sizeof(pOS_SerialIO));
  171.   if(IO) {
  172.  
  173. /*\
  174. *** Das Device wird geöffnet und auf die IO-Struktur 'eingebrant'.
  175. *** Sollte der Vorgang fehlschlagen, liefert pOS_OpenDevice den Error
  176. *** zurück.
  177. \*/
  178.     if(0==pOS_OpenDevice("pserial.device",0,(pOS_IORequest*)IO,0,0)) {
  179.  
  180. /*\
  181. *** Das "pserial.device" soll eine Zeichenkette schreiben. Die pOS_DoIO-Funktion
  182. *** führt das Schreibkommando synchron aus und meldet uns einen eventuellen
  183. *** Fehler zurück.
  184. \*/
  185.       IO->sio_Command=CMD_WRITE;
  186.       IO->sio_Data=(APTR)"12345";
  187.       IO->sio_Length=5;
  188.       if(0==pOS_DoIO((pOS_IORequest*)IO)) printf("ok\n");
  189.       else printf("Cannot CMD_WRITE, error=%ld\n",IO->sio_Error);
  190.  
  191. /*\
  192. *** Nach vollbrachter Arbeit muß das Device unbedingt wieder geschlossen werden.
  193. \*/
  194.       pOS_CloseDevice((pOS_IORequest*)IO);
  195.     }
  196.     else printf("Cannot open device, error=%ld\n",IO->sio_Error);
  197.  
  198. /*\
  199. *** Der IO-Speicher wird freigegeben.
  200. \*/
  201.     pOS_DeleteIORequest((pOS_IORequest*)IO);
  202.   }
  203.   else printf("no mem\n");
  204.  
  205. /*\
  206. *** Das mp_SigBit wird freigegeben.
  207. \*/
  208.   pOS_DestructMsgPort(&ReplyPort);
  209. }
  210.  
  211.  
  212. Einfache asynchrone Device-Kommunikation:
  213. ------------------------------------------
  214.  
  215. {
  216.   ...
  217.   IO->sio_Command=CMD_WRITE;
  218.   IO->sio_Data=(APTR)"12345";
  219.   IO->sio_Length=5;
  220.  
  221. /*\
  222. *** Starten der asynchronen Device-Bearbeitung.
  223. \*/
  224.   pOS_SendIO((pOS_IORequest*)IO);
  225.   ...
  226.   ... asynhrone Aktion
  227.   ...
  228.  
  229. /*\
  230. *** Zwischen pOS_SendIO und pOS_WaitIO darf die IO nicht verändert werden !!!
  231. ***
  232. *** Warten, bis das Device seine Bearbeitung vollendet hat.
  233. \*/
  234.   pOS_WaitIO((pOS_IORequest*)IO);
  235.   if(IO->sio_Error != IOERR_None) ...
  236.   ...
  237. }
  238.  
  239.  
  240.  
  241.  
  242. Erweiterte asynchrone Device-Kommunikation:
  243. ------------------------------------------
  244.  
  245. {
  246.   ...
  247.   IO->sio_Command=CMD_WRITE;
  248.   IO->sio_Data=(APTR)"12345";
  249.   IO->sio_Length=5;
  250.  
  251. /*\
  252. *** Starten der asynchronen Device-Bearbeitung.
  253. \*/
  254.   pOS_SendIO((pOS_IORequest*)IO);
  255.   ...
  256.   ... asynhrone Aktion
  257.   ...
  258.  
  259. /*\
  260. *** Abbrechen einer Device-Bearbeitung. Der folgende pOS_WaitIO
  261. *** MUSS unbedingt aufgerufen werden.
  262. \*/
  263.   if(...) pOS_AbortIO((pOS_IORequest*)IO);
  264.  
  265.  
  266. /*\
  267. *** Zwischen pOS_SendIO und pOS_WaitIO darf die IO nicht verändert werden !!!
  268. ***
  269. *** Warten, bis das Device seine Bearbeitung vollendet hat.
  270. \*/
  271.   pOS_WaitIO((pOS_IORequest*)IO);
  272.   if(IO->sio_Error != IOERR_None) ...
  273.   ...
  274. }
  275.  
  276. ©proDAD
  277.