- Add DDK alignment macros and move/rename the ones in the NDK for user-mode only...
[reactos.git] / reactos / include / ndk / readme.txt
index a9bbc9d..acff107 100644 (file)
@@ -116,6 +116,55 @@ you would like to be credited for it.
 \r
 3. USAGE\r
 \r
-3.1 TODO (COPY FROM WIKI)\r
-\r
-... TODO ... (COPY FROM WIKI)\r
+3.1 ORGANIZATION\r
+\r
+   * The NDK is organized in a main folder (include/ndk) with arch-specific subfolders (ex: include/ndk/i386). \r
+   * The NDK is structured by NT Subsystem Component (ex: ex, ps, rtl, etc). \r
+   * The NDK can either be included on-demand (#include <ndk/xxxxx.h>) or globally (#include <ndk/ntndk.h>).\r
+     The former is recommended to reduce compile time. \r
+   * The NDK is structured by function and type. Every Subsystem Component has an associated "xxfuncs.h" and\r
+    "xxtypes.h" header, where "xx" is the Subsystem (ex: iofuncs.h, iotypes.h) \r
+   * The NDK has a special file called "umtypes.h" which exports to User-Mode or Native-Mode Applications the\r
+     basic NT types which are present in ntdef.h. This file cannot be included since it would conflict with\r
+     winnt.h and/or windef.h. Thus, umtypes.h provides the missing types. This file is automatically included\r
+     in a User-Mode NDK project. \r
+   * The NDK also includes a file called "umfuncs.h" which exports to User-Mode or Native-Mode Applications\r
+     undocumented functions which can only be accessed from ntdll.dll. \r
+   * The NDK has another special file called "ifssupp.h", which exports to Kernel-Mode drivers a few types which\r
+     are only documented in the IFS kit, and are part of some native definitions. It will be deprecated next year\r
+     with the release of the WDK. \r
+\r
+3.2 USING IN YOUR PROJECT\r
+\r
+    *  User Mode Application requiring Native Types: \r
+\r
+       #define WIN32_NO_STATUS   /* Tell Windows headers you'll use ntstatus.s from NDK */\r
+       #include <windows.h>      /* Declare Windows Headers like you normally would */\r
+       #include <ntndk.h>        /* Declare the NDK Headers */\r
+\r
+    * Native Mode Application: \r
+\r
+       #include <windows.h>      /* Declare Windows Headers for basic types. NEEDED UNTIL NDK 1.5 */\r
+       #include <ntndk.h>        /* Declare the NDK Headers */\r
+\r
+    * Kernel Mode Driver: \r
+\r
+       #include <ntddk.h>       /* Declare DDK Headers like you normally would */\r
+       #include <ntndk.h>       /* Declare the NDK Headers */\r
+\r
+    * You may also include only the files you need (example for User-Mode application):\r
+\r
+       #define WIN32_NO_STATUS   /* Tell Windows headers you'll use ntstatus.s from NDK */\r
+       #include <windows.h>      /* Declare Windows Headers like you normally would */\r
+       #include <rtlfuncs.h>     /* Declare the Rtl* Functions */\r
+\r
+3.3 CAVEATS\r
+\r
+    * winternl.h: This header, part of the PSDK, was released by Microsoft as part of one of the governmen\r
+      lawsuits against it, and documents a certain (minimal) part of the Native API and/or types. Unforunately,\r
+      Microsoft decided to hack the Native Types and to define them incorrectly, replacing real members by "reserved"\r
+      ones. As such, you 'cannot include winternl.h in any project that uses the NDK. Note however, that the NDK fully\r
+      replaces it and retains compatibility with any project that used it.\r
+    * Native programs: Native programs must include "windows.h" until the next release of the NDK (1.5). The upcoming\r
+      version will automatically detect the lack of missing types and include them. Note however that you will still need\r
+      to have the PSDK installed.\r