Import from casper's repository

svn path=/trunk/documentation/; revision=21185
This commit is contained in:
Art Yerkes 2006-02-23 07:32:57 +00:00
parent 35c930b169
commit d876532e4d
21 changed files with 720 additions and 0 deletions

11
README Normal file
View File

@ -0,0 +1,11 @@
This is the documentation directory for the ReactOS project.
Directory Layout:
api\ : Documentation for various APIs.
articles\ : Howto's, Articles and related documentation.
audit\ : Documentation about and gathered by the audit.
reverse.engineering\ : Clean-Room effort documentation.
: _Only_ human language and pseudo-code documentation is allowed here.

0
api/.gitignore vendored Normal file
View File

BIN
articles/CacheMan.pdf Normal file

Binary file not shown.

BIN
articles/GDI_call_flow.jpg Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 34 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 40 KiB

BIN
articles/opengl32.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 10 KiB

BIN
articles/pnp1.pdf Normal file

Binary file not shown.

View File

@ -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.

View File

@ -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_device_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.

View File

@ -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.

View File

@ -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.

View File

@ -0,0 +1,108 @@
; Listing generated by Microsoft (R) Optimizing Compiler Version 14.00.50727.42
TITLE f:\reactos\trunk\documentation\audit\switch_default\switch_default.cpp
.686P
.XMM
include listing.inc
.model flat
INCLUDELIB MSVCRTD
INCLUDELIB OLDNAMES
PUBLIC ??_C@_04DFOOMHBJ@Bar?6?$AA@ ; `string'
PUBLIC ??_C@_04DEEPCGMJ@Foo?6?$AA@ ; `string'
PUBLIC _wmain
EXTRN __imp__printf:PROC
EXTRN __RTC_CheckEsp:PROC
EXTRN __RTC_Shutdown:PROC
EXTRN __RTC_InitBase:PROC
; COMDAT ??_C@_04DFOOMHBJ@Bar?6?$AA@
; File f:\reactos\trunk\documentation\audit\switch_default\switch_default.cpp
CONST SEGMENT
??_C@_04DFOOMHBJ@Bar?6?$AA@ DB 'Bar', 0aH, 00H ; `string'
CONST ENDS
; COMDAT ??_C@_04DEEPCGMJ@Foo?6?$AA@
CONST SEGMENT
??_C@_04DEEPCGMJ@Foo?6?$AA@ DB 'Foo', 0aH, 00H ; `string'
CONST ENDS
; COMDAT rtc$TMZ
rtc$TMZ SEGMENT
__RTC_Shutdown.rtc$TMZ DD FLAT:__RTC_Shutdown
rtc$TMZ ENDS
; COMDAT rtc$IMZ
rtc$IMZ SEGMENT
__RTC_InitBase.rtc$IMZ DD FLAT:__RTC_InitBase
; Function compile flags: /Odtp /RTCsu /ZI
rtc$IMZ ENDS
; COMDAT _wmain
_TEXT SEGMENT
tv64 = -208 ; size = 4
_a$ = -8 ; size = 4
_argc$ = 8 ; size = 4
_argv$ = 12 ; size = 4
_wmain PROC ; COMDAT
; 8 : {
push ebp
mov ebp, esp
sub esp, 208 ; 000000d0H
push ebx
push esi
push edi
lea edi, DWORD PTR [ebp-208]
mov ecx, 52 ; 00000034H
mov eax, -858993460 ; ccccccccH
rep stosd
; 9 : int a = 1;
mov DWORD PTR _a$[ebp], 1
; 10 :
; 11 : switch(a) {
mov eax, DWORD PTR _a$[ebp]
mov DWORD PTR tv64[ebp], eax
; 12 : default:
; 13 : printf("Foo\n");
mov esi, esp
push OFFSET ??_C@_04DEEPCGMJ@Foo?6?$AA@
call DWORD PTR __imp__printf
add esp, 4
cmp esi, esp
call __RTC_CheckEsp
; 14 : break;
; 15 : }
; 16 :
; 17 : printf("Bar\n");
mov esi, esp
push OFFSET ??_C@_04DFOOMHBJ@Bar?6?$AA@
call DWORD PTR __imp__printf
add esp, 4
cmp esi, esp
call __RTC_CheckEsp
; 18 :
; 19 : return 0;
xor eax, eax
; 20 : }
pop edi
pop esi
pop ebx
add esp, 208 ; 000000d0H
cmp ebp, esp
call __RTC_CheckEsp
mov esp, ebp
pop ebp
ret 0
_wmain ENDP
_TEXT ENDS
END

13
audit/switch_default/ReadMe.txt Executable file
View File

@ -0,0 +1,13 @@
Test Application: default_switch
Author: Arty
Purpose: Check for reverse engineerability of the C construct:
switch( x ) {
default:
...
break;
}
Status: Disassembly of test code reveals that distinguishing a default-only
switch from unadorned code is impossible. Therefore, this construction cannot
have arrived by reverse engineering.

View File

