From 59fb8753bcfc3ddcf7670a2ebc7d5ae69e3110fd Mon Sep 17 00:00:00 2001
From: nmlgc <nmlgc@nmlgc.net>
Date: Thu, 4 Feb 2021 20:16:03 +0100
Subject: [PATCH] [Maintenance] Only use the `far` keyword to declare intent

Part of P0134, funded by [Anonymous].
---
 CONTRIBUTING.md            | 8 ++++++++
 th01/hardware/frmdely.c    | 2 +-
 th01/hardware/graph.cpp    | 2 +-
 th01/hardware/ptrans.hpp   | 4 +---
 th01/hardware/ptrans_d.cpp | 4 +---
 th01/main/boss/nop.cpp     | 2 +-
 th02/frmdely2.c            | 2 +-
 th02/hardware/frmdelay.h   | 4 ++--
 th04/formats/bb_stage.c    | 2 +-
 th04/frmdely2.c            | 2 +-
 th04/main/rank.hpp         | 5 ++---
 th05/frmdelay.cpp          | 2 +-
 12 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1e8d7b2f..a622acfb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -233,6 +233,14 @@ C++, Open Watcom, and Visual C++, which will ease future third-party ports.
   }
   ```
 
+* All original `.EXE` binaries use the *large* memory model, meaning that both
+  function and data pointers are `far` by default. Therefore, pointers and
+  references should only explicitly be declared `far` if
+
+  1. they are actually constructed from a segment and an offset via the two
+     methods above, or
+  2. the code performs segment/offset arithmetic on them.
+
 ## Naming conventions
 
 * ASM file extensions: `.asm` if they emit code, `.inc` if they don't
diff --git a/th01/hardware/frmdely.c b/th01/hardware/frmdely.c
index 6ee4a95d..2bc34528 100644
--- a/th01/hardware/frmdely.c
+++ b/th01/hardware/frmdely.c
@@ -3,7 +3,7 @@
 #define z_vsync_reset1() (vsync_frame = 0)
 // #define z_vsync_reset2() (vsync_unused = 0)
 
-void far frame_delay(unsigned int frames)
+void frame_delay(unsigned int frames)
 {
 	while(vsync_frame < frames) {}
 	z_vsync_reset1();
diff --git a/th01/hardware/graph.cpp b/th01/hardware/graph.cpp
index d73b22a8..c3f8a6c5 100644
--- a/th01/hardware/graph.cpp
+++ b/th01/hardware/graph.cpp
@@ -741,7 +741,7 @@ void graph_putsa_fx(
 	register screen_x_t x = left;
 	uint16_t codepoint;
 	dots16_t glyph_row;
-	unsigned char far *vram;
+	dots8_t far *vram;
 	int fullwidth;
 	int first_bit;
 	int weight = fx_weight_from(col_and_fx);
diff --git a/th01/hardware/ptrans.hpp b/th01/hardware/ptrans.hpp
index 681cc828..eeb35d21 100644
--- a/th01/hardware/ptrans.hpp
+++ b/th01/hardware/ptrans.hpp
@@ -7,8 +7,6 @@
 // each animation frame.
 void pagetrans_diagonal_8x8(unsigned int step_ms);
 void pagetrans_diagonal_8x8_with_palette(
-	unsigned int step_ms,
-	Palette4 far &pal_cur,
-	const Palette4 far &pal_target
+	unsigned int step_ms, Palette4 &pal_cur, const Palette4 &pal_target
 );
 // -----------------------------------------------
diff --git a/th01/hardware/ptrans_d.cpp b/th01/hardware/ptrans_d.cpp
index a09c09e8..3fea37a5 100644
--- a/th01/hardware/ptrans_d.cpp
+++ b/th01/hardware/ptrans_d.cpp
@@ -44,9 +44,7 @@ static const int FRAME_COUNT = (
 );
 
 void pagetrans_diagonal_8x8_with_palette(
-	unsigned int step_ms,
-	Palette4 far &pal_cur,
-	const Palette4 far &pal_target
+	unsigned int step_ms, Palette4 &pal_cur, const Palette4 &pal_target
 )
 {
 	int comp;
diff --git a/th01/main/boss/nop.cpp b/th01/main/boss/nop.cpp
index 45e888c7..36752990 100644
--- a/th01/main/boss/nop.cpp
+++ b/th01/main/boss/nop.cpp
@@ -1,5 +1,5 @@
 #include "th01/main/boss/boss.hpp"
 
-void far boss_nop(void)
+void boss_nop(void)
 {
 }
diff --git a/th02/frmdely2.c b/th02/frmdely2.c
index 415f618d..ca3c48bb 100644
--- a/th02/frmdely2.c
+++ b/th02/frmdely2.c
@@ -3,7 +3,7 @@
 #include "master.hpp"
 #include "th02/hardware/frmdelay.h"
 
-void pascal far frame_delay_2(int frames)
+void pascal frame_delay_2(int frames)
 {
 	vsync_reset1();
 	while(vsync_Count1 < frames) {}
diff --git a/th02/hardware/frmdelay.h b/th02/hardware/frmdelay.h
index 174cdf12..07394e61 100644
--- a/th02/hardware/frmdelay.h
+++ b/th02/hardware/frmdelay.h
@@ -1,2 +1,2 @@
-void pascal far frame_delay(int frames);
-void pascal far frame_delay_2(int frames);
+void pascal frame_delay(int frames);
+void pascal frame_delay_2(int frames);
diff --git a/th04/formats/bb_stage.c b/th04/formats/bb_stage.c
index 450a2ba1..a6df3e3a 100644
--- a/th04/formats/bb_stage.c
+++ b/th04/formats/bb_stage.c
@@ -1,6 +1,6 @@
 extern bb_seg_t bb_stage_seg;
 
-void pascal near bb_stage_load(const char far* fn)
+void pascal near bb_stage_load(const char *fn)
 {
 #if GAME == 5
 	bb_stage_seg = bb_load(fn);
diff --git a/th04/frmdely2.c b/th04/frmdely2.c
index a43e458b..095585fe 100644
--- a/th04/frmdely2.c
+++ b/th04/frmdely2.c
@@ -5,7 +5,7 @@
 #include "master.hpp"
 #include "th02/hardware/frmdelay.h"
 
-void pascal far frame_delay_2(int frames)
+void pascal frame_delay_2(int frames)
 {
 	vsync_reset1();
 	while(vsync_Count1 < frames) {}
diff --git a/th04/main/rank.hpp b/th04/main/rank.hpp
index 0903af90..0c29a33d 100644
--- a/th04/main/rank.hpp
+++ b/th04/main/rank.hpp
@@ -2,7 +2,6 @@
 
 extern unsigned char rank;
 
-int pascal far select_for_rank(
-	int for_easy, int for_normal,
-	int for_hard, int for_lunatic
+int pascal select_for_rank(
+	int for_easy, int for_normal, int for_hard, int for_lunatic
 );
diff --git a/th05/frmdelay.cpp b/th05/frmdelay.cpp
index 319ca515..0ef8e3b9 100644
--- a/th05/frmdelay.cpp
+++ b/th05/frmdelay.cpp
@@ -5,7 +5,7 @@ extern "C" {
 #include "master.hpp"
 #include "th02/hardware/frmdelay.h"
 
-void pascal far frame_delay(int frames)
+void pascal frame_delay(int frames)
 {
 	_BX = _SP;
 	__asm { mov bx, ss:[bx+4]; } /* = */ (frames);