- Add DDK alignment macros and move/rename the ones in the NDK for user-mode only...
[reactos.git] / reactos / include / ndk / readme.txt
index 61085e6..acff107 100644 (file)
@@ -2,6 +2,20 @@ Native Development Kit README
         NDK 1.00\r
 -----------------------------\r
 \r
+0. PREABMLE\r
+\r
+0.1 COPYRIGHT\r
+\r
+The NDK is Copyright © 2005 Alex Ionescu.\r
+\r
+0.2 CONTACT INFORMATION\r
+\r
+The author, Alex Ionescu, may be reached through the following means:\r
+\r
+Email:         alex.ionescu@reactos.com\r
+Mail:  2246, Duvernay. H3J 2Y3. Montreal, QC. CANADA.  \r
+Phone:         (514)581-7156\r
+\r
 1. LICENSE\r
 \r
 1.1 OPEN SOURCE USAGE\r
@@ -45,8 +59,112 @@ legal action on the part of the author.
 If you are unsure of have any questions about the NDK License, please contact the\r
 author for further clarification.\r
 \r
-2. USAGE\r
-\r
-2.1 TODO (COPY FROM WIKI)\r
+2. ORIGINS OF NDK MATERIAL, AND ADDING YOUR OWN\r
 \r
-... TODO ... (COPY FROM WIKI)\r
+2.1 CONTRIBUTIONS AND SOURCES\r
+\r
+The NDK could not exist without the various contributions made by a variety of people\r
+and sources. The following public sources of information were lawfully used:\r
+\r
+- GNU NTIFS.H, Revision 43\r
+- W32API, Version 2.5\r
+- Microsoft Driver Development Kit 2003 SP1\r
+- Microsoft Driver Development Kit 2000\r
+- Microsoft Driver Development Kit NT 4\r
+- Microsoft Driver Development Kit WinME\r
+- Microsoft Installable File Systems Kit 2003 SP1\r
+- Microsoft Windows Debugger (WinDBG) 6.5.0003.7\r
+- Microsoft Public Symbolic Data\r
+- Microsoft Public Windows Binaries (strings)\r
+- OSR Technical Articles\r
+- Undocumented windows 2000 Secrets, a Programmer's Cookbook\r
+- Windows NT/2000 Native API Reference\r
+- Windows NT File System Internals\r
+- Windows Internals I - II\r
+- Windows Internals 4th Edition\r
+\r
+If the information contained in these sources was copyrighted, the information was not\r
+copied, but simply used as a basis for developing a compatible and identical definition.\r
+No information protected by a patent or NDA was used. All information was publically\r
+located through the Internet or purchased or licensed for lawful use.\r
+\r
+Additionally, the following people contributed to the NDK:\r
+\r
+- Eric Kohl\r
+- Filip Navara\r
+- Steven Edwards\r
+\r
+2.2 BECOMING A CONTRIBUTOR\r
+\r
+To contribute information to the NDK, simply contact the author with your new structure,\r
+definition, enumeration, or prototype. Please make sure that your addition is:\r
+\r
+1) Actually correct!\r
+2) Present in Windows NT 5, 5.1, 5.2 and/or 6.0\r
+3) Not already accessible through another public header in the DDK, IFS, WDK and/or PSDK.\r
+4) From a publically verifiable source. The author needs to be able to search for your\r
+   addition in a public information location (book, Internet, etc) and locate this definition.\r
+5) Not Reversed. Reversing a type is STRONGLY discouraged and a reversed type will more then likely\r
+   not be accepted, due to the fact that functionality and naming will be entirely guessed, and things\r
+   like unions are almost impossible to determine. It can also bring up possible legal ramifications\r
+   depending on your location. However, using a tool to dump the strings inside an executable\r
+   for the purpose of locating the actual name or definition of a structure (sometimes possible due\r
+   to ASSERTs or debugging strings) is considered 'fair use' and will be a likely candidate.\r
+\r
+If your addition satsfies these points, then please submit it, and also include whether or not\r
+you would like to be credited for it.\r
+\r
+3. USAGE\r
+\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