@ -0,0 +1,66 @@
; Listing generated by Microsoft (R) Optimizing Compiler Version 14.00.50727.42
TITLE f:\reactos\trunk\documentation\audit\switch_default\switch_default.cpp
.686P
.XMM
include listing.inc
.model flat
INCLUDELIB OLDNAMES
PUBLIC ??_C@_04DEEPCGMJ@Foo?6?$AA@ ; `string'
PUBLIC ??_C@_04DFOOMHBJ@Bar?6?$AA@ ; `string'
EXTRN @__security_check_cookie@4:PROC
EXTRN __imp__printf:PROC
; COMDAT ??_C@_04DFOOMHBJ@Bar?6?$AA@
CONST SEGMENT
??_C@_04DFOOMHBJ@Bar?6?$AA@ DB 'Bar', 0aH, 00H ; `string'
CONST ENDS
; COMDAT ??_C@_04DEEPCGMJ@Foo?6?$AA@
CONST SEGMENT
??_C@_04DEEPCGMJ@Foo?6?$AA@ DB 'Foo', 0aH, 00H ; `string'
CONST ENDS
PUBLIC _wmain
; Function compile flags: /Ogtpy
; File f:\reactos\trunk\documentation\audit\switch_default\switch_default.cpp
; COMDAT _wmain
_TEXT SEGMENT
_argc$ = 8 ; size = 4
_argv$ = 12 ; size = 4
_wmain PROC ; COMDAT
; 8 : {
push esi
; 9 : int a = 1;
; 10 :
; 11 : switch(a) {
; 12 : default:
; 13 : printf("Foo\n");
mov esi, DWORD PTR __imp__printf
push OFFSET ??_C@_04DEEPCGMJ@Foo?6?$AA@
call esi
; 14 : break;
; 15 : }
; 16 :
; 17 : printf("Bar\n");
push OFFSET ??_C@_04DFOOMHBJ@Bar?6?$AA@
call esi
add esp, 8
; 18 :
; 19 : return 0;
xor eax, eax
pop esi
; 20 : }
ret 0
_wmain ENDP
_TEXT ENDS
END

View File

@ -0,0 +1,8 @@
// stdafx.cpp : source file that includes just the standard includes
// switch_default.pch will be the pre-compiled header
// stdafx.obj will contain the pre-compiled type information
#include "stdafx.h"
// TODO: reference any additional headers you need in STDAFX.H
// and not in this file

15
audit/switch_default/stdafx.h Executable file
View File

@ -0,0 +1,15 @@
// stdafx.h : include file for standard system include files,
// or project specific include files that are used frequently, but
// are changed infrequently
//
#pragma once
#define WIN32_LEAN_AND_MEAN // Exclude rarely-used stuff from Windows headers
#include <stdio.h>
#include <tchar.h>
// TODO: reference additional headers your program requires here

View File

@ -0,0 +1,21 @@
// switch_default.cpp : Defines the entry point for the console application.
//
#include "stdafx.h"
int _tmain(int argc, _TCHAR* argv[])
{
int a = 1;
switch(a) {
default:
printf("Foo\n");
break;
}
printf("Bar\n");
return 0;
}

View File

@ -0,0 +1,20 @@

Microsoft Visual Studio Solution File, Format Version 9.00
# Visual C++ Express 2005
Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "switch_default", "switch_default.vcproj", "{A9C5980E-90F0-4207-9892-C5582192DA91}"
EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Win32 = Debug|Win32
Release|Win32 = Release|Win32
EndGlobalSection
GlobalSection(ProjectConfigurationPlatforms) = postSolution
{A9C5980E-90F0-4207-9892-C5582192DA91}.Debug|Win32.ActiveCfg = Debug|Win32
{A9C5980E-90F0-4207-9892-C5582192DA91}.Debug|Win32.Build.0 = Debug|Win32
{A9C5980E-90F0-4207-9892-C5582192DA91}.Release|Win32.ActiveCfg = Release|Win32
{A9C5980E-90F0-4207-9892-C5582192DA91}.Release|Win32.Build.0 = Release|Win32
EndGlobalSection
GlobalSection(SolutionProperties) = preSolution
HideSolutionNode = FALSE
EndGlobalSection
EndGlobal

Binary file not shown.

View File

