home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 420.lha / Example_device / Example.doc.pp / Example.doc
Encoding:
Text File  |  1990-10-05  |  13.9 KB  |  202 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.                   *
  24. ;*                                                                   *
  25. ;*********************************************************************
  26. ;*                           History                                 *
  27. ;*                                                                   *
  28. ;* 20Sep89 jrr Original crib from Amiga Rom Kernel Manual.           *
  29. ;* 23Jul90 jrr Extensive descriptive prose added.                    *
  30. ;* 10Sep90 jrr Uploaded to BIX and made available on my BBS.         *
  31. ;*                                                                   *
  32. ;*********************************************************************
  33. ;*          Whats Different from the Rom Kernel Example              *
  34. ;*                                                                   *
  35. ;* The following Exec device represents a very simple skeleton for   *
  36. ;* use as a starting point for authors.  It was derived from the     *
  37. ;* sample device in the Amiga ROM Kernel: Includes & Autodocs, but   *
  38. ;* has had documentation and folklore from various places folded     *
  39. ;* into the comments in order to explain some of the 'magic'.        *
  40. ;*                                                                   *
  41. ;* For simplicity, the following components of the original example  *
  42. ;* have been stripped out:                                           *
  43. ;*   o Automount at Autoconfig time when a matching board is found   *
  44. ;*   o Hardware interrupt fielding support                           *
  45. ;*   o AmigaDOS volume/device support                                *
  46. ;*                                                                   *
  47. ;* I also stripped out all code that make this device implement a    *
  48. ;* ram disk.  I found the assumption that the device was a disk      *
  49. ;* tended to bias the structure away from a character device a bit.  *
  50. ;* I hope I made it more generic, albeit less practical.  This code  *
  51. ;* implements a null device that does nothing except go through the  *
  52. ;* motions.                                                          *
  53. ;*                                                                   *
  54. ;* I added code to implement a signal semaphore to arbitrate access  *
  55. ;* to the device's internal global data.  I would like to add code   *
  56. ;* to make the unit task a full process so that it can perform DOS   *
  57. ;* operations if needed in a real design, but have not yet done so.  *
  58. ;*                                                                   *
  59. ;*********************************************************************
  60. ;*                   Exec-Style Device Skeleton                      *
  61. ;*                                                                   *
  62. ;* What is a Device?                                                 *
  63. ;*                                                                   *
  64. ;* An Exec-style device is a logical abstraction of standard and     *
  65. ;* custom functions used to manage a piece of either real or         *
  66. ;* simulated hardware.  The term 'device' in this file refers to the *
  67. ;* abstraction as represented by this software, not the hardware     *
  68. ;* itself.  A device is an Exec shared library that by convention    *
  69. ;* a few extra function vectors that caller's can utilize for        *
  70. ;* control.  Except for this and the fact that the code resides in a *
  71. ;* different directory, it -is- a shared library.  By convention a   *
  72. ;* device can spin off background tasks to handle work, but shared   *
  73. ;* libraries are capable of this too, they just tend not to.  So a   *
  74. ;* 'static' library or passive piece of code is what we call a       *
  75. ;* library, and a 'dynamic' library or active piece of code with a   *
  76. ;* life of its own we call a device.                                 *
  77. ;*                                                                   *
  78. ;* For those with IBM-PC backgrounds, an Exec-style device can       *
  79. ;* functionally be thought of as a BIOS rom.  Although BIOS roms do  *
  80. ;* not act as independent tasks, the low-level nature of the BIOS    *
  81. ;* interface is similar to a device.  You wouldn't think of using    *
  82. ;* the PCDOS Copy command to send a file to the screen using INT 10H *
  83. ;* (Video), and AmigaDOS commands cannot necessarily be used to talk *
  84. ;* to Exec devices directly.                                         *
  85. ;*                                                                   *
  86. ;* A device can be activated in one of three ways.                   *
  87. ;*                                                                   *
  88. ;* a) It can auto-mounted by the BindDrivers AmigaDOS command in     *
  89. ;*    response to the presence of a piece of vendor hardware.  It is *
  90. ;*    matched up with the hardware by checking the autoconfigure     *
  91. ;*    manufacturer ID built into the hardware with the product code  *
  92. ;*    within the tooltype of a icon in the expansion directory.  The *
  93. ;*    icon is for the file containing the device code.               *
  94. ;*                                                                   *
  95. ;* b) It can be manually mounted by a user in response to the Mount  *
  96. ;*    AmigaDOS command.  This requires that an entry be defined in   *
  97. ;*    a 'mountlist' file defining the configuration of the device.   *
  98. ;*                                                                   *
  99. ;* c) It can be activated by an application calling the Exec routine *
  100. ;*    OpenDevice() for use within the application.                   *
  101. ;*                                                                   *
  102. ;* Method a) and b) above are typically used when AmigaDOS needs to  *
  103. ;* be made aware of the device, either as a logical name (PRT:) or   *
  104. ;* as a raw media on which a filesystem resides (DF0:).  Method c)   *
  105. ;* is used when AmigaDOS does not need to be aware of the device     *
  106. ;* and/or the device represents internal or low-level functionality, *
  107. ;* like a LAN adapter interface.                                     *
  108. ;*                                                                   *
  109. ;*********************************************************************
  110. ;*                     ! Obscure Bug Alert !                         *
  111. ;* You should be aware that there is a bug in the Exec v1.3 function *
  112. ;* MakeLibrary().  If the device name within the code is different   *
  113. ;* from the name used in the OpenDevice() call, either in case or    *
  114. ;* spelling, the device will be loaded into memory, the code for its *
  115. ;* initialization will be executed, and then Exec will deallocate    *
  116. ;* the device node *** while leaving the node linked into the system *
  117. ;* lists ***!!  This results in very strange system behavior and a   *
  118. ;* crash during an Expunge.  This is because AmigaDOS is             *
  119. ;* case-INsensitive, but Exec is case-sensitive.  Also, the name in  *
  120. ;* the OpenDevice() is used to locate the file to load, but the name *
  121. ;* inside the code is used to reference the device in memory.        *
  122. ;*                                                                   *
  123. ;* The moral: Insure device names match *exactly* in all cases.      *
  124. ;*                                                                   *
  125. ;*********************************************************************
  126. ;*     The Role and Importance of Single-Threading (Forbid'ing)      *
  127. ;*                                                                   *
  128. ;* At Load Initialization Time:                                      *
  129. ;*                                                                   *
  130. ;* During the setup of an Exec-style device, there is a window of    *
  131. ;* vulnerability due to the multitasking nature of the Amiga.  It is *
  132. ;* possible for two separate applications to attempt to open a       *
  133. ;* device concurrently.                                              *
  134. ;*                                                                   *
  135. ;* Application A issues an open request, whereupon AmigaDOS loads    *
  136. ;* the code into memory and executes the LoadInitRoutine function    *
  137. ;* within the device.  This function is single-threaded by Exec who  *
  138. ;* does a Forbid() before executing the device's LoadInitRoutine.    *
  139. ;* This is because the device node is not yet on the system list of  *
  140. ;* known devices and if a request from Application B came along,     *
  141. ;* there would now be two copies of the device in memory and trying  *
  142. ;* to initialize.                                                    *
  143. ;*                                                                   *
  144. ;* This means that the LoadInitRoutine should -not- break the        *
  145. ;* Forbid() by doing a Wait(), either directly or indirectly by      *
  146. ;* calling AmigaDOS or other functions that could do a Wait().  This *
  147. ;* means no OpenLibrary(), OpenDevice() or file operations.          *
  148. ;*                                                                   *
  149. ;* At Device Open Time:                                              *
  150. ;*                                                                   *
  151. ;* When the DevOpen entry point of the device is called by Exec,     *
  152. ;* either right after the code is loaded or on subsequent opens, the *
  153. ;* device node is on the system list of known devices.  This means   *
  154. ;* that there is no risk of Exec trying to load duplicate copies of  *
  155. ;* the device.  However, there is a risk of two tasks trying to      *
  156. ;* perform the open setup within DevOpen in the device at the same   *
  157. ;* time.  Depending upon the nature of the open setup code in your   *
  158. ;* device, this may be fine or dangerous.  For this reason Exec      *
  159. ;* single-threads device opens just as it does device initialization *
  160. ;* (as detailed above).  If your code does not need this protection, *
  161. ;* it may break the Forbid() to perform some special setup you need. *
  162. ;*                                                                   *
  163. ;* If by chance your device needs to break the Forbid() but still do *
  164. ;* its open setup in an exclusive fashion, there is a solution       *
  165. ;* (proposed by Bill Hawes on BIX in Amiga.Sw/Exec).  You define a   *
  166. ;* signal semaphore in your device global data and obtain a lock at  *
  167. ;* the start of your open setup.  This allows other tasks to run and *
  168. ;* yet single-threads your open setup code.                          *
  169. ;*                                                                   *
  170. ;* Also don't forget that if there is some operation that must be    *
  171. ;* performed on the first open of a device only and that cannot be   *
  172. ;* done at load initialization time, you can use the open count kept *
  173. ;* within the device node to detect the first open/last close.  You  *
  174. ;* should do this -after- locking your device semaphore to insure    *
  175. ;* you remain the first opener/last closer during the operation.     *
  176. ;*                                                                   *
  177. ;*********************************************************************
  178. ;*        The Ramifications of Being a Task Versus a Process         *
  179. ;*                                                                   *
  180. ;* An Exec-style device must never assume that its caller is a full  *
  181. ;* process and not a task.  Remember that tasks are scheduling       *
  182. ;* entities and cannot perform any DOS operations such as file opens *
  183. ;* or open libraries or devices which may indirectly do a file open. *
  184. ;* When a device is invoked via BeginIO(), AbortIO() or              *
  185. ;* CloseDevice(), the caller may quite likely be a task which means  *
  186. ;* you are restricted to things a task can do.  However, when the    *
  187. ;* device is servicing an OpenDevice(), it obviously is running in a *
  188. ;* process or the DOS call by Exec to open the device file and load  *
  189. ;* it would have failed.  This means that during opens, you may      *
  190. ;* perform DOS functions, although this assumption may yet be wrong. *
  191. ;*                                                                   *
  192. ;* In addition, the unit task created by a device to handle I/O      *
  193. ;* requests is typically a task.  This device contains additional    *
  194. ;* code to promote the unit task into a full process for maximum     *
  195. ;* flexibility.  This adds only a little code at open time and a     *
  196. ;* little larger task control block.  A process does -not- consume   *
  197. ;* more CPU time during execution than a task.  The Exec scheduler   *
  198. ;* treats them equally.                                              *
  199. ;*                                                                   *
  200. ;*********************************************************************
  201.  
  202.