Added isapnp audit documentation. Added: trunk/documentation/audit/drivers/bus/ Added: trunk/documentation/audit/drivers/bus/isapnp.txt _____
Added: trunk/documentation/audit/drivers/bus/isapnp.txt --- trunk/documentation/audit/drivers/bus/isapnp.txt 2006-02-04 19:07:37 UTC (rev 94) +++ trunk/documentation/audit/drivers/bus/isapnp.txt 2006-02-05 09:48:22 UTC (rev 95) @@ -0,0 +1,166 @@
+Audit result: ISA PNP driver +Result: Based substantially on linux implementation/Necessary implementation + +The isapnp driver implements a virtual device which serves as the parent bus +of devices which follow the ISA Plug And Play specification. + +The specification can be found here: +http://www.microsoft.com/whdc/resources/respec/specs/pnpisa.mspx + +The ISA PnP 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. + +@isapnp.c:1727-1737 -- Initialize callbacks in the DriverObject + +IRPs handled by the ISA PnP driver are outlined in: + +Art Baker, "The Windows NT Device Driver Book", chapter 8, page 166 lists + +- IRP_MJ_CREATE +- IRP_MJ_CLOSE +- IRP_MJ_READ +- IRP_MJ_WRITE +- IRP_MJ_DEVICE_CONTROL + +Which are generic IRP types resulting from NtCreateFile, NtClose, NtReadFile, +NtWriteFile and NtDeviceIoControl and are implemented for virtually all device +drivers, and may be considered as required. + +OSROnline ( http://www.osronline.com/DDKx/kmarch/k113_8ur6.htm ) describes +handling of: + +- IRP_MJ_PNP + +Which is required for Plug And Play capable bus drivers. + +Some of these provide minor codes which further distinguish the requested +task. In the case of IRP_MJ_DEVICE_CONTROL, these codes are device or function +specific. + +In the case of IRP_MJ_PNP, the minor codes are well known. + +Handling of each Irp type and subtype is outlined below: + +ISAPNPDispatchOpenClose (isapnp.c:1580-1586) +Status: Obvious. + +ISAPNPDispatchReadWrite (isapnp.c:1596-1602) +Status: Obvious. + +ISAPNPDispatchDeviceControl (isapnp.c:1612-1634) +Status: +Tail starting at 1627: Obvious. +Head until line 1621: Obvious. +At line 1621: A switch statement with a single default failure case appears. +Status: +audit/switch_default/ReadMe.txt -- Such a construct cannot be arrived at +through reverse engineering + +ISAPNPControl (isapnp.c:1644-1676) +Status: Obvious +This function dispatches to several other functions: + +ISAPNPQueryDeviceRelations +ISAPNPStartDevice +ISAPNPStopDevice + +And otherwise performs only IRP completion activities outlined in +audit/drivers/standard_irp_handling_tasks.txt + +ISAPNPQueryDeviceRelations (isapnp.c:1491-1510) +Status: Obvious +Following form with the other functions in the file, ISAPNPQuery +DeviceRelations uses a switch statement to dispatch to another +function in the case of a recognized request type. That a switch +statement is used for a single non-default case, given that it +is also used for default-only switches in the same file, reflects +a stylistic choice that allows more cases to be added without +changing the basic code structure. + +As documented here: +http://www.osronline.com/DDKx/kmarch/pnp-irps_5aia.htm + +ISAPNPQueryDeviceRelations dispatches to ISAPNPQueryBusRelations. + +ISAPNPQueryBusRelations: (isapnp.c:1423-1481) +Status: obvious +Head until line 1440 -- obvious +Tail after line 1468 -- obvious +@isapnp.c:1440 -- Compute the size of the DEVICE_RELATIONS return based on +the number of detected devices (from device extension) +-1 (constant) explained here: +http://www.codecomments.com/archive421-2005-5-501037.html +@isapnp.c:1450-1454 -- obvious -- list crawl +@isapnp.c:1457 -- Call to IoCreateDevice as described: +http://www.osronline.com/DDKx/kmarch/k104_8piq.htm +@isapnp.c:1465 -- Example of marking a device as being created by a bus driver +http://www.osronline.com/showThread.cfm?link=5419 + +ISAPNPStartDevice: (isapnp.c:1520-1549) +Status: obvious +Head until line 1531 -- obvious +Tail after line 1542 -- obvious +This function simply calls several functions to which functionality is +delegated, and gracefully responds to failures. + +IsolatePnPCards +BuildDeviceList +BuildResourceListsForAll + +BuildDeviceList: +Status: based on linux isapnp_device_list +(http://glide.stanford.edu/lxr/ident?v=linux-2.6.5;i=isapnp_build_devic e_list) + +BuildResourceListsForAll: (@isapnp.c:1348-1362) +Status: obvious +This function simply iterates over every card, calling +BuildResourceListsForCard on each + +BuildResourceListsForCard: (@isapnp.c:1324-1338) +Status: obvious +Iterates logical functions per card, calling BuildResourceLists for each + +BuildresourceLists: (@isapnp.c: (@isapnp.c:1273-1315) +Status: necessary +In order to make resource information available to windows PNP drivers, each +Physical device object must have an IO_RESOURCE_REQUIREMENTS_LIST attached. +This function prepares these lists as documented here: +http://msdn.microsoft.com/library/default.asp?url=/library/en-us/Kernel _r/hh/Kernel_r/k112_3a1f163a-5841-4284-9ee7-c0999e1a9bbc.xml.asp +http://www.osronline.com/ddkx/kmarch/plugplay_7mef.htm + +@isapnp.c:1279 -- Compute size of resource list in memory +@isapnp.c:1288-1302 -- Prepare memory for resource list storage +@isapnp.c:1302-1312 -- Call BuildResourceList for each slot +@isapnp.c:Tail after 1312 -- Set list size. AlternativeLists set to the +number of lists returned. + +BuildResourceList: (isapnp.c:1211-1264) +Status: necessary +Fills in an IO_RESOURCE_LIST as documented +@isapnp.c:Head before 1230 -- Necessary list management code. +@isapnp.c:1230-1232 -- Set header information for resource list +@isapnp.c:1234-1245 -- Crawl list information gathered while enumerating cards +@isapnp.c:1245-1247 -- Copy resource information +@isapnp.c:Tail after 1251 -- Tails of list crawls + +IsolatePnPCards: (isapnp.c:293-356) +Status: Based on linux isapnp_isolate +This function carries out the Isolation Protocol described in the ISA PNP +specification. + +(isapnp) shall refer to the ISA PNP Specification + +Based substantially on linux isapnp_isolate +(http://glide.stanford.edu/lxr/ident?v=linux-2.6.5;i=isapnp_isolate) + +Used Functions: +IsolateReadDataPortSelect + +IsolateReadDataPortSelect: +Status: Based on Linux isapnp_isolate_rdp_select +(http://glide.stanford.edu/lxr/ident?v=linux-2.6.5;i=isapnp_isolate_rdp _select) + +Past this point, there is a 1 to 1 correspondence between functions in the +linux isapnp/core.c and reactos' isapnp.c.
-
arty＠svn.reactos.org