home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 420.lha / Example_device / Ex_Main.asm < prev    next >
Assembly Source File  |  1990-09-29  |  14KB  |  251 lines
  1. ;*********************************************************************
  2. ;*                       Origin and Purpose                          *
  3. ;*                                                                   *
  4. ;* This device represents things I would liked to have known when    *
  5. ;* starting out writing devices.  I found it hard to get firm data   *
  6. ;* on device design, and collected everything I could find into this *
  7. ;* file.  Sure it has lots of comments, but it makes a great basic   *
  8. ;* skeleton or classroom presentation.                               *
  9. ;*                                                                   *
  10. ;* I apologize in advance for any bugs, oversights or errors.  As    *
  11. ;* always, corrections and design tips are welcome.                  *
  12. ;*                                                                   *
  13. ;* Send comments, flames, etc. to the following:                     *
  14. ;*                                                                   *
  15. ;*                             Tau Productions                       *
  16. ;*                             Jeff Rush                             *
  17. ;*                             BIX: jrush                            *
  18. ;*                             BBS: (214) 231-1372 Rising Star       *
  19. ;*                             Fidonet: 1:124/4206 (Dallas, Tx)      *
  20. ;*                                                                   *
  21. ;* All changes I made are hereby in the Public Domain.  Commodore    *
  22. ;* retains its copyright, if any, of the original code in the Rom    *
  23. ;* Kernel manuals since this is a derivative work.  -Jeff Rush       *
  24. ;*                                                                   *
  25. ;*********************************************************************
  26. ;*                           History                                 *
  27. ;*                                                                   *
  28. ;* 20Sep89 jrr Original crib from Amiga Rom Kernel Manual.           *
  29. ;* 23Jul90 jrr Extensive descriptive prose added.                    *
  30. ;*                                                                   *
  31. ;*********************************************************************
  32.         TITLE   Example Device Driver for Tutorial Use
  33.         SMALLOBJ    ; Use PC-Relative Addressing
  34.         OPTIMON     ; Enable C.A.P.E. 68K Optimizations
  35.  
  36.         SECTION TheOnlySection
  37.  
  38.         ;************
  39.         ;* Includes *
  40.         ;************
  41.         NOLIST
  42.         INCLUDE "exec/types.i"
  43.         INCLUDE "exec/devices.i"
  44.         INCLUDE "exec/initializers.i"
  45.         INCLUDE "exec/memory.i"
  46.         INCLUDE "exec/resident.i"
  47.         INCLUDE "exec/io.i"
  48.         INCLUDE "exec/ables.i"
  49.         INCLUDE "exec/errors.i"
  50.         INCLUDE "exec/tasks.i"
  51.         INCLUDE "exec/semaphores.i"
  52.         INCLUDE "hardware/intbits.i"
  53.  
  54.         INCLUDE "asmsupp.i"
  55.  
  56.         INCLUDE "Example.i"     ; Device-Specific Definitions
  57.         LIST
  58.  
  59.         ;*************
  60.         ;* Constants *
  61.         ;*************
  62. VERSION     EQU 1       ; Version of This Device
  63. REVISION    EQU 1       ; Revision of This Device
  64.  
  65.         ;******************
  66.         ;* Public Symbols *
  67.         ;******************
  68.         ; This Name is for Debugging Use, to Annotate Serial-Debug Output
  69.         IFNE    INFO_LEVEL      ; If Any Debugging Enabled at All
  70.         XDEF    subSysName
  71.         ENDC
  72.  
  73.         XDEF    CmdTable    ; Device Global Command Dispatch Table
  74.         XDEF    MyName      ; Name of This Device (for Tagging Ports and Tasks)
  75.  
  76.         ;********************
  77.         ;* External Symbols *
  78.         ;********************
  79.  
  80.         ; Defined in Ex_Support.Asm
  81.         XREF    EndCode         ; Label at End of Device Code
  82.  
  83.         ; Defined in Ex_EntryPts.Asm
  84.         XREF    LoadInitRoutine ; Initialization when Device First Loads into Memory
  85.         XREF    DevOpen         ; Unit Allocation for Each Time Device is Opened
  86.         XREF    DevClose        ; Unit Deallocation for Each Time Device is Opened
  87.         XREF    DevExpunge      ; Remove Device from Memory if No One is Using It
  88.         XREF    DevNull         ; Reserved for Future Expansion
  89.         XREF    DevBeginIO      ; Initiate an I/O Request either Now or Put in Queue
  90.         XREF    DevAbortIO      ; Abort an I/O Request either Active or in Queue
  91.  
  92.         ; Defined in Ex_StdCmds.Asm
  93.         XREF    CmdInvalid      ; Handle an Unknown or Out-of-Range Command
  94.         XREF    CmdReset        ; Reset the Device
  95.         XREF    CmdRead         ; Read Data from the Device for Caller
  96.         XREF    CmdWrite        ; Write Data into the Device from Caller
  97.         XREF    CmdUpdate       ; Force Outbound Data from Caches onto Device
  98.         XREF    CmdClear        ; Discard All Pending Unread Data inside Device
  99.         XREF    CmdStop         ; Suspend Device Operations
  100.         XREF    CmdStart        ; Resume Device Operations
  101.         XREF    CmdFlush        ; Discard All Queued but Unprocessed I/O Requests
  102.  
  103. ;*********************************************************************
  104. ;*                    First Executable Location                      *
  105. ;*********************************************************************
  106.         MOVEQ   #-1,D0  ; Return Failure Result Code
  107.         RTS             ; (In case user tried to execute us as a program)
  108.  
  109. ;*********************************************************************
  110. ;*                        ROMTAG Structure                           *
  111. ;*                                                                   *
  112. ;* This ROMTAG is used by Exec to construct a device node in memory  *
  113. ;* when the device code is loaded.  The setup sequence appears to be *
  114. ;* as follows: (Assuming a standard AUTOINIT-flag environment)       *
  115. ;*                                                                   *
  116. ;*  1) Exec receives a request to open a device.                     *
  117. ;*  2) Exec realizes it is not in memory at this time.               *
  118. ;*  3) Exec locates it on disk in the global directory DEVS:.        *
  119. ;*  4) Exec scatter-loads it into memory as a Segment List (seglist) *
  120. ;*  5) Exec scans the first hunk loaded for a ROMTAG signature and   *
  121. ;*     invokes an InitResident() Exec function on it. InitResident() *
  122. ;*     performs steps 6, 7 and 8 below.                              *
  123. ;*  6) Exec examines the Initialization Table pointed to in the      *
  124. ;*     ROMTAG and allocates a device node structure of the correct   *
  125. ;*     size in memory.  This is performed by the Exec function       *
  126. ;*     MakeLibrary() which also performs step 7 below.               *
  127. ;*  7) Continuing to use the Initialization Table, Exec then         *
  128. ;*     a) copies the function vector table into the device node,     *
  129. ;*        using MakeFunctions().                                     *
  130. ;*     b) initializes the device's global data space according       *
  131. ;*        to the INITSTRUCTs detailed in the DataTable, using the    *
  132. ;*        function InitStruct().                                     *
  133. ;*     c) calls the loadtime initialization code (if the code ptr is *
  134. ;*        non-NULL).                                                 *
  135. ;*  8) If the loadtime initialization code returns a zero (NULL) in  *
  136. ;*     D0, Exec  unloads the device and fails the caller's original  *
  137. ;*     open request.  Otherwise the loadtime initialization code     *
  138. ;*     returns the address of the device node structure.             *
  139. ;*  9) Exec then links the device node into the global system list   *
  140. ;*     of known Exec devices.                                        *
  141. ;* 10) Lastly, Exec invokes the device's open routine using the      *
  142. ;*     vector table setup earlier in the device node.                *
  143. ;*                                                                   *
  144. ;* In the case of an OpenDevice() request where the device is        *
  145. ;* already in memory, either because someone else has it open or     *
  146. ;* because someone used it recently, only step 10 above is executed. *
  147. ;*                                                                   *
  148. ;* High Memory                                                       *
  149. ;*                 +-----------------------------------+             *
  150. ;*                 | Device's Global Data Area         |             *
  151. ;*                 | (Contents specific to device)     |             *
  152. ;*                 +-----------------------------------+             *
  153. ;*  Device Ptr ===>| Library Node Structure:           |             *
  154. ;*                 |   Version, Revision               |             *
  155. ;*                 |   Various Flags                   |             *
  156. ;*                 |   NegSize                         |             *
  157. ;*                 |   PosSize                         |             *
  158. ;*                 |   IdString                        |             *
  159. ;*                 |   OpenCnt                         |             *
  160. ;*                 +-----------------------------------+             *
  161. ;*                 | Vector (Jump) Table:              |             *
  162. ;*                 |   OPEN     (Device Ptr Offset -6) |             *
  163. ;*                 |   CLOSE    (  "     "    "   -12) |             *
  164. ;*                 |   EXPUNGE  (  "     "    "   -18) |             *
  165. ;*                 |   NULLFUNC (  "     "    "   -24) |             *
  166. ;*                 |   BEGINIO  (  "     "    "   -30) |             *
  167. ;*                 |   ABORTIO  (  "     "    "   -36) |             *
  168. ;*                 +-----------------------------------+             *
  169. ;* Low Memory                                                        *
  170. ;*********************************************************************
  171. MyRomTag:
  172.         DC.W    RTC_MATCHWORD   ; UWORD RT_MATCHWORD (Signature)
  173.         DC.L    MyRomTag        ; APTR  RT_MATCHTAG  (Back Ptr to Myself)
  174.         DC.L    EndCode         ; APTR  RT_ENDSKIP   (Ptr to End of This Hunk)
  175.         DC.B    RTF_AUTOINIT    ; UBYTE RT_FLAGS     (Flags)
  176.         DC.B    VERSION         ; UBYTE RT_VERSION   (Major Version#)
  177.         DC.B    NT_DEVICE       ; UBYTE RT_TYPE      (Type of Module)
  178.         DC.B    0               ; BYTE  RT_PRI       (Initialization Priority)
  179.         DC.L    MyName          ; APTR  RT_NAME      (Ptr to Node Name)
  180.         DC.L    MyID            ; APTR  RT_IDSTRING  (Ptr to ID String)
  181.         DC.L    InitTable       ; APTR  RT_INIT      (Ptr to Initialization Table)
  182.  
  183.         ; This Name is for Debugging Use, to Annotate Serial-Debug Output
  184.         IFNE    INFO_LEVEL  ;If any debugging enabled at all
  185. subSysName:
  186.         DC.B    'Example',0
  187.         ENDC
  188.  
  189. MyID:   DC.B    'Example 1.2 (25 Jul 1990)',13,10,0
  190.  
  191. MyName: DC.B    'Example.device',0                  ; Name of My Device
  192.  
  193.         ;*****************************************************************
  194.         ;* The Romtag specified above states that we were RTF_AUTOINIT.  *
  195.         ;* This means that the RT_INIT structure member points to one of *
  196.         ;* these tables below.  If the AUTOINIT bit was not set then     *
  197.         ;* RT_INIT would point to a routine to run.                      *
  198.         ;*****************************************************************
  199.         CNOP    0,4               ; Force Long Word Alignment
  200. InitTable:
  201.         DC.L    MyDev_Sizeof      ; Size of My Device's Global Data Space
  202.         DC.L    CodeTable         ; Ptr to Table of Function Vectors
  203.         DC.L    DataTable         ; Ptr to Table of Data Initializers
  204.         DC.L    LoadInitRoutine   ; Loadtime Initialization Routine to Execute
  205.  
  206. CodeTable:      ; These Function Pointers are Order-Dependent
  207.         DC.L    DevOpen           ; Open a Unit of the Device
  208.         DC.L    DevClose          ; Close a Unit of the Device
  209.         DC.L    DevExpunge        ; Expunge (Remove from Memory) the Device
  210.         DC.L    DevNull           ; Reserved¨for Future Use
  211.         DC.L    DevBeginIO        ; Begin (either now or put in queue) an I/O Request
  212.         DC.L    DevAbortIO        ; Abort an Existing I/O Request
  213.         DC.L    -1                ; End of Table
  214.  
  215.         ;***********************************************************************
  216.         ;* The data table initializes static data structures. The format is    *
  217.         ;* specified in exec/InitStruct routine's manual pages.  The INITBYTE/ *
  218.         ;* INITWORD/INITLONG macros are in the file "exec/initializers.i". The *
  219.         ;* first argument is the offset from the device base for this byte/    *
  220.         ;* word/long. The second argument is the value to put in that cell.    *
  221.         ;***********************************************************************
  222.         CNOP    0,4               ; Force Long Word Alignment
  223. DataTable:
  224.         INITBYTE   LN_TYPE,NT_DEVICE        ; Set Node Type to 'Device'
  225.         INITLONG   LN_NAME,MyName           ; Set Node Name Ptr to My Name
  226.         INITBYTE   LIB_FLAGS,LIBF_SUMUSED!LIBF_CHANGED
  227.         INITWORD   LIB_VERSION,VERSION      ; Set Device Major Version
  228.         INITWORD   LIB_REVISION,REVISION    ; Set Device Minor Version
  229.         INITLONG   LIB_IDSTRING,MyID        ; Set ID String Ptr to My ID
  230.         DC.L       0                        ; End of Table
  231.  
  232.         ;******************************************
  233.         ;* Device-Specific Command Dispatch Table *
  234.         ;******************************************
  235. CmdTable:
  236.         DC.L    CmdInvalid    ;$00000001  ;0  CMD_INVALID     Signal Invalid Command
  237.         DC.L    CmdReset      ;$00000002  ;1  CMD_RESET       Reset Device to Initialized State
  238.         DC.L    CmdRead       ;$00000004  ;2  CMD_READ        Read Data from Device
  239.         DC.L    CmdWrite      ;$00000008  ;3  CMD_WRITE       Write Data to Device
  240.         DC.L    CmdUpdate     ;$00000010  ;4  CMD_UPDATE      Flush Device Caches Out
  241.         DC.L    CmdClear      ;$00000020  ;5  CMD_CLEAR       Discard Queued Input Data
  242.         DC.L    CmdStop       ;$00000040  ;6  CMD_STOP        Restart Device Operations
  243.         DC.L    CmdStart      ;$00000080  ;7  CMD_START       Suspend Device Operations
  244.         DC.L    CmdFlush      ;$00000100  ;8  CMD_FLUSH       Discard Queued Write Requests
  245.  
  246. ;*********************************************************************
  247. ;*                                                                   *
  248. ;*********************************************************************
  249.         END
  250.  
  251.