DB L'Hello how are you?'

            DUS 'I am a Unicode string with new line and null terminator',0Dh,0Ah,0

Inserting blocks of data

The syntax for a DATABLOCK is as follows:-

MyBlockData DATABLOCK_BEGIN      ;comment
    .
    . data is inserted here
    .
DATABLOCK_END

Initialising using addresses of labels

MS1 DB 'First string to use',0
MS2 DB 'Second string to use',0
Strings DD MS1,MS2            ;Strings to hold address of the strings

MOV ESI,ADDR MS2

MOV ESI,[Strings+4]

MOV ESI,[Strings+EAX*4]

PROCEDURE_TO_CALL DD FIRSTPROC,SECONDPROC
MOV ESI,ADDR PROCEDURE_TO_CALL     ;get procedures in esi
MOV ESI,[ESI+EAX*4]                ;get correct procedure
CALL [ESI]                         ;call the procedure

Code and the starting addresstop

What is "code"?

What is the "starting address"?

How is execution controlled?

How do you set the starting address?

START:

If you don't want to use START, you can specify the starting address using one of these methods in GoLink's command line or command file:-

-entry STARTINGADDRESS
/entry STARTINGADDRESS

If you are using the MS linker you need to make a slight change to your label. It must be preceded by an underline character. So your label is _START: in your source script. Then you would use one of these instructions to the linker (without the underline character):-

-ENTRY START
/ENTRY START

Labels: unique, re-usable and scopedtop

What is a label?

Unique labels

NAMEOFLABEL:

(in data section)
HELLO  DB 0        ;label HELLO
BYE:   DB 0        ;label BYE
MEAGAIN            ;label MEAGAIN
(in code section)
RICE:              ;label RICE
PEAS: FRAME        ;label PEAS
BEANS FRAME        ;label BEANS

Re-usable labels

The scope of a label defines from where it can be accessed using it own unmodified name. Lets look at these two types of re-usable labels in turn.

Locally scoped re-usable labels

.looptop           ;label looptop
.fin               ;label fin

JZ >.fin
CALCULATE:
.fin
RET

If you want to jump past a unique code label to a locally scoped re-usable label, you can either use another unique code label as the destination of the jump, or you can use an unscoped re-usable label. Or for advanced use, you can use the locally scoped label within an automated stack frame see re-usable label scope in automated stack frames.

Locally scoped re-usable labels are sent to the debugger as symbols together with their "owner". Therefore the symbol sent to the debugger in the above example is CALCULATE.fin, and another way to jump past that unique label would be with JZ >CALCULATE.fin.

Unscoped re-usable labels

L1:
24:
24.6:

Jumping to labels: short and long code jumpstop

The direction indicators

JZ >.fin         ;jump forward to .fin
JMP >.exit       ;jump forward to .exit
LOOP .looptop    ;loop backwards to .looptop
LOOP <.looptop   ;loop backwards to .looptop (alternative form)

JZ >L10          ;jump forward to L10
JNC L3           ;jump backwards to L3
JNC <L3          ;jump backwards to L3 (alternative form)
JMP 100          ;jump backwards to 100

Jumps to unique labels

Conditional jumps to unique labels

JZ EXTERNALLABEL

JNZ >
JMP EXTERNALLABEL
:

Unconditional jumps to unique labels

JMP LABEL               ;look for label in all source scripts
JMP <INTERNALLABEL1     ;only look for label earlier in source script
JMP >INTERNALLABEL2     ;only look for label later in source script

Jumps to single colons

:
CALL PROCESS
LOOPZ <

CMP EAX,EDX
JZ >
CALL PROCESS
:
RET

The importance of long or short jumps

Telling GoAsm to code a long jump

JZ >>.fin         ;long forward jump to .fin
JZ LONG >.fin     ;long forward jump to .fin (alternative form)
JC <<A1           ;long backward jump to A1
JC LONG A1        ;long backward jump to A1 (alternative form)
JC LONG <A1       ;long backward jump to A1 (alternative form)

DEC ECX
JNZ LONG L2          ;long jump replacing LOOP
OR ECX,ECX           ;test for ecx=0
JZ LONG >L44         ;long jump replacing JECXZ

Whether long or short jumps are coded

• GoAsm will always code a long jump if specified (for those instructions that support this).
• For backward jumps to unique and also locally scoped labels, GoAsm will automatically code a short jump if possible, if not a long jump.
• For backward jumps to unscoped labels, GoAsm will code a short jump.
• For forward jumps to unscoped and also locally scoped labels, GoAsm will code a short jump.
• For forward jumps to unique labels, GoAsm will code a long jump.

Accessing labelstop

Getting the address of a label

Here are examples using unique labels:-

MOV ESI,ADDR Process_dabs  ;get in esi the address of the code label Process_dabs
MOV ESI,ADDR Hello2        ;get in esi the address of the string labelled Hello2
MOV ESI,ADDR HelloX+10h    ;get in esi the address 16 bytes beyond HelloX

MOV ESI,ADDR CALCULATE.fin ;get in esi the address of the code label .fin in the CALCULATE procedure

MOV ESI,ADDR Lv1.pszText   ;get in esi the address of the psztext member in the formal structure Lv1

LEA R11,ADDR Non_Local_Label
PUSH R11

LEA R11,ADDR Non_Local_Label
MOV [MEMORY64],R11

Reading data from the place pointed to by a label

MOV ESI,ADDR Hello1     ;get in esi the address of the dword Hello1
MOV EAX,[ESI]           ;get in eax the value of Hello1

MOV EAX,[Hello1]        ;get in eax the value of Hello1

Writing to the place pointed to by a label

MOV ESI,ADDR Hello1     ;get in esi the address of the dword Hello1
MOV [ESI],EAX           ;write the value in eax to Hello1

MOV [Hello1],EAX        ;write the value in eax to Hello1

Reading and writing to labels using displacement

PARAM_DATA DD 0     ;+0h
           DD 0     ;+4h
           DD 55h   ;+8h
           DD 0     ;+0Ch
           DD 0     ;10h

MOV ESI,ADDR PARAM_DATA
MOV EAX,[ESI+8h]           ;get in eax value of third dword
MOV [ESI+8h],EDX           ;and insert edx instead

MOV EAX,[PARAM_DATA+8h]    ;get in eax value of third dword
MOV [PARAM_DATA+8h],EDX    ;and insert edx instead

Reading and writing to labels using indexation

PARAM_DATA DD 10h DUP 0

MOV ESI,ADDR PARAM_DATA
MOV EAX,[ESI+ECX*4]        ;get in eax value of ecx dword
MOV [ESI+ECX*4],EDX        ;and insert edx instead

MOV EAX,[PARAM_DATA+ECX*4]        ;get in eax value of ecx dword
MOV [PARAM_DATA+ECX*4],EDX        ;and insert edx instead

MOVZX EAX,B[PARAM_DATA+ECX]       ;get in eax value of ecx byte
MOVZX EAX,W[PARAM_DATA+ECX*2]     ;get in eax value of ecx word
MOV Q[PARAM_DATA+ECX*8],EDX       ;insert edx at ecx qword

Reading and writing to labels using indexation and displacement

PARAM_DATA DD 19h,0,0,22222h
           DD 1Ah,0,0,44444h
           DD 1Bh,0,0,66666h
           DD 1Ch,0,0,88888h
           DD 1Dh,0,0,0AAAAAh
           DD 1Eh,0,0,0CCCCCh

MOV ESI,ADDR PARAM_DATA
CMP EAX,[ESI+ECX*4]        ;see if there is eax value at ecx dword
JNZ >L2                    ;no
MOV EDX,[ESI+ECX*4+0Ch]    ;yes so get the result in edx

CMP EAX,[PARAM_DATA+ECX*4]        ;see if there is eax value at ecx dword
JNZ >L2                           ;no
MOV EDX,[PARAM_DATA+ECX*4+0Ch]    ;yes so get the result in edx

Calling (or jumping to) procedurestop

What is a "procedure"?

PROCESS_HASH:       ;label to the procedure
XOR EAX,EAX
MOV EDX,ESI
CALL PH23
MOV EDX,866h        ;return from the procedure with edx=866h
RET

Transferring execution to a procedure

PROCESS_HASH:
XOR EAX,EAX
MOV EDX,ESI
CALL PH23           ;transfer execution to the PH23 procedure and return
MOV EDX,866h        ;return from the procedure with edx=866h
JMP >SOMEWHERE_ELSE
;
START:              ;start place for execution
JMP PROCESS_HASH
;

CALL and JMP to procedure syntax

CALL PROCESS_HASH
JMP PROCESS_HASH

CALL [PROCADDRESS]
CALL [PROCTABLE+20h]
CALL [ESI]
CALL [ESI+EDX]
JMP [4000000h]

CALL EAX
JMP EDI

More complex syntax

#define Hello PROCESS_HASH
CALL Hello       ;treated as a call to PROCESS_HASH
CALL 100h        ;treated as a call to a relative address
CALL [HELLO3+ECX+EDX*4]
CALL [HELLO3+ECX+EDX*4+9000h]
CALL $$          ;a call to the start of the current section
CALL $+20h       ;a call 20h bytes ahead

CALL and JMP to procedures outside the object file or section

So if you want to call a procedure in another source script (which will be producing another object file) just call it in the usual way. Similarly if you have a procedure in another executable (usually a Dll) you can do the same.

For example, suppose you have written My.Dll containing a calculation algorithm you wish to use with the label CALCULATE. You could call it as follows:-

CALL CALCULATE

In your list of Dlls you give to GoLink you will specify My.Dll. GoLink will first look for the code label CALCULATE in the object files, but will then look in the specified Dlls. Most other linkers look in library files (.lib files) for the functions they contain, which means you have to make a lib file. Either way, in GoAsm syntax there is nothing further for you to do in your source script. If the linker does not find the destination of the call, an error will be shown.
This form of the call is a relative call using the opcode E8.

You could also use this form:-

CALL [CALCULATE]

See also:-
using static code libraries
direct importing by ordinal or specific Dll
using the C Run-time library

Calls to Windows APIs - 32-bits and 64-bitstop

Calling Windows APIs (which reside in Windows system Dlls) is very simple where there are no parameters, for example in 32-bit Windows you can use:-

CALL GetModuleHandle

INVOKE GetModuleHandle

Most Windows APIs, however, expect to be sent parameters (also known as "arguments") when they are called. It is the programmer's job to ensure that these parameters are sent to the API correctly. The parameters contain the information, or pointers to information, which tell the API what to do. Sometimes the parameters contain addresses of places in memory where the API will insert information.

How you send the parameters depends on whether you are assembling for 32-bit or 64-bits Windows. This is because they each use different calling conventions, and this affects the way parameters are sent and used. 32-bit Windows uses the standard calling convention (STDCALL) and 64-bit Windows uses the so-called fast calling convention (FASTCALL).

GoAsm provides ARG and INVOKE which can be used for both platforms. GoAsm creates the correct code to suit the calling convention to be used. If you are writing only for 32-bits you can use PUSH and CALL to send the parameters, but if you want to port your code to 64-bit Windows later, you will need to change these to ARG and INVOKE. In both 32-bit and 64-bit source code you would use CALL to call procedures in your own executables, unless you are sending parameters to them using one of these calling conventions.

In the STDCALL calling convention used in 32-bit Windows, all the parameters are put on the stack by the caller, and the stack pointer (ESP) is moved to the top of the parameters on the stack. Then the API is called. The API uses the parameters on the stack and before returning it restores the stack to equilibrium by moving the stack pointer to the position it was before the first parameter was put on the stack.
In the FASTCALL calling convention used in 64-bit Windows, the first four parameters are put in the RCX,RDX,R8 and R9 registers instead of on the stack. However, subsequent parameters are put on the stack. The caller needs to ensure that the stack pointer (in this case RSP) is moved to the top of the parameters as usual, allowing for the first four parameters which are held in registers (this is to permit the API to keep them on the stack as if they had been put there in the first place). Another difference is that the API does not restore the stack into equilibrium before returning from the call (this change makes it easier for a handful of APIs which do not have a fixed number of parameters).

To enable the same source to be used both for 32-bit and 64-bit programming you would send the parameters using ARG and then call the API using INVOKE, for example:-

ARG 40h,RDX,RAX,[hwnd]
INVOKE MessageBoxA

PUSH 40h,EDX,EAX,[hwnd]
CALL MessageBoxA

MOV R9,40h
MOV R8,RDX
MOV RDX,RAX
MOV RCX,[hwnd]
SUB RSP,20h
CALL MessageBoxA
ADD RSP,20h

Calls to Windows APIs - using INVOKE

int MessageBox(
    HWND hwnd,            // handle of owner window
    LPCTSTR lpText,       // address of text in message box
    LPCTSTR lpCaption,    // address of title of message box
    UINT uType            // style of message box
   );

INVOKE MessageBoxA, [hwnd],EAX,EDX,40h

ARG 40h,RDX,RAX,[hwnd]
INVOKE MessageBoxA

INVOKE lets you straddle two or more lines using the continuation character:-

INVOKE CreateWindowExA, WS_EX_OVERLAPPEDWINDOW, ADDR szClassName, \
                        ADDR szWindowName,\
                        WS_OVERLAPPEDWINDOW+THING,\
                        100,16,400,0,0,0,[hInstance],0

When using INVOKE, if you like to tuck away your parameters in a defined word then GoAsm will still get them in the correct order, for example:-

z_function_params=3,2,1
INVOKE z_function, z_function_params

ARG 1,2,3
INVOKE z_function

Calls to Windows APIs - ANSI and Unicode versions

The Unicode version accepts and/or outputs strings in Unicode, that is two bytes per character based on the current Unicode character set. These are also sometimes called "wide" characters. The Unicode version of the API will end in "W".
In your source script you need to specify which API you wish to call by adding A or W at the end of the API name. When you link your object file and the linker has been unable to find the API in the other executable (or in the .lib files if you are not using GoLink) this is probably because you have forgotten to add the required A or W. Another reason, however, could be that you haven't provided GoLink with the name of the Dll holding the API (or the correct .lib files if you are not using GoLink).
If you want automatically to make the correct "A" or "W" call depending on whether you are making an ANSI or Unicode version of your application this can be done using Unicode/ANSI switching. See writing Unicode programs for information about this in detail.
There is no difference between 32-bit assembly and 64-bit assembly in this respect. This is because 64-bit Windows has ANSI and Unicode versions of the APIs just like 32-bit Windows.
 

---

PUSH or ARG pointers to strings and datatop

Pointers to null terminated strings

GoAsm supports an extension of PUSH or ARG which is very helpful when programming in Windows. Often in Windows you need to send to an API a parameter which is a pointer to a null-terminated string for example (in 32-bits):-

MBTITLE   DB 'Hello',0
MBMESSAGE DB 'Click OK',0
PUSH 40h, ADDR MBTITLE, ADDR MBMESSAGE, [hwnd]
CALL MessageBoxA

To make this easier GoAsm permits the use of PUSH or ARG like this:-

PUSH 40h,'Hello','Click OK',[hwnd]
CALL MessageBoxA

or, if you were writing source for 32-bit or 64-bit platforms:-

ARG 40h,'Hello','Click OK',[hwnd]
INVOKE MessageBoxA

or if you prefer to send parameters after INVOKE:-

INVOKE MessageBoxA, [hwnd],'Click OK','Hello',40h

You can also use this with Unicode strings as follows:-

ARG 40h,L'Hello',L'Click OK',[hwnd]
INVOKE MessageBoxW
INVOKE MessageBoxW, [hwnd],L'Click OK',L'Hello',40h

When you use any of these forms the string will always be null-terminated. What is happening here is that GoAsm places the string in the const section if there is one (or the data section if there is one, if not, in the code section) and adds a null-terminator. Then GoAsm creates the correct instruction and gives it a pointer to the string. No symbol is made for debugging purposes.

In 64-bit assembly, GoAsm ensures that Unicode strings are aligned on a word boundary as required by the system. Note that this is similar to PUSH ADDR and will make use of the R11 register and take advantage of the shorter RIP-relative addressing of the LEA instruction.

Pushing pointers to raw data

You can do a similar thing with ordinary raw data (in bytes) using the < and > operators. For example:-

PUSH <23,24,25>                  ;push a pointer to the bytes 23,24,25

or

PUSH <23,6 DUP 20h,23>           ;push a pointer to the bytes 23,six spaces then 23

or

PUSH <'Hi',0Dh,0Ah,'There',0>    ;push a pointer to the null terminated string on two lines

You can also use the < and > operators in this way with ARG and after INVOKE. What is happening here is that GoAsm places the data declaration between the < and > operators in the const section if there is one (or the data section if there is one, if not, in the code section). Then GoAsm creates the correct instruction and gives it a pointer to the data. No symbol is made for debugging purposes.
Note that when using the < and > operators in this way no null terminator is added to strings.

In 64-bit assembly, GoAsm ensures that data is aligned on a word boundary as would be required by the system if the data contains Unicode strings.

Moving pointers to strings and data into registerstop

You can also establish null terminated strings and data and move pointers to them into registers using the following syntax (for example):-

MOV EAX,ADDR 'This is a string'
MOV EAX,ADDR <'String',0Dh,0Ah>

