arch/all-mingw32/README.txt

   1  This file contains various notes about Windows-hosted port of AROS.
   2
   3  1. COMPILING
   4
   5  This port currently can only be compiled under Windows OS. In order to do this
   6 you need:
   7
   8 a) Working Cygwin environment (Mingw's MSYS is expected to work too but it's not tested).
   9 b) Netpbm package of course.
  10 c) AROS-targetted crosscompiler. Cygwin version of it can be found on AROS Archives:
  11    http://archives.aros-exec.org/index.php?function=browse&cat=development/cross
  12    I compile it using gcc version 3.3.1, however i beleive more recent versions will
  13    work too.
  14 d) Mingw32 libraries package for Cygwin.
  15
  16  That's all. Execute "./configure --target=mingw32-i386", than make.
  17
  18  2. RUNNING
  19
  20  In order to run AROS open a command line, go to root AROS directory ("AROS"), and run
  21 "boot\AROSBootstrap.exe". This port behaves like UNIX-hosted, it uses emul.handler, which
  22 makes your current directory to be root of your SYS:.
  23  You can specify some options on the command line for bootstrap and AROS. Enter
  24 "boot\AROSBootstrap.exe -h" to learn about them. --hostmem option currently does nothing.
  25
  26  3. HACKING
  27
  28  Here i'll describe how AROS should interact with host OS (Windows in our case). This is very tricky,
  29 however it all ends up in two simple rules when you get the whole picture.
  30
  31  3.1. Two simple rules.
  32
  33  1. If you need to call some WinAPI functions, enclose the call (or several calls if you do them in a batch)
  34 in Forbid()/Permit() pair. Otherwise you may get random sudden aborts (AROS just quits without any message).
  35  2. Do not call any operations that would block (I/O to serial/parallel ports for example). From the Windows'
  36 point of view the whole AROS is one thread. If you block it, the whole AROS gets non-responsive until it's
  37 unblocked. No task scheduling will occur at all.
  38
  39  3.2. Performing wait operations in Windows.
  40
  41  Often it's needed to wait for some event on Windows side. A good example of this is handling keyboard and mouse.
  42 You have to sit and wait until some message arrives. Another example could be serial port I/O (which can take rather
  43 long time). Such things are implemented using virtual hardware (VH). A VH unit is represented by asynchronous Windows
  44 thread that you create. You can use anything in order to talk to this thread. The simplest and most efficient way
  45 to do it is having some structure in memory where you put the data and then signal to your VH thread to start working
  46 somehow (for example by triggering an event or posting a message to its queue). While your thread works, AROS works too.
  47 When your VH thread finishes its job, it should call KrnCauseIRQ() function from kernel_native.dll. This causes an IRQ
  48 on AROS side and AROS can read back the data from your structure.
  49  As you can see, this works exactly in the same way as real hardware.
  50  Note that thread switching in Windows seems to be rather slow, so avoid using VH threads if possible (for example you
  51 can use overlapped I/O with serial port, where Windows itself will play a role of VH thread, because in this case you
  52 may directly specify an event to signal when the I/O completes). However corresponsind part in kernel_native.dll is not
  53 designed yet (you can't get pointer to IRQ event object), but this will change as soon as someone needs it.
  54  Look at wingdi.hidd source code for a good example of VH implementation.
  55
  56  3.3.In-depth description of AROS task scheduler implementation.
  57
  58  As you can see, Windows-hosted AROS acts very much like AROS on real hardware. In fact it's little simple virtual machine.
  59 There are two Windows threads. One thread (let's call it "main thread") runs all AROS processes. In order to perform task
  60 switching there is a second Windows thread, representing a "CPU" (let's call it VCPU - virtual CPU). It sits in a loop
  61 waiting for several objects (these objects are emulated hardware IRQs). The first of them is a periodic 50Hz waitable timer,
  62 it's the heart of the VM. Its IRQ is responsible for generating VBLANK interrupt in exec and counting quantums (this is also
  63 done in exec.library on AROS side). when any IRQ happens, VCPU stops main thread and remembers its CPU context. It's a supervisor
  64 mode, from this thread AROS interrupt handlers are called. After all processing it looks if task switching should be done.
  65 If yes, VCPU substitutes the context of main thread with the context of next scheduled AROS process. Then it resumes main thread.
  66  As a result, single Windowsthread runs all AROS processes in turn (actually this thread represents user mode of virtual CPU).
  67  This is why it's necessary to enclose WinAPI calls in Forbid()/Permit() pair. Windows probably attempts to protect itself from
  68 hackers this way and keeps an eye on thread's context (mostly stack) during execution of a system call. If task switch occurs
  69 while main thread is inside a sycall (it's actually paused by Windows in this state), context swap happens. The syscall notices
  70 that the stack changes and silently aborts the whole process. As a result, AROS just silently quits without any error messages.
  71  Task switcher can be also run manually by RaiseException() WinAPI call. This happens inside exec's Cause(), and is responsible
  72 for causing SoftInts.
  73  All other objects which VCPU waits on are simple triggerable events. They are triggered by KrnCauseIRQ() and are used by various
  74 drivers in order to communicate with VH threads. Currently their allocation is static, but dynamic allocation is really needed and
  75 will be implemented in future.
  76  For more details see kernel.resource, i hope the code is clear enough.
  77
  78  26.02.2009, Pavel Fedin <sonic.amiga@gmail.com>