spbhost.h 6.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358
  1. /*++
  2. Copyright (c) 2015 Minoca Corp.
  3. This file is licensed under the terms of the GNU General Public License
  4. version 3. Alternative licensing terms are available. Contact
  5. info@minocacorp.com for details. See the LICENSE file at the root of this
  6. project for complete licensing information.
  7. Module Name:
  8. spbhost.h
  9. Abstract:
  10. This header contains definitions for creating and managing Simple
  11. Peripheral Bus controllers.
  12. Author:
  13. Evan Green 14-Aug-2015
  14. --*/
  15. //
  16. // ------------------------------------------------------------------- Includes
  17. //
  18. #include <minoca/spb/spb.h>
  19. //
  20. // ---------------------------------------------------------------- Definitions
  21. //
  22. #ifndef SPB_API
  23. #define SPB_API __DLLIMPORT
  24. #endif
  25. #define SPB_CONTROLLER_INFORMATION_VERSION 1
  26. //
  27. // ------------------------------------------------------ Data Type Definitions
  28. //
  29. typedef struct _SPB_CONTROLLER SPB_CONTROLLER, *PSPB_CONTROLLER;
  30. typedef
  31. KSTATUS
  32. (*PSPB_HOST_CONFIGURE) (
  33. PVOID Context,
  34. PRESOURCE_SPB_DATA Configuration
  35. );
  36. /*++
  37. Routine Description:
  38. This routine configures the given Simple Peripheral Bus controller.
  39. Arguments:
  40. Context - Supplies the host controller context.
  41. Configuration - Supplies a pointer to the new configuration to set.
  42. Return Value:
  43. Status code.
  44. --*/
  45. typedef
  46. KSTATUS
  47. (*PSPB_HOST_SUBMIT_TRANSFER) (
  48. PVOID Context,
  49. PSPB_TRANSFER Transfer
  50. );
  51. /*++
  52. Routine Description:
  53. This routine is called to execute a single transfer on the Simple
  54. Peripheral Bus. The host controller is responsible for implementing the
  55. delay set in the transfer.
  56. Arguments:
  57. Context - Supplies the host controller context.
  58. Transfer - Supplies a pointer to the transfer to begin executing. The
  59. controller can return immediately, and should call
  60. SpbProcessCompletedTransfer when the transfer completes.
  61. Return Value:
  62. Status code indicating whether or not the transfer was successfully
  63. started.
  64. --*/
  65. typedef
  66. VOID
  67. (*PSPB_HOST_LOCK_BUS) (
  68. PVOID Context,
  69. PRESOURCE_SPB_DATA Configuration
  70. );
  71. /*++
  72. Routine Description:
  73. This routine is called when the bus is being locked for a particular
  74. transfer set or directly via the interface. The software synchronization
  75. portion of locking the bus is handled by the SPB library, this routine
  76. only needs to do hardware-specific actions (like selecting or deselecting
  77. device lines).
  78. Arguments:
  79. Context - Supplies the host controller context.
  80. Configuration - Supplies a pointer to the configuration of the handle that
  81. locked this bus. The configure bus function will still be called, this
  82. is only passed for reference if bus-specific actions need to be
  83. performed (like selecting or deselecting the device).
  84. Return Value:
  85. None.
  86. --*/
  87. typedef
  88. VOID
  89. (*PSPB_HOST_UNLOCK_BUS) (
  90. PVOID Context
  91. );
  92. /*++
  93. Routine Description:
  94. This routine is called when the bus is being unlocked.
  95. Arguments:
  96. Context - Supplies the host controller context.
  97. Return Value:
  98. None.
  99. --*/
  100. /*++
  101. Structure Description:
  102. This structure stores the set of Simple Peripheral Bus controller functions
  103. called by the SPB library.
  104. Members:
  105. Configure - Stores a pointer to a function used to set the current bus
  106. parameters.
  107. SubmitTransfer - Stores a pointer to a function used to begin a new
  108. transfer.
  109. LockBus - Stores an optional pointer to a function that is called when the
  110. bus is being locked.
  111. UnlockBus - Stores an optional pointer to a function that is called when
  112. the bus is being unlocked.
  113. --*/
  114. typedef struct _SPB_FUNCTION_TABLE {
  115. PSPB_HOST_CONFIGURE Configure;
  116. PSPB_HOST_SUBMIT_TRANSFER SubmitTransfer;
  117. PSPB_HOST_LOCK_BUS LockBus;
  118. PSPB_HOST_UNLOCK_BUS UnlockBus;
  119. } SPB_FUNCTION_TABLE, *PSPB_FUNCTION_TABLE;
  120. /*++
  121. Structure Description:
  122. This structure defines the information provided to the SPB library by a
  123. Simple Peripheral Bus controller.
  124. Members:
  125. Version - Stores the value SPB_CONTROLLER_INFORMATION_VERSION, used to
  126. enable future expansion of this structure.
  127. Context - Stores an opaque context pointer that is passed to the SPB
  128. controller functions.
  129. Device - Stores a pointer to the OS device associated with this controller.
  130. MaxFrequency - Stores the maximum bus clock frequency.
  131. BusType - Stores the bus type for this controller.
  132. Features - Stores a bitfield of features about this controller. See
  133. SPB_FEATURE_* definitions.
  134. FunctionTable - Stores the table of functions the library uses to call back
  135. into the controller.
  136. --*/
  137. typedef struct _SPB_CONTROLLER_INFORMATION {
  138. ULONG Version;
  139. PVOID Context;
  140. PDEVICE Device;
  141. ULONG MaxFrequency;
  142. RESOURCE_SPB_BUS_TYPE BusType;
  143. ULONG Features;
  144. SPB_FUNCTION_TABLE FunctionTable;
  145. } SPB_CONTROLLER_INFORMATION, *PSPB_CONTROLLER_INFORMATION;
  146. //
  147. // -------------------------------------------------------------------- Globals
  148. //
  149. //
  150. // -------------------------------------------------------- Function Prototypes
  151. //
  152. SPB_API
  153. KSTATUS
  154. SpbCreateController (
  155. PSPB_CONTROLLER_INFORMATION Registration,
  156. PSPB_CONTROLLER *Controller
  157. );
  158. /*++
  159. Routine Description:
  160. This routine creates a new Simple Peripheral Bus controller.
  161. Arguments:
  162. Registration - Supplies a pointer to the host registration information.
  163. Controller - Supplies a pointer where a pointer to the new controller will
  164. be returned on success.
  165. Return Value:
  166. Status code.
  167. --*/
  168. SPB_API
  169. VOID
  170. SpbDestroyController (
  171. PSPB_CONTROLLER Controller
  172. );
  173. /*++
  174. Routine Description:
  175. This routine destroys a Simple Peripheral Bus controller.
  176. Arguments:
  177. Controller - Supplies a pointer to the controller to tear down.
  178. Return Value:
  179. None.
  180. --*/
  181. SPB_API
  182. KSTATUS
  183. SpbStartController (
  184. PSPB_CONTROLLER Controller
  185. );
  186. /*++
  187. Routine Description:
  188. This routine starts a Simple Peripheral Bus controller.
  189. Arguments:
  190. Controller - Supplies a pointer to the controller.
  191. Return Value:
  192. Status code.
  193. --*/
  194. SPB_API
  195. VOID
  196. SpbStopController (
  197. PSPB_CONTROLLER Controller
  198. );
  199. /*++
  200. Routine Description:
  201. This routine stops a Simple Peripheral Bus controller.
  202. Arguments:
  203. Controller - Supplies a pointer to the controller.
  204. Return Value:
  205. None.
  206. --*/
  207. SPB_API
  208. PSPB_TRANSFER
  209. SpbTransferCompletion (
  210. PSPB_CONTROLLER Controller,
  211. PSPB_TRANSFER Transfer,
  212. KSTATUS Status
  213. );
  214. /*++
  215. Routine Description:
  216. This routine is called by an SPB host controller when a transfer has
  217. completed.
  218. Arguments:
  219. Controller - Supplies a pointer to the controller.
  220. Transfer - Supplies a pointer to the transfer that completed.
  221. Status - Supplies the status code the transfer completed with.
  222. Return Value:
  223. Returns a new transfer to begin executing if there are additional transfers
  224. in this set and the previous transfer completed successfully.
  225. NULL if no new transfers should be started at this time.
  226. --*/