Target NativeNT: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		(Windows only)
2	2
3	3		This target allows to compile applications for the basic Windows NT kernel interface. This includes usermode applications und kernelmode device drivers.
4	4
5	5		## Reasons for this port
6	6
7	7		Windows NT operating systems (Windows NT 3.5 up to Windows 7) are based on a design that allows running different environments (called "environment subsystem") that user applications interact with.
8	8
9	9		Examples are
10	10
11	11		- the infamous Win32 subsystem (which provides the WinAPI)
12	12		- the POSIX / Interix subsystem (included as SUA in Windows Vista/7 Ultimate and Enterprise)
13	13		- OS/2 subsystem (dropped in Windows 2000)
14	14
15	15		Those subsystems don't use the usual WinAPI, but the API of the NT kernel itself which is exposed through ntdll.dll to user space. Also the device drivers that run on a Windows NT system don't use the WinAPI, but the API provided by ntoskrnl.exe and hal.dll.
16	16
17	17		As the Win32/64 targets link to WinAPI I saw no better way than to start a new target which supports the kernel API, but thanks to the very common structure of Win32/64 and NativeNT (same binary format, many kernel32 functions are similar to ntdll ones) the implementation of this port is rather (!) easy.
18	18
19	19		## Supported systems
20	20
21	21		In theory, user mode applications and device drivers can support all Windows NT versions from Windows NT 4 or even 3.51 on, but the only tested systems are currently:
22	22
23	23		- Windows 2000 (Windows NT 5.0)
24	24		- [ReactOS](http://www.ReactOS.org/) (equivalent to Windows 2003 or Windows NT 5.2, see also [[ReactOS]])
25	25
26	26		The supported versions depend on the used functions. For a rather complete list and the supported kernels see [here](http://jedi-apilib.sourceforge.net/native/NativeList.html).
27	27
28	28		Also the only supported processor architecture is currently i386. A port to x86_64 (Windows XP and newer) is planned in the near future. Also once the ARM and PPC ports of ReactOS are mature enough (e. g. kernel itself and early user mode is running) I plan to make ports for them.
29	29
30	30		Note: Device drivers for WinCE systems are NOT possible with this port, as that system has a different kernel structure.
31	31
32	32		## Building the compiler
33	33
34	34		Currently only a cross compiler is available. To build it you need a version of Free Pascal newer than revision 14568, e.g. FPC 2.6 or later.
35	35
36	36		On Linux and similar:
37	37
38	38		``` bash
39	39		cd $YourFPCDir
40	40		cd compiler
41	41		make
42	42		cp ppc386 $WhereYouWantTheCompiler
43	43		cd ../utils/fpcm
44	44		make
45	45		cp fpcmake $WhereYouWantFPCMake
46	46		```
47	47
48	48		On Windows (assuming you use an SVN checkout/source directory):
49	49
50	50		- go to directory where you checked out FPC
51	51		- open cmd.exe (e. g. Start -\> Run -\> Write "cmd" -\> OK )
52	52		- navigate to your FPC directory
53	53
54	54		```dos
55	55		cd compiler
56	56		make
57	57		cp ppc386.exe %WhereYouWantTheCompiler%
58	58		cd ..\utils\fpcm
59	59		make
60	60		cp fpcmake.exe %WhereYouWantFPCMake%
61	61		```
62	62
63	63		Notes:
64	64
65	65		- on Windows, you need to have the GNU make utility in your PATH (e.g. the one provided with Lazarus) or use its absolute path
66	66		- on Windows and Linux/*nix you need to have FPC in your PATH or supply it to make with "FPC=path/to/fpc/binary"
67	67		- you do not need to do the copy steps, it's mainly useful if you want to replace your installed (trunk) compiler
68	68		- compiling the fpcmake utility is needed!
69	69
70	70		## Building the RTL
71	71
72	72		Now you can compile the RTL
73	73
74	74		- for usermode
75	75
76	76		``` bash
77	77		make FPC=$YourNewPPC386Binary OS_TARGET=nativent
78	78		```
79	79
80	80		- for kernelmode
81	81
82	82		``` bash
83	83		make FPC=$YourNewPPC386Binary OS_TARGET=nativent OPT="-dKMODE"
84	84		```
85	85
86	86		\$YourNewPPC386Binary is "../../compiler/ppc386" when you didn't copy it to another directory.
87	87
88	88		The compiled units will be in "../units/i386-nativent" (relative from nativent directory).
89	89
90	90		Note:
91	91
92	92		- the define for kernel mode is needed, because the differences between kernel and user mode are rather huge, but I also didn't want to maintain two targets for this (also a normal user doesn't compile the RTL very often)
93	93		- if you want to have both RTLs compile the kernel mode one first and copy the units to an "i386-nativent-kmode" directory (for example)
94	94
95	95		## Usermode Hello World
96	96
97	97		### Building
98	98
99	99		If you're experienced enough you can modify your fpc.cfg to include the NativeNT units (TODO), but for now I only use compiler command line switches.
100	100
101	101		``` pascal
102	102		program helloworld;
103	103
104	104		uses
105	105		// as WriteLn is not supported, yet, we need to
106	106		// use the functions provided by the kernel directly
107	107		NDK, NDKUtils;
108	108
109	109		var
110	110		ntstr: TNtUnicodeString;
111	111		interval: TLargeInteger;
112	112		begin
113	113		ShortStrToNtStr('Hello World!'#13#10, ntstr);
114	114		NtDisplayString(@ntstr);
115	115		FreeMem(ntstr.buffer);
116	116
117	117		// wait 3 seconds
118	118		interval.QuadPart := - 3000 * 10000;
119	119		NtDelayExecution(@interval);
120	120		end.
121	121		```
122	122
123	123		Compile like this
124	124
125	125		``` bash
126	126		$YourNewPPC386 -n -Tnativent -Fu$PathToUserModeRTL helloworld.pas
127	127		```
128	128
129	129		You should now have a helloworld.exe file in your current directory.
130	130
131	131		Note: Your anti virus may complain about this new executable, but it is clean!
132	132
133	133		### Running
134	134
135	135		Important: Do NOT test this on a production machine (I mean it!). I'm not responsible for any damage to your computer.
136	136
137	137		Copy the new executable to your test machine (e.g. a VM) into the system32 directory of your Windows/ReactOS installation (e.g. C:\WINNT\system32 up to Windows 2000, C:\Windows\system32 from Windows XP on, C:\ReactOS\system32 on ReactOS). You might want to backup the registry file system32\config\SYSTEM (e.g. not needed if you use QEMU with an QCow2 base image). Open regedit (Start -\> Run -\> Write "regedit" -\> OK) and navigate to
138	138
139		-	~~`HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Session Manager`~~
	139	+	```text
	140	+	HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Session Manager
	141	+	```
140	142
141	143		and edit the BootExecute value (you should see a "autochk" in there). Add this after the "AutoCheck" entry:
142	144
143		-	~~`HelloWorld helloworld`~~
	145	+	```text
	146	+	HelloWorld helloworld
	147	+	```
144	148
145	149		First "HelloWorld" is a custom name and second one is the name of the executable inside the system32 directory. You can optionally pass arguments after "helloworld" like "*" in "AutoCheck" entry, but you need to parse them manually as ParamStr/-Count isn't implemented yet.
146	150
147	151		Now restart the machine. You should see a "Hello World!" message in the top left corner of the screen after the boot screen. If you see a Bluescreen: well, I hope you didn't use a production machine.
148	152
149	153		## Kernelmode Hello World
150	154
151	155		### Building
152	156
153	157		The note about configuration in user mode applies here, too.
154	158
155	159		``` pascal
156	160		library helloworld; // this is important - do not try a "program" here
157	161
158	162		// tell FPC that we want to compile a kernel mode application
159	163		// (NEEDS a RTL that was compiled with KMODE)
160	164		{$apptype native}
161	165
162	166		uses
163	167		// for entry point types and debug output
164	168		DDK;
165	169
166	170		// this method is called once our driver is unloaded
167	171		procedure DriverUnload(aObject: PDriverObject); stdcall;
168	172		begin
169	173		DbgPrint('Unloading driver');
170	174		end;
171	175
172	176		// during the entry point the variables DriverObject and
173	177		// RegistryPath are valid
174	178		begin
175	179		DbgPrint('Hello World!');
176	180
177	181		// we need to setup the unload routine or the driver will
178	182		// only be unloaded on shutdown!
179	183		DriverObject^.DriverUnload := @DriverUnload;
180	184		end.
181	185		```
182	186
183	187		Compile like this:
184	188
185	189		``` bash
186	190		$YourNewPPC386 -n -Tnativent -Fu$PathToKernelModeRTL -ohelloworld.sys helloworld.pas
187	191		```
188	192
189	193		The naming convention for drivers is ".sys", so we change the extention from .dll to .sys.
190	194
191	195		### Running
192	196
193	197		Note: As long as you set the driver to "start on demand", instead of "start on boot" or "start automatically" you might do this on a production machine, but I don't recommend it.
194	198
195	199		To see the debug messages you need a tool for Windows like [DebugView](http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx) (I didn't test this on ReactOS, though) which needs to be started before the driver.
196	200
197	201		Now copy the driver to the system32\drivers directory on your test machine.
198	202
199	203		To run a driver you need to install it as a service (yes, drivers are regarded as "services" - this might be a heritage of the Mach architecture of Windows NT). I've created a tool which uses the Service Control Manager API to do this, but until I've uploaded it somewhere you need to install it manually:
200	204
201	205		- open regedit
202	206		- navigate to HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services
203	207		- create a new key and give it a unique name (e.g. "helloworld")
204	208		- add the following values in there:
205	209
206	210		\| Name \| Type \| Value \|
207	211		\|--------------\|-----------\|---------------------------------\|
208	212		\| ErrorControl \| DWORD \| 0x00000001 \|
209	213		\| ImagePath \| EXPAND_SZ \| system32\drivers\helloworld.sys \|
210	214		\| Start \| DWORD \| 0x00000003 \|
211	215		\| Type \| DWORD \| 0x00000001 \|
212	216
213	217		Note: You might not be able to create an expandable string value (EXPAND_SZ) in Windows (you can in ReactOS and Vista for certain), so you need to trick by exporting another driver entry and modifying that or you write a Pascal tool which creates those entries.
214	218
215	219		Before you can start the driver you need to generate a PE checksum for it (as far as I know Windows checks the PE checksum at least for drivers). You need a tool which can generate a PE checksum or you can write your own one (there are some examples on the net). Also you can wait until I've uploaded my DriverHelper tool which can do this, too.
216	220
217	221		After you've created the checksum, you can finally start the driver:
218	222
219	223		- open cmd.exe
220	224		- type "net start helloworld" (the name of the KEY you created)
221	225		- now you should get a "Hello World!" message inside DebugView (or whatever application you use for viewing debug output)
222	226		- type "net stop helloworld" to unload the driver (you should get another message in your debuging application)
223	227
224	228		Note: If you get a BSOD you can simply restart and everything will be fine until you start the driver again.
225	229
226	230		## Driver signing
227	231
228	232		A 64-bit kernel mode driver needs to be signed. And it may be that on Windows 10+ a 32-bit driver also needs to be signed. You can during development use a local certificate for that as per the DDK documentation on MSDN.
229	233
230	234		32-bit drivers below or equal to platform Windows 7 are known to work.
231	235
232	236		---
233	237		From the Free Pascal wiki, page "Target NativeNT", as it stood on 2022-10-22 after a change by Alextp, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
234	238		Category: Windows

Back to history