doc/FAQ

   1 Q: Latest CVS?
   2 A: Access to the latest CVS development tree:
   3         cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs login
   4                         Just hit ENTER (empty password)
   5         cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs -z3 checkout -d captive priv/captive
   6         cd captive
   7         cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs -z3 checkout -d reactos -r captive -kk priv/reactos
   8
   9    The final mapping of directories to CVS repository after the step above:
  10         captive         -> priv/captive
  11         captive/macros  -> macros
  12         captive/reactos -> priv/reactos
  13
  14    Current diff of captive changes against reactos (it may have backlog):
  15         cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs -z3 rdiff -u -R -r bp_captive -r captive priv/reactos
  16
  17    Official reactos website:
  18         http://www.reactos.com/
  19
  20    Access to the original reactos source tree (mirrored to my "priv/reactos"):
  21         cvs -d :pserver:cvsanon@mok.lvcm.com:/CVS/ReactOS login
  22                         Type the password "cvsanon" (without quotes)
  23         cvs -d :pserver:cvsanon@mok.lvcm.com:/CVS/ReactOS -z3 checkout reactos
  24
  25    You may also like ViewCVS web access to the repository:
  26         http://cvs.jankratochvil.net/viewcvs/priv/captive/
  27         http://cvs.jankratochvil.net/viewcvs/priv/reactos/?only_with_tag=captive
  28         http://cvs.jankratochvil.net/viewcvs/macros/
  29
  30    Finally you can compile the package from the "captive" directory:
  31         ./autogen.pl
  32         make
  33
  34    The package gets preconfigured with --enable-maintainer-mode option
  35    automatically by './autogen.pl'. You can later just update the "captive"
  36    subdirectory if it is your currentdir:
  37         cvs update
  38         ./autogen.pl
  39         make
  40
  41    Although './autogen.pl' should not be needed do not bugreport if it wan't
  42    rerun as some dependencies may not be respected by the package.
  43
  44 Q: Why it is based on static structures, no multithreading possibility?
  45 A: reactos has also static design therefore there would be no possibility
  46    to use the whole libcaptive in multithreaded way.
  47    Another question is whether to support multithreading in the scope of one
  48    reactos machine - this would be possible but it is not yet implemented
  49    in libcaptive. All such points should be marked by "TODO:thread"
  50
  51 Q: Prefer during libcaptive coding the GNU stylee or reactos (=W32) coding style?
  52 A: Hard decision as captive connects these two worls together.
  53    It was decided to prefer coding in GNU style in the Gnome specific way.
  54
  55    Full function replaces apparently must use the same calling conventions.
  56    Coding of the full-replace should be done in GNU style if coded from scratch
  57    although it is permitted to leave the original function code if only minor
  58    modifications were performed (decide whether it is not better to patch
  59    reactos source files instead to keep the code unified).
  60    Any other code besides function replace should use GNU style calling conventions.
  61
  62    All the normal (GNU) world uses 32-bit wchar_t but reactos (=W32) uses
  63    16-bit (unsigned short) wchar_t. This would need GCC -fshort-wchar option.
  64    It has effect on L"literal-string" or L'c' character-constants.
  65    Unfortunately they expect libc-named functions such as wcsrchr(3) to also
  66    follow this broken 16-bit way. FIXME: reactos-compat-includes
  67
  68 Q: How is the libcaptive project trustworthy?
  69 A: We have to run foreign native closed-source W32 code which is certainly NOT
  70    trust trustworthy in any way. We could close it to some separate address
  71    space and give it some safe gateways to invoce our code for the public world
  72    (read "UNIX processes") interaction. It would be too much complicated
  73    without any gain thus we choose to open our libcaptive-using process to any
  74    attacks by W32 but the whole libcaptive process MUST be closed by a sandbox.
  75    Of course all the communication with libcaptive must be taken with care by
  76    taint-aware code.
  77
  78 Q: How to check valid input arguments? Invalid processing state assumptions?
  79 A: libcaptive uses uses various Gnome macros out of <glib/gmessages.h>.
  80    The common final still should run safely when all theses checks are disabled
  81    as the bug-free code should never invoce them. This is the same for
  82    libcaptive with a little excuse for foreign native closed-source W32 code
  83    beign run which can <a href="FIXME:How is the libcaptive project trustworthy?"
  84    >never be trusted</a>. As we glued all the libcaptive code
  85    together with the W32 code we no longer can protect all the borders to the
  86    enemy land inside the one tainted process. Therefore even fully trusted
  87    libcaptive code can never safely run with <glib/gmessages.h> checks
  88    disabled. YMMV if your trust W32 code. Be aware that W32 code has to also
  89    handle correctly all the corrupted disk data structure to comply with such
  90    trusted relationship. I really dunno if it complies but I don't care as
  91    I don't trust anyway.
  92
  93 Q: Is it safe to captive_cleanup() the process and captive_init() it again?
  94 A: It should be possible to fully cleanup the state of libcaptive even after
  95    <a href="FIXME:How to check valid input arguments? Invalid processing state assumptions?"
  96    ><glib/gmessages.h> failures</a>. It is currently not implemented and it
  97    may get dropped at all in the future as libcaptive process MUST be sandboxed
  98    anyway. You are recommended (currently required) to terminate the sandboxed
  99    process and initialize the new one instead of captive_cleanup().
 100
 101 Q: I am missing symbol although it is already implemented by reactos.
 102 A: First look at $(top_srcdir)/src/libcaptive/ke/exports.captivesym
 103    where it may be enough to add such symbol to the list of exported symbols.
 104    If it is not compiled at all find such symbol definition in reactos.
 105    If such file or directory isn't listed in captive reactos compilation part
 106    you may need to add it to $(top_srcdir)/src/libcaptive/reactos/ according
 107    to the template files around - you will really only add the file to
 108    Makefile.am, no real file gets copied there (just symlinked automatically).
 109
 110    Usuaully you will also like to edit the appended file and simplify it by lines
 111         #ifndef LIBCAPTIVE
 112    and
 113         #endif /* LIBCAPTIVE */
 114    as too much (useless for you now) code would have dependencies on other
 115    missing code and you would get into never ending race of solving missing ones.
 116    If the feature being implemented is some feature not needed or not suitable
 117    for the emulation by libcaptive you should implement the emulation
 118    below $(top_srcdir)/src/libcaptive/ directly. The filename should conform
 119    to the reactos directory tree standard if applicable.
 120
 121    Always rather implement emply emulation function than patching the referring
 122    code to prevent code development conflicts with the mainstream reactos.
 123
 124 Q: Why not Wine instead of ReactOS?
 125 A: Although <a href="http://www.winehq.com/">Wine</a> has better development
 126    activity than <a href="http://www.reactos.com/">ReactOS</a> the decision
 127    is strictly technical. We need to run W32 file system driver which always
 128    lives in kernel-land in W32 system design.
 129         guest-OS host-OS       implements  core library correspondence
 130         Wine     GNU/Linux     user        ntdll
 131         ReactOS  i386 hardware kernel+user ntoskrnl
 132    (ReactOS is going to reuse Wine for its 'user' part.)
 133    FIXME: href in the table title:
 134         host-OS: http://www.vmware.com/support/reference/common/glossary/#hostos
 135         guest-OS: http://www.vmware.com/support/reference/common/glossary/#guestos
 136    While ReactOS is nice to provide us the wanted kernel emulation we also
 137    need to run the guest-OS in GNU/Linux. Initially I wanted to extend Wine
 138    to the kernel emulation effort but fortunately
 139    <a href="mailto:Steven_Ed4153@yahoo.com">Steven Edwards<a> pointed me to
 140    the ReactOS project which better suits the needs of captive.
 141
 142    The host-OS problem unfortunately hits us on ReactOS but this isn't
 143    much hard task. W32 is designed to be hardware-independent using its <code>hal.dll</code>.
 144    Unfortunately ReactOS doesn't follow this design and thus we have to patch
 145    and replace various parts of hardware-dependent code even inside <code>ntoskrnl.exe</code>.
 146
 147    Some functions are provided both by <code>ntdll.dll</code> and
 148    <code>ntoskrnl.exe</code> in W32. Suggested by
 149    <a href="mailto:chorns@users.sourceforge.net">Casper Hornstrup</a> this has
 150    to be differentiated as <code>ntdll.dll</code> lives in the userland
 151    (low addressspace) and <code>ntoskrnl.exe</code> in the kernelland
 152    (high addressspace). Unfortunately these two guys are very far each other
 153    and they would have serious problems to correctly hear themselves as the
 154    addresspace differentiates at 0x80000000. For completeness it may also
 155    differentiate at 0xC0000000 address instead depending on whether /3GB was
 156    specified during startup. BTW reactos always uses 0xC0000000 point (macro
 157    <code>KERNEL_BASE</code>) although this address doesn't apply in any way on
 158    reactos running in host-OS GNU/Linux when compiled for libcaptive.
 159
 160 Q: Is libcaptive limited to filesystems? What about general W32 driver support?
 161 A: Yes, libcaptive implements W32 kernel subsystem (mostly by reactos)
 162          in GNU/Linux. It should be possible to use it for any kernel-level W32
 163          closed-source binary although you will need to extend the currently
 164          filesystem-centric supported W32 kernel API functions and you may also need
 165          to extend 'libcaptive/ps/signal.c' SIGSEGV handler to emulate possible W32
 166          driver access to hardware (if not solved by some more straightforward access
 167          permission).
 168
 169 Q: What is Ordinal in the W32 library symbols import/export scope?
 170 A: Each exported symbol has its Ordinal specified - this number specifies the offset
 171    in the library symbol table. During the symbol import from a different module
 172    it can specify either the full symbol name or just this number - Ordinal.
 173    I dunno why it was ever created as the symbol name string size is very tiny.
 174    Fortunately the current versions of W32 binaries no longer utilize this Ordinal
 175    feature thus captive doesn't provide them in its export.
 176
 177 Q: Why I don't see debug info for imported binary W32 modules? Do you use W32 symbol files?
 178 Q: W32 symbol files have different debugging info structure. We would have to
 179    convert it and I am not aware Wine or ReactOS already done this task.
 180    Not yet implemented and I currently do not plan to do it.
 181
 182 Q: Any competiting projects?
 183 A: Depending on your demands you may be interested in one of:
 184    <a href="http://www.powerquest.com/partitionmagic/">PowerQuest PartitionMagic</a>:
 185         proprietary; $70
 186    <a href="http://www.acronis.com/products/osselector/">Acronis OS Selector</a>:
 187         proprietary; $45
 188
 189 Q: Do you differentiate cdecl/stdcall/fastcall functions?
 190 A: W32 uses
 191    <a href="http://msdn.microsoft.com/library/en-us/vclang/html/_core_argument_passing_and_naming_conventions.asp"
 192    >three different types of function calls</a>.
 193    captive is completely compiled with the GNU standard function calls "cdecl"
 194    - _even_ the functions from reactos source files with different design
 195    function call type (=calltype) are all compiled as GNU standard "cdecl" ones and thus
 196    the whole project uses one unified calltype. There is always one 'relaying'
 197    function generated inside libcaptive/ke/exports.c file named
 198    functionname_calltype (such as functionname_fastcall etc.).
 199
 200    Relaying function are generated as:<dl>
 201    <dt>cdecl</dt><dd>No relaying function generated, just a simple #define.
 202         You won't see this function in the gdb backtrace.
 203         We cannot generate it by C code as we do not know the number of its arguments.
 204         We require the host OS GCC feature "__attribute__((__cdecl__))"
 205         although it should be the default function call.
 206         </dd>
 207    <dt>stdcall</dt><dd>Relaying stub generated, all arguments passed.
 208         We require the host OS GCC feature "__attribute__((__stdcall__))".
 209         </dd>
 210    <dt>fastcall</dt><dd>W32 puts first two arguments to ECX and EDX.
 211         GCC puts the arguments in the order EAX, EDX, ECX, ...
 212         Although GCC can change this order by "-mreg-alloc=REGS" commandline
 213         option such option is not supported by stock GNU/Linux GCC compilers.
 214         Therefore we pretend an unused first argument and swap the order of
 215         second vs. third function argument to get the right parameter pass.
 216         We require the host OS GCC feature "__attribute__((__regparm__(3)))".
 217         We require the host OS GCC feature "__attribute__((__stdcall__))".
 218    </dl>
 219    32-bit return value in EAX is always passed back although it may be vain.
 220    Please see the documentation of "captivesym.pl" for more information.
 221
 222    Unfortutely the situation is dense during calling from the standard
 223    calltype forced captive/reactos to the foreign binary W32 code as this
 224    code we cannot recompile in any way. All function prototypes leading
 225    to the W32 binary code are declared by CAPTIVE_CDECL or CAPTIVE_STDCALL
 226    macros from "captive/calltype_reactos.h". These macros have to be
 227    #ifdef-ed inside reactos code as they are not available during standalong
 228    reactos compilation. CAPTIVE_FASTCALL is not provided but it should not be
 229    needed as the non-core kernel code inside foreign W32 binaries usually
 230    does not provide any FASTCALL functions. There may be problem if some
 231    internal reactos code gets compiled while being called through
 232    CAPTIVE_CDECL or CAPTIVE_STDCALL declared protypes - there is currently
 233    no such case known.
 234
 235 Q: What happens if the calltype differs than expected by caller/callee?
 236 A: If it is fastcall/non-fastcall type you will usually find it easily
 237    as the passed arguments will differ. stdcall/cdecl types is much harder
 238    as the only effect will be unexpected ESP returned which gets automatically
 239    corrected during the caller function return from EBP.
 240
 241    We may do some sanity checking in libcaptive/ps/signal.c SIGSEGV handler
 242    but any such solution is just a perusing of expected W32 binary code
 243    stack frame handling code. It is not possible to correctly do such sanity
 244    check as it would have to be coded directly into the W32 binary code.
 245
 246 Q: Which registers get saved during various function calltypes?
 247 A: EDI, ESI, EBX is always saved on stack. It is stored on the stack
 248    in this particular order from bottom to top addresses (therefure
 249    it is stored by 'push EBX', 'push ESI', 'push EDI').
 250
 251    Fortunately GNU/Linux GCC AFAIK has the same register saving behaviour.
 252    If you get some register corruption please check
 253    <a href="What happens if the calltype differs than expected by caller/callee?">function calltypes</a>.
 254
 255 Q: Why do you call the platform "W32"?
 256 A: http://mail.gnu.org/pipermail/libtool/2000-September/000110.html
 257
 258 Q: What captive-specific W32 registry entries do you use?
 259 A: "\captive\filesystem"    as the base path for the loaded W32 filesystem
 260
 261 Q: Why do you use reactos instead of native <code>ntoskrnl.exe</code>?
 262 A: Although the reactos implementation is not native and therefore it will
 263    always have has some incompatibilities with native W32 platform it is
 264    much easier to debug anything with source-available code.
 265    If there will be serious compatibility problems we may start replacing
 266    reactos implementation with native <code>ntoskrnl.exe</code> code
 267    but it should be considered as last resort - it is enough pain to debug
 268    closed source filesystem drivers behaviour while all the other system
 269    components are still opensourced.
 270
 271    Not using <code>ntoskrnl.exe</code> has no license gain as you already
 272    need valid W32 licence to use native filesystem driver. Any known W32
 273    license covering W32 native filesystem driver also covers <code>ntoskrnl.exe</code>.
 274
 275 Eric Kohl, reactos developer:
 276         ..." and ReactOS cannot run on Linux!"
 277         "ReactOS won't run on Linux because of direct hardware access!"