[libbus] Add thread ownership functions
[people/sha0/winvblock.git] / src / include / bus.h
1 /**
2  * Copyright (C) 2009-2011, 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 /* Forward declaration. */
31 struct WVL_BUS_T;
32
33 /**
34  * A bus thread routine.
35  *
36  * @v bus       The bus to be used in the thread routine.
37  *
38  * If you implement your own bus thread routine, you should call
39  * WvlBusProcessWorkItems() within its loop.
40  */
41 typedef VOID STDCALL WVL_F_BUS_THREAD(IN struct WVL_BUS_T *);
42 typedef WVL_F_BUS_THREAD * WVL_FP_BUS_THREAD;
43
44 /**
45  * A bus PnP routine.
46  *
47  * @v bus               The bus to receive the PnP IRP.
48  * @v irp               The IRP to process.
49  * @ret NTSTATUS        The status of the operation.
50  */
51 typedef NTSTATUS STDCALL WVL_F_BUS_PNP(IN struct WVL_BUS_T *, IN PIRP);
52 typedef WVL_F_BUS_PNP * WVL_FP_BUS_PNP;
53
54 /* Device state. */
55 typedef enum WVL_BUS_STATE {
56     WvlBusStateNotStarted,
57     WvlBusStateStarted,
58     WvlBusStateStopPending,
59     WvlBusStateStopped,
60     WvlBusStateRemovePending,
61     WvlBusStateSurpriseRemovePending,
62     WvlBusStateDeleted,
63     WvlBusStates
64   } WVL_E_BUS_STATE, * WVL_EP_BUS_STATE;
65
66 /* The bus type. */
67 typedef struct WVL_BUS_T {
68     PDEVICE_OBJECT LowerDeviceObject;
69     PDEVICE_OBJECT Pdo;
70     PDEVICE_OBJECT Fdo;
71     UINT32 Children;
72     WVL_FP_BUS_THREAD Thread;
73     KEVENT ThreadSignal;
74     BOOLEAN Stop;
75     WVL_E_BUS_STATE OldState;
76     WVL_E_BUS_STATE State;
77     WVL_FP_BUS_PNP QueryDevText;
78     struct {
79         LIST_ENTRY Nodes;
80         USHORT NodeCount;
81         LIST_ENTRY WorkItems;
82         KSPIN_LOCK WorkItemsLock;
83         PETHREAD Thread;
84       } BusPrivate_;
85   } WVL_S_BUS_T, * WVL_SP_BUS_T;
86
87 /* A child PDO node on a bus.  Treat this as an opaque type. */
88 typedef struct WVL_BUS_NODE {
89     struct {
90         LIST_ENTRY Link;
91         PDEVICE_OBJECT Pdo;
92         WVL_SP_BUS_T Bus;
93         /* The child's unit number relative to the parent bus. */
94         UINT32 Num;
95       } BusPrivate_;
96   } WVL_S_BUS_NODE, * WVL_SP_BUS_NODE;
97
98 /**
99  * A custom work-item function.
100  *
101  * @v context           Function-specific data.
102  *
103  * If a driver needs to enqueue a work item which should execute in the
104  * context of the bus' controlling thread (this is the thread which calls
105  * WvlBusProcessWorkItems()), then this is the function prototype to be
106  * used.
107  */
108 typedef VOID STDCALL WVL_F_BUS_WORK_ITEM(PVOID);
109 typedef WVL_F_BUS_WORK_ITEM * WVL_FP_BUS_WORK_ITEM;
110
111 typedef struct WVL_BUS_CUSTOM_WORK_ITEM {
112     WVL_FP_BUS_WORK_ITEM Func;
113     PVOID Context;
114   } WVL_S_BUS_CUSTOM_WORK_ITEM, * WVL_SP_BUS_CUSTOM_WORK_ITEM;
115
116 /* Exports. */
117 extern WVL_M_LIB VOID WvlBusInit(WVL_SP_BUS_T);
118 extern WVL_M_LIB VOID WvlBusProcessWorkItems(WVL_SP_BUS_T);
119 extern WVL_M_LIB VOID WvlBusCancelWorkItems(WVL_SP_BUS_T);
120 extern WVL_M_LIB NTSTATUS WvlBusStartThread(
121     IN WVL_SP_BUS_T,
122     OUT PETHREAD *
123   );
124 extern WVL_M_LIB BOOLEAN STDCALL WvlBusInitNode(
125     OUT WVL_SP_BUS_NODE,
126     IN PDEVICE_OBJECT
127   );
128 extern WVL_M_LIB NTSTATUS STDCALL WvlBusAddNode(
129     WVL_SP_BUS_T,
130     WVL_SP_BUS_NODE
131   );
132 extern WVL_M_LIB NTSTATUS STDCALL WvlBusRemoveNode(WVL_SP_BUS_NODE);
133 extern WVL_M_LIB NTSTATUS STDCALL WvlBusEnqueueIrp(WVL_SP_BUS_T, PIRP);
134 extern WVL_M_LIB NTSTATUS STDCALL WvlBusEnqueueCustomWorkItem(
135     WVL_SP_BUS_T,
136     WVL_SP_BUS_CUSTOM_WORK_ITEM
137   );
138 extern WVL_M_LIB NTSTATUS STDCALL WvlBusSysCtl(
139     IN WVL_SP_BUS_T,
140     IN PIRP
141   );
142 extern WVL_M_LIB NTSTATUS STDCALL WvlBusPower(
143     IN WVL_SP_BUS_T,
144     IN PIRP
145   );
146 /* IRP_MJ_PNP dispatcher in bus/pnp.c */
147 extern WVL_M_LIB NTSTATUS STDCALL WvlBusPnpIrp(
148     IN WVL_SP_BUS_T,
149     IN PIRP,
150     IN UCHAR
151   );
152 extern WVL_M_LIB UINT32 STDCALL WvlBusGetNodeNum(
153     IN WVL_SP_BUS_NODE
154   );
155 extern WVL_M_LIB WVL_SP_BUS_NODE STDCALL WvlBusGetNextNode(
156     IN WVL_SP_BUS_T,
157     IN WVL_SP_BUS_NODE
158   );
159 extern WVL_M_LIB PDEVICE_OBJECT STDCALL WvlBusGetNodePdo(
160     IN WVL_SP_BUS_NODE
161   );
162 extern WVL_M_LIB UINT32 STDCALL WvlBusGetNodeCount(
163     WVL_SP_BUS_T
164   );
165 extern WVL_M_LIB BOOLEAN STDCALL WvlBusRegisterOwnerThread(IN WVL_SP_BUS_T);
166 extern WVL_M_LIB BOOLEAN STDCALL WvlBusNotOwned(IN WVL_SP_BUS_T);
167
168 #endif  /* WVL_M_BUS_H_ */