Return to README.PROGRAMMERS CVS log

Up to [UNIX Amiga Emulator] / uae

Annotation of uae/README.PROGRAMMERS, revision 1.1

1.1     ! root        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: - Some coding guidelines.
        !            11:   * Avoid GNU C extensions by all means. They make your code non-portable.
        !            12:   * Avoid GNU indentation style by all means. It makes your code unreadable.
        !            13:   * Try to indent your code nicely. There are editors like JED, which is
        !            14:     available from space.mit.edu:/pub/davis and highly recommendable, that do
        !            15:     this for you automatically.
        !            16:   * Use eight space tabs, four space tabs make a mess of the code.
        !            17: - If you have access to more than one Unix system, try compiling/running your
        !            18:   code on all of these. Remember, UAE is supposed to run on the DEC Alpha: so
        !            19:   don't assume sizeof(char*) == sizeof(int) == sizeof(long)
        !            20: - If you have more than one Kickstart, try your code with each one.
        !            21: - Patches are welcome in any form, but diff -u or diff -c output is preferred.
        !            22:   If I get whole source files, the first thing I do is to run diff on it. You 
        !            23:   can save me some work here (and make my mailbox smaller).
        !            24: 
        !            25: Some possible projects, in order of estimated difficulty:
        !            26: - Someone with a 68000 data sheet might check whether all opcodes are
        !            27:   decoded correctly and whether all instructions really do what they are 
        !            28:   supposed to do (I'm pretty sure it's OK by now, but you never know...).
        !            29: - Modify UAE to run in two threads for systems that have more than one CPU.
        !            30:   I've thought of a way how to do it, but I don't have a multiprocessor board
        !            31:   to try this. Here's how it works: Start with smart update method #1. This
        !            32:   method nicely bundles all the data necessary for drawing a scanline into two
        !            33:   structures: linedescr and line_data. Instead of actually drawing the line
        !            34:   in the main task, signal the second one to use that information. Synchronize
        !            35:   the two at the end of a frame to avoid lossage.
        !            36:   If I haven't overlooked a big problem, it should be trivial.
        !            37:   Sound output could also be moved into a separate task, but the gain will be
        !            38:   much smaller.
        !            39: - Implement all 68020 instructions/addressing modes. 
        !            40: - Improve the Kickstart replacement to boot more demos.
        !            41: - Write an Amiga program that communicates with UAE and provides a user-
        !            42:   interface similar to the X Windows one, but from within the emulation.
        !            43: - Calculating the flags after each instruction is time consuming and usually
        !            44:   completely unnecessary. Modify gencpu to generate instructions that don't
        !            45:   set the flags, and have some code in the central loop to decide which
        !            46:   set of instructions to use. This means additional overhead, of course,
        !            47:   which might eat any improvements. [Tried it, hardly a difference, but 
        !            48:   maybe I did it in a stupid way]
        !            49: - Translate Kickstart ROM (or any software) to C code with a slightly
        !            50:   modified gencpu, and link it to the rest of the emulator. Definitely 
        !            51:   possible, maybe illegal. Better don't do that for now.
        !            52: - Make a modified gencpu that can generate x86 assembly instead of C. This
        !            53:   might give a nice speedup. However, the CPU emulation already is the
        !            54:   fastest part in UAE - screen updates are much more time consuming.
        !            55:   [Partly done, some __asm__ magic for flag calculations. Bad for performance
        !            56:   are all the unnecessary register push/pops that the compiler generates.]
        !            57: - Improve sound emulation (Find bugs).
        !            58: - Snapshots as in CPE. Will need to collect all the variables containing
        !            59:   important information. Fairly easy, but boring. (Use core dumps instead :-)
        !            60: - Find out why uae.device doesn't work with Kick 1.3. Not really important,
        !            61:   no one in his right mind uses it anyway now there is the unixfs.device
        !            62: - Make unixfs.device bootable.
        !            63: - The playfield hardware is the only important part of the Amiga that is 
        !            64:   not really well documented in the HRM. Write some test programs that
        !            65:   do all sorts of weird things with the copper (like turning off bitplane 
        !            66:   DMA during a line, and turning it directly on again: VERY interesting
        !            67:   result) and try to emulate this perfectly.
        !            68: - Figure out a diskfile format that supports every possible non-standard
        !            69:   format.
        !            70: - Translate basic blocks of m68k instructions to intermediate code that is 
        !            71:   interpreted instead of the actual code. Optimize it of course.
        !            72:   (Not sure whether it would really be faster. But ARDI's Executor does
        !            73:   a splendid job on translation. This should really help even if the target
        !            74:   code isn't native).
        !            75: - Implement 68551 MMU. I have docs now. Not among the most necessary things.
        !            76: - Implement 68882 FPU. Not among the most necessary items, either. (Some docs)
        !            77: - Implement AGA support. Maybe some easy parts can be tried first (like 8
        !            78:   bitplane support). I have sufficient documentation by now.
        !            79: - Reimplement Amiga OS. (Well-behaved) Amiga programs could then be made
        !            80:   to use the X Window System as a "public screen". Of course, not all the
        !            81:   OS would have to be re-done, only Intuition/GFX. [Started, look at gfxlib.c]
        !            82: - Translate instructions on the fly to native code, like Executor does.
        !            83:   I'll NEVER try that one myself.
        !            84: - Find some extremely clever ways to optimize the smart update methods. Maybe
        !            85:   try to support scrolling. Maybe find a way to update only parts of a line
        !            86:   (similar to LOW_BANDWIDTH). All such methods would probably be terribly
        !            87:   complicated, and not easy to get right without sacrificing compatibility.
        !            88:   Maybe it's not such a good idea.
        !            89: - Port it to Java
        !            90: - A formal proof of correctness would be nice.
        !            91: 
        !            92: Things I don't really want to do:
        !            93: - Full ECS support, with braindamage like Productivity and SuperHires.
        !            94: 
        !            95: How it works
        !            96: 
        !            97: Let's start with the memory emulation. All addressable memory is split into
        !            98: banks of 64K each. Each bank can define custom routines accessing bytes, 
        !            99: words, and longwords. All banks that really represent physical memory just 
        !           100: define these routines to write/read the specified amount of data to a chunk 
        !           101: of memory. This memory area is organized as an array of WORDs, which means 
        !           102: that those parts of the emulator that want to access memory in a linear 
        !           103: fashion can get a (WORD *) pointer and use it to circumvent the overhead of
        !           104: the put_word() and get_word() calls. That is done, for example, in the
        !           105: pfield_doline() function which handles screen refreshes.
        !           106: Memory banks that represent hardware registers (such as the custom chip bank
        !           107: at 0xDF0000) can trap reads/writes and take any necessary actions.
        !           108: In some places, this scheme is abused: The uae.device and unixfs.device are
        !           109: stored in a segment at 0xF00000 containing a ROMtag structure, so it is
        !           110: recognized at bootup. Since this is a ROM area, writes shouldn't occur
        !           111: normally and are therefore used to trap into emulation routines for these
        !           112: devices.
        !           113: 
        !           114: To provide a good emulation of graphical effects, only one thing is vital:
        !           115: Copper and playfield emulation have to be kept absolutely synchronous. If the
        !           116: copper writes to (say) a color register in a specific cycle, the playfield 
        !           117: hardware needs to use the new information in the next word of data it 
        !           118: processes.
        !           119: UAE 0.1 used to call routines like do_pfield() and do_copper() each time the
        !           120: CPU emulator had finished an instruction. That was one of the reasons why it
        !           121: was so slow. Recent versions try to draw complete scanlines in one piece. This
        !           122: is possible if the copper does not write to any registers affecting the
        !           123: display during that scanline. Therefore, drawing the line is deferred until
        !           124: the last cycle of the line. If the copper writes to a hardware register before
        !           125: that, the function pfield_may_need_update() is called and this one determines
        !           126: whether it should fall back to the cycle-for-cycle approach. This is very
        !           127: rarely needed, mainly for copper-plasma effects and such, and the general case
        !           128: is much faster.
        !           129: 
        !           130: The CPU emulator no longer has to call all sorts of functions after each
        !           131: instruction. Instead, it keeps a list of events that are scheduled (timer
        !           132: interrupts, hsync and vsync events) and their "arrival time". Only the time
        !           133: for the next event is checked after each CPU instruction. If it's higher than
        !           134: the current cycle counter, the CPU can continue to execute.
        !           135: 
        !           136: 
        !           137: Portability
        !           138: 
        !           139: The main thing you need to worry about when porting UAE to a new platform is
        !           140: the OS dependent source file handling all the graphics output. Currently,
        !           141: there are xwin.c, svga.c, mac.c, dos-grx.c, dos-null.c, bebox.cpp and
        !           142: NeXTwin.m. Rewriting one of these to use the features of your operating
        !           143: system should be fairly easy.
        !           144: You might need to worry a little about datatypes. UAE requires that your C
        !           145: compiler supports 8 bit, 16 bit and 32 bit integers, otherwise a MC68000
        !           146: emulation would be not very easy to get right. Some typedefs to hide the
        !           147: actual types used can be found in amiga.h. The CPU emulation is not the only
        !           148: place that makes some potentially non-portable assumptions: The graphics
        !           149: code in custom.c, mainly the pfield_doline() function and its friends, may
        !           150: need some work if you have a really weird architecture.
        !           151: The only thing that's left are some Unixoid assumptions, mainly in
        !           152: filesys.c, but also in debug.c. Put in a few #ifdefs and modify the Makefile
        !           153: if necessary/possible, or make up a dummy unixfs-null.c file that contains 
        !           154: stubs.
        !           155: Apart from all that, it's fairly portable...

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.