[device] Introduce device__set function
[people/sha0/winvblock.git] / src / include / device.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 _device_h
22 #  define _device_h
23
24 /**
25  * @file
26  *
27  * Device specifics.
28  */
29
30 #  include "portable.h"
31
32 enum _device__state
33 {
34   NotStarted,
35   Started,
36   StopPending,
37   Stopped,
38   RemovePending,
39   SurpriseRemovePending,
40   Deleted
41 };
42 winvblock__def_enum ( device__state );
43
44 /* Forward declaration */
45 winvblock__def_struct ( device__type );
46
47 /**
48  * Device PDO creation routine
49  *
50  * @v dev_ptr           The device whose PDO should be created
51  * @ret pdo_ptr         Points to the new PDO, or is NULL upon failure
52  */
53 #  define device__create_pdo_decl( x ) \
54 \
55 PDEVICE_OBJECT STDCALL \
56 x ( \
57   IN device__type_ptr dev_ptr \
58  )
59 /*
60  * Function pointer for a device PDO creation routine.
61  * 'indent' mangles this, so it looks weird
62  */
63 typedef device__create_pdo_decl (
64    ( *device__create_pdo_routine )
65  );
66 /**
67  * Create a device PDO
68  *
69  * @v dev_ptr           Points to the device that needs a PDO
70  */
71 extern winvblock__lib_func device__create_pdo_decl (
72   device__create_pdo
73  );
74
75 /**
76  * Device initialization routine
77  *
78  * @v dev_ptr           The device being initialized
79  */
80 #  define device__init_decl( x ) \
81 \
82 winvblock__bool STDCALL \
83 x ( \
84   IN device__type_ptr dev_ptr \
85  )
86 /*
87  * Function pointer for a device initialization routine.
88  * 'indent' mangles this, so it looks weird
89  */
90 typedef device__init_decl (
91    ( *device__init_routine )
92  );
93
94 /**
95  * Device close routine
96  *
97  * @v dev_ptr           The device being closed
98  */
99 #  define device__close_decl( x ) \
100 \
101 void STDCALL \
102 x ( \
103   IN device__type_ptr dev_ptr \
104  )
105 /*
106  * Function pointer for a device close routine.
107  * 'indent' mangles this, so it looks weird
108  */
109 typedef device__close_decl (
110    ( *device__close_routine )
111  );
112 /**
113  * Close a device
114  *
115  * @v dev_ptr           Points to the device to close
116  */
117 extern winvblock__lib_func device__close_decl (
118   device__close
119  );
120
121 /**
122  * Device deletion routine.
123  *
124  * @v dev_ptr           Points to the device to delete.
125  */
126 typedef void STDCALL device__free_func(IN device__type_ptr);
127 /**
128  * Delete a device.
129  *
130  * @v dev_ptr           Points to the device to delete.
131  */
132 extern winvblock__lib_func device__free_func device__free;
133
134 /**
135  * Initialize the global, device-common environment
136  *
137  * @ret ntstatus        STATUS_SUCCESS or the NTSTATUS for a failure
138  */
139 extern STDCALL NTSTATUS device__init (
140   void
141  );
142
143 /**
144  * Create a new device
145  *
146  * @ret dev_ptr         The address of a new device, or NULL for failure
147  *
148  * This function should not be confused with a PDO creation routine, which is
149  * actually implemented for each device type.  This routine will allocate a
150  * device__type, track it in a global list, as well as populate the device
151  * with default values.
152  */
153 extern winvblock__lib_func device__type_ptr device__create (
154   void
155  );
156
157 winvblock__def_struct ( device__ops )
158 {
159   device__create_pdo_routine create_pdo;
160   device__init_routine init;
161   device__close_routine close;
162   device__free_func * free;
163 };
164
165 typedef void STDCALL (device__thread_func)(IN void *);
166
167 /* Details common to all devices this driver works with */
168 struct _device__type
169 {
170   winvblock__bool IsBus;        /* For debugging */
171   /* A device's IRP dispatch routine. */
172   driver__dispatch_func * (dispatch);
173   /* The device's thread routine. */
174   device__thread_func * (thread);
175   /* The device's thread wakeup signal. */
176   KEVENT (thread_wakeup);
177   /* The device's IRP queue. */
178   LIST_ENTRY (irp_list);
179   /* The device's IRP queue lock. */
180   KSPIN_LOCK (irp_list_lock);
181   PDEVICE_OBJECT Self;
182   PDEVICE_OBJECT Parent;
183   PDRIVER_OBJECT DriverObject;
184   device__state State;
185   device__state OldState;
186   irp__handler_chain irp_handler_chain;
187   device__type_ptr next_sibling_ptr;
188   device__ops ops;
189   LIST_ENTRY tracking;
190   winvblock__any_ptr ext;
191 };
192
193 extern winvblock__lib_func device__type_ptr device__get(PDEVICE_OBJECT);
194 extern winvblock__lib_func device__type_ptr device__set(
195     PDEVICE_OBJECT,
196     device__type_ptr
197   );
198
199 #endif                          /* _device_h */