Return to README.PROGRAMMERS CVS log

Up to [UNIX Amiga Emulator] / uae / docs

Annotation of uae/docs/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 68020 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: - Improve the Kickstart replacement to boot more demos.
        !            40: - Snapshots as in CPE. Will need to collect all the variables containing
        !            41:   important information. Fairly easy, but boring. (Use core dumps instead :-)
        !            42: - Find out why uae.device has to be mounted manually with Kick 1.3.
        !            43:   The problem seems to be that we don't have a handler for it. I _think_ what
        !            44:   we need is the seglist of the standard filesystem handler. Problem is,
        !            45:   DOS hasn't been started when the devices are initialized and so we can't get
        !            46:   to the DosBase->RootNode->FileHandlerSeg pointer, and then there is the
        !            47:   confusing matter of BCPL GlobVecs and other weird stuff...
        !            48: - The playfield hardware is the only important part of the Amiga that is 
        !            49:   not really well documented in the HRM. Write some test programs that
        !            50:   do all sorts of weird things with the copper (like turning off bitplane 
        !            51:   DMA during a line, and turning it directly on again: VERY interesting
        !            52:   result) and try to emulate this perfectly.
        !            53:   Not _really_ necessary, I think: Surprisingly, and unlike 8 bit computer
        !            54:   software, Amiga programs usually seem to make use only of documented hardware
        !            55:   features.
        !            56: - Figure out a diskfile format that supports every possible non-standard
        !            57:   format.
        !            58: - Implement 68551 MMU. I have docs now. Not among the most necessary things.
        !            59: - Implement AGA support. Some bits and pieces exist.
        !            60: - Reimplement Amiga OS. (Well-behaved) Amiga programs could then be made
        !            61:   to use the X Window System as a "public screen". Of course, not all the
        !            62:   OS would have to be re-done, only Intuition/GFX. [Started, look at gfxlib.c]
        !            63: - Find some extremely clever ways to optimize the smart update methods. Maybe
        !            64:   try to support scrolling. Maybe find a way to update only parts of a line
        !            65:   (similar to LOW_BANDWIDTH). All such methods would probably be terribly
        !            66:   complicated, and not easy to get right without sacrificing compatibility.
        !            67:   Maybe it's not such a good idea.
        !            68: - Port it to Java and Emacs Lisp
        !            69: - A formal proof of correctness would be nice.
        !            70: 
        !            71: Things I don't really want to do:
        !            72: - Full ECS support, with braindamage like Productivity and SuperHires.
        !            73: 
        !            74: How it works
        !            75: 
        !            76: Let's start with the memory emulation. All addressable memory is split into
        !            77: banks of 64K each. Each bank can define custom routines accessing bytes, 
        !            78: words, and longwords. All banks that really represent physical memory just 
        !            79: define these routines to write/read the specified amount of data to a chunk 
        !            80: of memory. This memory area is organized as an array of WORDs, which means 
        !            81: that those parts of the emulator that want to access memory in a linear 
        !            82: fashion can get a (WORD *) pointer and use it to circumvent the overhead of
        !            83: the put_word() and get_word() calls. That is done, for example, in the
        !            84: pfield_doline() function which handles screen refreshes.
        !            85: Memory banks that represent hardware registers (such as the custom chip bank
        !            86: at 0xDF0000) can trap reads/writes and take any necessary actions.
        !            87: In some places, this scheme is abused: The uae.device and unixfs.device are
        !            88: stored in a segment at 0xF00000 containing a ROMtag structure, so it is
        !            89: recognized at bootup. Since this is a ROM area, writes shouldn't occur
        !            90: normally and are therefore used to trap into emulation routines for these
        !            91: devices.
        !            92: 
        !            93: To provide a good emulation of graphical effects, only one thing is vital:
        !            94: Copper and playfield emulation have to be kept absolutely synchronous. If the
        !            95: copper writes to (say) a color register in a specific cycle, the playfield 
        !            96: hardware needs to use the new information in the next word of data it 
        !            97: processes.
        !            98: UAE 0.1 used to call routines like do_pfield() and do_copper() each time the
        !            99: CPU emulator had finished an instruction. That was one of the reasons why it
        !           100: was so slow. Recent versions try to draw complete scanlines in one piece. This
        !           101: is possible if the copper does not write to any registers affecting the
        !           102: display during that scanline. Therefore, drawing the line is deferred until
        !           103: the last cycle of the line. If the copper writes to a hardware register before
        !           104: that, the function pfield_may_need_update() is called and this one determines
        !           105: whether it should fall back to the cycle-for-cycle approach. This is very
        !           106: rarely needed, mainly for copper-plasma effects and such, and the general case
        !           107: is much faster.
        !           108: 
        !           109: The CPU emulator no longer has to call all sorts of functions after each
        !           110: instruction. Instead, it keeps a list of events that are scheduled (timer
        !           111: interrupts, hsync and vsync events) and their "arrival time". Only the time
        !           112: for the next event is checked after each CPU instruction. If it's higher than
        !           113: the current cycle counter, the CPU can continue to execute.
        !           114: 
        !           115: 
        !           116: Portability
        !           117: 
        !           118: The main thing you need to worry about when porting UAE to a new platform is
        !           119: the OS dependent source file handling all the graphics output. Currently,
        !           120: there are xwin.c, svga.c, mac.c, dos-grx.c, dos-null.c, bebox.cpp and
        !           121: NeXTwin.m. Rewriting one of these to use the features of your operating
        !           122: system should be fairly easy.
        !           123: You might need to worry a little about datatypes. UAE requires that your C
        !           124: compiler supports 8 bit, 16 bit and 32 bit integers, otherwise a MC68000
        !           125: emulation would be not very easy to get right. Some typedefs to hide the
        !           126: actual types used can be found in amiga.h. The CPU emulation is not the only
        !           127: place that makes some potentially non-portable assumptions: The graphics
        !           128: code in custom.c, mainly the pfield_doline() function and its friends, may
        !           129: need some work if you have a really weird architecture.
        !           130: The only thing that's left are some Unixoid assumptions, mainly in
        !           131: filesys.c, but also in debug.c. Put in a few #ifdefs and modify the Makefile
        !           132: if necessary/possible, or make up a dummy unixfs-null.c file that contains 
        !           133: stubs.
        !           134: 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.