uae/README.PROGRAMMERS - annotate

Return to README.PROGRAMMERS CVS log

Up to [UNIX Amiga Emulator] / uae

Annotation of uae/README.PROGRAMMERS, revision 1.1.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...

unix.superglobalmegacorp.com

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