@ -0,0 +1,229 @@
<?xml version="1.0" encoding="Windows-1252"?>
<VisualStudioProject
ProjectType="Visual C++"
Version="8.00"
Name="switch_default"
ProjectGUID="{A9C5980E-90F0-4207-9892-C5582192DA91}"
RootNamespace="switch_default"
Keyword="Win32Proj"
>
<Platforms>
<Platform
Name="Win32"
/>
</Platforms>
<ToolFiles>
</ToolFiles>
<Configurations>
<Configuration
Name="Debug|Win32"
OutputDirectory="$(SolutionDir)$(ConfigurationName)"
IntermediateDirectory="$(ConfigurationName)"
ConfigurationType="1"
CharacterSet="1"
>
<Tool
Name="VCPreBuildEventTool"
/>
<Tool
Name="VCCustomBuildTool"
/>
<Tool
Name="VCXMLDataGeneratorTool"
/>
<Tool
Name="VCWebServiceProxyGeneratorTool"
/>
<Tool
Name="VCMIDLTool"
/>
<Tool
Name="VCCLCompilerTool"
Optimization="0"
PreprocessorDefinitions="WIN32;_DEBUG;_CONSOLE"
MinimalRebuild="true"
BasicRuntimeChecks="3"
RuntimeLibrary="3"
UsePrecompiledHeader="2"
AssemblerOutput="4"
WarningLevel="3"
Detect64BitPortabilityProblems="true"
DebugInformationFormat="4"
/>
<Tool
Name="VCManagedResourceCompilerTool"
/>
<Tool
Name="VCResourceCompilerTool"
/>
<Tool
Name="VCPreLinkEventTool"
/>
<Tool
Name="VCLinkerTool"
AdditionalDependencies="kernel32.lib $(NoInherit)"
LinkIncremental="2"
GenerateDebugInformation="true"
SubSystem="1"
TargetMachine="1"
/>
<Tool
Name="VCALinkTool"
/>
<Tool
Name="VCManifestTool"
/>
<Tool
Name="VCXDCMakeTool"
/>
<Tool
Name="VCBscMakeTool"
/>
<Tool
Name="VCFxCopTool"
/>
<Tool
Name="VCAppVerifierTool"
/>
<Tool
Name="VCWebDeploymentTool"
/>
<Tool
Name="VCPostBuildEventTool"
/>
</Configuration>
<Configuration
Name="Release|Win32"
OutputDirectory="$(SolutionDir)$(ConfigurationName)"
IntermediateDirectory="$(ConfigurationName)"
ConfigurationType="1"
CharacterSet="1"
WholeProgramOptimization="1"
>
<Tool
Name="VCPreBuildEventTool"
/>
<Tool
Name="VCCustomBuildTool"
/>
<Tool
Name="VCXMLDataGeneratorTool"
/>
<Tool
Name="VCWebServiceProxyGeneratorTool"
/>
<Tool
Name="VCMIDLTool"
/>
<Tool
Name="VCCLCompilerTool"
PreprocessorDefinitions="WIN32;NDEBUG;_CONSOLE"
RuntimeLibrary="2"
UsePrecompiledHeader="2"
AssemblerOutput="4"
WarningLevel="3"
Detect64BitPortabilityProblems="true"
DebugInformationFormat="3"
/>
<Tool
Name="VCManagedResourceCompilerTool"
/>
<Tool
Name="VCResourceCompilerTool"
/>
<Tool
Name="VCPreLinkEventTool"
/>
<Tool
Name="VCLinkerTool"
AdditionalDependencies="kernel32.lib $(NoInherit)"
LinkIncremental="1"
GenerateDebugInformation="true"
SubSystem="1"
OptimizeReferences="2"
EnableCOMDATFolding="2"
TargetMachine="1"
/>
<Tool
Name="VCALinkTool"
/>
<Tool
Name="VCManifestTool"
/>
<Tool
Name="VCXDCMakeTool"
/>
<Tool
Name="VCBscMakeTool"
/>
<Tool
Name="VCFxCopTool"
/>
<Tool
Name="VCAppVerifierTool"
/>
<Tool
Name="VCWebDeploymentTool"
/>
<Tool
Name="VCPostBuildEventTool"
/>
</Configuration>
</Configurations>
<References>
</References>
<Files>
<Filter
Name="Source Files"
Filter="cpp;c;cc;cxx;def;odl;idl;hpj;bat;asm;asmx"
UniqueIdentifier="{4FC737F1-C7A5-4376-A066-2A32D752A2FF}"
>
<File
RelativePath=".\stdafx.cpp"
>
<FileConfiguration
Name="Debug|Win32"
>
<Tool
Name="VCCLCompilerTool"
UsePrecompiledHeader="1"
/>
</FileConfiguration>
<FileConfiguration
Name="Release|Win32"
>
<Tool
Name="VCCLCompilerTool"
UsePrecompiledHeader="1"
/>
</FileConfiguration>
</File>
<File
RelativePath=".\switch_default.cpp"
>
</File>
</Filter>
<Filter
Name="Header Files"
Filter="h;hpp;hxx;hm;inl;inc;xsd"
UniqueIdentifier="{93995380-89BD-4b04-88EB-625FBE52EBFB}"
>
<File
RelativePath=".\stdafx.h"
>
</File>
</Filter>
<Filter
Name="Resource Files"
Filter="rc;ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe;resx;tiff;tif;png;wav"
UniqueIdentifier="{67DA6AB6-F800-4c08-8B7A-83BB121AAD01}"
>
</Filter>
<File
RelativePath=".\ReadMe.txt"
>
</File>
</Files>
<Globals>
</Globals>
</VisualStudioProject>

0
reverse.engineering/.gitignore vendored Normal file
View File