When GoAsm deals with this code it places a null terminated string or the data between the < and > operators in the const section if there is one (or the data section if there is one, if not, in the code section). Then GoAsm gives the pointer to the data so created to the instruction. No symbol is made for debugging purposes.
Note that when using the < and > operators no null terminator is added to strings.
Note also how this differs from the syntax for inserting character immediates into a register. The difference is in the use of the ADDR operator.

This works the same way in 64-bit programming except that GoAsm ensures that a Unicode string or data is word aligned in memory as required by the system. Note that this is similar to PUSH ADDR and will make use of the R11 register and take advantage of the shorter RIP-relative addressing of the LEA instruction.

---

Using character immediates in codetop

GoAsm does not reverse store word and dword character immediates as MASM does. So for example,

MOV AL,'1'
MOV AX,'12'          ;regarded as bytes - 1 first then 2
MOV EAX,'ABCD'       ;regarded as bytes - A first, then B then C then D

This makes it much easier to add short strings to memory eg. to add the extension .fil to a filename in memory you can code:-

MOV [EDI],'.fil'     ;or
MOV EAX,'.fil'
MOV [EDI],EAX

and not

MOV [EDI],'lif.'     ;or
MOV EAX,'lif.'
MOV [EDI],EAX

CMP works in the same way for example:-

CMP AL,'1'
CMP EAX,'ABCD'
CMP [EDI],'.fil'

This does not change the usual reverse order of material not in quotes so for example when you want to add a carriage return and then a linefeed to text you can still use:-

MOV AX,0A0Dh
STOSW

Here the carriage return (0Dh) which is in AL, is loaded into memory first, then the linefeed (0Ah) in AH is loaded into memory.
If the string is shorter than the register or memory type absolute zeroes are added for example,

MOV EAX,'ABC'        ;codes as A then B then C then zero

When writing source code for Unicode programs you can ensure that character immediates are Unicode or if necessary, switched between ANSI and Unicode see using the correct string in quoted immediates and switching quoted strings and immediates.

In 64-bit programming you can use the 64-bit registers to contain character immediates which are 8 characters long, for example:-

MOV RAX,'Saturday'

However, the CMP instruction is limited to 32-bits, so for example

CMP RAX,'Saturday'

would show an error.

---

Type indicatorstop

Why they are needed and how they are provided

Looking at the instruction

MOV [ESI],20h

This puts the number 20h into a place in memory whose address is contained in the register esi. But what is missing from this instruction is whether the number should be loaded as a byte, as a word or as a dword. In other words should one, two or four bytes of memory be altered? All assemblers require a type indicator in instructions of this sort. The syntax in other assemblers is (using dword as an example):-

MOV DWORD PTR [ESI],20h       ;MASM
MOV DWORD [ESI],20h           ;NASM
MOV D[ESI],20h                ;A386

Of course I have used the A386 syntax which requires a lot less typing so that in GoAsm the type indicators you can use are:-

B meaning byte
W meaning word (two bytes)
D meaning dword (four bytes)
Q meaning qword (eight bytes)
T meaning tword (ten bytes)

You can also use these two switchable type indicators:-

S meaning string (default of 1 for ANSI byte, or 2 for Unicode word)
P meaning pointer (default of 4 for 32-bit dword, or 8 for 64-bit qword)

See here for more on using the switched type indicator for Unicode/ANSI switching.
See here for more on using the switched type indicator for 32-bit/64-bit switching.

Type indicator also required for named memory references

Like NASM, GoAsm does not type-check, so it will not know the size of this sort of operation:-

INC [COUNT]

Here GoAsm does not know (and in fact does not care) whether COUNT is a byte, word or dword. Therefore you must give this a type indicator too for example:-

INC B[COUNT]

Although this is a little more work for the programmer, in fact it can be argued that it makes your source script easier to read and understand, since you can always see the size of the operation from the instruction itself, rather than having to go back to see if COUNT was declared as a byte, word or dword.

What instructions require a type indicator?

Generally all instructions where the size of the operation is not obvious. Some of these examples use named memory references, others memory references pointed to by registers:-

AND B[MAINFLAG],0FEh
ADC W[EAX],66h
ADD D[MEM_AREA],66h
BT D[EBX],31D
CMP D[HELLOWORD],0Dh
DEC D[ECX]
DIV B[HELLO]
INC D[EDX]
MOV B[MEM_AREA],23h
MOVSX EDX,B[EDI]
MUL B[HELLO]
NEG W[ESI]
NOT D[HELLO3]
OR B[MAINFLAG],1h
SETZ B[BYTETEST]
SHL W[IAMAWORD],23h
SHL D[IAMADWORD],CL
SUB D[EBP+10h],20D
TEST B[ESP+4h],1h
XOR D[IMAWORD],11111111h

And in 64-bit programming you might also see, for example

ADC W[RAX],66h
BT D[R12],31D
INC Q[RDX]
NEG W[R15D]

What instructions do not require a type indicator?

Where the size of the operation is obvious from the use of a register for example

AND [MAINFLAG],CL
CMP [HELLOWORD],EDI
MOV [IAMABYTE],AL
MOV [IAMADWORD],ESI
OR [MAINFLAG],BH
XCHG CL,[ESI]

Also none of the mmx, xmm or 3DNow! instructions require a type indicator. Several of the x87 floating point instructions do not need a type indicator. Those which do can take more than one operand size. There are also several instructions which can only take one operand size so with these there is no need for a type indicator. For example CALL, JMP, PUSH, and POP always take a dword. See half stack operations for the use of PUSHW and POPW. Also some less common instructions do not need a type indicator, for example ARPL, BOUND, BSF, BSR, CMOV (in all forms), CMPXCHG, and CMPXCHG8B.
 

---

Repeat instructionstop

Repeat instructions are available for PUSH, POP, INC, DEC, and of course when declaring data, for example:-

PUSH 0,23h,[hwnd],ADDR lParam,EAX
POP EAX,[EBP+2Ch],[hwnd]
DEC ECX,EDX,[COUNT]
INC [EBP+10h],EDI
DB 23h,24h,25h

The instructions here are always assembled in left-to-right order.
 

---

Numbers and arithmetictop

Numbers

Most assemblers use the following syntax for numbers:-

66ABCDEh      ;a hex number
34567789      ;a decimal number
1100011B      ;a binary number
1.0           ;a real number
1.0E0         ;a real number

GoAsm accepts these numbers but also supports numbers in these formats:-

9999999D      ;a decimal number
0x456789      ;a hex number

A hex number which begins with a letter (that is A to F, being values 10 to 15 decimal) must begin with a zero, for example:-

0A789ABCDh
or
0xA789ABCD

Arithmetic

GoAsm can perform limited arithmetic in data declarations, duplicate amounts in DUP, definitions, when declaring definitions, when using definitions, and in operands to code instructions. You are not allowed to use the multiply sign (asterisk) inside square brackets other than when using an index register.

Be careful using the OR, AND and NOT logical operators, since these are actually mnemonics. Although GoAsm recognises them if you use them in places where mnemonics are not expected, you can use instead | for OR, & for AND, and ! for NOT.

Arithmetic in brackets is carried out first, otherwise calculations are carried out in strict left-to-right order. Here are some examples:-

DB 2*3
DB (2+30h)/(2+1)
DD (2000h+40h-20h)/2
DD SIZEOF HELLO/2
DD 444444h & 226222h
DB 20h/2 DUP 44h
DB 6+2 DUP 0
#define globule (2*3)/2
DB globule
DD globule|100h
DD 2D00h>>8
DQ 2D00h<<48
MOV EAX,globule|100h
MOV EAX,SIZEOF HELLO*2
MOV EAX,ADDR HELLO+10h
MOV EAX,0x68+0x69-0x70
MOV EAX,[MemName+0x68+0x69-0x70]
MOV EAX,[ESI*4+45000h]
MOV EAX,[ESI*4+SIZEOF HELLO/2]
MOV EAX,8+8*2       ;result is 32
MOV EAX,8+(8*2)     ;result is 24

Divisions are rounded according to the result eg.

MOV EAX,32/3        ;puts 11 into eax
MOV EAX,31/3        ;puts 10 into eax
MOV EAX,10/4        ;puts 3 into eax

GoAsm assumes that all multiplication and division is carried out using unsigned numbers. MUL and DIV are used at compile-time and not their signed counterparts IMUL and IDIV. See understand signed numbers for more about signed numbers.

Declaring real numbers

Real numbers are numbers which can contain a representation of a value of less than 1. GoAsm expects all real numbers in the source script to be in the form of a floating point number, that is a number made up of digits which have point within them. The point must be represented by a "period" (a full stop, ASCII character value 2Eh). The point can be anywhere within the digits. The real number may have a signed decimal exponent at the end of the number (using "e" or "E" following the IEEE Floating Point Standard). The x87 floating point registers of the processor can accept real numbers to 32, 64 or 80 bit resolutions. The 3DNow! and SSE instructions work with 32-bit real numbers and the SSE2 instructions use 64-bit real numbers.
Sometimes these types are called:-
32-bit single-precision
64-bit double-precision
80-bit extended-precision
So real numbers can be declared as dwords (32-bit), qwords (64-bit) or twords (80-bit). Here are some examples of real number data declarations:-

DD 1.6789E3
DQ 1.6789E3
DT 1.6789E3
DD 3 DUP 7.6789E-2
DQ 678.27896435E3
DT 1.2

You may also declare PI directly either as a tword, qword or dword as follows:

DD PI            ;pi as a dword
DQ PI            ;pi as a qword
DT PI            ;pi as a tword

GoAsm tries to achieve maximum accuracy in providing pi by writing a known number directly into the mantissa.

You can also declare real numbers as follows:-

PUSH 1.1
MOV EAX,1.1

Both of these use a 32-bit format for the real number. The first places that number on the stack and the second moves it into the specified register.

GoAsm's conversion accuracy

GoAsm uses special algorithms to ensure optimum accuracy in loading the real number data declaration to data. In the case of a tword (80 bit) data declaration the calculation is performed if necessary to a maximum of 92 bits and then rounded down to fit into the 64 bit mantissa. Conversion to a qword (64 bits) is carried out using the maximum available precision (53 bit mantissa) with "near" rounding. Conversion to a dword (32 bits) is carried out using the maximum available precision (24 bit mantissa) with "near" rounding.

Directly loading the exponent and mantissa

Instead of using real numbers to load the floating point registers you can declare a tword and load the exponent and mantissa directly using the FLD instruction. In order to do this you will need to know the exponent and mantissa values to load (these can either be calculated or found and checked using one of the fpu panes in GoBug). Suppose, for example you want a representation of pi which is as accurate as possible and you know that this is an exponent of +0002 and a mantissa of +C90FDAA22168C235h. Then you can declare this number using:-

DIRECT_PI DT 4000C90FDAA22168C235h

and load it using:-

FLD T[DIRECT_PI]

The most significant bit (bit 79) in this tword declaration is a sign bit indicating whether the real number is positive or negative. In this case the number is positive because the sign bit is not set. The remainder of the first four hex digits contain the exponent. This is biased by a value of +3FFEh in 80 bit real numbers. This permits exponents of between -3FEEh and +4001h to be handled without using the most significant bit (the exponents become 0 to 7FFFh). The remainder of the hex digits contain the mantissa.
It is much more difficult to load the exponent and mantissa directly using dword and qword data declarations. This is because the division between exponent and mantissa in those types of numbers is not at a 4 bit boundary. This makes it difficult to work out the correct hex numbers to declare, bearing in mind the bias which needs to be applied.
 

---

Characters in GoAsmtop

Strings of characters

In your source script you will often be relying on character representation for example:-

Mess DB 'I am a string of characters',0
PUSH 'This is supposed to be a carat ^'
MOV EAX,'£$|@'

It must be asked what actual values are loaded by GoAsm when issuing these instructions? At assemble time GoAsm views your source script using Windows file mapping, and then reads it character by character. In other words GoAsm is given the value of the characters in the source script by Windows. When GoAsm loads in the object file strings of the sort shown above, it loads the same value character as given to it by Windows. In the case of conversions from ANSI to Unicode strings, these are passed first through the API MultiByteToWideChar. This means that the value given to GoAsm by Windows will match that in the current character set (code page). Accordingly you need to ensure that the character set used in the computer which runs GoAsm is the character set for which your program is designed to run.

If you are using a source script which is in a Unicode format (UTF-8 or UTF-16) then the codepage issue disappears. The correct characters are given by their Unicode value.

Characters specified directly

Sometimes you will specify characters by their actual values to try to deal with character set variations for example,

CMP AL,124D       ;see if character is an OR as in some character sets
JZ >L4            ;yes
CMP AL,221D       ;see if character is an OR as in some character sets
JZ >L4            ;yes

Here you have already allowed for a possible variation in the user's own character set. If necessary you can arrange for your code to test the user's character set at run-time, and to test for the correct characters or use the correct strings accordingly. You can also test the language of the user's machine and provide strings in the correct language. The resource APIs provide a way this can be done automatically - see the manual to GoRC, my resource compiler.
 

---

Operatorstop

These are some operators which may be used in the source script which have a special meaning to GoAsm.

,               - the instruction is not finished, continue
; or //         - a comment line - ignore to end of line
/*.........*/   - continuous comment - ignore between the marks
\               - the material is continuing on the next line
- number        - the number is negative
! number        - invert the number (like NOT)
NOT             - invert the number
~ number        - same
+               - the plus sign
-               - the minus sign
*               - the multiply sign
/               - the divide sign
|               - bitwise OR
OR              - bitwise OR
&               - bitwise AND
AND             - bitwise AND
<< number       - bit shift left by the number
>> number       - bit shift right by the number
(....)          - perform calculation in brackets first

## in a definition has a special meaning see using double hashes in definitions.
 

---

Advanced featurestop

Structures - different types and uses

What are structures?

Structures are data areas of a fixed size which hold data in various components (structure members). They can range from very loose arrangements to highly formalised ones with structures within structures (nested structures). They can be data areas established by ordinary data declaration or from STRUCT templates. Structures are very important in Windows programming and GoAsm supports all types.
See also unions.

Using simple structures in Windows programming

Let's take the LV_COLUMN structure which is used to organise the columns in a listview control. The following code sends the LVM_INSERTCOLUMN message (value 101Bh) to the ListView control to make a new column with the index number of the column in eax. The column details are contained in the LV_COLUMN structure. Here is how it might be used in 32-bit code:-

PUSH ADDR LV_COLUMN,EAX,101Bh,hListView
CALL SendMessageA              ;insert eax column

Now let's look more closely at the LV_COLUMN structure.
In the Windows header file Commctrl.h (pre-Win_IE 300 version) which contains information about the structure it is described as a structure of six dwords. In one sense therefore the structure can be regarded as 6 dwords which can be declared very simply as follows:-

LV_COLUMN DD 6 DUP 0

However, in the Windows information, each of the six dwords has a name which gives some idea of what it is used for, which is useful. Also the very first dword is a mask which identifies which of the later members of the structure are valid. This mask is important because a later version of the structure has another two members, and the mask needs to be different. So it might be better to declare the structure in data like this so that the mask can be initialised with a value, and so that you can see the names in your source script:-

LV_COLUMN
  DD 0Fh       ;+0h mask
  DD 2h        ;+4h fmt=LVCFMT_CENTER=2
  DD 0         ;+8h cx
  DD 0         ;+0Ch pszText
  DD 0         ;+10h cchTextMax
  DD 0         ;+14h iSubItem

Here see that whilst declaring the structure in data we have taken the opportunity to initialise two of the members with values which will not change and have included in the comments the offset details, member names and other information.

Reading from and writing to the simple structure

It is very easy to read from and write to the simple structure shown above for example:-

MOV EDI,ADDR LV_COLUMN
MOV ESI,ADDR ColumnText     ;get the column text to use
MOV [EDI+0Ch],ESI           ;and give it to the structure
MOV D[EDI+8h],50D           ;and make the width 50 pixels

or you can use:-

MOV ESI,ADDR ColumnText     ;get the column text to use
MOV [LV_COLUMN+0Ch],ESI     ;and give it to the structure
MOV D[LV_COLUMN+8h],50D     ;and make the width 50 pixels

More formalised structures using STRUCT

Some programmers prefer to be more formal when using structures by using a structure template. This is done in two stages. The first stage is to make a template by using STRUCT and give a name to the template. This does not actually declare any data.

Here is an example of a structure template made with the name LV_COLUMN:-

LV_COLUMN STRUCT
  mask       DD 0Fh       ;mask
  fmt        DD 2h        ;LVCFMT_CENTER=2
  cx         DD 0
  pszText    DD 0
  cchTextMax DD 0
  iSubItem   DD 0
ENDS

I have added some comments here to help understand the initialisation of two members of the structure. Note ENDS (literally END STRUCT) marks the end of the template. If you prefer you can also mark the end of the template by giving the structure name again followed by ENDS eg.

LV_COLUMN ENDS

The second stage is to use the template. You do this by using the template in the data section, usually preceded by a label, for example:-

Lv1 LV_COLUMN

Here you have declared six dwords using the LV_COLUMN structure template and you have given the structure declaration the label Lv1.

The symbols created by formalised structures

