Differences

This shows you the differences between two versions of the page.

--- blog:pushbx:2022:0826_dual_code_segments_mechanisms [2022-08-26 01:21:03 +0200 Aug Fri]
ecm created
+++ blog:pushbx:2022:0826_dual_code_segments_mechanisms [2022-08-26 21:37:33 +0200 Aug Fri] (current)
ecm boot-loaded, far-like mode switching reworded, section_of for unused symbols, example
@@ Line 41: / Line 41: @@
 for three reasons:
-  - Allowing boot loaded mode where no MZ loader is used.
+  - Allowing boot-loaded mode where no MZ loader is used.
   - Allowing the debugger to be compressed without parsing relocations into the depacker.
   - Allowing to dynamically determine the layout and placement of the code segments at run time instead of leaving them fixed relative to the PSP.
@@ Line 73: / Line 73: @@
 The dual return helper examines the index and replaces it
 by the desired segment or selector to which to return.
-This complication serves the possible need for calls to be made
+This complication allows any function
-which switch modes in the debugger's control flow.
+to switch modes
+(from Real/Virtual 86 Mode to Protected Mode, or vice versa).
+The possible need for this was determined
+important enough to support such uses,
+although no current users are known.
 The index supports both modes.
 An actual segment or selector value is inserted to replace
@@ Line 89: / Line 93: @@
 The ''section_of_function'' macro is used at a function's definition
 to verify that the correct section was specified.
+''section_of'' may be used even when the specified function
+does not exist, for example when it is not included
+due to the current build options.
+A label specified with the ''section_of_function'' macro,
+however, must correspond to an earlier use of ''section_of''.
+===== Examples =====
+This example is based on
+[[https://hg.pushbx.org/ecm/ldebug/rev/e60574d47874#l1.7|the initial revision]]
+that introduced the dual code sections support.
+This is what the ''bu_relocated'' function would look like
+as a normal, near-callable function
+within the single ''lDEBUG_CODE'' section:
+<code>bu_relocated:
+	lframe near
+	lpar word, sign
+	lenter
+	mov ax, word [bp + ?sign]
+	mov di, msg.bu_relocated.sign
+	call hexword
+	mov dx, msg.bu_relocated
+	call putsz
+	lleave
+	lret</code>
+Note that this hardcodes a near stack frame. And this is how it would be called:
+<code>	mov ax, 2642h
+	 push ax
+	call bu_relocated</code>
+Next, here's how to change it to a dual-callable function
+which goes into the ''lDEBUG_CODE2'' section
+if that is used:
+<code>%if _DUALCODE
+	usesection lDEBUG_CODE2
+%endif
+section_of bu_relocated
+dualfunction
+bu_relocated:
+	lframe dualdistance
+	lpar word, sign
+	lenter
+	mov ax, word [bp + ?sign]
+	mov di, msg.bu_relocated.sign
+	nearcall hexword
+	mov dx, msg.bu_relocated
+	nearcall putsz
+	lleave
+	dualreturn
+	lret</code>
+And this is a caller:
+<code>	mov ax, 2642h
+	 push ax
+	dualcall bu_relocated</code>
+Note the uses of ''dualdistance'' and ''dualreturn''.
+When this source is compiled with dual code segments enabled,
+the distance of the stack frame will be far instead.
+If the build is DPMI-capable then
+the ''dualcall'' helper function
+will push a far-like return address,
+which the ''dualreturn'' helper will then
+convert into a segmented far return address.
+The ''lret'' will expand to a ''retf 2'' in this case.
+Converting function calls to use the ''nearcall'' method
+only involves replacing plain ''call'' instructions
+by the ''nearcall'' macro invocation,
+as well as specifying the correct sections
+with ''section_of''.
+As mentioned, a function must not use ''lpar'' parameters
+on its stack in order to call it using ''nearcall''.
 {{tag>ldebug segmentation}}

pushbx wiki

User Tools

Site Tools

Differences

Page Tools