src/include/bus.h

   1 /**
   2  * Copyright (C) 2009-2010, Shao Miller <shao.miller@yrdsb.edu.on.ca>.
   3  * Copyright 2006-2008, V.
   4  * For WinAoE contact information, see http://winaoe.org/
   5  *
   6  * This file is part of WinVBlock, derived from WinAoE.
   7  *
   8  * WinVBlock is free software: you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation, either version 3 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * WinVBlock is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with WinVBlock.  If not, see <http://www.gnu.org/licenses/>.
  20  */
  21 #ifndef WVL_M_BUS_H_
  22 #  define WVL_M_BUS_H_
  23
  24 /**
  25  * @file
  26  *
  27  * Bus specifics.
  28  */
  29
  30 /**
  31  * A bus thread routine.
  32  *
  33  * @v bus       The bus to be used in the thread routine.
  34  *
  35  * If you implement your own bus thread routine, you should call
  36  * WvBusProcessWorkItems() within its loop.
  37  */
  38 typedef void STDCALL WVL_F_BUS_THREAD(IN WV_SP_BUS_T);
  39 typedef WVL_F_BUS_THREAD * WVL_FP_BUS_THREAD;
  40
  41 /**
  42  * A bus PnP routine.
  43  *
  44  * @v bus               The bus to receive the PnP IRP.
  45  * @v irp               The IRP to process.
  46  * @ret NTSTATUS        The status of the operation.
  47  */
  48 typedef NTSTATUS STDCALL WV_F_BUS_PNP(IN WV_SP_BUS_T, IN PIRP);
  49 typedef WV_F_BUS_PNP * WV_FP_BUS_PNP;
  50
  51 /* Device state. */
  52 typedef enum WV_BUS_STATE {
  53     WvBusStateNotStarted,
  54     WvBusStateStarted,
  55     WvBusStateStopPending,
  56     WvBusStateStopped,
  57     WvBusStateRemovePending,
  58     WvBusStateSurpriseRemovePending,
  59     WvBusStateDeleted,
  60     WvBusStates
  61   } WV_E_BUS_STATE, * WV_EP_BUS_STATE;
  62
  63 /* The bus type. */
  64 typedef struct WV_BUS_T {
  65     PDEVICE_OBJECT LowerDeviceObject;
  66     PDEVICE_OBJECT Pdo;
  67     PDEVICE_OBJECT Fdo;
  68     winvblock__uint32 Children;
  69     WVL_FP_BUS_THREAD Thread;
  70     KEVENT ThreadSignal;
  71     winvblock__bool Stop;
  72     WV_E_BUS_STATE OldState;
  73     WV_E_BUS_STATE State;
  74     WV_FP_BUS_PNP QueryDevText;
  75     struct {
  76         LIST_ENTRY Nodes;
  77         USHORT NodeCount;
  78         LIST_ENTRY WorkItems;
  79         KSPIN_LOCK WorkItemsLock;
  80       } BusPrivate_;
  81   } WV_S_BUS_T, * WV_SP_BUS_T;
  82
  83 /* A child PDO node on a bus.  Treat this as an opaque type. */
  84 typedef struct WV_BUS_NODE {
  85     struct {
  86         LIST_ENTRY Link;
  87         PDEVICE_OBJECT Pdo;
  88         WV_SP_BUS_T Bus;
  89         /* The child's unit number relative to the parent bus. */
  90         winvblock__uint32 Num;
  91       } BusPrivate_;
  92   } WV_S_BUS_NODE, * WV_SP_BUS_NODE;
  93
  94 /**
  95  * A custom work-item function.
  96  *
  97  * @v context           Function-specific data.
  98  *
  99  * If a driver needs to enqueue a work item which should execute in the
 100  * context of the bus' controlling thread (this is the thread which calls
 101  * WvBusProcessWorkItems()), then this is the function prototype to be
 102  * used.
 103  */
 104 typedef void STDCALL WV_F_BUS_WORK_ITEM(void *);
 105 typedef WV_F_BUS_WORK_ITEM * WV_FP_BUS_WORK_ITEM;
 106 typedef struct WV_BUS_CUSTOM_WORK_ITEM {
 107     WV_FP_BUS_WORK_ITEM Func;
 108     void * Context;
 109   } WV_S_BUS_CUSTOM_WORK_ITEM, * WV_SP_BUS_CUSTOM_WORK_ITEM;
 110
 111 /* Exports. */
 112 extern winvblock__lib_func void WvBusInit(WV_SP_BUS_T);
 113 extern winvblock__lib_func WV_SP_BUS_T WvBusCreate(void);
 114 extern winvblock__lib_func void WvBusProcessWorkItems(WV_SP_BUS_T);
 115 extern winvblock__lib_func void WvBusCancelWorkItems(WV_SP_BUS_T);
 116 extern winvblock__lib_func NTSTATUS WvBusStartThread(
 117     IN WV_SP_BUS_T,
 118     OUT PETHREAD *
 119   );
 120 extern winvblock__lib_func winvblock__bool STDCALL WvBusInitNode(
 121     OUT WV_SP_BUS_NODE,
 122     IN PDEVICE_OBJECT
 123   );
 124 extern winvblock__lib_func NTSTATUS STDCALL WvBusAddNode(
 125     WV_SP_BUS_T,
 126     WV_SP_BUS_NODE
 127   );
 128 extern winvblock__lib_func NTSTATUS STDCALL WvBusRemoveNode(WV_SP_BUS_NODE);
 129 extern winvblock__lib_func NTSTATUS STDCALL WvBusEnqueueIrp(WV_SP_BUS_T, PIRP);
 130 extern winvblock__lib_func NTSTATUS STDCALL WvBusEnqueueCustomWorkItem(
 131     WV_SP_BUS_T,
 132     WV_SP_BUS_CUSTOM_WORK_ITEM
 133   );
 134 extern winvblock__lib_func NTSTATUS STDCALL WvBusSysCtl(
 135     IN WV_SP_BUS_T,
 136     IN PIRP
 137   );
 138 extern winvblock__lib_func NTSTATUS STDCALL WvBusPower(
 139     IN WV_SP_BUS_T,
 140     IN PIRP
 141   );
 142 /* IRP_MJ_PNP dispatcher in bus/pnp.c */
 143 extern winvblock__lib_func NTSTATUS STDCALL WvBusPnp(
 144     IN WV_SP_BUS_T,
 145     IN PIRP,
 146     IN UCHAR
 147   );
 148 extern winvblock__lib_func winvblock__uint32 STDCALL WvBusGetNodeNum(
 149     IN WV_SP_BUS_NODE
 150   );
 151 extern winvblock__lib_func WV_SP_BUS_NODE STDCALL WvBusGetNextNode(
 152     IN WV_SP_BUS_T,
 153     IN WV_SP_BUS_NODE
 154   );
 155 extern winvblock__lib_func PDEVICE_OBJECT STDCALL WvBusGetNodePdo(
 156     IN WV_SP_BUS_NODE
 157   );
 158 extern winvblock__lib_func winvblock__uint32 STDCALL WvBusGetNodeCount(
 159     WV_SP_BUS_T
 160   );
 161
 162 #endif  /* WVL_M_BUS_H_ */