In GoAsm, symbols are made for the label of the structure itself and also for the each named member of the structure. These can then be referenced directly and also can be passed to the debugger.
So for example:-

RECT STRUCT
     left   DD
     top    DD
     right  DD
     bottom DD
ENDS
rc RECT

creates the following symbols:-

rc
rc.left
rc.top
rc.right
rc.bottom

Reading from and writing to the formalised structure

Using the formalised structure allows you to be more specific in your source script when reading from and writing to the structure, for example:-

MOV ESI,ADDR ColumnText     ;get the column text to use
MOV [Lv1.pszText],ESI       ;and give it to the structure
MOV D[Lv1.cx],50D           ;and make the width 50 pixels

or even

MOV ESI,ADDR ColumnText     ;get the column text to use
MOV EDX,ADDR Lv1.pszText    ;get the psztext member
MOV [EDX],ESI               ;and load the text to use
MOV EDX,ADDR Lv1.cx         ;get the cx member
MOV D[EDX],50D              ;and make the width 50 pixels

But there is still nothing to stop you from doing this which is the same thing:-

MOV ESI,ADDR ColumnText     ;get the column text to use
MOV [Lv1+0Ch],ESI           ;and give it to the structure
MOV D[Lv1+8h],50D           ;and make the width 50 pixels

Although it is more complex to set up, the advantage of the former method is that when you look at your code in the symbolic debugger the symbols in the structure will appear in full, with both the structure label and the member name appearing which is some advantage. This is because GoAsm creates symbols for all the members of the structure and passes these to the linker. As far as I am aware this is unique to GoAsm and other assemblers do not do this.

Getting the offset of structure members

Sometimes you need to get the offset of a member within the structure. You do this by referring to the structure by name followed by a period and the name of the member, for example

POINT STRUCT
   left  DD 0
   right DD 0
ENDS

Then

MOV EBX,POINT.right

This loads the value 4 into EBX, which is the distance of the member from the beginning of the structure.

This way of getting an offset is sometimes useful to get information sent by Windows in a structure. As an example, the OFNHookProc callback procedure receives from Windows information in a WM_NOTIFY message. The lParam parameter contains a pointer to an OFNOTIFY structure. This is a nested structure with the following form:-

OFNOTIFY STRUCT
  hdr     NMHDR
  lpOFN   DD
  pszFile DD
ENDS

where the NMHDR structure is:-

NMHDR STRUCT
  hwndFrom DD
  idFrom   DD
  code     DD
ENDS

So within your window procedure you can get the value of the member idFrom in the NMHDR (identifier of the control sending the message) as follows:-

MOV ESI,[EBP+14h]                 ;get the pointer to the OFNOTIFY structure
MOV EAX,[ESI+OFNOTIFY.hdr.idFrom]
MOV EDX,[ESI+OFNOTIFY.pszFile]

In fact what is happening here is that OFNOTIFY.hdr.idFrom resolves to a value of 4; OFNOTIFY.pszFile resolves to a value of 10h. These are their correct offsets from the beginning of the OFNOTIFY structure. Of course the structures concerned must be known to GoAsm. This is done by including the structure templates in the assembler source script, somewhere earlier in the file.

Overriding the initialisation of the structure

Suppose you have a structure called RECT as follows:-

RECT STRUCT
    left   DD 10
    top    DD 10
    right  DD 120
    bottom DD 90
ENDS

You can override the initialisation of the structure using the < and >, { and } operators for example

rc1 RECT <0,20,120,300>

sets the dwords in the data structure to 0, 20, 120 and 300 respectively.
You can use the question mark and the comma, or just the comma to ignore some members, for example:-

rc1 RECT <0,?,?,300>
rc1 RECT <0,,,300>

here you override only the first and fourth members of the structure.

Using braces you can pick and choose which members to override:-

rc1 RECT {left=2,top=5}

or you can mix the two methods:-

rc1 RECT <{left=2,top=5},300h>

When using braces you don't need to specify the full symbol name (in the above example this would be "rc1.left" and "rc1.top"). Instead you only specify the ultimate name ("left" and "top"). The override is also carried out into nested structures, so if you use the same names for members within a nested structure it is possible to initialise several members at once using one brace override.

Initialising structure members which have DUP data declarations

If members of a structure are established using DUP, you can either override the initialisation by using a string or by specifying each element within < and > brackets:-

UP STRUCT
  DB 27 DUP 0
  DB 2  DUP 0
ENDS
Pent UP <'My cat was born on 23 April',<23h,4h>>

So, for example here is the GUID structure and a typical initialisation for COM:-

GUID STRUCT
    Data1 dd ?
    Data2 dw ?
    Data3 dw ?
    Data4 db 8 dup ?
GUID ENDS
IID_IShellLink GUID <0000214eeh, 00000h, 00000h, <0c0h, 00h, 00h, 00h, 00h, 00h, 00h, 46h>>

Some syntax rules when using STRUCT

One important rule is that since GoAsm is a one-pass assembler structure templates must be made in the source script before they are used. This is because GoAsm cannot know in advance how large the structure is going to be. GoAsm is rather more relaxed with its syntax for STRUCT than other assemblers. STRUC means the same as STRUCT. There is no need to provide any initial values at all, and it does not matter that members are not named, so

RECT STRUCT
     left   DD
     top    DD
     right  DD
     bottom DD
ENDS

and

RECT STRUCT
     left   DD 0
            DD 2 DUP 0
     bottom DD 0
ENDS

and

RECT STRUCT DD 4 DUP 0 ENDS

are equally valid structure declarations. However, where members are named they must be on a new line.
You may reuse the name for structure members, provided the structure's name is different, eg.

RECT STRUCT
     left   DD 0
     top    DD 0
     right  DD 0
     bottom DD 0
ENDS
RECT2 STRUCT
     left   DD 0
     top    DD 0
     right  DD 0
     bottom DD 0
ENDS

If you use ? in the initialisation of the structure members this has the same effect as using zero. This does not result in the data being recorded as uninitialised, as it would do with an ordinary data declaration, so

RECT STRUCT
     left   DD ?
     top    DD ?
     right  DD ?
     bottom DD ?
ENDS
rc1 RECT

is perfectly valid, but the data will go in the section initialised to zero as if zeroes had been used.

In a structure template you can make additional data on one line in the usual way so that this would be a structure template of four dwords:-

RECT STRUCT
     lefttop     DD 0,0
     rightbottom DD 0,0
ENDS

Repeat structure declarations

It may be useful to create arrays and tables using structure templates. For example:-

RECT <>,<>,<>,<>

Creates four RECT structures (four dwords in each). Since no label has been used in front of the RECT, no symbols at all will be created and passed to the debugger. In this example:-

Buffer RECT <0,0,10,10>,<5,5,20,20>,<8,8,30,30>

an array is made of three RECT structures (four dwords in each) initialised to the values provided. Symbols will only be made for the very first structure. This is to avoid duplication of symbol names.

If you want the members of the array to have unique symbol names you would need to use (for example):-

Buffer1 RECT <0,0,10,10>
Buffer2 RECT <5,5,20,20>
Buffer3 RECT <8,8,30,30>

or

Buffer RECT3 <0,0,10,10,  5,5,20,20,  8,8,30,30>

where RECT3 is a structure of 3 RECTS.

If you don't need to initialise the structures you can repeat them using either:-

Buffer RECT <>,<>,<>

which creates three RECT structures, or

Buffer RECT,RECT,RECT

which does the same thing.

You can also use DUP to repeat structures for example:-

ThreeRects RECT 3 DUP <>
FiveRects  RECT 5 DUP <23,24,25,26>

In the second example each RECT is initialised to the same value. Initialisation of duplicated structures in this way can only be done at the top level and not in nested structures.

Nested structures using STRUCT

Structures can be nested by using a structure within another, so

RECT STRUCT
     left   DD 0
     top    DD 0
     right  DD 0
     bottom DD 0
ENDS
StructTest STRUCT
    a DD    6
    b RECT
    c DD    7
    d DD    8
ENDS

Then

Hello StructTest

Creates seven dwords. The symbols created (and passed to the debugger) are:-

Hello
Hello.a
Hello.b
Hello.b.left
Hello.b.top
Hello.b.right
Hello.b.bottom
Hello.c
Hello.d

and they can be read from or written to in the usual way, for example

MOV D[Hello.b.left],100h     ;make rectangle start at 256 pixels

Like structure members, nested structures need not be named, so that this is perfectly valid:-

StructTest STRUCT
      DD     6
      RECT
    c DD     7
    d DD     8
ENDS

Internally nested structures

Structures can be nested by declaring a structure within a structure, so

StructTest STRUCT
    a DD    6
    b STRUCT
      left   DD 0
      top    DD 0
      right  DD 0
      bottom DD 0
      ENDS
    c DD    7
    d DD    8
ENDS

Then

Hello StructTest

produces the same result as StructTest in the previous example. The only difference is that the RECT structure is not available for use elsewhere.

Overriding initialisation in nested structures

You need carefully to use the < and > brackets to initialise the correct members of the nested structure. Each < bracket will go deeper into the nest and each > bracket will come back by one out of that nest. When coming out of a nest a comma is expected after the > bracket. So in the StructTest nested structure (given above):-

rc1 StructTest <23,<10,20,120,300>,44,55>

will initialise the main structure and also its nested RECT member

rc1 StructTest <,<10,20,120,?>,44,55>

will only override the initialisation of some members as will

rc1 StructTest <,<10,20,120,>,44,55>

but this will not change the nested RECT member:-

rc1 StructTest <,,44,55>

A good way to keep track of the brackets is to visualise a question mark for those members which you do not want to alter. Or you can even insert the mark for easier reading, for example the last example can be written:-

rc1 StructTest <?,?,44,55>

Override priority

The higher the level of override the greater its priority so for example, suppose you have these structure templates:-

RECT STRUCT
     left   DD 1
     top    DD 2
     right  DD 3
     bottom DD 4
ENDS
StructTest STRUCT
    a DD    6
    b RECT  <3333h,4444h,5555h,>
    c DD    7
    d DD    8
ENDS

Then

Hello StructTest <,<,0Bh,0Ch,>,,>

Then RECT would be initialised to 3333h,0Bh,0Ch,4

Overrides naming members using { } braces have a higher priority than overrides using the < and > brackets.

Using strings in structures

You can use strings in structures in the same way as you would in an ordinary data declaration for example:-

StringStruct STRUCT
   DB 'I am a lonely string in a struct',0
   DB 'I will keep you company',0
ENDS

Structures with strings: initialisation and override

If a structure is declared with ?, then it could be any size when used with strings eg.

Rect STRUCT
   a DB ?
     DB 0
   b DB ?
     DB 0
ENDS
RC1 Rect <'Hello',,'Goodbye'>

will set the Rect structure to null terminated strings of 5 and 7 bytes respectively.
When the size of the member of a structure is already set eg.

Rect STRUCT
   a DB 'Hello'
     DB 0
   b DB 'Goodbye'
     DB 0
ENDS

Then overriding the initialisation will not change the size of the members, so that eg.

RC1 Rect <'Goodbye',,'Hello'>

would result in a string at label Rect.a of 'Goodb' and a string at label Rect.b of 'Hello ', where the rest of the string is padded with nulls.

The initialisation of structures members established using DUP can also be overriden by strings for example:-

UP STRUCT
   DB 20 DUP 0
ENDS
Pent UP <"Hello">

results in the string Hello followed by 15 nulls.

See also Using Unicode strings in structures.

Conditional assembly in structures

You can use conditional assembly directly within a structure, for example

NMHDR STRUCT
hwndFrom DD
idFrom   DD
code     DD
ENDS
;
NMTTDISPINFO STRUCT
hdr NMHDR
lpszText DD
#if STRINGS UNICODE
szText DW 80 DUP ?
#else
szText DB 80 DUP ?
#endif
hinst    DD
uFlags   DD
lParam   DD
ENDS

DATA
Use1 NMTTDISPINFO
Use2 NMTTDISPINFO <<>,,"Hello",,,,>

The second use of the structure will assemble the string "Hello" either in Unicode or in ANSI depending on whether STRINGS are defined as Unicode.
see conditional assembly.

Unionstop

What are unions?

Unions, like structures, are data areas of a fixed size which hold data in various components (union members). Like structures, no data area is actually created when you declare a union template. This is done when you use the template. Unions differ from structures in that each member of the union starts off at same address in memory. Unions are useful if you want to use different labels to address the same data area. Which label you address at run-time might then depend on eventualities such as the version of the operating system on which the program is being run. The size of a union is always set to the largest data declaration within it. You can mix unions with structures to form complex templates. You can declare unions in local data and repeat them in the same way as you can for structures.

For example, take the union template declared as follows:-

Thing UNION
      Cat DD 0
      Dog DW 0
      Rat DB 0
ENDS

Then you can use this template as follows:-

Hungry Thing

This then sets aside a data area of 4 bytes (a dword). Why only 4 bytes? Because each member starts in the same place. The end of the union template is marked by ENDS although you can use ENDUNION if you prefer.

The symbols created by this union are:-

Hungry
Hungry.Cat
Hungry.Dog
Hungry.Rat

And you can address these labels in the usual way, for example:-

MOV [Hungry.Cat],EAX
MOV AL,[Hungry.Dog]
MOV ESI,[Hungry.Rat]

Which of course since each member starts in the same place, is the same as:-

MOV [Hungry.Cat],EAX
MOV AL,[Hungry.Cat]
MOV ESI,[Hungry.Cat]

Nested unions

You can nest unions in structures, or nest structures in unions, or nest unions in unions, for example

Laugh STRUCT
     Balm     DW 0
     Ointment DB 0
ENDS
;
Zebra UNION
     Tiger  DD 0
     Hyaena Laugh
ENDS
;
Lion STRUCT
     BagPuss DB 3 DUP 0
     Striped Zebra
ENDS
;
Fierce Lion

Which produces the following symbols at the following offsets from Fierce:-

Fierce                         +0
Fierce.BagPuss                 +0
Fierce.Striped                 +3
Fierce.Striped.Tiger           +3
Fierce.Striped.Hyaena          +3
Fierce.Striped.Hyaena.Balm     +3
Fierce.Striped.Hyaena.Ointment +5

Internally nested unions

Unions can be nested by declaring them within a structure or union, so

Lion STRUCT
     BagPuss DB 3 DUP 0
     Striped UNION
             Tiger  DD 0
             Hyaena STRUCT
                    Balm     DW 0
                    Ointment DB 0
                    ENDS
             ENDS
ENDS
;
Fierce Lion

produces the same result as the previous example. The only difference is that Laugh and Zebra are not available for use elsewhere.

Initialising union members

In the same way as in structures you can use the < and > operators to initialise unions with strings or numeric values, for example:-

Cat UNION
Ginger DB
Tortie DW
Grey   DD
Tabby  DQ
ENDS
Hungry    Cat <"a string for Ginger">
Anxious   Cat <,4444h>                  ;initialises the word
Sleepy    Cat <,,55555555h>             ;initialises the dword
Insistent Cat <,,,6666666666666666h>    ;initialises the qword

It is even more difficult when using unions to keep track of the < and > operators, so instead if you prefer, you can specify the name of the member inside { and } operators, or you can initialise them at run time, for example:-

Scaredy Cat {Ginger="a string for Ginger"}
GString DB "a string for the Grey cat"
MOV [Scaredy.Grey],ADDR GString         ;loads a pointer to GString

Remember that since union members are at the same place a later initialisation can rub over an earlier one.
The optional question mark (?) is useful to show that you do not want to rub out an earlier override.

Example:-

Laugh STRUCT
     Balm     DW 6666h
     Ointment DB
ENDS
;
Zebra UNION
     Tiger  DD 88888888h
     Hyaena Laugh
ENDS
;
Lion STRUCT
     BagPuss DB
             DB
             DB
     Striped Zebra
ENDS
;
Fierce Lion <{Ointment=0AAh}22h,33h,44h,<?,<?,55h>>>

Which initialises the data area as follows:-

At Fierce.BagPuss            (at offset +0) 22h,33h,44h
Then at Fierce.Striped.Tiger (at offset +3) 66h,66h,0AAh,88h

What happened here is that the Tiger dword at +3 in the Zebra union was initialised to 88888888h but then overidden by the values of Balm and Ointment (which were within the same union). Only the very last byte survived.
 

---

Definitions: equates, macros and #definestop

Making something mean something else

Equates, macros and #defines give a meaning to a word. The word is defined. Once defined, from that point on in the source script, the definition is used instead of the original word if the context permits it. If the word as defined means a number, then assembler programmers tend to call the definition an "equate", because traditionally the word would be defined using the EQU operator or the = operator. If the word as defined means a string, then traditionally it would be called a text equate. If the word as defined means something more than just a number or string, perhaps for example a series of instructions, then assembler programmers tend to call it a "macro". This is because traditionally the word would be defined using the MACRO operator.

When using GoAsm, for definitions which can be fitted onto one line, you might like to use EQU or =, or #define as you would in "C". Just use the one you like best. You can use the continuation character ("\") to allow definitions to span more than one line, but it is better if you use MACRO...ENDM instead. This avoids syntax problems.

