From 0e59b9a61f936cf02cd225a56f2ff36c76a25e0f Mon Sep 17 00:00:00 2001
From: Jonathan Campbell <jonathan@castus.tv>
Date: Sun, 27 Nov 2016 10:42:26 -0800
Subject: [PATCH] readme

---
 tiny-model-readme.txt | 100 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 tiny-model-readme.txt

diff --git a/tiny-model-readme.txt b/tiny-model-readme.txt
new file mode 100644
index 000000000..5fd4720d2
--- /dev/null
+++ b/tiny-model-readme.txt
@@ -0,0 +1,100 @@
+Notes regarding DOSLIB's 16-bit tiny model builds.
+
+Watcom C does not natively have a "tiny" model, though
+the linker does when generating a .COM file.
+
+The problem, is that anything involving FAR pointers
+or references generates segment base relocations, which
+the .COM linker ignores. If not rectified, the resulting
+binary will crash.
+
+Things that trigger Watcom C to generate far segment
+relocations:
+
+  - declaring variables as "far"
+
+    example: unsigned char far somearray[1024];
+
+  - typecasting a function or variable from near to far
+
+    example: void far *ptr = (void far*)(&var);
+
+  - calling a function with a parameter that takes a
+    far pointer, and passing a near pointer (near to
+    far conversion as part of the function call).
+
+    example:
+
+            void interrupt vecthandler() { /* function is "near", in DGROUP */
+                ...
+            }
+
+            ...
+            _dos_setvect(0xAA,vecthandler);
+
+The Open Watcom V2's stance on generating segment
+relocations is understandable: the small memory model
+acts the way it does and a lot of code relies on it.
+Making the compiler assume CS = DGROUP and load segment
+registers would break that. However, that means no
+official support for what I'm trying to do for the
+tiny model.
+
+DOSLIB's tiny model is explicitly defined as like the
+small memory model, but with the strict limitation that
+CS = DS = DGROUP, therefore, no segment relocations
+are needed at runtime to do near to far conversions,
+because the code can always pull it out of CS.
+
+To accomplish that, a patching tool is included in this
+project. The tool reads the symbol information, and then
+uses the FIXUP table to patch opcodes in the code segment
+so that the code loads from CS instead of a 16-bit immediate
+word that the EXE relocation table would *normally* overwrite
+with the segment value. The patched OBJ is then written back
+over the original, and then linked into the final binary
+to produce a working .COM executable. The tool is named
+"OMFSEGDG", or "OMF segment DGROUP patching utility".
+
+To avoid corrupting the code, or making patches that are
+unreasonable, the tool enforces the rule that it will only
+patch a segment relocation if:
+
+  * The FIXUP refers to the TEXT segment, or a segment
+    that is of the CODE class.
+
+  * It's an EXTERN reference (it can't know until final
+    linking where the EXTERN goes, so as part of the tiny
+    model, it must assume it's in the same DGROUP)
+
+  * The FIXUP refers to the DGROUP segment group.
+
+For any other case, it will refuse to patch that segment
+relocation, and will print a warning.
+
+In this project, OBJ files generated by both Open Watcom
+C and NASM are patched in the tiny memory model target
+to make them usable in a .COM executable model.
+
+===== KNOWN ISSUES WITH TINY MODEL =====
+
+ * Watcom C's floating point library (8087 emulation)
+
+   You may see a warning in the .map file and on the console
+   about the floating point emulator. There is nothing I
+   can do about that at this time, however, I have yet to
+   see any issues appear.
+
+   For the time being, to be safe, try not to use floating
+   point in your tiny model targets.
+
+ * far-declared variables cannot be fixed up in this manner
+
+   If you declare a variable of type "far", Watcom C will
+   usually create a new SEGDEF for that variable which will
+   not be part of DGROUP, and therefore will not be patchable
+   for the tiny memory model.
+
+   At this time, OMFSEGDG does not yet recognize this case,
+   and the resulting binary will fail and possibly crash.
+