diff --git a/README b/README new file mode 100644 index 0000000..7b32408 --- /dev/null +++ b/README @@ -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. + diff --git a/api/.gitignore b/api/.gitignore new file mode 100644 index 0000000..e69de29 diff --git a/articles/CacheMan.pdf b/articles/CacheMan.pdf new file mode 100644 index 0000000..3f4111b Binary files /dev/null and b/articles/CacheMan.pdf differ diff --git a/articles/GDI_call_flow.jpg b/articles/GDI_call_flow.jpg new file mode 100644 index 0000000..d63ba2e Binary files /dev/null and b/articles/GDI_call_flow.jpg differ diff --git a/articles/fpu_state_saving.png b/articles/fpu_state_saving.png new file mode 100644 index 0000000..3f04720 Binary files /dev/null and b/articles/fpu_state_saving.png differ diff --git a/articles/opengl32.png b/articles/opengl32.png new file mode 100644 index 0000000..7bf61d2 Binary files /dev/null and b/articles/opengl32.png differ diff --git a/articles/pnp1.pdf b/articles/pnp1.pdf new file mode 100644 index 0000000..456651b Binary files /dev/null and b/articles/pnp1.pdf differ diff --git a/audit/drivers/base/null.txt b/audit/drivers/base/null.txt new file mode 100644 index 0000000..7ed5e57 --- /dev/null +++ b/audit/drivers/base/null.txt @@ -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. diff --git a/audit/drivers/bus/isapnp.txt b/audit/drivers/bus/isapnp.txt new file mode 100644 index 0000000..60f0dae --- /dev/null +++ b/audit/drivers/bus/isapnp.txt @@ -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. diff --git a/audit/drivers/standard_driver_entry_tasks.txt b/audit/drivers/standard_driver_entry_tasks.txt new file mode 100644 index 0000000..bc370d9 --- /dev/null +++ b/audit/drivers/standard_driver_entry_tasks.txt @@ -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. diff --git a/audit/drivers/standard_irp_handling_tasks.txt b/audit/drivers/standard_irp_handling_tasks.txt new file mode 100644 index 0000000..383e13e --- /dev/null +++ b/audit/drivers/standard_irp_handling_tasks.txt @@ -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. diff --git a/audit/switch_default/Debug/switch_default.asm b/audit/switch_default/Debug/switch_default.asm new file mode 100755 index 0000000..6c696d9 --- /dev/null +++ b/audit/switch_default/Debug/switch_default.asm @@ -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 diff --git a/audit/switch_default/ReadMe.txt b/audit/switch_default/ReadMe.txt new file mode 100755 index 0000000..a2dbca7 --- /dev/null +++ b/audit/switch_default/ReadMe.txt @@ -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. diff --git a/audit/switch_default/Release/switch_default.asm b/audit/switch_default/Release/switch_default.asm new file mode 100755 index 0000000..a30aff4 --- /dev/null +++ b/audit/switch_default/Release/switch_default.asm @@ -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 diff --git a/audit/switch_default/stdafx.cpp b/audit/switch_default/stdafx.cpp new file mode 100755 index 0000000..56580c1 --- /dev/null +++ b/audit/switch_default/stdafx.cpp @@ -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 diff --git a/audit/switch_default/stdafx.h b/audit/switch_default/stdafx.h new file mode 100755 index 0000000..83cd4a7 --- /dev/null +++ b/audit/switch_default/stdafx.h @@ -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 +#include + + + +// TODO: reference additional headers your program requires here diff --git a/audit/switch_default/switch_default.cpp b/audit/switch_default/switch_default.cpp new file mode 100755 index 0000000..e351f17 --- /dev/null +++ b/audit/switch_default/switch_default.cpp @@ -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; +} + diff --git a/audit/switch_default/switch_default.sln b/audit/switch_default/switch_default.sln new file mode 100755 index 0000000..fb8bd02 --- /dev/null +++ b/audit/switch_default/switch_default.sln @@ -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 diff --git a/audit/switch_default/switch_default.suo b/audit/switch_default/switch_default.suo new file mode 100755 index 0000000..c2047e7 Binary files /dev/null and b/audit/switch_default/switch_default.suo differ diff --git a/audit/switch_default/switch_default.vcproj b/audit/switch_default/switch_default.vcproj new file mode 100755 index 0000000..583cfbc --- /dev/null +++ b/audit/switch_default/switch_default.vcproj @@ -0,0 +1,229 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/reverse.engineering/.gitignore b/reverse.engineering/.gitignore new file mode 100644 index 0000000..e69de29