Since GoAsm is a one-pass assembler, you must ensure that your definitions are not used before they are declared in the source script. Once a word has been defined you can change its definition but GoAsm will warn you of this since it may not be intended.

Here are some examples how definitions can be used.

Defining words to mean numbers or strings (data examples)

Here are three examples which define a word as a constant value. The first uses =, the second uses EQU and the third uses #define. They all do the same thing.

WS_CHILD=40000000h
WS_CHILD EQU 40000000h
#define WS_CHILD 40000000h

You can use arithmetic or strings or even other definitions when you define a word. Here are some examples:-

SKIP_VALUE EQU 20h|40h
#define SKIP_VALUE 20h|40h
HelloText='Hello world'
#define HelloText "Hello world"
MANIA=SKIP_VALUE+WS_CHILD

If you don't give a value for the equate it is set to a value of 1 that is, in Windows-speak, TRUE. For example:-

NT_VERSION=
NT_VERSION EQU
#define NT_VERSION

Once a word is defined you can use the word in almost any situation where the definition is valid, for example:-

DB HelloText
PUSH WS_CHILD|WS_VISIBLE|SS_OWNERDRAW
MOV EAX,WS_CHILD
MOV EAX,[ESI+SKIP_VALUE]
MOV EAX,MANIA+800h

Defining words to provide code instructions

Here is an example of how you can define a word to mean a code instruction:-

#define lParam [EBP+14h]

Then to use the definition you could code as follows:-

MOV lParam,EAX        ;same as MOV [EBP+14h],EAX

Using arguments when defining words

Arguments are values which are given when the definition is used. These values are then used within the definition or macro itself. So, for example:-

RECTB(%a,%b,%c,%d) = DD %a,%b,%c,%d

Then, you can declare four dwords initialised as specified in the arguments:-

rc1 RECTB (10,10,100,200)      ;same as DD 10,10,100,200

Here is another example using #define:-

#define DBDATA(%a,%b) DB %a DUP %b
DBDATA(3,'x')                    ;same as DB 3 DUP 'x'

There is an important syntax rule when using arguments in definitions. When giving the definition the arguments in brackets must be tight against the word which is defined so that

RECTB(%a,%b,%c,%d)

is good but

RECTB (%a,%b,%c,%d)

is bad. This rule is to ensure that GoAsm knows the things in brackets are arguments and not something else.
You must also ensure that the names of the arguments are unusual and will not be found in any other material used in the definition or macro. This avoids other things being replaced inadvertently. Hence the percentage sign is used in the above examples.

Multi-line definitions

The definition can straddle lines to make them more readable or to allow you to add comments. For example:-

#define WS_POPUP            0x80000000L
#define WS_BORDER           0x00800000L
#define WS_SYSMENU          0x00080000L
#define WS_POPUPWINDOW      (WS_POPUP          | \
                             WS_BORDER         | \
                             WS_SYSMENU)

This last example was taken straight out of the Windows header file Winuser.h and you can see that it is in typical "C" syntax. GoAsm is quite happy with this. In fact in GoAsm the brackets are optional, so this is also perfectly good syntax:-

#define WS_POPUPWINDOW       WS_POPUP          | \
                             WS_BORDER         | \
                             WS_SYSMENU

You may prefer to use MACRO...ENDM instead of the continuation character. The above example can then be re-written as:-

WS_POPUPWINDOW MACRO WS_POPUP    |
                     WS_BORDER   |
                     WS_SYSMENU
               ENDM

Multi-line definitions: stack frame example (windows callback)

This applies only to 32-bit programming.

You can use the multi-line definition method to make a word mean several lines of code instruction, for example:-

OPEN_STACKFRAME(a) =  PUSH EBP \
                      MOV EBP,ESP \
                      SUB ESP,a*4 \
                      PUSH EBX,EDI,ESI
CLOSE_STACKFRAME   =  POP ESI,EDI,EBX \
                      MOV ESP,EBP \
                      POP EBP

Using MACRO...ENDM this is:-

OPEN_STACKFRAME(a) MACRO PUSH EBP
                      MOV EBP,ESP
                      SUB ESP,a*4
                      PUSH EBX,EDI,ESI
                   ENDM
CLOSE_STACKFRAME   MACRO POP ESI,EDI,EBX
                         MOV ESP,EBP
                         POP EBP
                   ENDM

In this example the word OPEN_STACKFRAME is defined to make a stack frame which could typically be used in a windows procedure called by the Windows system. It has an argument which holds the number of dwords in the stack frame to accept local data (the stack pointer is moved by that amount so that the stack can be used to hold local data). The second definition in this example closes the stack frame. Now here is how to use these definitions. In the code section:-

WndProc:              ;name of this procedure
OPEN_STACKFRAME (6)   ;create space for 6 dwords of local data
        ;----------------- insert window procedure code here
CLOSE_STACKFRAME
RET 10h               ;remove from stack 4 parameters sent by windows

Now lets add some refinement so that the stack can be accessed easily:-

lParam =[EBP+14h]     ;
wParam =[EBP+10h]     ; get ready to access the parameters which
uMsg   =[EBP+0Ch]     ; are sent by Windows to the window procedure
hwnd   =[EBP+8h]      ;
;
hDC    =[EBP-4h]      ; some names of data things
hBrush =[EBP-8h]      ; often used in different
hPen   =[EBP-0Ch]     ; window procedures
DATA1  =[EBP-10h]     ;
DATA2  =[EBP-14h]     ; space for more local data
DATA3  =[EBP-18h]     ;

Inside the stack frame which has been made here the parameters sent by Windows (hwnd, uMsg, wParam and lParam) will always be on the stack at EBP+14h to EBP+8h. Then at EBP+4h we find the return address after the call. At EBP we have the previous value of EBP which we pushed when the stack frame was made. Then at EBP-4h to EBP-18h we have the space for our local data, which in this example can be accessed using the definitions hDC, hBrush, hPen, DATA1, DATA2 and DATA3 (or whatever you want to call them). Then at EBP-1Ch we have the value of EBX when it was pushed when the stack frame was made. Likewise EDI is at EBP-20h and ESI is at EBP-24h. All these values are protected while the stack frame remains open (they will not be written over by other functions until the callback is finished). To access the data within the stack frame you must make sure you don't change ebp (or if you do use it, you restore it to its original value). You don't have to access the data by name. In this example MOV EAX,[hBrush] is the same as MOV EAX,[EBP-8h]. This is a matter of style and taste. Using these methods you can establish as much local data as you want, and if you stick to a fixed method like this you will always know where your local data is. In this example, the first dword of local data is always at EBP-4h. Subtract 4 from this value to access each additional dword of local data.

There are many other ways of dealing with the stack in callbacks. See callback stack frames in 32-bits and 64-bits, and automated stack frames using FRAME...ENDF, LOCALS, and USEDATA.
See also "understand the stack" part 1 and part 2.

Conditional assembly in macros

If you use conditional assembly in your definitions it is recommended that you use MACRO. ..ENDM instead of the continuation character method.

Here is an example:-

STRINGS UNICODE
CODE
;
#define REPORT
;
MBMACRO(%lpTextW) MACRO
#ifdef REPORT
INVOKE MessageBoxW,0,addr %lpTextW,"Report",40h
#endif
ENDM
;
MBMACRO("This code was assembled!")

In the above code the Message Box is displayed. But if the line defining REPORT is commented out, then it is not displayed. The "This code was assembled!" string is sent as an argument to the macro.
see conditional assembly.

Counting the arguments with ARGCOUNT

This applies only to 32-bit programming.

ARGCOUNT returns the number of arguments given when the definition is used and this can be used with conditional assembly in definitions. For example, suppose you have macro26 defined as:-

macro26(%a,%b,%c,%d,%e,%f) = #if ARGCOUNT=6   \
                            PUSH %f           \
                            #endif            \
                            #if ARGCOUNT >=5  \
                            PUSH %e           \
                            #endif            \
                            #if ARGCOUNT >=4  \
                            PUSH %d           \
                            #endif            \
                            #if ARGCOUNT >=3  \
                            PUSH %c           \
                            #endif            \
                            #if ARGCOUNT >=2  \
                            PUSH %b           \
                            #endif            \
                            #if ARGCOUNT >=1  \
                            PUSH %a           \
                            #endif

and then you use macro26 as follows

macro26(4,3,2,1)

then the value of ARGCOUNT would be four and the code would be the same as if you had coded:-

PUSH 1,2,3,4

In the above example, the first two pushes are skipped over because ARGCOUNT is neither 6 (in the first test) nor greater than or equal to 5 (in the second test).

This can be enlarged to provide a "C" function call macro where the stack is cleared up after the call (the correct number of bytes is added to the stack pointer ESP after the call):-

macro26(%x,%a,%b,%c,%d,%e,%f) = #if ARGCOUNT=7   \
                               PUSH %f           \
                               #endif            \
                               #if ARGCOUNT >=6  \
                               PUSH %e           \
                               #endif            \
                               #if ARGCOUNT >=5  \
                               PUSH %d           \
                               #endif            \
                               #if ARGCOUNT >=4  \
                               PUSH %c           \
                               #endif            \
                               #if ARGCOUNT >=3  \
                               PUSH %b           \
                               #endif            \
                               #if ARGCOUNT >=2  \
                               PUSH %a           \
                               #endif            \
                               CALL %x           \
                               ADD ESP,ARGCOUNT-1*4

and here is another way to do it:-

cinvoke(funcname,%1,%2,%3,%4,%5) = \
                               #if ARGCOUNT=1 \
                               invoke funcname  \
                               #elif ARGCOUNT=2   \
                               invoke funcname,%1  \
                               #elif ARGCOUNT=3      \
                               invoke funcname,%1,%2  \
                               #elif ARGCOUNT=4        \
                               invoke funcname,%1,%2,%3 \
                               #elif ARGCOUNT=5          \
                               invoke funcname,%1,%2,%3,%4 \
                               #elif ARGCOUNT=6             \
                               invoke funcname,%1,%2,%3,%4,%5 \
                               #endif                          \
                               #if ARGCOUNT>1                   \
                               ADD ESP,ARGCOUNT-1*4               \
                               #endif

These would then be used as follows:-

   cinvoke(_cprintf,23,24,25,26,27)
   macro26(_cprintf,23,24,25,26,27)

If you don't like using the continuation character, you can use MACRO...ENDM instead.

Using double hashes in definitions

A double hash in a definition joins two elements, removing all spaces in between. This enables you to create one single word out of one or more components, for example:-

LVERS=0030
MVERS=0044h
VERSION=LVERS##MVERS
;
MOV EAX,VERSION

Here VERSION is defined as the number 00300044h.

When to use definitions and when not to

Some programmers use definitions as often as possible. In my opinion this makes the source script more difficult to read. My criterion here is how easy it is for someone else to run through the source code and see what it is doing. If that person must frequently refer to other files or to lists of definitions to understand the source code, then it is bad coding. Used in moderation in Windows programming, however, definitions can be helpful to explain the source script. For example:-

PUSH WS_CHILD|WS_VISIBLE|SS_OWNERDRAW

means a lot more than:-

PUSH 5000000Dh

although the comment could provide clarity without using a definition:-

PUSH 5000000Dh        ;WS_CHILD, WS_VISIBLE, SS_OWNERDRAW

This example reduces clarity in your code and should be avoided:-

#define wParam EBP+10h
MOV EAX,[wParam]      ;same as MOV EAX,[EBP+10h]

The reason this is bad is that the reference [wParam] makes it appear that wParam is a label. Better is:-

#define wParam [EBP+10h]
MOV EAX,wParam

This is clearer because in GoAsm the only thing you can address in this way without using square brackets is a definition.

This is also bad and should be avoided at all costs:-

#define GET_LPARAM MOV EAX,[EBP+14h]
GET_LPARAM

Better programming practice is to use

CALL GET_LPARAM

and call it properly as a function. However when manipulating the stack it is very difficult to use a procedure since the CALL and RET themselves alter the stack. So in this instance it may be convenient to use a definition if source script clarity does not suffer. See for an example the OPEN_STACKFRAME and CLOSE_STACKFRAME examples above.

Also there seems little point in doing this:-

THOUSAND=1000D
MOV EAX,THOUSAND

when this would do perfectly well:-

MOV EAX,1000D

One use for definitions is if you want your source to be understandable to non-English speakers. Then you can translate all mnemonics using equates: see using defined words in Unicode files.
 

---

Importing: using run-time librariestop

Using the C Run-time library

With GoAsm it's easy to use the C run-time library. These are a number of functions contained in Crtdll.dll or Msvcrt.dll (or their variants) which are usually found on a Windows computer in the system folder. Information about the library is available from Microsoft's developer site (MSDN). The main thing to remember when using these functions is that although you send parameters to the function on the stack, the function does not restore the stack. Therefore you will need to use ADD ESP,x after the call, x being the number of bytes used for the parameters.
 

---

Importing: data, by ordinal, by specific Dlltop

Importing data

At run-time, data can only be imported indirectly. That is to say you can only import a pointer to data. However, using that pointer you can get the data itself.
For example, assuming DATA_VALUE is a data export in another program in GoAsm you get the pointer and the data as follows:-

MOV EBX,[DATA_VALUE]       ;get pointer to DATA_VALUE
MOV EAX,[EBX]              ;get the value

In the same way as for importing procedures from other programs at link-time you give the linker (GoLink anyway) the name of the executable containing the import.

Direct importing by ordinal

The type of importing we have been looking at using CALL procedure will import the procedure by name. What happens here is that when the Windows loader starts the program it searches through the Dlls for the imports required by the program. This is done by comparing the names of the Dll exports against the names of the program's imports. To speed up this process with private Dlls sometimes exporting and importing by ordinal is used. Then the loader can find the correct import by using an index to a table within the Dll. Note that it is unwise to do this in the case of Windows system Dlls since the ordinal numbers of the exports are not guaranteed to be the same across different Dll versions.

Using GoAsm and its companion program GoLink, you can import by ordinal using this simple syntax:-

CALL MyDll:6

This will call procedure number 6 in MyDll.dll. Note that the extension "dll" is assumed if no extension is given. Suppose you want a Dll to call a function in the main executable by ordinal, then you could use:-

CALL Main.exe:15

This calls the 15th function in Main.exe.
Calls to ordinals using the absolute form (using opcodes FF15) will result from using this syntax:-

CALL [Main.exe:15]

You should not include the path of the file in the call. GoLink carries out a wide search for specified files, but if it is necessary to provide a path this should be given to the linker and not incorporated in the call in the assembler script.
Obviously in order to use this method of calling a function by ordinal you must ensure that the ordinal number of the function is fixed see exporting by ordinal.

Note: the above only applies to GoLink

There is another way to use ordinals using LoadLibrary to load the Dll (or return a handle if it is already loaded) and then calling GetProcAddress passing the ordinal value to get the value of the procedure to call. Finally you call the procedure as returned by GetProcAddress.

Importing by specific Dll

Occasionally you may want to force the linker to use an import from a specific Dll. You might need to do this if two or more Dlls (given to the linker at link-time) offer functions with the same name. You can therefore force GoLink to link to a particular Dll using the syntax:-

CALL NameOfDll:NameOfAPI

Note: this only applies to GoLink
 

---

Exporting procedures and datatop

You can make your procedures and your data available to other executables by exporting them. In Windows it is usual for Dlls to be used for exports, but sometimes a Dll will need to call a procedure or use data in an Exe file, and in that case the Exe file will also export. Exporting can be done either at link time (you tell the linker which symbols to export), or using GoAsm, you can also do it at assemble time. GoAsm then gives the linker the export information via the .drectve section in the object file (note that not all linkers support this).
There are two ways to declare exports in GoAsm. You can either declare all the exports at the top of your file (before any sections are declared) or you can declare them within your source code as you go along. You may use either or both of these methods to suit your own preference.
Here is an example of declaring all the exports before any sections are declared:-

EXPORTS CALCULATE, ADJUST_DATA, DATA_VALUE

Here is an example of declaring an export as you go along:-

EXPORT CALCULATE:
CMP EAX,EDX                ;code for the
JZ >4                      ;procedure

This code exports the label to the procedure CALCULATE.
If you prefer you can have the two words on separate lines for example:-

EXPORT
CALCULATE:
CMP EAX,EDX                ;code for the
JZ >4                      ;procedure

Exporting data

Data can only be exported indirectly. That is to say you can only export a pointer to data. However, using that pointer the importing program can get the data itself.
You may use exactly the same method to export a data label as used to export a code label. There is no need to declare the label as data or code. This is because it is the linker's job to check whether the label is within a data or code section. Here is an example of a data label export:-

EXPORT DATA_VALUE DD 0

This exports the data label DATA_VALUE. The recipient would obtain the value of DATA_VALUE in the following way:-

MOV EBX,[DATA_VALUE]       ;get pointer to DATA_VALUE
MOV EAX,[EBX]              ;get the value

Exporting by ordinal

Normally exports are conducted by name. What happens here is that when the Windows loader starts the program it searches through the Dlls for the imports required by the program. This is done by comparing the names of the Dll exports against the names of the program's imports. To speed up this process with private Dlls sometimes exporting and importing by ordinal is used. Then the loader can find the correct import by using an index to a table within the Dll. Note that it is unwise to do this in the case of Windows system Dlls since the ordinal numbers of the exports are not guaranteed to be the same across different Dll versions.
In order to use this method it is clearly imperative that the exporting program specifies an ordinal value for a particular export and the linker must not change this. Again, using GoAsm you can specify the correct ordinal value and pass this to the linker via the .drectve section (not all linkers support this).
Here is how to specify an export by ordinal if exports are listed before any sections are declared:-

