Q: Latest CVS?
A: Access to the latest CVS development tree:
   	cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs login
   			Just hit ENTER (empty password)
   	cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs -z3 checkout -d captive priv/captive
   	cd captive
   	cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs -z3 checkout -d reactos -r captive -kk priv/reactos

   The final mapping of directories to CVS repository after the step above:
   	captive         -> priv/captive
   	captive/macros  -> macros
   	captive/reactos -> priv/reactos

   Current diff of captive changes against reactos (it may have backlog):
   	cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs -z3 rdiff -u -R -r bp_captive -r captive priv/reactos

   Official reactos website:
   	http://www.reactos.com/

   Access to the original reactos source tree (mirrored to my "priv/reactos"):
   	cvs -d :pserver:cvsanon@mok.lvcm.com:/CVS/ReactOS login
   			Type the password "cvsanon" (without quotes)
   	cvs -d :pserver:cvsanon@mok.lvcm.com:/CVS/ReactOS -z3 checkout reactos

   You may also like ViewCVS web access to the repository:
   	http://cvs.jankratochvil.net/viewcvs/priv/captive/
   	http://cvs.jankratochvil.net/viewcvs/priv/reactos/?only_with_tag=captive
   	http://cvs.jankratochvil.net/viewcvs/macros/

   Finally you can compile the package from the "captive" directory:
   	./autogen.pl
   	make

   The package gets preconfigured with --enable-maintainer-mode option
   automatically by './autogen.pl'. You can later just update the "captive"
   subdirectory if it is your currentdir:
   	cvs update
   	./autogen.pl
   	make

   Although './autogen.pl' should not be needed do not bugreport if it wan't
   rerun as some dependencies may not be respected by the package.

Q: Why it is based on static structures, no multithreading possibility?
A: reactos has also static design therefore there would be no possibility
   to use the whole libcaptive in multithreaded way.
   Another question is whether to support multithreading in the scope of one
   reactos machine - this would be possible but it is not yet implemented
   in libcaptive. All such points should be marked by "TODO:thread"

Q: Prefer during libcaptive coding the GNU stylee or reactos (=W32) coding style?
A: Hard decision as captive connects these two worls together.
   It was decided to prefer coding in GNU style in the Gnome specific way.

   Full function replaces apparently must use the same calling conventions.
   Coding of the full-replace should be done in GNU style if coded from scratch
   although it is permitted to leave the original function code if only minor
   modifications were performed (decide whether it is not better to patch
   reactos source files instead to keep the code unified).
   Any other code besides function replace should use GNU style calling conventions.

   All the normal (GNU) world uses 32-bit wchar_t but reactos (=W32) uses
   16-bit (unsigned short) wchar_t. This would need GCC -fshort-wchar option.
   It has effect on L"literal-string" or L'c' character-constants.
   Unfortunately they expect libc-named functions such as wcsrchr(3) to also
   follow this broken 16-bit way. FIXME: reactos-compat-includes

Q: How is the libcaptive project trustworthy?
A: We have to run foreign native closed-source W32 code which is certainly NOT
   trust trustworthy in any way. We could close it to some separate address
   space and give it some safe gateways to invoce our code for the public world
   (read "UNIX processes") interaction. It would be too much complicated
   without any gain thus we choose to open our libcaptive-using process to any
   attacks by W32 but the whole libcaptive process MUST be closed by a sandbox.
   Of course all the communication with libcaptive must be taken with care by
   taint-aware code.

Q: How to check valid input arguments? Invalid processing state assumptions?
A: libcaptive uses uses various Gnome macros out of <glib/gmessages.h>.
   The common final still should run safely when all theses checks are disabled
   as the bug-free code should never invoce them. This is the same for
   libcaptive with a little excuse for foreign native closed-source W32 code
   beign run which can <a href="FIXME:How is the libcaptive project trustworthy?"
   >never be trusted</a>. As we glued all the libcaptive code
   together with the W32 code we no longer can protect all the borders to the
   enemy land inside the one tainted process. Therefore even fully trusted
   libcaptive code can never safely run with <glib/gmessages.h> checks
   disabled. YMMV if your trust W32 code. Be aware that W32 code has to also
   handle correctly all the corrupted disk data structure to comply with such
   trusted relationship. I really dunno if it complies but I don't care as
   I don't trust anyway.

Q: Is it safe to captive_cleanup() the process and captive_init() it again?
A: It should be possible to fully cleanup the state of libcaptive even after
   <a href="FIXME:How to check valid input arguments? Invalid processing state assumptions?"
   ><glib/gmessages.h> failures</a>. It is currently not implemented and it
   may get dropped at all in the future as libcaptive process MUST be sandboxed
   anyway. You are recommended (currently required) to terminate the sandboxed
   process and initialize the new one instead of captive_cleanup().

