Index: readme.txt
===================================================================
--- readme.txt	(revision d2b98395b419c8106dfd05f271daf2bc240dfa96)
+++ readme.txt	(revision d44e0013efd9bd49fb468b5195d1d3274e61d734)
@@ -209,2 +209,37 @@
 repository. Just in case you are interested in them, but would prefer
 not to go through the emulator exercise.
+
+
+Pitfalls
+--------
+
+There are a few differences between the Alcyon compiler and a
+modern-day GCC cross-compiler for the Motorola 68k.
+
+  * Alcyon uses 16-bit integers, whereas GCC defaults to 32-bit
+    integers. That's why we pass the -mshort option to GCC.
+
+  * The Alcyon compiler's ABI assumes that registers A2 and D2 are
+    saved by the caller of a function, if needed. GCC, however,
+    assumes that it's the called function that is responsible for
+    preserving A2 and D2.
+
+    Right now, we work around this issue by passing the -ffixed-d2 and
+    -ffixed-a2 options to GCC. This prevents GCC from using these two
+    registers at all when generating code.
+
+    Ultimately, we should fix the hand-written assembly language
+    functions to preserve A2 and D2, so that GCC code generation can
+    use all registers.
+
+  * The hand-written assembly language code expects C function names
+    to be prefixed with an underscore. That's why we pass the
+    -fleading-underscore option to GCC. However, this breaks linking
+    with libgcc, which doesn't use leading underscores.
+
+    Currently, we work around this issue by stripping the leading
+    underscore from references to libgcc functions using objcopy. See
+    misc/rewrite.txt for the function name mapping.
+
+    Ultimately, we should fix any references to C functions in the
+    hand-written assembly language code.