[ros-diffs] [arty] 39: Added analysis of null driver.

Added analysis of null driver.
Added: trunk/reactos/documentation/audit/drivers/
Added: trunk/reactos/documentation/audit/drivers/base/
Added: trunk/reactos/documentation/audit/drivers/base/null.txt
Added:
trunk/reactos/documentation/audit/drivers/standard_driver_entry_tasks.tx
t
Added:
trunk/reactos/documentation/audit/drivers/standard_irp_handling_tasks.tx
t
  _____  

Added: trunk/reactos/documentation/audit/drivers/base/null.txt
--- trunk/reactos/documentation/audit/drivers/base/null.txt
2006-01-30 00:02:45 UTC (rev 38)
+++ trunk/reactos/documentation/audit/drivers/base/null.txt
2006-01-30 00:12:14 UTC (rev 39)
@@ -0,0 +1,32 @@

+Audit result: NULL driver
+Result: Obvious implementation
+
+The null driver implements two virtual devices;
+
+\device\null -- A device which always consumes all bytes written and
which 
+perpetually reads at EOF (this is similar to the unix /dev/null
device).
+@null.c:155
+
+\device\zero -- A device which simulates an infinite well of zero bytes
on
+read, and which rejects attempts to write.
+@null.c:156
+
+The null driver initializes resources in its DriverEntry function as
outlined
+in drivers/standard_driver_entry_tasks.txt.  This initialization can be
+considered trivial, as it performs only tasks which are trivially
considered
+to be required.
+
+@null.c:159 -- Register dispatch functions
+@null.c:167,184 -- Create device object
+@null.c:176,193 -- Gracefully handle failures
+@null.c:200 -- Set buffered IO flag as described here:
+http://msdn.microsoft.com/library/default.asp?url=/library/en-us/IFSK_r
/hh/IFSK_r/irpref_e73f783d-00eb-4d50-82a2-67ce60a36c76.xml.asp
+
+The null driver contains only one other nonempty function, the IRP
handling
+dispatch function.  This function can be considered to be trivial in
that
+everything it does is trivially considered to be required as outlined
in
+drivers/standard_irp_handling_tasks.txt.
+
+@null.c:82 -- Protect the kernel mode environment
+@null.c:58,62,78,85,115,121,127,133,138 -- Complete irps on behalf of
user
+  processes.
  _____  

Added:
trunk/reactos/documentation/audit/drivers/standard_driver_entry_tasks.tx
t
---
trunk/reactos/documentation/audit/drivers/standard_driver_entry_tasks.tx
t	2006-01-30 00:02:45 UTC (rev 38)
+++
trunk/reactos/documentation/audit/drivers/standard_driver_entry_tasks.tx
t	2006-01-30 00:12:14 UTC (rev 39)
@@ -0,0 +1,12 @@

+These tasks are required of the DriverEntry portion of any driver, and
are
+described in "The Windows NT Device Driver Book" by Art Baker.
+
+While mostly outlined in chapters 4 and 5, essential tasks include:
+
+- Initializing the device object with function pointers which are
called to
+  service IRPs on behalf of drivers and devices.
+- Creating device objects used to represent driver instances and making
them
+  available by name in the kernel namespace.
+- Possibly acquiring resources for well known, fixed instance devices
such as
+  legacy ISA.
+- Gracefully handling errors and cleaning up resources.
  _____  

Added:
trunk/reactos/documentation/audit/drivers/standard_irp_handling_tasks.tx
t
---
trunk/reactos/documentation/audit/drivers/standard_irp_handling_tasks.tx
t	2006-01-30 00:02:45 UTC (rev 38)
+++
trunk/reactos/documentation/audit/drivers/standard_irp_handling_tasks.tx
t	2006-01-30 00:12:14 UTC (rev 39)
@@ -0,0 +1,19 @@

+These tasks are required of any IRP handling callbacks provided by a
driver
+and are outlined in "The Windows NT Device Driver Book" by Art Baker,
chapters
+9, 10 and 11.
+
+Essential tasks are:
+
+- In the case of device open, close and cleanup requests, manage
resources
+  needed by each open device instance, including device specific and
driver
+  specific data allocated in DRIVER_EXTENSION and DEVICE_EXTENSION
structures,
+  any uncompleted, queued IRPs, and any internally queued requests on
behalf
+  of either ioctls which cause persistent driver state changes or
hardware with
+  persistent states that must be tracked.
+- Actually interacting with hardware in order to fulfill user requests.
+- Manage access to user buffers using MDLs.
+- Complete or enqueue IRPs on behalf of user processes or other
drivers.
+- Manage timers and other system services needed to ensure that the
system
+  functions correctly.
+- Protect the kernel mode environment from harm by validating pointers
to user
+  memory.