EXPORTS CALCULATE:2, DATA_VALUE:6

Here the linker will be instructed to use the ordinals 2 and 6 for the exports. If you are using the alternative method of declaring exports (within a section) you can use for example:-

EXPORT:2 CALCULATE:

or in the case of data:-

EXPORT:6 DATA_VALUE DD 0

Exporting by ordinal without a name

Exporting by ordinal does not stop the name of the export appearing in the final executable. This is because it is the importing program which decides whether to import by ordinal or by name. All the exporting program can do is to fix the ordinal value. However sometimes a programmer might like to ensure no name for the export appears in the final executable. You sometimes see such "no name" exports in system Dlls for example, probably in order to hide the job carried out by particular functions. In order to do this in GoAsm add the word NONAME to the end of the export for example:-

EXPORT:2:NONAME
CALCULATE:

Here the value of the code label CALCULATE will be exported as ordinal number 2, but the name of the export will not appear in the final executable. This means that if another program tried to call the CALCULATE function it would fail. The function can only be called by ordinal.
 

---

Automated register and flags save and restore using USES...ENDUtop

The USES statement followed by a list of registers, causes the registers to be PUSHed on the stack in the same order in which they appear in the list. Then, until ENDU is found in the source script (or ENDUSES if you prefer) any RET encountered will cause the registers to be POPed from the stack in reverse order. For example:-

ProcX:
USES EAX,EBX,ECX     ;ready to PUSH the registers on the stack
CMP EAX,ESI          ;first mnemonic causes the PUSHes to occur
;
; code for the procedure
;
.finnc
CLC                  ;ready to return carry flag not set
RET                  ;POP all registers in reverse followed by RET
;
.finc
STC                  ;ready to return carry flag set
RET                  ;POP all registers in reverse followed by RET
ENDU                 ;end all special POP action when RET found

You can also automatically push and pop the flags, using FLAGS which is a reserved word in GoAsm:-

USES FLAGS

You cannot change or add to the list of registers from within the procedure. To do that you would need an ENDU followed by a fresh USES list. If you need to RET without popping the registers you can use RETN ("normal" RET).

In 64-bit programming you can use the extended versions of the general purpose registers (RAX to RSP) and also the new 64-bit registers (R8 to R15). You can also use the 32-bit versions of the general purpose registers (EAX to ESP). This is because when PUSHing registers the 32-bit forms and the 64-bit forms are interchangeable (they produce the same opcode). So, whether you are assembling for 32-bits or for 64-bits,

USES RAX,RBX,RCX

will code the same as

USES EAX,EBX,ECX

This helps towards transportability of your code between the two platforms.
 

---

Callback stack frames in 32-bits and 64-bitstop

Introduction
Stack frames in 32-bit Windows
        Accessing the parameters from the stack
        Restoring the stack to equilibrium before returning to the caller
        Provide space on the stack for local data
        Preserve for Windows the EBX, ESI, EDI and EBP registers
Stack frames in 64-bit Windows
        Record and access the parameters
        Provide space on the stack for local data
        Preserve for Windows the non-volatile registers

See also "understand the stack" part 1 and part 2.

Introduction

In Windows programming, stack frames are needed for window procedures, hook procedures, superclassing and subclassing, Dll load and unload procedures, and for other callbacks. Callback procedures are all called by Windows, using your program's own thread.

In GoAsm the creation and use of stack frames is all automated when you use FRAME...ENDF.
See automated stack frames for how to use this in practice.

Since 32-bit and 64-bit Windows stack frames are different, they need to be treated separately. But the syntax for using FRAME...ENDF and their companion instructions such as LOCALS and USEDATA..ENDU are the same on both platforms. For this reason when you use FRAME...ENDF it is possible to use the same source script for both. See writing 64-bit programs for more information about 64-bit programming generally.

Stack frames in 32-bit Windows

The job that the stack frame has to do is dictated by the calling convention which is used. 32-bit Windows uses the standard calling convention (STDCALL). In this case the stack frame in a window procedure needs to do four jobs:-

• Access the parameters sent by Windows (which are sent on the stack)
• Restore the stack to equilibrium before returning to the caller
• Provide space on the stack for local data
• Preserve for Windows the EBX, ESI, EDI and EBP registers if they are altered

All four of these are equally important.

Accessing the parameters from the stack

Windows pushes the parameters on the stack before calling your window procedure. This is exactly the same as your code pushing parameters on the stack before calling an API. When Windows calls a window procedure it sends the following parameters as dwords placed on the stack (the words used here are the ones commonly used to label these parameters):-

hwnd        window handle
uMsg        message identifier
wParam      data
lParam      data

Your window procedure needs to access these parameters. One way is to POP them off the stack into static data, but an easier (and safer) way is to keep them on the stack and reference them directly from the stack. This is better because window procedures sometimes call themselves. This may seem odd, but one example will suffice. Suppose your window procedure needs to fill the window with the correct material at the right time. This is called "painting" the window. This is done by responding to the Windows message WM_PAINT (message number 0Fh). Now the proper way to respond to this message is first to call the API BeginPaint, then to paint the window then to call the API EndPaint. One of the things BeginPaint does is to prepare the window for the paint. In doing so it sends another message to your window procedure, this time WM_ERASEBKGRND (message number 14h). So while your window procedure is dealing with this second message it has not yet returned from the API BeginPaint. After the second message has been dealt with BeginPaint will return. So the window procedure is recursive that is to say, it can come back to itself. For each message (except for hwnd) the parameters will be different. If they are kept on the stack it means that each time the window procedure will be called the parameters will be kept on a different part of the stack and cannot be written over.

A typical 32-bit stack frame will be set up as follows:-

TypicalStackFrame:
PUSH EBP          ;save the value of ebp which will be altered    } called the
MOV EBP,ESP       ;give current value of stack pointer to ebp     } "prologue"
;                 ;POINT "X"
;                 ;code to isolate WM_PAINT message
PUSH ADDR PAINTSTRUCT
PUSH [hwnd]
CALL BeginPaint   ;get ready to paint window
;                 ;paint window and call EndPaint
;
MOV ESP,EBP       ;restore the stack pointer to previous value    } called
POP EBP           ;restore the value of ebp                       } the
RET 10h           ;return to caller adjusting the stack pointer   } "epilogue"

During any recursion esp will be changed since further use of the stack will be made. But ebp is always saved and restored by this procedure so it can always be relied on to access the correct part of the stack for the message being dealt with.
This is probably best illustrated by an example. In a typical window procedure responding to the message WM_ERASEBKGRND taking a snapshot of the stack when execution is at point "X" the stack will look similar to this (I have missed out a lot of use of the stack for clarity):-

ebp-4h	the next push will go here
ebp	saved value of ebp
ebp+4h	caller's return address
ebp+8h	hwnd
ebp+0Ch	uMsg
ebp+10h	wParam
ebp+14h	lParam
ebp+18h	)
ebp+1Ch	) other use of stack
ebp+20h	) (BeginPaint etc)
ebp+24h	)
ebp+28h	saved value of ebp
ebp+2Ch	caller's return address
ebp+30h	hwnd
ebp+34h	uMsg
ebp+38h	wParam
ebp+3Ch	lParam

Here the parameters lParam, wParam, uMsg and hwnd which are on the stack at ebp+3Ch to ebp+30h are those sent to the window procedure on the WM_PAINT message. Then at ebp+2Ch there is the return address of the caller sending the WM_PAINT message (this will be a call from a Windows Dll). Then ebp+28h is the value of ebp saved on the first instruction coming into the window procedure on the WM_PAINT message. Between ebp+24h and ebp+1Ch is some use of the stack within your window procedure before you called the API BeginPaint. In fact there would be two PUSHes, and then on calling the API the return address (back into your window procedure) would be put on the stack. The fourth PUSH here could be something PUSHed onto the stack by BeginPaint itself prior to sending the WM_ERASEBKGRND message. In practice there would be much more use of the stack within BeginPaint here. The next thing you see at ebp+14h is lParam again. But this is a different lParam than that at ebp+3Ch. This is the lParam sent with WM_ERASEBKGRND. The remainder of the entries up to the current value of EBP are those relating to the WM_ERASEBKGRND message.
Now lets see what happens when BeginPaint returns. Since we know that BeginPaint will always restore ebp to the value it was on entry to the API, we know that ebp on return will point to the stack at ebp+28h in the above stack frame. From that point, you can see the earlier parameters (those sent with WM_PAINT) can be accessed using ebp+8h, ebp+0Ch, ebp+10h and ebp+14h as before. They were preserved and were not written over by the call to BeginPaint and by the recursion into the window procedure.

Restoring the stack to equilibrium before returning to the caller

It is also the job of the windows procedure to restore the stack to equilibrium before it returns to the caller. This involves moving the stack pointer to a higher value by 4 bytes (a dword) for each argument which is sent (each PUSH by the caller has reduced the value of ESP by four so it points to a higher place on the stack). This is exactly what Windows itself does when you call an API. For example, in

PUSH ADDR PAINTSTRUCT
PUSH [hwnd]
CALL BeginPaint   ;get ready to paint window

the stack pointer (esp) was made more negative by 8 bytes by reason of the two pushes before the call to the API BeginPaint. But after the return from BeginPaint, the stack pointer is back where it started. This is because within BeginPaint it was made more positive by 8 bytes before returning to your code.
Window procedures always have 4 parameters so you know the stack pointer must be moved by 16 bytes to restore it. Other types of callbacks have different numbers of parameters. The Windows SDK gives the appropriate information about those.
The caller could use ADD ESP,10h to add the 16 bytes after the call but the easiest way is for the procedure itself to move the stack pointer before returning to the caller using the RET instruction with a number, for example RET 10h. This instruction POPs from the stack the caller's return address, moves the stack pointer (ESP register) by the correct number of bytes in this case 16, then finally diverts execution to the caller's return address.

Provide space on the stack for local data

Another important task for the callback procedure is to provide space for local data. Local data is data which is kept on the stack while execution is continuing in the callback procedure. It is lost after execution leaves the procedure. We have already seen how data on the stack (in the form of parameters) is preserved by making a stack frame. Space for local data uses the same principle. Suppose we need space for 3 dwords on the stack because we want to preserve this data however deep the window procedure recurses. Then we would code:-

TypicalStackFrame:
PUSH EBP          ;save the value of ebp which will be altered    }
MOV EBP,ESP       ;give current value of stack pointer to ebp     } "prologue"
SUB ESP,0Ch       ;make space for local data                      }
;                 ;POINT "X"
;
;                 ;window procedure code
;
MOV ESP,EBP       ;restore the stack pointer to previous value    }
POP EBP           ;restore the value of ebp                       } "epilogue"
RET 10h           ;return to caller adjusting the stack pointer   }

Here we have moved the stack pointer by 12 bytes, which is exactly the same as if we had done 3 PUSHes. This provides an area of the stack which cannot be used for any other purpose.

Using FRAME...ENDF you can create the stack frame automatically.
Here is a typical use of FRAME...ENDF which does the same as the TypicalStackFrame code above, as well as providing names for the parameters which are sent to the window procedure and names for each dword of local data:-

WndProc FRAME hwnd,uMsg,wParam,lParam
LOCALS hDC,hInst,KEEP
;                 ;POINT "X"
;
;                 ;code goes here
;
RET
ENDF

The stack actually looks like this (at point "X" again):-

ebp-10h	the next push will go here
ebp-0Ch	space for local data KEEP ← esp is currently here (top of local data)
ebp-8h	space for local data hInst
ebp-4h	space for local data hDC
ebp	saved value of ebp ← ebp given value of esp when it was here
ebp+4h	caller's return address
ebp+8h	hwnd
ebp+0Ch	uMsg
ebp+10h	wParam
ebp+14h	lParam
ebp+18h	)
ebp+1Ch	) other use of stack

Of course if the stack pointer is adjusted in this way it must also be restored. But this time it is automatic because it is simply restored to the value of ebp before returning to the caller, and ebp was saved before the stack pointer was moved to make space for local data.

Preserve for Windows the EBX, ESI, EDI and EBP registers

Finally your windows procedure must preserve the ebx, esi, edi and ebp registers. EBP is saved and restored already by the prologue and epilogue code. As for EBX, ESI and EDI, it is probably a good idea to save and restore these even if they are not actually changed by your window procedure, then you need not worry about this any further. In the same way, you can rely on a Windows API preserving these registers. This is particularly useful in assembler programming because you can keep useful handles and other values in these registers whilst calling APIs. You can easily do this using the USES statement for example:-

WndProc FRAME hwnd,uMsg,wParam,lParam
USES EBX,ESI,EDI
LOCALS hDC,hInst,KEEP
;
;                 ;code goes here
;
RET
ENDF

Stack frames in 64-bit Windows

The job that the stack frame has to do is dictated by the calling convention which is used. 64-bit Windows uses the so-called fast calling convention (FASTCALL). Instead of the caller putting the parameters on the stack as in the STDCALL convention, the first four parameters are put in the RCX,RDX,R8 and R9 registers. If there are any more parameters these are put on the stack. So the window procedure needs to do these jobs:-

• Record on the stack the parameters sent in the registers and access any additional parameters sent by Windows on the stack
• Provide space on the stack for local data
• Preserve for Windows the "non-volatile" registers of they are altered. These are the RBP,RBX,RDI,RSI,R12 to R15 and XMM6 to XMM15 registers.

There is no need for the window procedure to restore the stack to equilibrium before returning to the caller. This job is done by the caller.

Record and access the parameters

The RCX,RDX,R8 and R9 registers are "volatile". That is to say Windows does not guarantee that they will be maintained across an API call. The first four parameters are, however, sent in these registers. This means that as soon as your window procedure makes an API call it is possible that the parameters will be written over. For this reason it is necessary to keep these parameters safely. They could be kept in the non-volatile registers, but the Windows documentation recommends that they are kept on the stack itself. Apparently this is done within the APIs themselves. In the FASTCALL calling convention as documented and implemented in 64-bit Windows, the caller is obliged to move RSP more negatively by 32 bytes before making the call to provide space on the stack for this to be done. The stack places so reserved are called "placeholders". Each parameter has its own known placeholder. In the light of this one might be forgiven for querying why FASTCALL was chosen if the parameters end up on the stack anyway. They might have well been put there by the caller in the first place!

To deal with the requirement to record the parameters sent in the registers, when you use FRAME...ENDF in 64-bit code, GoAsm creates instructions like this at the beginning of the stack frame:-

MOV [RSP+8h],RCX
MOV [RSP+10h],RDX
MOV [RSP+18h],R8
MOV [RSP+20h],R9
PUSH RBP
MOV RBP,RSP

This code puts the parameters in their placeholders on the stack. If there are fewer than four parameters not all these instructions are emitted. Note that parameter five (if present) is already on the stack at [RSP+28h], parameter six is at [RSP+30h] etc. The final two instructions set up RBP as a pointer to the data, having saved RBP first so it can be restored later.

In the epilogue you would expect to see something like:-

LEA RSP,[RBP]
POP RBP
RET

The LEA instruction here is used instead of the simpler MOV RSP,RBP to help the Windows exception handler to identify the epilogue.

Provide space on the stack for local data

This works in exactly the same way as in a 32-bit stack frame except that each local data item must be at least a qword in size. So for example if there were three local data qwords, the instruction to make space for it would be SUB RSP,18h.

Preserve for Windows the non-volatile registers

RBP is saved and restored already by the prologue and epilogue code. As for the general purpose registers RBX,RDI,RSI and R12 to R15, if they are altered by the window procedure, they will need to be restored in value. The easiest way to do this is to use the USES statement. This keeps them on the stack. The XMM6 to XMM15 registers can be saved and restored en bloc, using the FXSAVE and FXRSTOR instructions.

Taking a typical use of FRAME...ENDF as follows:-

WndProc FRAME hwnd,uMsg,wParam,lParam
USES RBX,RSI,RDI
LOCALS hDC,BUFFER[256]:B
;               ;POINT 'X'
;               ;code goes here
;
RET
ENDF

Here is how the stackframe turns out in 64-bit assembly, using the RSP and RBP values at the start of code proper at POINT 'X' (note that RBP is 32 bytes less than RSP was when entering the procedure: this is because of the PUSH RBP,RBX,RSI and RDI instructions):-

rbp-118h	next push goes here
rbp-110h	) 256 byte buffer ← rsp is currently here (top of local data)
	)
	)
rbp-8h	hDC
rbp	saved value of rdi ← rbp given value of rsp when it was here
rbp+8h	saved value of rsi
rbp+10h	saved value of rbx
rbp+18h	saved value of rbp
rbp+20h	caller's return address
rbp+28h	place holding hwnd (originally in rcx)
rbp+30h	place holding uMsg (originally in rdx)
rbp+38h	place holding wParam (originally in r8)
rbp+40h	place holding lParam (originally in r9)
rbp+48h	param #5 if present
rbp+50h	param #6 if present

