arch/all-mingw32/README.txt

   1  This file contains various notes about Windows-hosted port of AROS.
   2  At the moment both x86 (i386 and x86_64) processors are supported. ARM support
   3  is in very early experimental state, and is likely to be postponed until Windows 8
   4  release. Windows CE lacks some capabilities necessary to run hosted AROS, and it is
   5  unclear if a workaround can be found.
   6
   7  1. COMPILING
   8
   9  In order to compile it natively under Windows OS you need:
  10
  11 a) Working Cygwin or MinGW + MSYS environment.
  12 b) Netpbm package of course.
  13 c) Native gcc v3 (for Cygwin). In gcc v4 -mno-cygwin option is no more supported. If you use MSYS
  14    you're free from this restriction and can use the latest gcc.
  15 d) AROS-targetted crosscompiler. It can be found on AROS Archives:
  16    http://archives.aros-exec.org/index.php?function=browse&cat=development/cross
  17 e) Mingw32 libraries package (only for Cygwin).
  18 f) libiconv plus development files (only for MinGW - for building makecountry).
  19
  20  That's all. Execute "./configure --target=mingw32-<your_cpu>", then "make".
  21
  22  You can also crosscompile it under other OS. The only restriction (implied by configure script,
  23 needs to be fixed): build system CPU should be different from i386. Otherwise configure suggests native build
  24 and attempts to use host's gcc as a kernel compiler (one that builds a bootstrap and helper DLLs). Of course
  25 it won't work. For cross-compiling you need the same toolset as for native build, plus Mingw32-targetted
  26 crosscompiler. Currently cross-build is succesfully performed on Linux/x86-64 using native gcc v4.1.2 and
  27 both crosscompilers v4.2.2 (built from vanilla source tree).
  28
  29  2. RUNNING
  30
  31  In order to run AROS open a command line, go to root AROS directory ("AROS"), and run
  32 "boot\AROSBootstrap.exe". This port behaves like UNIX-hosted, it uses emul.handler, which
  33 makes your current directory to be root of your SYS:.
  34  You can specify some options on the command line for bootstrap and AROS. Enter
  35 "boot\AROSBootstrap.exe -h" to learn about them. --hostmem option currently does nothing.
  36
  37  3. HACKING
  38
  39  Here i'll describe how AROS should interact with host OS (Windows in our case). This is very tricky,
  40 however it all ends up in two simple rules when you get the whole picture.
  41
  42  3.1. Two simple rules.
  43
  44  1. If you need to call some WinAPI functions, enclose the call (or several calls if you do them in a batch)
  45 in Forbid()/Permit() pair. Otherwise you may get random sudden aborts (AROS just quits without any message).
  46  2. Do not call any operations that would block (I/O to serial/parallel ports for example). From the Windows'
  47 point of view the whole AROS is one thread. If you block it, the whole AROS gets non-responsive until it's
  48 unblocked. No task scheduling will occur at all.
  49
  50  3.2. Performing wait operations in Windows.
  51
  52  Often it's needed to wait for some event on Windows side. A good example of this is handling keyboard and mouse.
  53 You have to sit and wait until some message arrives. Another example could be serial port I/O (which can take rather
  54 long time). Such things are implemented using virtual hardware (VH). A VH unit is represented by asynchronous Windows
  55 thread that you create when you start up the driver (this is an equivalent of hardware discovery on a real machine).
  56 You can use anything in order to talk to this thread. The simplest and most efficient way to do it is having some
  57 structure in memory where you put the data and then signal to your VH thread to start working somehow (for example by
  58 triggering an event or posting a message to its queue). While your thread works, AROS works too. When your VH thread
  59 finishes its job, it should call KrnCauseIRQ() function from kernel_native.dll. This causes an IRQ on AROS side and
  60 AROS can read back the data from your structure.
  61  As you can see, this works exactly in the same way as real hardware.
  62  Note that thread switching in Windows seems to be rather slow, so avoid using VH threads if possible (for example you
  63 can use overlapped I/O with serial port, where Windows itself will play a role of VH thread, because in this case you
  64 may directly specify an event to signal when the I/O completes).
  65  Look at wingdi.hidd source code for a good example of VH implementation.
  66
  67  3.3. In-depth description of AROS task scheduler implementation.
  68
  69  As you can see, Windows-hosted AROS acts very much like AROS on real hardware. In fact it's little simple virtual machine.
  70 There are two Windows threads. One thread (let's call it "main thread") runs all AROS processes. In order to perform task
  71 switching there is a second Windows thread, representing a "CPU" (let's call it VCPU - virtual CPU). It sits in a loop
  72 waiting for several objects (these objects are emulated hardware IRQs). The first of them is a periodic 50Hz waitable timer,
  73 it's the heart of the virtual machine. Its IRQ is responsible for generating VBLANK interrupt in exec and counting quantums
  74 (this is also done in exec.library on AROS side). when any IRQ happens, VCPU stops main thread and remembers its CPU context.
  75 It's a supervisor mode, from this thread AROS interrupt handlers are called. After all processing it looks if task switching
  76 should be done. If yes, VCPU substitutes the context of main thread with the context of next scheduled AROS process. Then it
  77 resumes main thread.
  78  As a result, single Windows thread runs all AROS processes in turn (actually this thread represents user mode of virtual CPU).
  79  This is why it's necessary to enclose WinAPI calls in Forbid()/Permit() pair. Windows probably attempts to protect itself from
  80 hackers this way and keeps an eye on thread's context (mostly stack) during execution of a system call. If task switch occurs
  81 while main thread is inside a syscall (it's actually paused by Windows in this state), context swap happens. The syscall notices
  82 that the stack changes and silently aborts the whole process. As a result, AROS just silently quits without any error messages.
  83  Task switcher can be also run manually by RaiseException() WinAPI call, which has its reflection as krnSysCall() macro on
  84 AROS side. This is used by KrnSwitch(), KrnSchedule(), KrnDispatch() and KrnCause() functions.
  85  All other objects which VCPU waits on are simple triggerable events. They are managed dynamically by drivers using a special
  86 Windows-side API:
  87
  88  KrnAllocIRQ()     - Allocate an IRQ for the use with the driver.
  89  KrnFreeIRQ()      - Free an allocated IRQ (should be used when the driver releases resources and exits).
  90  KrnCauseIRQ()     - Cause an IRQ on AROS side.
  91  KrnGetIRQObject() - Obtain a HANDLE of the IRQ object. For an IRQ allocated by KrnAllocIRQ() it will be a simple triggerable
  92                      event. You may use this handle for example for overlapped I/O operations.
  93
  94   These are not AROS functions! They are legal to call only from within hardware emulation threads.
  95
  96   For more details see kernel.resource, i hope the code is clear enough.
  97
  98  20.09.2010, Pavel Fedin <pavel_fedin@mail.ru>