334 lines
11 KiB
Plaintext
334 lines
11 KiB
Plaintext
|
|
|
|
How to write flat 32->16 thunks
|
|
|
|
1. INTRO
|
|
--------------------------------------------------------------------
|
|
|
|
|
|
- What are flat 32->16 thunks?
|
|
|
|
THUNK.EXE is really three compilers that share a common parser.
|
|
This file describes the "flat thunk" mode, which generates 32->16
|
|
thunks that are mostly 32-bit (the other two modes are 16->32 thunks
|
|
and 32->16 thunks that are mostly 16-bit).
|
|
|
|
|
|
- Why should I use flat thunks?
|
|
|
|
Flat thunks do most of their work in 32-bit mode. This means better
|
|
performance since they use a minimum number of selector loads
|
|
and replace far16 calls with near32 calls. Also, the
|
|
flat compiler is an aggressive optimizer: early results show
|
|
a 30-40% code size reduction over the 16-bit code generator.
|
|
|
|
|
|
- Then why use 16-bit 32->16 thunks at all?
|
|
|
|
Approximately 200 thunks in Chicago have hand-coded portions which
|
|
need to be ported by hand to 32-bit mode. For compatibility,
|
|
16-bit thunks will be with us for some time to come.
|
|
|
|
|
|
- Can I have both 16-bit and 32-bit thunks in my component?
|
|
|
|
Yes, but you will need two thunk scripts: one for the 16-bit thunks
|
|
and one for the 32-bit thunks. There is no way to mix types in a single
|
|
script.
|
|
|
|
|
|
- How does the thunk compiler work?
|
|
|
|
The thunk compiler's input is a "thunk script", which is a list
|
|
of C-style function prototypes and typedefs. It outputs a .asm file which
|
|
is really two .asm files in one. Assemble it with the "-DIS_16"
|
|
flag and you get a 16-bit .obj which you link into your 16-bit
|
|
component. Assemble it with the "-DIS_32" flag and you get a 32-bit
|
|
.obj which you link into your 32-bit component.
|
|
|
|
The 16-bit component contains a jump table containing the 16:16
|
|
address of each function named in your thunk scripts (these functions
|
|
must exist elsewhere as PASCAL functions in your 16-bit component).
|
|
The 32-bit half contains a STDCALL function for each thunk which
|
|
converts its parameters to 16-bit and then calls (through some
|
|
kernel32 magic) the 16-bit target named in the jump table. When
|
|
a 32-bit app invokes a thunked api, it calles these compiler-generated
|
|
STDCALL functions directly.
|
|
|
|
For example, the thunk declaration for the LineTo api looks like this:
|
|
|
|
typedef int INT;
|
|
typedef unsigned int UINT;
|
|
typedef UINT HANDLE;
|
|
typedef HANDLE HDC;
|
|
|
|
BOOL LineTo(HDC, INT, INT) =
|
|
BOOL LineTo(HDC, INT, INT)
|
|
{
|
|
}
|
|
|
|
The first function "prototype" declares the form of the 16-bit target
|
|
and second declares the form the of the 32-bit target. As in most
|
|
thunks, the two prototypes are identical. Like the C compiler, the
|
|
thunk compiler interprets "int" as "short" in the 16-bit prototype
|
|
and "long" in the 32-bit prototype.
|
|
|
|
When this is fed through the thunk compiler, this is what pops out.
|
|
On the 16-bit half, there is a jump table:
|
|
|
|
externDef LineTo:far16
|
|
|
|
FT_GdiFThkTargetTable:
|
|
...
|
|
dw offset LineTo
|
|
dw seg LineTo
|
|
|
|
and LineTo is (say) entry #79. The 32-bit half contains the code:
|
|
|
|
|
|
; LineTo(16) = LineTo(32) {}
|
|
;
|
|
; dword ptr [ebp+8]: param1
|
|
; dword ptr [ebp+12]: param2
|
|
; dword ptr [ebp+16]: param3
|
|
;
|
|
public LineTo@12
|
|
LineTo@12:
|
|
FAPILOG16 1377 ;DEBUG only -- log api call
|
|
push ebp
|
|
mov ebp,esp
|
|
sub esp,40 ;Work-space for kernel32
|
|
push word ptr [ebp+8] ;param1: dword->word
|
|
push word ptr [ebp+12] ;param2: dword->word
|
|
push word ptr [ebp+16] ;param3: dword->word
|
|
mov cl,79 ;Thunk index
|
|
call QT_Call16_ShortToLong
|
|
leave
|
|
ret 12
|
|
|
|
When a Win32 app calls "LineTo", it transfers directly to this
|
|
routine, which builds a 16-bit call frame and calls a local routine
|
|
asking it to please invoke api #79 in the 16-bit jump table and
|
|
sign-extend the return value (each component gets its own set
|
|
of QT_ routines which knows what jump table to use.)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2. PROCEDURE FOR ADDING FLAT THUNKS
|
|
------------------------------------------------------------------------
|
|
|
|
1. Write a thunk script containing thunk declarations and typedef's
|
|
as above. core\thunk\gdifthk.thk and core\thunk\usrfthk.thk are
|
|
good examples to start from. Put the lines:
|
|
|
|
enablemapdirect3216 = true;
|
|
flatthunks = true;
|
|
|
|
at the start of your script. This tells the compiler you intend
|
|
to write 32->16 thunks and to generate 32-bit code.
|
|
|
|
The naming convention for flat thunk scripts is FooFThk.thk where
|
|
"Foo" identifies your component. If you keep your script in
|
|
the core\thunk directory, please follow this convention.
|
|
|
|
|
|
|
|
2. Compile your thunk script:
|
|
|
|
$(TNT) $(THUNK) -ynTb -t FooFThk FooFThk.thk FooFThk.asm
|
|
|
|
$(TNT) = dev\tools\c\bin\tnt.exe
|
|
$(THUNKCOM) = dev\tools\binr\thunk.exe
|
|
|
|
The "-t FooFThk" provides a string which the thunk compiler uses
|
|
to individualize identifier names. By convention, use the
|
|
stem of your thunk script filename.
|
|
|
|
For debug builds, eliminate the "-b" flag.
|
|
|
|
The makefile in core\thunk has all this set up so it's easiest
|
|
to check your thunk script there.
|
|
|
|
|
|
|
|
|
|
3. Create a empty header file "FooFThk.inc". The 32-bit half of the *.asm
|
|
file includes this header. This is where you put special-case
|
|
code for your thunks.
|
|
|
|
|
|
|
|
|
|
4. Link the 16-bit half of FooFThk.asm into your 16-bit component.
|
|
Pass these flags to the assembler:
|
|
|
|
-DIS_16
|
|
|
|
Add the export:
|
|
|
|
FT_FOOFTHKTHKCONNECTIONDATA
|
|
|
|
to your *.def file and mark it internal. The 32-bit half
|
|
dynalinks to this symbol to access the 16-bit jump table.
|
|
|
|
|
|
|
|
|
|
|
|
5. Link the 32-bit half of FooFThk.asm into your 32-bit component.
|
|
Pass these flags to the assembler:
|
|
|
|
-DIS_32
|
|
|
|
Core\thunk\fltthk.inc and FooFThk.inc must be in the
|
|
include path.
|
|
|
|
Do not pass the -DFT_DEFINEFTCOMMONROUTINES flag to activate
|
|
the "ifdef"'d part of the .asm file. The "ifdef'd" part
|
|
contains common support code that's to be linked into kernel32
|
|
only. Including it in another module wastes code.
|
|
|
|
|
|
|
|
|
|
6. In your DLL initialization procedure, execute the following
|
|
for each PROCESS_ATTACH call:
|
|
|
|
FT_FooFThkConnectToFlatThkPeer PROTO near
|
|
pszDll16:dword,
|
|
pszDll32:dword
|
|
|
|
pszDll16 db 'foo16.dll',0 ;name of your 16-bit dll
|
|
pszDll32 db 'foo32.dll',0 ;name of your 32-bit dll
|
|
|
|
...
|
|
|
|
|
|
|
|
invoke FT_FooFThkConnectToFlatThkPeer,
|
|
offset pszDll16,
|
|
offset pszDll32
|
|
or eax,eax
|
|
jz failed
|
|
; success
|
|
|
|
This initializes the flat thunks. The call executes a loadlibrary
|
|
and getprocess address on the 16-bit module. The init routine
|
|
itself is generated by the thunk compiler in the 32-bit half
|
|
of the .asm file.
|
|
|
|
|
|
|
|
7. Link your 32-bit module with dev\lib\kernel32.lib if you're
|
|
not doing so already. The thunk code needs the import records
|
|
for the support routines in kernel32.
|
|
|
|
|
|
|
|
8. Build the components and test. Under debug, you
|
|
can get a debug-port message for each flat thunk by
|
|
setting the "fapilog16" variable in win32c.dll to 1.
|
|
The "[F]" before the api name tells you that it's a flat thunk.
|
|
|
|
|
|
|
|
|
|
3. WHAT'S IN AND OUT FOR FLAT THUNKS
|
|
-------------------------------------------------------------------------
|
|
|
|
The flat code generator supports:
|
|
|
|
- Structures passed by value or reference.
|
|
- Structures within structures.
|
|
- Pointers within structures, provided that the object
|
|
pointed to doesn't require repacking. The object can be
|
|
another structure.
|
|
- Arrays of scalars embedded in structures.
|
|
- The "input", "output" and "inout" qualifiers for pointer
|
|
arguments. Default is "input".
|
|
- "passifhinull" for pointer arguments.
|
|
- The "hinstance" primitive type (for mapping instance handles)
|
|
- "passifnull" for hinstances
|
|
- "structsize" for integer structure fields
|
|
|
|
- Returning pointers provided that the object pointed to requires
|
|
no repacking. The object can be a structure.
|
|
- The "voidtotrue" and "voidtofalse" qualifiers.
|
|
|
|
|
|
Not supported:
|
|
- Arrays of pointers or arrays of structures.
|
|
- The "deleted" qualifier.
|
|
- The "byname" qualifier
|
|
- The "maptoretval" semantic.
|
|
- The "sizeof" and "countof" semantics.
|
|
- The "localheap" semantic.
|
|
- The "reverserc" semantic.
|
|
- The "callback" semantic.
|
|
- "body = special", "raw pack/unpack", "push", "special".
|
|
No hand-coding for flat thunks is allowed. Use wrappers
|
|
instead to thunk complex routines.
|
|
|
|
|
|
|
|
|
|
4. SPECIAL-CASING A THUNK BODY
|
|
---------------------------------------------------------------------------
|
|
**** HAND-CODING FOR THUNK BODIES IS BEING PHASED OUT. USE
|
|
WRAPPERS TO THUNK COMPLEX API. SEE ATSUSHIK IF YOU NEED HELP
|
|
ON THIS.
|
|
****
|
|
|
|
|
|
|
|
|
|
13. APPENDIX I:
|
|
------------------------------------------------------------------------------
|
|
NEW for the flat code generator:
|
|
Revision 1: STRUCTSIZE and HINSTANCES
|
|
|
|
|
|
Structure size fields:
|
|
You can now thunk those fields that contain the size of its
|
|
containing structure. Just put the "structsize" keyword after
|
|
the field name, like this:
|
|
|
|
typedef struct tagFOO {
|
|
DWORD cbSize structsize;
|
|
LPSTR this;
|
|
LPSTR that;
|
|
} FOO;
|
|
|
|
The compiler will insert the 16-bit structure size when packing in,
|
|
and the 32-bit structure size when packing out. You can mark
|
|
any integral type field as "structsize", including UINT.
|
|
|
|
|
|
HInstance:
|
|
There's a new primitive data type "hinstance" (lowercase). I'll
|
|
add a typedef for HINSTANCE (uppercase) as soon as I've cleaned out
|
|
the old usage of HINSTANCE.
|
|
|
|
"hinstance" maps to a 32-bit value for the 32-bit side and a 16-bit
|
|
value for the 16-bit side. Hinstances can appear anywhere an integer
|
|
can (except as the return value type).
|
|
|
|
NULL gets mapped to the current hinstance by default. You can make
|
|
NULL map to NULL instead by adding the "passifnull" qualifier.
|
|
If the hinstance is a structure field, add the "passifnull" qualifier
|
|
as you would "structsize". If it's a parameter, put
|
|
|
|
paramname = passifnull;
|
|
|
|
inside the curly braces.
|
|
|
|
Everyone is reminded that the 16-bit "hinstance" for a 32-bit app is
|
|
really the hmodule. This works because most api that ask for hinstances
|
|
really want hmodules.
|
|
|
|
|
|
|