---

Automated stack frames using FRAME...ENDF, LOCALS and USEDATAtop

Introduction

---

      The basics
      Accessing the parameters and local data within an automated frame
      Using structures as local data in a stack frame

Practice

---

      Some practical considerations
      Calling procedures within the stack frame - use of RETN
      Calling procedures outside the stack frame - use of USEDATA

Advanced use

---

      Declaring message-specific local data - positioning the LOCAL statement
      Creating a minimised window procedure
      Locally defined words using #localdef or LOCALEQU
      Re-usable label scope in automated stack frames
      Inheritance and scope when using USEDATA..ENDU
      Releasing local data and making new local data - use of LOCALFREE

General

---

      Some syntax points when using FRAME...ENDF
      Some syntax points when using USEDATA...ENDU
      What you can see in the debugger.

The basicssub-menu

FRAME...ENDF is similar to MASM's PROC...ENDP, but with GoAsm you can do a lot more. Subroutines can also use data on the stack using USEDATA...ENDU. And you can declare local data dynamically. This permits you within the window procedure to declare only the local data which is actually required for a particular message. You can use locally defined words which only operate within their own FRAME..ENDF envelopes or USEDATA..ENDU areas associated with them.
Also in GoAsm the syntax is more relaxed and the source script is much easier to understand because there is no type or parameter checking.

You use FRAME...ENDF to make an automated stack frame. Here is how you would use it:-

WndProc FRAME hwnd,uMsg,wParam,lParam
USES EBX,ESI,EDI
LOCALS hDC,BUFFER[256]:B
;
;               ;code goes here
;
RET
ENDF

When you use FRAME..ENDF in this way GoAsm creates a stack frame "behind your back". For this reason it may be mistrusted a little. Assembler programmers like to know what is going on, which is why they are assembler programmers in the first place! So I'm going to describe this in some detail. You don't need to know all these details.
If you want you can skim over these details and see how FRAME...ENDF works in practice from the Hello World 3 GoAsm sample program.

In the code above, FRAME tells GoAsm that you want to make an automated stack frame.
ENDF signifies the end of the automated stack frame.
The words after "FRAME" are the parameters. In this case there are four parameters which are being given the names shown here. There is no need to add anything else since GoAsm knows the size of the parameters. In 32-bit coding they are always dwords; in 64-bit coding they are always qwords.
USES tells GoAsm which registers need to be preserved in the frame. Here we use the 32-bit registers, but in 64-bit assembly this is read as USES RBX,RSI,RDI without having to change the source code (in the case of PUSH register its the same opcode which is generated for each platform).
LOCALS permits you to declare and label local data in the frame. GoAsm adds up the size of this local data and sets aside space for it on the stack. When declaring local data, in 32-bit assembly dword is the default, and in 64-bit assembly qword is the default. The default is used if you don't give a size for the data. So in the example, hDC is a dword. There is also an area on the stack called BUFFER. This is 256 bytes because of the [256]:B. Instead of B you can use W,D,Q or T for words, dwords, qwords or twords respectively or you can use the name of a structure see using structures as local data in a stack frame.

GoAsm automatically creates the prologue code as described in the 32-bit or 64-bit sections above.
GoAsm will add the epilogue code each time it sees a RET within the frame delineated by FRAME...ENDF.

Accessing the parameters and local data within an automated framesub-menu

Within a frame made in this way you can access the parameters send to the window procedure. In the following 32-bit example the offsets from EBP which are generated by GoAsm are given on the assumption there is no USES statement (64-bit coding is very similar but it uses RBP and each stack element is 8 bytes instead of 4):-

PUSH [hwnd]          ;equivalent to PUSH [EBP+8h]
MOV EAX,[uMsg]       ;equivalent to MOV EAX,[EBP+0Ch]
MOV EBX,ADDR wParam  ;equivalent to LEA EBX,[EBP+10h]
PUSH ADDR lParam     ;equivalent to PUSH EBP then ADD D[ESP],14h
MOV EBX,[hDC]        ;equivalent to MOV EBX,[EBP-10h]
MOV EBX,ADDR BUFFER  ;equivalent to LEA EBX,[EBP-110h]

In this coding GoAsm finds on the stack the correct position of the label you are accessing and codes it appropriately for you. If you use the /l option on the command line you can see this in the list file output. Alternatively you can see this in the debugger.

Note that the address of the buffer is given at its most negative point. This is correct, so if you code:-

MOV D[BUFFER+10h],44h

You are inserting the value 44h at a dword which is 16 bytes into the buffer.

Note that GoAsm sets the value of EBP after PUSHing the registers named in the USES statement. This arrangement permits the amount of local data to be adjusted dynamically on a message-specific basis. But it also means that if you have a USES statement in a FRAME the offset of the parameters from EBP will be greater than otherwise. So, for example if you PUSH three registers in a FRAME with the USES statement as follows:-

USES EBX,EDI,ESI

then EBP will be pushed further away from the parameters by 12 bytes. So in this example hwnd would be at [EBP+14h], uMsg at [EBP+18h], wParam at [EBP+1Ch] and lParam at [EBP+20h]. When coding you need not worry about the exact position of the parameters relative to EBP, but you will need to be aware of this when looking at your code in the debugger. See also what you can see in the debugger.

Using structures as local data in a stack framesub-menu

In this example, local data of a size to suit the structure RECT, previously declared in your source script, is established on the stack.

RECT STRUCT
  left   DD 0
  top    DD 0
  right  DD 0
  bottom DD 0
ENDS
;
WndProc FRAME hwnd,uMsg,wParam,lParam
LOCALS hDC,rc1:RECT
;
;               ;code goes here
;
RET
ENDF

Each element of the RECT structure can be accessed in the same way as if it were in static data for example (again using 32-bit examples):-

MOV EAX,[rc1.right]        ;equivalent to MOV EAX,[EBP-0Ch]
MOV EAX,[ESI+RECT.right]   ;equivalent to MOV EAX,[ESI+8h]
MOV EAX,SIZEOF RECT        ;equivalent to MOV EAX,10h
MOV EAX,ADDR rc1.right     ;equivalent to LEA EAX,[EBP-0Ch]
PUSH [rc1.right]           ;equivalent to PUSH [EBP-0Ch]
PUSH ADDR rc1.right        ;equivalent to PUSH EBP then ADD D[ESP],-0Ch
PUSH ADDR rc1              ;equivalent to PUSH EBP then ADD D[ESP],-14h

Some practical considerationssub-menu

Exactly how you want to use the facility provided by FRAME...ENDF will be a matter of personal taste.
You may want to enclose all your window procedure code within the FRAME...ENDF frame. In that case you will need to ensure that sub-routines use a "normal" RET by using RETN.
You may want to keep the FRAME...ENDF frame as compact as possible but yet access the parameters and local data from outside it. You can do this by specifying a USEDATA...ENDU area.
You may want to declare message-specific local data rather than for the stack FRAME as a whole. You can do this by positioning the LOCAL statement.
You may want to combine these methods with a message table to create a minimised window procedure.
You may want to release local data areas and then make new local data areas. You can do this by using the LOCALFREE statement.

Calling procedures within the stack frame - use of RETNsub-menu

You can have as many return points from the FRAME procedure using RET as you like. Each one will produce the epilogue code which is run when leaving the stack frame. However, this also means that if you have additional procedures within the stack frame you must be careful to use RETN ("normal" RET) to avoid creating epilogue code for those.
Only the main FRAME procedure ought to be called from outside the FRAME. Calling any additional procedures can cause unpredictable results. This is because procedures within the FRAME...ENDF envelope expect to address parameters and local data using the stack pointer (RBP or EBP) and this will not have been set up if called from outside.
Here is an example in practice:-

WndProc FRAME hwnd,uMsg,wParam,lParam
USES EBX,ESI,EDI
LOCAL hDC,BUFFER[256]:B
MOV EAX,[uMsg]        ;get message sent by Windows
CMP EAX,0Fh           ;see if it is WM_PAINT
JNZ >L2               ;no
CALL WINDOW_PAINT     ;paint the window
XOR EAX,EAX           ;return zero to show message dealt with
RET                   ;restore stack and return to Windows
;
L2:
ARG [lParam],[wParam],[uMsg],[hwnd]
INVOKE DefWindowProcA ;allow Windows to deal with the message
RET                   ;restore stack and return to Windows
;
WINDOW_PAINT:
;  code to paint the window
RETN                  ;do ordinary return from paint procedure
;
ENDF                  ;stop all FRAME action from this point onwards

Calling procedures outside the stack frame - use of USEDATA...ENDUsub-menu

You may prefer to keep the frame itself compact and call outside the frame to help the readability of your code. You can do this and still maintain access to the parameters and local data within the frame by using the USEDATA statement followed by the name of the frame concerned. For example, the WM_PAINT message in the frame above might call this procedure:-

PAINT:
USEDATA WndProc
INVOKE BeginPaint, [hwnd],ADDR lpPaint     ;get in eax the DC to use
MOV [hDC],EAX
INVOKE Ellipse, [hDC],[lpPaint.rcPaint.left],   \
                      [lpPaint.rcPaint.top] ,   \
                      [lpPaint.rcPaint.right],  \
                      [lpPaint.rcPaint.bottom]
INVOKE EndPaint, [hwnd],ADDR lpPaint
XOR EAX,EAX
RET
ENDU

Here the procedure PAINT is using local data in the FRAME called WndProc. All the code above is outside the FRAME...ENDF envelope.
You can also use USEDATA to access local data in other USEDATA..ENDU areas.
Just make sure that USEDATA is used later in the source script than any parameters and local data declarations that it relies on. This is because GoAsm is a one pass assembler and it needs to find the position of that earlier data.
If a procedure which is called from a FRAME or a USEDATA area does not need to access any of the parameters, local data, or locally defined words, then it need not have its own USEDATA statement.

More than one exit point or procedure within a USEDATA...ENDU area

Just as when using FRAME...ENDF, you can have as many return points from the USEDATA procedure using RET as you like. Each one will produce the correct epilogue code which is run when leaving the USEDATA area. However, this also means that if you have additional procedures within the USEDATA area you must be careful to use RETN ("normal" RET) to avoid creating epilogue code for those.
Only the first USEDATA procedure ought to be called from outside the USEDATA..ENDU area. This is because the correct code to access the stack will only be set up for this first procedure.

Declaring message-specific local data - positioning the LOCAL statementsub-menu

In the examples so far the area of local data held on the stack has been declared for the stack FRAME overall. But you may prefer to establish some or all of the local data on a message-specific basis. Here is an example of how to do this:-

WndProc FRAME hwnd,uMsg,wParam,lParam
USES EBX,ESI,EDI
LOCAL hDC             ;declare hDC for frame-wide use
MOV EAX,[uMsg]        ;get message sent by Windows
CMP EAX,0Fh           ;see if it is WM_PAINT
JNZ >L2               ;no
CALL WINDOW_PAINT     ;paint the window
XOR EAX,EAX           ;return zero to show message dealt with
RET                   ;restore stack and return to Windows
;
L2:
ARG [lParam],[wParam],[uMsg],[hwnd]
INVOKE DefWindowProcA ;allow Windows to deal with the message
RET                   ;restore stack and return to Windows
;
ENDF                  ;stop all FRAME action from this point onwards
;
WINDOW_PAINT:
USEDATA WndProc       ;use parameters and local data from WndProc
LOCAL ps:PAINTSTRUCT  ;make local data areas
LOCAL BUFFER[1024]:B  ;specifically for this message
;
ARG ADDR ps,[hwnd]
INVOKE BeginPaint     ;get ready to paint window
MOV [hDC],EAX         ;keep the device context in hDC local data
;  code to paint the window
RET                   ;do ordinary return from paint procedure
ENDU                  ;end use of WndProc frame data

Creating a minimised window proceduresub-menu

Using the methods described you can create a minimised window procedure using a message table. The window procedure itself needs to be no larger than this:-

WndProc FRAME hwnd,uMsg,wParam,lParam
MOV EAX,[uMsg]
MOV ECX,SIZEOF MESSAGES/8
MOV EDX,OFFSET MESSAGES
:
DEC ECX
JS >.notfound
CMP [EDX+ECX*8],EAX     ;see if its the correct message
JNZ <                   ;no
CALL [EDX+ECX*8+4]      ;call the correct procedure for the message
JNC >.exit
.notfound
INVOKE DefWindowProcA,[hwnd],[uMsg],[wParam],[lParam]
.exit
RET
ENDF

Somewhere in the data or const section would be the following table for the messages (in practice there would be a lot more messages than this):-

MESSAGES DD 1h,  CREATE     ;the message value then the code address
         DD 2h,  DESTROY
         DD 0Fh, PAINT
NextLabel:

And then in the code section (and below WndProc) you would have the code for these messages, for example:-

CREATE:
USEDATA WndProc    ;use stack data in the window procedure frame
USES EBX,EDI,ESI   ;preserve the registers for Windows
LOCALS LocalData   ;establish required local data area
;
; code to execute on the WM_CREATE message
;
XOR EAX,EAX        ;return nc and eax=0 to continue creating the window
RET                ;restore the registers and then RET
ENDU               ;stop all automated action and access to data

In the minimised window procedure DefWindowProc is not called unless either the message is not found in the message table or the message code returns with the carry flag set. Some messages must call DefWindowProc even if they are processed by the window procedure - see the Windows SDK.

Locally defined words using #localdef or LOCALEQUsub-menu

Within a FRAME..ENDF envelope you can use locally defined words. The definition can be made either in the FRAME..ENDF envelope itself or in an associated USEDATA..ENDU area.
Their scope is limited to the FRAME or USEDATA area. See inheritance and scope when using USEDATA..ENDU for more details about how this works in practice.
You define such local words using #localdef (or LOCALEQU if you prefer - they do the same thing).

For example:-

FrameProc1 FRAME Param
#localdef THING1 23h
THING2 LOCALEQU 88h
;
MOV EAX,THING1       ;local define 23h
MOV EAX,THING2       ;local define 88h
;
RET
ENDF
;
MyFunction44: USEDATA FrameProc1
#localdef THING3 0CCh
;
MOV EAX,THING1       ;local define should be 23h
MOV EAX,THING2       ;local define should be 88h
;
RET
ENDU