Q: I am missing symbol although it is already implemented by reactos.
A: First look at $(top_srcdir)/src/libcaptive/ke/exports.captivesym
   where it may be enough to add such symbol to the list of exported symbols.
   If it is not compiled at all find such symbol definition in reactos.
   If such file or directory isn't listed in captive reactos compilation part
   you may need to add it to $(top_srcdir)/src/libcaptive/reactos/ according
   to the template files around - you will really only add the file to
   Makefile.am, no real file gets copied there (just symlinked automatically).

   Usuaully you will also like to edit the appended file and simplify it by lines
   	#ifndef LIBCAPTIVE
   and
   	#endif /* LIBCAPTIVE */
   as too much (useless for you now) code would have dependencies on other
   missing code and you would get into never ending race of solving missing ones.
   If the feature being implemented is some feature not needed or not suitable
   for the emulation by libcaptive you should implement the emulation
   below $(top_srcdir)/src/libcaptive/ directly. The filename should conform
   to the reactos directory tree standard if applicable.

   Always rather implement emply emulation function than patching the referring
   code to prevent code development conflicts with the mainstream reactos.

Q: Why not Wine instead of ReactOS?
A: Although <a href="http://www.winehq.com/">Wine</a> has better development
   activity than <a href="http://www.reactos.com/">ReactOS</a> the decision
   is strictly technical. We need to run W32 file system driver which always
   lives in kernel-land in W32 system design.
   	guest-OS host-OS       implements  core library correspondence
   	Wine     GNU/Linux     user        ntdll
   	ReactOS  i386 hardware kernel+user ntoskrnl
   (ReactOS is going to reuse Wine for its 'user' part.)
   FIXME: href in the table title:
   	host-OS: http://www.vmware.com/support/reference/common/glossary/#hostos
   	guest-OS: http://www.vmware.com/support/reference/common/glossary/#guestos
   While ReactOS is nice to provide us the wanted kernel emulation we also
   need to run the guest-OS in GNU/Linux. Initially I wanted to extend Wine
   to the kernel emulation effort but fortunately
   <a href="mailto:Steven_Ed4153@yahoo.com">Steven Edwards<a> pointed me to
   the ReactOS project which better suits the needs of captive.

   The host-OS problem unfortunately hits us on ReactOS but this isn't
   much hard task. W32 is designed to be hardware-independent using its <code>hal.dll</code>.
   Unfortunately ReactOS doesn't follow this design and thus we have to patch
   and replace various parts of hardware-dependent code even inside <code>ntoskrnl.exe</code>.

   Some functions are provided both by <code>ntdll.dll</code> and
   <code>ntoskrnl.exe</code> in W32. Suggested by
   <a href="mailto:chorns@users.sourceforge.net">Casper Hornstrup</a> this has
   to be differentiated as <code>ntdll.dll</code> lives in the userland
   (low addressspace) and <code>ntoskrnl.exe</code> in the kernelland
   (high addressspace). Unfortunately these two guys are very far each other
   and they would have serious problems to correctly hear themselves as the
   addresspace differentiates at 0x80000000. For completeness it may also
   differentiate at 0xC0000000 address instead depending on whether /3GB was
   specified during startup. BTW reactos always uses 0xC0000000 point (macro
   <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: 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
   it can specify either the full symbol name or just this number - Ordinal.
   I dunno why it was ever created as the symbol name string size is very tiny.
   Fortunately the current versions of W32 binaries no longer utilize this Ordinal
   feature thus captive doesn't provide them in its export.

Q: Why I don't see debug info for imported binary W32 modules? Do you use W32 symbol files?
Q: W32 symbol files have different debugging info structure. We would have to
   convert it and I am not aware Wine or ReactOS already done this task.
   Not yet implemented and I currently do not plan to do it.

Q: Any competiting projects?
A: Depending on your demands you may be interested in one of:
   <a href="http://www.powerquest.com/partitionmagic/">PowerQuest PartitionMagic</a>:
   	proprietary; $70
   <a href="http://www.acronis.com/products/osselector/">Acronis OS Selector</a>:
   	proprietary; $45

Q: Do you differentiate cdecl/stdcall/fastcall functions?
A: W32 uses
   <a href="http://msdn.microsoft.com/library/en-us/vclang/html/_core_argument_passing_and_naming_conventions.asp"
   >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 generated inside libcaptive/ke/exports.c file named
   functionname_calltype (such as functionname_fastcall etc.).

   Realying 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.
   	We require the host OS GCC feature "__attribute__((__cdecl__))"
   	although it should be the default function call.
   	</dd>
   <dt>stdcall</dt><dd>Relaying stub generated, all arguments passed.
   	We require the host OS GCC feature "__attribute__((__stdcall__))".
   	</dd>
   <dt>fastcall</dt><dd>W32 puts first two arguments to ECX and EDX.
   	GCC puts the arguments in the order EAX, EDX, ECX, ...
   	Although GCC can change this order by "-mreg-alloc=REGS" commandline
   	option such option is not supported by stock GNU/Linux GCC compilers.
   	Therefore we pretend an unused first argument and swap the order of
   	second vs. third function argument to get the right parameter pass.
   	We require the host OS GCC feature "__attribute__((__regparm__(3)))".
   	We require the host OS GCC feature "__attribute__((__stdcall__))".
   </dl>
   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.

Eric Kohl, reactos developer:
	..." and ReactOS cannot run on Linux!"
	"ReactOS won't run on Linux because of direct hardware access!"