home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / u / uae / Docs / README_PRO < prev    next >
Text File  |  1997-06-06  |  17KB  |  314 lines
  1. You can help to make this program better. If you fix bugs or implement new
  2. features, I'd be grateful if you send me patches. For a list of interesting
  3. projects, and for a brief summary on how UAE works, see below.
  4.  
  5. A few guidelines for anyone who wants to help:
  6. - Please contact me first before you implement major new features. Someone 
  7.   else might be doing the same thing already. This has already happened :-(
  8.   Even if no one else is working on this feature, there might be alternative
  9.   and better/easier/more elegant ways to do it.
  10. - If you have more than one Kickstart, try your code with each one.
  11. - Patches are welcome in any form, but diff -u or diff -c output is preferred.
  12.   If I get whole source files, the first thing I do is to run diff on it. You 
  13.   can save me some work here (and make my mailbox smaller).
  14.  
  15. Some possible projects, in order of estimated difficulty:
  16. - Someone running *BSD on a x86 might want to try using X86.S on such a
  17.   system. It's likely that only configure needs to be modified.
  18. - Add gamma correction
  19. - Repair support of the serial interface. Sending data seems to work,
  20.   receiving does not. Maybe this has to be implemented in a completely 
  21.   different way (a serial.device? If you do that, don't do it native. At least
  22.   not all of it. Amiga libraries shouldn't be implemented completely native
  23.   in UAE, the parts which are not speed critical should be Amiga native so
  24.   they can call other 68k code safely).
  25. - Someone with a 68020 data sheet might check whether all opcodes are
  26.   decoded correctly and whether all instructions really do what they are 
  27.   supposed to do (I'm pretty sure it's OK by now, but you never know...).
  28. - Add 2.0 packets to filesys.c
  29. - Multi-thread support is there now, it just needs someone to test it on a SMP
  30.   machine and to fix it so it improves speed instead of slowing the thing 
  31.   down.
  32. - Improve the Kickstart replacement to boot more demos.
  33. - Snapshots as in CPE. Will need to collect all the variables containing
  34.   important information. Fairly easy, but boring. (Use core dumps instead :-)
  35.   _If_ someone attempts this, please be more clever than the various CPC
  36.   emulators and dump state only at one fixed point in the frame, preferrably
  37.   the vsync point.
  38. - Find out why uae.device has to be mounted manually with Kick 1.3.
  39.   The problem seems to be that we don't have a handler for it. I _think_ what
  40.   we need is the seglist of the standard filesystem handler. Problem is,
  41.   DOS hasn't been started when the devices are initialized and so we can't get
  42.   to the DosBase->RootNode->FileHandlerSeg pointer, and then there is the
  43.   confusing matter of BCPL GlobVecs and other weird stuff...
  44. - Some incompatibilities might be fixed with user-modifiable fudge variables
  45.   the same way it's done in various C64 emulators.
  46. - With the new display code, it would probably be easier than before to
  47.   implement ECS resolutions - however, a lot of places rely on the OCS timing
  48.   parameters and display sizes.
  49. - Figure out a diskfile format that supports every possible non-standard
  50.   format.
  51. - Implement 68551 MMU. I have docs now. Not among the most necessary things.
  52.   Difficult, at least without using C++ exception handling.
  53. - Implement AGA support. Some bits and pieces exist.
  54. - Reimplement Amiga OS. (Well-behaved) Amiga programs could then be made
  55.   to use the X Window System as a "public screen". Of course, not all the
  56.   OS would have to be re-done, only Intuition/GFX/Layers (which is enough). 
  57.   [Started, look at gfxlib.c - not usable yet.]
  58. - Find some extremely clever ways to optimize the smart update methods. Some
  59.   ideas:
  60.   a) Always use memcmpy() to check for bitplane differences. If no differences
  61.      are found, see if BPLxDELAY got modified, if so, scroll.
  62.      Problems: 
  63.       * You'd still have to draw a few pixels around the DIW borders. Not very
  64.         hard.
  65.       * Scrolling with memcpy in video memory can be terribly slow (no, I
  66.         shouldn't have bought the cheaper video card with DRAMs)
  67.       * At least every 15 pixels a full update has to be done since the
  68.         bitplane pointers get updated after that. And that's with the slowest
  69.     scrolling - if the playfield scrolls faster, the benefit converges
  70.     against zero.
  71.      You could also do vertical scrolling tests, but similar problems arise - 
  72.      where should one check? One line above/below? What about faster
  73.      scrolling? You could use the bitplane pointers as hints, but with
  74.      double/triple buffering this gets problematic, too.
  75.      On the whole, I don't think it would be worth the effort, even if it
  76.      works very well for a few games.
  77.   b) Well, there is no b). If I thought of something I forgot it while
  78.      writing a).
  79. - Port it to Java and Emacs Lisp
  80. - A formal proof of correctness would be nice.
  81.  
  82.  
  83. Source file layout
  84.  
  85. src/      contains (mostly) machine-independent C code.
  86. include/  contains header files included by C code.
  87. md-*/     CPU and compiler dependent files, linked to machdep by configure
  88. od-*/     operating system dependent files, linked to osdep by configure
  89. td-*/     thread library dependent files, linked to threaddep by configure
  90. sd-*/     Sound code. sd-* is only for sound systems which are not OS specific
  91.           or for which no "od-*" directory exists. Linked to sounddep
  92. targets/  Contains header files which contain some information about which
  93.           options a specific port of UAE understands.
  94.  
  95.  
  96. Coding style
  97.  
  98. As long as your code is hidden in a file buried in md-*/ or od-*/ where I
  99. never have a look at it, you can probably get away with not following these
  100. guidelines. 
  101.  
  102. * Do not include CR characters.
  103. * Do not use GNU C extensions if you can't hide them in a macro or in a
  104.   system-specific file so that an alternative implementation is available
  105.   when GNU C is not used.
  106.   This applies to _all_ OS/CPU/compiler specific details. Basically, nothing
  107.   of that sort should appear in src/*.c (we're a bit away from that goal at
  108.   the moment, but it's getting better).
  109. * Make sure your code does not make assumption about type sizes other than
  110.   the minimum widths allowed by C. If you need specific type sizes, use the
  111.   uae_u32 type and its friends.
  112. * Set up your editor so that tab characters round up to the next position
  113.   where ((cursorx-1) % 8) == 0, i.e. 8 space tabs. Do not use 4 space tabs,
  114.   that makes the code awful to read on other machines and worse to edit.
  115. * Lines can be up to 132 characters wide. Use SVGATextMode for the Linux
  116.   console, or use a windowing system in a high resolution.
  117. * Indentation - look at some code in custom.c and try to follow it. Don't
  118.   use GNU 2-space-in-weird-places indentation, I find it awful. But _do_
  119.   follow the GNU rules for adding whitespace in expressions, and those for
  120.   breaking up multiple-line if statements.
  121.   Fixed indentation rules almost never make sense - break the rules if that
  122.   makes your code more readable.
  123.   Hint: Get jed from space.mit.edu, /pub/davis. It can indent your code
  124.   automatically. Put the following into your .jedrc, and it will come out
  125.   right:
  126.   C_INDENT        = 4;
  127.   C_BRACE        = 0;
  128.   C_BRA_NEWLINE        = 0;
  129.   C_Colon_Offset    = 1;
  130.   C_CONTINUED_OFFSET    = 4;
  131.  
  132.  
  133. How it works
  134.  
  135. Let's start with the memory emulation. All addressable memory is split into
  136. banks of 64K each. Each bank can define custom routines accessing bytes, 
  137. words, and longwords. All banks that really represent physical memory just 
  138. define these routines to write/read the specified amount of data to a chunk 
  139. of memory. This memory area is organized as an array of uae_u8, which means 
  140. that those parts of the emulator that want to access memory in a linear 
  141. fashion can get a (uae_u8 *) pointer and use it to circumvent the overhead of
  142. the put_*() and get_*() calls. That is done, for example, in the
  143. pfield_doline() function which handles screen refreshes.
  144. Memory banks that represent hardware registers (such as the custom chip bank
  145. at 0xDF0000) can trap reads/writes and take any necessary actions.
  146. In some places, this scheme is abused: The uae.device and unixfs.device are
  147. stored in a segment at 0xF00000 containing a ROMtag structure, so it is
  148. recognized at bootup. Since this is a ROM area, writes shou