In the above example, if THING1 and THING2 are defined globally (using #define or EQU), that definition is ignored (the local definition takes priority).

#undef has local scope priority. If the word to be undefined is found locally, then #undef applies to that. If not, #undef will apply to a global label.

Re-usable label scope in automated stack framessub-menu

Re-usable labels beginning with a period can be accessed anywhere within an automated stack frame (which can be established using FRAME...ENDF). Other unique labels within the frame are ignored for this purpose, so for example,

ExampleProc FRAME Param
CMP EDX,EAX
JZ >.fin
LABEL1:
XOR EAX,EAX
.fin
RET
ENDF
LABEL2:

Here the jump to .fin will still work despite the existence of LABEL1. This is because the label .fin has the scope of the whole frame, and not just the code between LABEL1 and LABEL2. In other words using FRAME...ENDF enlarges the scope of the re-usable label to the whole frame.

Inheritance and scope when using USEDATA..ENDUsub-menu

A USEDATA..ENDU area can be associated either directly with a FRAME, or alternatively with another USEDATA..ENDU area.
This enables advanced users to select the local data and defined words which a USEDATA area can use.

The usual arrangement is to have each USEDATA area a child of the FRAME:-

FrameExample FRAME Param LOCAL LocalLabel1 #localdef CONSTANT 23h ; RET ENDF ; Usedata#1: USEDATA FrameExample MOV EAX,[LocalLabel1] MOV EAX,CONSTANT MOV EAX,[Param] RET ENDU ; Usedata#2: USEDATA FrameExample LOCAL Specific #localdef SPECIFIC_CONSTANT 444444h MOV EAX,[LocalLabel1] MOV EAX,CONSTANT MOV EAX,[Param] MOV EAX,[Specific] MOV EAX,SPECIFIC_CONSTANT RET ENDU

Here each USEDATA area can access the FRAME's parameters, local data and defined words. Note, however, that Usedata#2 has its own local data and defined word. Those can only be referenced within Usedata#2. If Usedata#1 tried to access them (or the code in FrameExample for that matter), they would not be found.

---

In the next arrangement, the first USEDATA area is a child of the FRAME and the second USEDATA area is its grandchild.

FrameExample FRAME Param LOCAL LocalLabel1 #localdef CONSTANT 23h ; RET ENDF ; Usedata#1: USEDATA FrameExample LOCAL Specific #localdef SPECIFIC_CONSTANT 444444h RET ENDU ; Usedata#2: USEDATA Usedata#1 MOV EAX,[LocalLabel1] MOV EAX,CONSTANT MOV EAX,[Param] MOV EAX,[Specific] MOV EAX,SPECIFIC_CONSTANT RET ENDU

Here, although each USEDATA area can access the frame's parameters, local data and defined words, Usedata#2 can also reference the local data and locally defined words in Usedata#1.

---

Releasing local data and making new local data - use of LOCALFREEsub-menu

LOCALFREE is only available for 32-bit programs and is not allowed with x86 or x64 modes due to the prologue stack usage information recorded for exception handling.

You can use LOCALFREE to release areas of local data ready to make new local data. This may help to conserve memory if you use the stack a lot. LOCALFREE will render existing local data declared in the FRAME or USEDATA...ENDU area in which it appears inaccessible to all later code in your source script. It will not affect local data in other FRAMES or USEDATA areas. When GoAsm sees LOCALFREE in the source script it causes the value of ESP/RSP to be restored to its value in the current FRAME or usedata area before any local data was declared. You can then declare new local data using LOCAL or LOCALS.
Only use LOCALFREE when the stack is in equilibrium. Do not use it if there are any outstanding PUSHes which need to be POPped. This is because the change to ESP/RSP will effectively rub over any outstanding PUSHes.
At the end of a procedure you do not need to use LOCALFREE since the stack is restored automatically on a RET anyway.
Here is an example of how to use LOCALFREE:-

CREATE:
USEDATA WndProc    ;use stack data in the window procedure frame
USES RBX,RDI,RSI   ;preserve the registers for Windows
LOCALS BUFFER[4000]:B    ;establish large buffer on the stack
;
; part code to execute on the WM_CREATE message
;
LOCALFREE                ;rub out large buffer
LOCALS BUFFER[256]:B     ;establish smaller buffer on the stack
;
; part code to execute on the WM_CREATE message
;
XOR RAX,RAX        ;return nc and rax=0 to continue creating the window
RET                ;restore the registers and then RET
ENDU               ;stop all automated action and access to data

Some syntax points when using FRAME...ENDFsub-menu

CodeLabel:
	FRAME Parameter List	;if any parameters are needed
	USES Register List	;if registers need to be saved
	LOCAL Local List	;if local variables are required
	;
	ret
	ENDF

Some syntax points when using USEDATA...ENDUsub-menu

CodeLabel:
	USEDATA SourceData
	USES Register List	;if registers need to be saved
	LOCAL Local List	;if local variables are required
	;
	ret
	ENDU

What you can see in the debuggersub-menu

In 32-bit FRAMEs, GoAsm PUSHes EBP and registers specified by USES first, then keeps the value of the stack pointer ESP in EBP using MOV EBP,ESP. On a RET this is reversed, so you will see MOV ESP,EBP followed one or more register POPs. Space is made for the local data using SUB ESP,x where x depends on the amount of space for local data required.
In 64-bit FRAMEs, GoAsm's first job is to store parameters #1 to #4 on the stack using an instruction like MOV [RSP+8h],RCX as described earlier. Then after PUSHing RBP and registers specified by USES, MOV RBP,RSP is used to keep the stack pointer. Coming out of the FRAME LEA RSP,[RBP] is used to restore RSP ready to POP the registers and a RET.

Code such as MOV EAX,[EBP-34h] or LEA,[EBP-56h] or PUSH EBP, ADD D[ESP],-60h (or their 64-bit register equivalents) will be generated when local data is accessed. The offset values will be positive when accessing parameters.

In USEDATA areas, since GoAsm does not know at assemble-time how much use of the stack there has been before the call to the USEDATA procedure, it makes a "shield" of 100h bytes (200h bytes in 64-bit assembly) to ensure that such stack use is protected from over-write. For this reason the offset numbers used when local data is accessed may be larger than expected.
Advanced users may like to adjust the size of the shield. This can be done using this syntax, for example:-

USEDATA WndProc SHIELDSIZE:20h      ;in 32-bit assembly
USEDATA WndProc SHIELDSIZE:40h      ;in 64-bit assembly

In USEDATA areas the value of the stack pointer is not kept in the EBP or RBP register because this already holds the stack pointer on entry into the FRAME. Instead, GoAsm keeps the value of the stack pointer at a convenient place on the stack. This is done when the first local data in the USEDATA area is declared. In order to do this safely GoAsm adds several lines of code culminating in MOV EAX,[EAX-4h] (or MOV RAX,[RAX-8h] in 64-bit assembly). GoAsm uses EAX/RAX during this process but restores its value afterwards, so you can still use it to pass information to the procedure. On a RET you will see the value of ESP/RSP being restored using POP ESP/RSP.

LOCALFREE will also cause a restoration of the stack pointer.

USES statements will cause PUSHes of the registers concerned before ESP/RSP is saved and POPs of the registers after it is restored.
 

Conditional assemblytop

What is conditional assembly and why use it?

The conditional directives

#if condition
text A
#endif

Here if the condition is TRUE text A will be assembled. If, however, the condition is FALSE, the assembler will jump over text A and will continue compiling from the #endif.

You can add something to do if the condition is FALSE as follows:-

#if condition
text A
#else
text B
#endif

Here if the condition is TRUE, text A will be assembled, but text B will not be assembled.

If, however, the condition is FALSE, text A will be jumped over but text B will be assembled.

The #endif indicates the end of the conditional frame, so that all text after that will be assembled.

The #else statement must always be next before the #endif.

You can add a further condition to the frame:-

#if condition1
text A
#elif condition2
text B
#endif

Here if condition1 is TRUE, text A will be assembled, but text B will be jumped over and assembly will continue from the #endif. If, however, condition1 is FALSE, text A will be jumped over to the #elif when condition2 will be tested. If then condition2 is TRUE, text B will be assembled. "#elif" is the same as "#elseif".

Adding the #else to the above conditional frame produces:-
#if condition1
text A
#elif condition2
text B
#else
text C
#endif

Here if condition1 is TRUE, text A will be assembled, but text B and text C will be jumped over and assembly will continue from the #endif. If, however, condition1 is FALSE, text A will be jumped over to the #elif when condition2 will be tested. If then condition2 is TRUE, text B will be assembled, and text C will be ignored; if, however condition2 is FALSE text B will be jumped over to the #else and text C will be assembled.

You can have as many #elifs as you like in each conditional frame, but there can only be one #else per frame, and each #if must have a corresponding #endif. Some programmers nest the conditional frames, but this can become very confusing and may not be good programming practice. If this is done it is recommended that you label each #endif with a comment so that you can see to which #if it refers.

Types of #if statements

#ifdef identifier

Examples of conditional assembly

#define HELLO
;
#ifdef HELLO
BSWAP EAX          ;swap the bytes in eax if HELLO is defined
#endif

#if HELLO==3
OUTPUT DD 3h       ;if HELLO is defined as 3 declare data label OUTPUT as 3
#elif WINVER>=400h
OUTPUT DD 4h       ;alternative data if WINVER is equal to or greater than 400h
#else
OUTPUT DD 5h       ;alterative data if neither of the above apply
#endif

GoASM /l /d WINVER=401h MyProg.ASM

GoASM /l /d VERSIONA MyProg.ASM

See also:-
conditional assembly in macros
conditional assembly in structures
 

Include files - using #include and INCBINtop

As far as GoAsm is concerned there are two types of include file as follows:-

Syntax for #include

path\filename can be either:-

Loading a file using INCBIN

DATA SECTION
BULKDATA INCBIN MyFile.txt        ;load the whole of MyFile.txt into data section with label BULKDATA
    INCBIN MyFile.txt, 100        ;miss out the first 100 bytes but load rest of file
    INCBIN MyFile.txt, 100, 300   ;miss out the first 100 bytes but load 300 bytes

Merging: using static code librariestop

What are static code libraries?

How to use static code libraries

CALL zlibstat.lib:compress

LIB1=c:\prog\libs\zlibstat.lib
CALL LIB1:compress

INVOKE zlibstat.lib:compress,[pCompHeap],ADDR ComprSize,[pHeap],[DataSize]
INVOKE LIB1:compress,[pCompHeap],ADDR ComprSize,[pHeap],[DataSize]

What happens when you call a library function

Not the Microsoft method

How GoAsm finds the correct lib file

Using JMP instead of CALL/INVOKE

JMP MyLib.lib:MainProc

How do you tell what is in a lib file?

Making your own lib files

LIB calculate.obj

LIB calculate.lib added.obj

Static code library bloat

Callbacks or data reliance

Getting data only, not code

CALCULATE1:
                        ;some code here
RET
CALL Lib1:DUMMY         ;ensure Lib1 is loaded at compile-time
CALCULATE2:
                        ;some code here
RET

Integration of the code and data, priority of same-name labels

So where should it be declared and what if it is declared more than once? A similar question arises with functions. The code for these may be in the main source script or in a library. The code may be duplicated in several places. The answer to the question lies in the priority rules. They are as follows:-
1. The GoAsm main source script and any "a" include files always have priority. In other words, any code label or data declaration in the scripts will always find their way into GoAsm's output file together with the code and data that they are labelling.
2. Subject to 1 above, the formal library calls (using the format library:functionname) have priority in the order in which they are called.

These rules mean that code libraries are able to call functions and to use data within the source scripts directly (without any assistance from the linker). They also mean that any label in a library which has already been used in the source script or in a library which has already been called will be ignored. For example suppose BUFFER is declared in the source script to be 256 bytes. If library1 declares it again as 128 bytes, the label is ignored. BUFFER will be 256 bytes in the output file. And further, although the data area reserved for BUFFER in library1 will be loaded in the output file, the label BUFFER will not point to that area but to the area declared in the source script. Now if in a later call, library2 declares BUFFER as 1024 bytes, again this data area will go into the output file, but BUFFER will point to the original data area. The reason GoAsm deals with same-name labels in this way is twofold. Firstly, it would be impossible for any assembler (or linker for that matter) to work out which label has priority from its size. This is because in GoAsm at assemble time and certainly at link time the size of a particular area pointed to by a label is not known for certain. This is because sometimes areas are enlarged by areas of unlabelled data or code, or sometimes other labels are used as pointers to an intermediate place within the area.
The rules also have significance for the ordering of data. Suppose your library relies on data being held in BUFFER and also upon data sometimes overflowing into an enlarged area labelled BUFFER_EXT, declared immediately after BUFFER in the libary. Now in the above example BUFFER would not actually point to the expected place (just before BUFFER_EXT). Instead it would point to the first BUFFER declaration somewhere else in the data section.

So I would suggest the following rules are followed when making lib files:-
1. Only use same-name labels in the source script and in the library if the labels are intended to point to the same thing at the same place, ie. to the first declared such label.
2. If data labels of the same-name are to be used in different functions in the lib file, be aware that the size of the data area which they identify will be set by the first declared such label. Also don't expect the data area which the label identifies to be placed in any particular position in the executable.

Use single object files only

Unicode supporttop

64-bit assemblytop

See
Calling Windows APIs in 32-bits and 64-bits
Callback stack frames in 32-bits and 64-bits
Writing 64-bit programs.
 

x86 compatible mode (32-bit assembly using 64-bit source)top

MOV RSI,ADDR String
MOV [RDI],AL
MOV RAX,[hInst]

In addition to this, in x86 compatibility mode,

• "x86" becomes a defined word and identifiable for conditional assembly using #if (not case sensitive)
• ARG RAX becomes PUSH EAX
• ARG ADDR WNDCLASS becomes PUSH ADDR WNDCLASS
• ARG 800h becomes PUSH 800h
• ARG [hInst] becomes PUSH [hInst]
• INVOKE works as STDCALL
• JRCXZ instruction works as JECXZ

Note that /x86 should not be used in the command line for Win32 source code (use it only for 32/64-bit switchable source code).

Even in x86 compatibility mode, you cannot use the new AMD64 registers, R8 to R15, XMM8 to XMM15, nor the new register addressing formats SIL,DIL,BPL,SPL,R8W to R15W, or R8D to R15D. This is because they are not available for use by a 32-bit executable.

Any source code which is incompatible with a 32-bit excutable should be switched at assemble time using conditional assembly.
See Calling Windows APIs in 32-bits and 64-bits in the GoAsm manual for more information about ARG and INVOKE.
See the file Hello64World3 for example source code which can make either a simple Win32 "Hello World" Window program or a Win64 one.
See also writing 64-bit programs for the detailed differences between 32-bit and 64-bit programs.
 

Sections - some advanced usetop

Naming sections

Adding the shared attribute

DATA SECTION "MyData" SHARED

Order of sections

CODE SECTION 'Asm$b'
;
CODE SECTION 'Asm$a'
;

Setting the section alignment

CONST SECTION '.xdata' ALIGN 8
;
;UNWIND_INFO
;
CONST SECTION '.pdata' ALIGN 4
;
;RUNTIME_FUNCTION
;

Adapting existing source files for GoAsmtop

AdaptAsm [command line switches] inputfile[.ext]

/h=this help
/a=adapt a386 file
/m=adapt masm file
/n=adapt nasm file
/fo=specify output path/file eg. /fo GoAsm\adapted.asm
/l=create log output file
/o=don't ask before overwriting input file
/x64=adapt file for 64-bits

What AdaptAsm does not do

• Check the declaration of sections. GoAsm primary syntax is DATA SECTION, CODE SECTION, CONST SECTION or CONSTANT SECTION, but CODE (or .CODE), DATA (or .DATA), and CONST (or .CONST) is also acceptable.
• Add type indicators to instructions where the type is not obvious to GoAsm.
• Convert macros to GoAsm syntax (if you still need them with GoAsm).
• If using MASM, your structure initialisations may either use <...> or {....} brackets. For GoAsm you need to ensure that these are all in <...> form (the {....} brackets are reserved for initialising individual members like in TASM - see more).
• If using NASM, convert your structure templates to GoAsm syntax.
• If using NASM, check all jumps to local labels defined within non-local labels (eg. JZ MyProc.34) and rename if necessary.
• Check all labels in the code section have colons (AdaptAsm does not do this for fear of adding a colon to a non-label).
• Check that AdaptAsm has not added square brackets to equate, macro and STRUC names. AdaptAsm tries to get a full list of these and will avoid giving them square brackets as far as possible.
• Check whether any CALLs or JMPs should be to memory references in square brackets (which would be unusual). AdaptAsm does not add square brackets for these instructions.
• Convert all MASM's REPEAT, .REPEAT, REPT, .UNTIL, .UNTILCXZ WHILE, .WHILE, .ENDW, .IF/.ELSE/.ELSEIF/.ENDIF instructions to traditional assembler CMP, TEST, LOOP and jump instructions.
• Check that any lines using segment overrides are correctly coded.
• Convert any use of SIZESTR to use $ location counter instead.
• If you have used TYPEDEF these will need to be removed and the script converted as appropriate.
• If using MASM structure templates ensure that the greater than and less than brackets are used instead of braces for sequential initialisation.
• Since there is no operator precedence in GoAsm check all arithmetic relying on a particular precedence. Eg. MOV EAX,8+8*2 is 32 in GoAsm.
• When converting PROC...ENDP to FRAME...ENDF automated stack frames GoAsm ignores the attribute STDCALL, which is standard in 32-bit Windows. This should be removed anyway for 64-bit Windows which uses FASTCALL (GoAsm automatically switches between the two). If you have used any other attributes after PROC you can probably remove these altgother - GoAsm leaves them alone - check them by hand.

What AdaptAsm does when adapting various input files. For what happens using the /x64 switch see using AdaptAsm to help convert to 64-bit programs
Action	a386 files using /a	masm files using /m	nasm files using /n
Unless the word is defined (eg. using an equate) square brackets are added to all memory references where they don't already have them eg. MOV EBX,MEM_REFERENCE becomes MOV EBX,[MEM_REFERENCE] but MOV EBX,OFFSET MEM_REFERENCE is left alone	yes	yes	no
Puts memory references combined with square brackets into correct form eg. MOV DX,sHEXw[ECX*2] becomes MOV DX,[sHEXw+ECX*2]	yes	yes	no
Adds ADDR to NASM memory references which do not have square brackets	no	no	yes
Type indicators and overrides BYTE, BYTE PTR, WORD, WORD PTR, DWORD, DWORD PTR, QWORD, QWORD PTR, and TWORD, TWORD PTR are replaced by the shortened equivalents, B,W,D,Q and T	yes	yes	yes
Swaps all direct quote immediates and word and dword character based data declarations so they read the correct way round eg. MOV [ESI],'exe.' becomes MOV [ESI],'.exe' MOV EAX,'morf' becomes MOV EAX,'from' DW 'GJ' becomes DW 'JG' DD 'dcba' becomes DD 'abcd'	yes	yes	no
Changes HELLO LABEL to HELLO:	yes	yes	no
The MASM-type @@: local labels and @F and @B jumps are converted to GoAsm format. They are given numbers in sequence through the file and where necessary the > indicator is added in the jump instructions.	no	yes	no
The NASM-type local labels preceded by a period eg. (".23") are converted to GoAsm format. The number remain unchanged but where necessary the > indicator is added in the jump instruction.	no	no	yes
In jump instructions NEAR and SHORT are removed (no longer used)	yes	yes	yes
Changes FPU registers from just a number to ST0 to ST7 eg. FDIV 0,1 becomes FDIV ST0,ST1	yes	no	no
Changes FPU registers from ST(0) to ST(7) to read ST0 to ST7 eg. FDIV ST(0),ST(1) becomes FDIV ST0,ST1	no	yes	no
Data declarations made using BYTE, ACHAR, SBYTE, are changed to DB. Data declarations made using WORD, SWORD, SHORTINT are changed to DW. Data declarations made using DWORD, HDC, ATOM, BOOL, HDWP, HPEN, HRGN, HSTR, HWND, LONG, LPFN, UINT, HFILE, HFONT, HICON, HHOOK, HMENU, HRSRC, HTASK, LPINT, LPSTR, LPVOID, WCHAR, HACCEL, HANDLE, HBRUSH, HLOCAL, LPARAM, LPBOOL, LPCSTR, LPLONG, LPTSTR, LPVOID, LPWORD, SDWORD, WPARAM, HBITMAP, HCURSOR, HGDIOBJ, HGLOBAL, INTEGER, LONGINT, LPBYTE, LPCTSTR, LPCVOID, LPDWORD, LRESULT, POINTER, WNDPROC, COLORREF, HPALETTE, HINSTANCE, HINTERNET, HMETAFILE, HTREEITEM, HCOLORSPACE, LOCALHANDLE, GLOBALHANDLE, HENHMETAFILE are all changed to DD. Data declarations made using QWORD and DWORDLONG are changed to DQ. Data declarations made using TWORD are changed to DT.	no	yes	no
TIMES duplicate data syntax used in NASM changed to DUP method of declaring duplicate data. Also RESB/RESW/RESD used in NASM to reserve uninitialised data changed to DUP ? method of declaring uninitialised data.	no	no	yes
TEXTEQU changed to its "C" type #define version. The equates EQU and = are not changed since GoAsm supports these.	no	yes	no
INCLUDE directive changed to #INCLUDE	yes	yes	yes
%INCLUDE directive changed to #INCLUDE	no	no	yes
Changes the IF/ELSE/ELSEIF/ENDIF/IFDEF series of directives (conditional assembly) to #IF/#ELSE/#ELSEIF/#ENDIF/#IFDEF The .IF/.ELSE/.ELSEIF/.ENDIF/.IFDEF and .WHILE and .BREAK directives are left untouched. These will have to be changed back to "pure" assembler to hand.	no	yes	no
Changes the %IF/%ELSE/%ELSEIF/%ENDIF/%IFDEF series of directives (conditional assembly) to #IF/#ELSE/#ELSEIF/#ENDIF/#IFDEF Changes the %DEFINE directive to #DEFINE	no	no	yes
Comments out all lines beginning with EXTRN or EXTERN, GLOBAL, or PUBLIC.	yes	yes	yes
PROC is changed to FRAME and ENDP to ENDF. In masm code, the parameters and the USES statement are adjusted to GoAsm syntax.	yes	yes	no
The size of LOCAL data in an automated stack frame is changed to the GoAsm shorter versions (B,W,Q,T) and D is removed altogether since this is the GoAsm default.	no	yes	no
Changes EVEN to ALIGN	yes	yes	yes
Various lines which GoAsm does not support commented out eg. NAME, TITLE, SUBTITLE, SUBTTL, PROTO lines etc.	yes	yes	yes
Various lines which GoAsm does not support are removed altogether eg. .ERR, .EXIT, .LIST, .286 etc.	yes	yes	yes
The word COMMENT is replaced by a semi-colon	yes	yes	yes

Miscellaneoustop

Special push instructionstop

Half stack operations

In Win32 data on the stack is held in dwords, and the value of ESP is always on a dword boundary after a PUSH or POP operation. GoAsm does support half stack operations, however, which push onto and pop from the stack only two bytes at a time instead of four. When using these instructions you must push or pop a second time to restore ESP to a dword boundary. To make the syntax obvious, GoAsm requires the use of PUSHW and POPW for these half-stack operations. PUSH and POP cannot be used - they always perform a dword stack operation. As an example, half stack instructions can be used in response to the WM_LBUTTONDOWN message:-

MOUSEX_POS DD 0
MOUSEY_POS DD 0
PUSH [EBP+14h]          ;push lParam onto the stack
POPW [MOUSEX_POS]       ;take the loword first
POPW [MOUSEY_POS]       ;then the hiword

PUSH ADDR lpFileTime
PUSHW [wFatTime]
PUSHW [wFatDate]
CALL DosDateTimeToFileTime

Pushing and popping flags

PUSH FLAGS

POP FLAGS

See also:-
PUSH or ARG pointers to strings and data,
callback stack frames in 32-bits and 64-bits.
 

Segment overridestop

In GoAsm segment overrides can be either before or after the mnemonic, for example:-

FS OR D[24h],100h
OR FS D[24h],100h
FS MOV [ESI],EAX
MOV FS[ESI],EAX

PUSH FS[0]          ;use FS PUSH [0] instead
POP FS[0]           ;use FS POP [0] instead
MOV [FS:0],EAX      ;use FS MOV [0],EAX instead

Using source informationtop

@line         current line being assembled
@filename     main source script being assembled
@filecur      current file being assembled

@line provides a 32-bit integer and can be used as follows:-

MOV EAX,@line         ;eax given the line number
PUSH @line            ;line number pushed on the stack
DD @line              ;line number declared in memory

PUSH @filename        ;pointer to null terminated string
DB @filename          ;not null terminated string
DB @filename,0        ;null terminated string

Using the location counters $ and $$top

Meaning of the location counters

Because both of these operators give positions in memory in the executable as loaded by Windows their values are not known to GoAsm at assemble-time, nor to the linker at link-time. In this respect they act like a code or data label. When you use them they do not have a value but they can be subtracted from each other or from memory references within the same section to produce a value. This is because their relative values are known.

Use of the location counters

HELLO DB 'He finally got the courage to talk to her',0
LENGTHOF_HELLO DB $-HELLO

MESSAGES DD ENDOF_MESSAGES-$
         DD MESS1,MESS2,MESS3,MESS4,MESS5
ENDOF_MESSAGES:

MESSAGES DD ENDOF_MESSAGES-MESSAGES
         DD MESS1,MESS2,MESS3,MESS4,MESS5
ENDOF_MESSAGES:

MESSAGES DD (ENDOF_MESSAGES-$-4)/4
         DD MESS1,MESS2,MESS3,MESS4,MESS5
ENDOF_MESSAGES:

LABEL400:
JMP $+20h       ;continue execution 20h bytes ahead

Here are some other examples of use in the code section:-

CALL $$       ;a call to the start of the current section
MOV EAX,$-$$  ;get distance to current location from start of current section

HELLOZ DD $$            ;HELLOZ to hold position at top of section
DB 100-($-$$) DUP 0     ;pad with zeroes to offset 100

#define globule $$+2+3
CODE SECTION
MOV EAX,globule

Alignment and the use of ALIGNtop

What is alignment?

In assembler, you can control both data and code alignment. We shall look first at data alignment and then briefly look at code alignment.

Need for data alignment

Alignment to satisfy Windows

For 32-bit Windows (NT/2000/XP and Vista running as Win32) the destination of many pointers to data given to the APIs need to be dword aligned, and often this is undocumented.
Even under Windows 9x there are several pointer destinations which must be dword aligned, for example the structures DLGITEMTEMPLATES and DLGITEMTEMPLATESEX. Also the Menu, class, title and font data in a DLGTEMPLATE must be word aligned and the structures used in the Network Management APIs must be dword aligned.
Certain members of bitmap structures must be aligned internally. XP requires that the height and width of compatible bitmaps is always divisible by four to ensure that each line is aligned properly.
There are certain SSE and SSE2 instructions which require 16-byte alignment of the memory area which they are dealing with, for example FXSAVE, FXRSTOR, MOVAPD, MOVAPS and MOVDQA.

For 64-bit Windows the alignment requirements are even stricter. It is essential to ensure that structure members are aligned on their "natural boundary". So a word should be on a word boundary, a dword on a dword boundary, qword on a qword boundary etc. This only works if the structure itself is properly aligned on the correct boundary. Basically the structure should be aligned on the natural boundary of its largest member. It is also important for the structure to end on the natural boundary of its largest member, if necessary by adding padding. Also in 64-bit Windows, the stack pointer RSP should also always be aligned to a 16-byte boundary on making an API call. More information about alignment requirements in 64-bit programming.

For both 32-bits and 64-bits, if the alignment is wrong the results are unpredictable, varying from mere non-appearance of controls, to program exit.

Alignment for speed

The alignment which achieves the greatest speed varies from processor to processor but generally it is a good idea to ensure that data is aligned in memory to suit the size in which it operates. For example a table of dwords would best be on a dword boundary. In theory both qwords and twords ought to be qword aligned for best performance.

Achieving correct data alignment

For Win64 GoAsm automatically aligns structures and structure members to suit the natural boundary of the structure and its members. GoAsm also pads the size of the structure to suit. GoAsm also automatically aligns the stack pointer ready for an API call.
See writing 64-bit programs for more information about how this works in practice.

Code alignment

Use of ALIGN

ALIGN 4         ;the next data will be dword aligned
ALIGN 16        ;(or ALIGN 10h) will align on the next 16 byte boundary

See also sections - some advanced use on section alignment.
 

Use of SIZEOFtop

Using SIZEOF when referring to data labels

MOV EAX,SIZEOF Hello
MOV EAX,SIZEOF(Hello)
MOV EAX,[ESI+SIZEOF Hello]
SUB ESP,SIZEOF Hello
DD SIZEOF Hello
Label DB SIZEOF Hello DUP 0
MOV EAX,SIZEOF Hello+4
MOV EAX,SIZEOF Hello-4
MOV EAX,SIZEOF Hello/2
MOV EAX,SIZEOF Hello*2

Hello DB 0
      DD 0
Hello2 DB 0

MOV EAX,SIZEOF Hello

Using SIZEOF with strings

WrongB DB 'You pressed the wrong button!,'0

MOV EAX,SIZEOF WrongB

Using SIZEOF when referring to code labels

START:
XOR EAX,EAX
XOR EAX,EAX
XOR EAX,EAX
XOR EAX,EAX
LABEL:
MOV EAX,SIZEOF START

Using SIZEOF with structures

Rect STRUCT
   left   DD
   top    DD
   right  DD
   bottom DD
ENDS
rc Rect

MOV EAX,SIZEOF Rect
and
MOV EAX,SIZEOF rc

Using SIZEOF with structure members

Rect STRUCT
   left   DD
          DD
   right  DD
   bottom DD
ENDS
rc Rect

MOV EAX,SIZEOF rc.left
and
MOV EAX,SIZEOF Rect.left

Using SIZEOF with unions and union members

Sleep STRUCT
     DW 2222h
     DB 0h
ENDS
Ness UNION
     Possums DB L'Balance'
     Koalas Sleep
     Devils  DB 'Roar'
ENDS
Happy Ness
SizeLabel DD SIZEOF Happy
          DD SIZEOF Ness
          DD SIZEOF Happy.Possums
          DD SIZEOF Happy.Koalas
          DD SIZEOF Happy.Devils

How structure initialisation may affect the size

When getting the size, any arguments which might otherwise be used to change the size of the structure are ignored for example

StringStruct STRUCT
   DB ?
ENDS

MOV EAX,SIZEOF StringStruct

StringStruct STRUCT
   DB LONGSTRING
ENDS

MOV EAX,SIZEOF StringStruct

Rect STRUCT
   DB TWELVE DUP 0
ENDS

Initialising a structure with SIZEOF

PARAM_STRUCT STRUCT
     DD 0
     DD 0
     DD 0
ENDS
ps1 PARAM_STRUCT <SIZEOF PARAM_STRUCT,,>

Using SIZEOF with local data

MyWndProc FRAME
LOCALS hDC,DemonFlag:B,Buffer[256]:B,MyRect:RECT
MOV EAX,SIZEOF hDC         ;4 in 32-bits, 8 in 64-bits (default size)
MOV EAX,SIZEOF DemonFlag   ;1
MOV EAX,SIZEOF Buffer      ;256
MOV EAX,SIZEOF MyRect      ;16
RET
ENDF

Using branch hintstop

What is branch prediction?

CMP EDX,EAX       ;compare edx and eax
JZ >L1            ;branch to L1 if edx=eax
                  ;lots of other instructions
L1:

All forward conditional jumps will not take place, and
All backwards conditional jumps (loops back) will take place.

What are branch hints?

2Eh - hint that the branch will not occur most of the time.
3Eh - hint that the branch will occur most of the time.

Inserting branch hints

DB 2Eh  ;or
DB 3Eh

hint.nobranch           ;insert 2Eh
hint.branch             ;insert 3Eh

CMP EDX,EAX             ;compare edx and eax
hint.branch JZ >L1      ;normally does branch to L1
                        ;lots of other instructions
L1:

Syntax to use FPU, MMX, and XMM registerstop

ST0
ST1
ST2
ST3
ST4
ST5
ST6
ST7

MM0
MM1
MM2
MM3
MM4
MM5
MM6
MM7

XMM0
XMM1
XMM2
XMM3
XMM4
XMM5
XMM6
XMM7

XMM8
XMM9
XMM10
XMM11
XMM12
XMM13
XMM14
XMM15

The "Wait" opcode (9Bh)

FCLEX
FINIT
FWAIT
FSAVE
FSETPM
FSTCW
FSTENV
FSTSW

Reporting assemble timetop

GOASM_REPORTTIME

Other GoAsm interruptstop

GOASM_ECHO Assembly has reached new heights

You can force GoAsm to stop assembly and exit using:-

GOASM_EXIT

GoAsm list filetop

GoAsm's error and warning messagestop

GoAsm Test.asm >output.fil

/b  beep on error
/ne no error messages
/ni no information messages
/nw no warning messages
/no no output messages at all

In a batch file, you can use the error return with ERRORLEVEL, for example the following will pause if there is an error return:-

GoAsm MyFile.asm
IF ERRORLEVEL 1 PAUSE

Using GoAsm with various linkerstop

Using GoLink

See the GoLink help file for full information about GoLink and how to use it. A typical batch file (with an extension .bat) to create a simple executable might be:-

GoAsm MyProg.asm
GoLink MyProg.obj Kernel32.dll User32.dll

You can use a command file with GoLink for example:-

GoLink @command.fil

#dynamiclinkfile path/filename, path/filename

There are several other command line switches and options when using GoLink. For more details please see the Golink help file, GoLink.htm.

Using ALINK

GoAsm MyProg.asm
ALINK @Respons.fil >link.opt

-m                            ;produces map file
-oPE                          ;makes a PE file
-o MyProg.Exe                 ;gives the output file name
-entry START                  ;signifies the starting address
-debug                        ;signifies debug symbols to be made
kernel32.lib                  ;
COMCTL32.lib                  ;  a lib file for each API
COMDLG32.lib                  ;  which is called in your program,
user32.lib                    ;  made using ALIB which is
gdi32.lib                     ;  part of the ALINK package
shell32.lib                   ;
MyProg.obj                    ;the input file

Using the Microsoft linker

Automatic decoration with /ms switch

In every such case the decoration is in this form:-

_CodeLabel@x

At link-time the MS linker expects the value of "@x" in both the caller and the callee to match exactly. This is therefore a limited form of parameter checking. When the /ms switch is used, GoAsm therefore needs to count the number of parameters used by the code label in order to get the value of "@x" correct. To achieve this, in the case of labels to FRAMEs, GoAsm counts the number of parameters declared in the FRAME and adjusts the decoration accordingly. In the case of a call using INVOKE again GoAsm counts the number of parameters used.

However, GoAsm cannot count the number of parameters to a call using CALL and assumes there are none. For this reason if there are any parameters you must use INVOKE for the decoration to work properly (and not an ordinary PUSH xxx, then CALL). Also note that if using ARG before INVOKE, each argument needs to be on its own line (not ARG 1,2,3).

So, for example if you use the following code with the /ms switch in GoAsm's command line:-

HelloProc FRAME hwnd,arg1,arg2
INVOKE MessageBoxA, [hwnd],'Click OK','Hello',40h

_HelloProc@12

_MessageBoxA@16

From GoAsm Version 0.49, ordinary code labels without parameters are also decorated. This is to enable such code labels to be recognised externally at link-time so that they can be called by other object files created by MS tools. They are given a parameter byte count of zero. This includes the label giving the starting address itself. So suppose your starting address in your source script is START: (no leading underline character). This is now decorated as:-

_START@0

-ENTRY START@0

Manual decoration

For example:-

PUSH 12h
CALL _GetKeyState@4       ;check for alt-key pressed

If you are making a dll, you will need to use a label for the starting address decorated in the same way, for example

_DLLENTRY@12:

After you have made those changes to your source script you are ready to make a batch file with the extension .bat to assemble the source and run the linker. These lines might be in the batch file:-

GoAsm MyProg.asm
LINK @Respons.fil

/OUT:MyProg.Exe                ;gives name of output file
/MAP                           ;produces map file
/SUBSYSTEM:WINDOWS             ;makes a Windows GDI executable
/ENTRY:START                   ;you have it as _START in the source!
/DEBUG:FULL                    ;do a debug output
/DEBUGTYPE:COFF                ;do embedded COFF symbols
MyProg.obj                     ;the input file
comctl32.lib                   ;
user32.lib                     ; lib files for each API which
gdi32.lib                      ; your program calls, these
kernel32.lib                   ; files come with the linker

Using definitions to help with the Microsoft linker

GetKeyState=_GetKeyState@4
CALL GetKeyState

GetKeyState=__imp__GetKeyState@4
CALL [GetKeyState]

Retaining leading underscores in library calls using the /gl switch

Alphabetical Indextop