+Using libcaptive for non-filesystem W32 drivers?
[captive.git] / doc / FAQ
diff --git a/doc/FAQ b/doc/FAQ
index 745eafb..e662add 100644 (file)
--- a/doc/FAQ
+++ b/doc/FAQ
@@ -157,6 +157,15 @@ A: Although <a href="http://www.winehq.com/">Wine</a> has better development
    <code>KERNEL_BASE</code>) although this address doesn't apply in any way on
    reactos running in host-OS GNU/Linux when compiled for libcaptive.
 
+Q: Is libcaptive limited to filesystems? What about general W32 driver support?
+A: Yes, libcaptive implements W32 kernel subsystem (mostly by reactos)
+        in GNU/Linux. It should be possible to use it for any kernel-level W32
+        closed-source binary although you will need to extend the currently
+        filesystem-centric supported W32 kernel API functions and you may also need
+        to extend 'libcaptive/ps/signal.c' SIGSEGV handler to emulate possible W32
+        driver access to hardware (if not solved by some more straightforward access
+        permission).
+
 Q: What is Ordinal in the W32 library symbols import/export scope?
 A: Each exported symbol has its Ordinal specified - this number specifies the offset
    in the library symbol table. During the symbol import from a different module
@@ -183,12 +192,12 @@ A: W32 uses
    >three different types of function calls</a>.
    captive is completely compiled with the GNU standard function calls "cdecl"
    - _even_ the functions from reactos source files with different design
-   function call type are all compiled as GNU standard "cdecl" ones and thus
-   the whole project uses one unified call type. There is always one 'relaying'
+   function call type (=calltype) are all compiled as GNU standard "cdecl" ones and thus
+   the whole project uses one unified calltype. There is always one 'relaying'
    function generated inside libcaptive/ke/exports.c file named
    functionname_calltype (such as functionname_fastcall etc.).
 
-   Realying function are generated as:<dl>
+   Relaying function are generated as:<dl>
    <dt>cdecl</dt><dd>No relaying function generated, just a simple #define.
        You won't see this function in the gdb backtrace.
        We cannot generate it by C code as we do not know the number of its arguments.
@@ -210,12 +219,59 @@ A: W32 uses
    32-bit return value in EAX is always passed back although it may be vain.
    Please see the documentation of "captivesym.pl" for more information.
 
+   Unfortutely the situation is dense during calling from the standard
+   calltype forced captive/reactos to the foreign binary W32 code as this
+   code we cannot recompile in any way. All function prototypes leading
+   to the W32 binary code are declared by CAPTIVE_CDECL or CAPTIVE_STDCALL
+   macros from "captive/calltype_reactos.h". These macros have to be
+   #ifdef-ed inside reactos code as they are not available during standalong
+   reactos compilation. CAPTIVE_FASTCALL is not provided but it should not be
+   needed as the non-core kernel code inside foreign W32 binaries usually
+   does not provide any FASTCALL functions. There may be problem if some
+   internal reactos code gets compiled while being called through
+   CAPTIVE_CDECL or CAPTIVE_STDCALL declared protypes - there is currently
+   no such case known.
+
+Q: What happens if the calltype differs than expected by caller/callee?
+A: If it is fastcall/non-fastcall type you will usually find it easily
+   as the passed arguments will differ. stdcall/cdecl types is much harder
+   as the only effect will be unexpected ESP returned which gets automatically
+   corrected during the caller function return from EBP.
+
+   We may do some sanity checking in libcaptive/ps/signal.c SIGSEGV handler
+   but any such solution is just a perusing of expected W32 binary code
+   stack frame handling code. It is not possible to correctly do such sanity
+   check as it would have to be coded directly into the W32 binary code.
+
+Q: Which registers get saved during various function calltypes?
+A: EDI, ESI, EBX is always saved on stack. It is stored on the stack
+   in this particular order from bottom to top addresses (therefure
+   it is stored by 'push EBX', 'push ESI', 'push EDI').
+
+   Fortunately GNU/Linux GCC AFAIK has the same register saving behaviour.
+   If you get some register corruption please check
+   <a href="What happens if the calltype differs than expected by caller/callee?">function calltypes</a>.
+
 Q: Why do you call the platform "W32"?
 A: http://mail.gnu.org/pipermail/libtool/2000-September/000110.html
 
 Q: What captive-specific W32 registry entries do you use?
 A: "\captive\filesystem"    as the base path for the loaded W32 filesystem
 
+Q: Why do you use reactos instead of native <code>ntoskrnl.exe</code>?
+A: Although the reactos implementation is not native and therefore it will
+   always have has some incompatibilities with native W32 platform it is
+   much easier to debug anything with source-available code.
+   If there will be serious compatibility problems we may start replacing
+   reactos implementation with native <code>ntoskrnl.exe</code> code
+   but it should be considered as last resort - it is enough pain to debug
+   closed source filesystem drivers behaviour while all the other system
+   components are still opensourced.
+
+   Not using <code>ntoskrnl.exe</code> has no license gain as you already
+   need valid W32 licence to use native filesystem driver. Any known W32
+   license covering W32 native filesystem driver also covers <code>ntoskrnl.exe</code>.
+
 Eric Kohl, reactos developer:
        ..." and ReactOS cannot run on Linux!"
        "ReactOS won't run on Linux because of direct hardware access!"