CONTENTS ___________________________________________________________________________

Chapter 1 BASM.DOC Inline assembly language . . BASM . . . . . . . . . . . Inline syntax . . . . . . Opcodes . . . . . . . . . String instructions . . Prefixes . . . . . . . . Jump instructions . . . Assembly directives . . Inline assembly references data and functions . . . .

. . . . . . . . . . . . . . . . to . .

1 1 1 2 3 5 5 5 6 6

Inline assembly and register variables . . . . . . . . . 7 Inline assembly, offsets, and size overrides . . . . . . 7 Using C structure members . . 7 Using jump instructions and labels . . . . . . . . . . . 8 Interrupt functions . . . . . . 9 Using low-level practices . . . 10 Index 13

TABLES ___________________________________________________________________________

1.1: Opcode mnemonics . . . . . . 4 1.2: String instructions . . . . . 5

1.3: Jump instructions . . . . . .6

ii

Online document ___________________________________________________________________________

BASM.DOC This online file tells you how to use the Turbo C++ built-in inline assembler (BASM) to include assembly language routines in your C and C++ programs without any need for a separate assembler. Such assembly language routines are called inline assembly, because they are compiled right along with your C routines, rather than being assembled separately, then linked together with modules produced by the C compiler. Of course, Turbo C++ also supports traditional mixedlanguage programming in which your C program calls assembly language routines (or vice-versa) that are separately assembled by TASM (Turbo Assembler), sold separately. In order to interface C and assembly language, you must know how to write 80x86 assembly language routines and how to define segments, data constants, and so on. You also need to be familiar with calling conventions (parameter passing sequences) in C and assembly language, including the pascal parameter passing sequence in C. Inline assembly ======================================================= language Turbo C++ lets you write assembly language code right inside your C and C++ programs. This is known as inline assembly. ------------------ If you don't invoke TASM, Turbo C++ can assemble your BASM inline assembly instructions using the built-in ------------------ assembler (BASM). This assembler can do everything TASM can do with the following restrictions: o It cannot use assembler macros

- 1 -

o It cannot handle 80386 or 80486 instructions o It does not permit Ideal mode syntax o It allows only a limited set of assembler directives (see page 6) ------------------ Of course, you also need to be familiar with the 80x86 Inline syntax instruction set and architecture. Even though you're ------------------ not writing complete assembly language routines, you still need to know how the instructions you're using work, how to use them, and how not to use them. Having done all that, you need only use the keyword asm to introduce an inline assembly language instruction. The format is asm opcode operands ; or newline where o opcode is a valid 80x86 instruction (Table 1.0 lists all allowable opcodes). o operands contains the operand(s) acceptable to the opcode, and can reference C constants, variables, and labels. o ; or newline is a semicolon or a new line, either of which signals the end of the asm statement. A new asm statement can be placed on the same line, following a semicolon, but no asm statement can continue to the next line. To include a number of asm statements, surround them with braces: The initial brace must appear on the same line as the asm keyword. asm { pop ax; pop ds iret } Semicolons are not used to start comments (as they are in TASM). When commenting asm statements, use C-style comments, like this:

- 2 -

asm mov ax,ds; /* This comment is OK */ asm {pop ax; pop ds; iret;} /* This is legal too */ asm push ds ;THIS COMMENT IS INVALID!! The assembly language portion of the statement is copied straight to the output, embedded in the assembly language that Turbo C++ is generating from your C or C++ instructions. Any C symbols are replaced with appropriate assembly language equivalents. Because the inline assembly facility is not a complete assembler, it may not accept some assembly language constructs. If this happens, Turbo C++ will issue an error message. You then have two choices. You can simplify your inline assembly language code so that the assembler will accept it, or you can use an external assembler such as TASM. However, TASM might not identify the location of errors, since the original C source line number is lost. Each asm statement counts as a C statement. For example, myfunc() { int i; int x; if (i > 0) asm mov x,4 else i = 7; } This construct is a valid C if statement. Note that no semicolon was needed after the mov x,4 instruction. asm statements are the only statements in C that depend on the occurrence of a new line. This is not in keeping with the rest of the C language, but this is the convention adopted by several UNIX-based compilers. An assembly statement can be used as an executable statement inside a function, or as an external declaration outside of a function. Assembly statements located outside any function are placed in the data segment, and assembly statements located inside functions are placed in the code segment.

- 3 -

------------------ You can include any of the 80x86 instruction opcodes as Opcodes inline assembly statements. There are four classes of ------------------ instructions allowed by the Turbo C++ compiler: o normal instructions--the regular 80x86 opcode set o string instructions--special string-handling codes o jump instructions--various jump opcodes o assembly directives--data allocation and definition Note that all operands are allowed by the compiler, even if they are erroneous or disallowed by the assembler. The exact format of the operands is not enforced by the compiler. ------------------------------------------------------Opcode mnemonics aaa aad aam aas adc add and bound call cbw clc cld cli cmc cmp cwd daa das dec div enter f2xm1 fabs fadd faddp fbld fbstp fchs fclex fcom fcomp fcompp fdecstp** fdisi fdiv fdivp fdivr fdivrp feni ffree** fiadd ficom ficomp fidiv fidivr fild fimul fincstp** finit fist fistp fisub fisubr fld fld1 fldcw fldenv fldl2e fldl2t fldlg2 fldln2 fldpi fldz fmul fmulp fnclex fndisi fneni fninit fnop fnsave fnstcw fnstenv fnstsw fpatan fprem fptan frndint frstor fsave fscale fsqrt fst fstcw fstenv fstp fstsw fsub fsubp fsubr fsubrp ftst fwait fxam fxch fxtract fyl2x fyl2xp1 hlt idiv imul in inc int into iret lahf lds lea leave les lsl

This table lists the opcode mnemonics that can be used in inline assembler. Inline assembly in routines that use floating-point emulation doesn't support the opcodes marked with **.

- 4 -

mul neg nop not

stc std sti sub test verr verw wait xchg xlat xor ------------------------------------------------------String instructions ======================================================= In addition to the listed opcodes, the string instructions given in the following table can be used alone or with repeat prefixes. String instructions stos cmpsb stosb cmpsw stosw ins insb lodsw movs outsb scasw lodsb outs scasb lods movsw scas ------------------------------------------------------cmps insw movsb outsw

or out pop popa popf push pusha pushf rcl rcr

ret rol ror sahf sal sar sbb shl shr smsw

------------------------------------------------------Prefixes ======================================================= The following prefixes can be used: lock rep repe repne repnz repz

Jump instructions ======================================================= Jump instructions are treated specially. Since a label cannot be included on the instruction itself, jumps must go to C labels (discussed in "Using jump instructions and labels" on page 8). The allowed jump instructions are given in the next table.

- 5 -

Table 1.3: Jump instructions (continued)_______________ Jump instructions ------------------------------------------------------ja jge jnc jns loop jae jl jne jnz loope jb jle jng jo loopne jbe jmp jnge jp loopnz jc jna jnl jpe loopz jcxz jnae jnle jpo je jnb jno js jg jnbe jnp jz ----------------------------------------Assembly directives ======================================================= The following assembly directives are allowed in Turbo C++ inline assembly statements: db -----------------Inline assembly references to data and functions -----------------dd dw extrn

You can use C symbols in your asm statements; Turbo C++ automatically converts them to appropriate assembly language operands and appends underscores onto identifier names. You can use any symbol, including automatic (local) variables, register variables, and function parameters. In general, you can use a C symbol in any position where an address operand would be legal. Of course, you can use a register variable wherever a register would be a legal operand. If the assembler encounters an identifier while parsing the operands of an inline assembly instruction, it searches for the identifier in the C symbol table. The names of the 80x86 registers are excluded from this search. Either uppercase or lowercase forms of the register names can be used.

- 6 -

Inline assembly and register variables ======================================================= Inline assembly code can freely use SI or DI as scratch registers. If you use SI or DI in inline assembly code, the compiler won't use these registers for register variables. Inline assembly, offsets, and size overrides ======================================================= When programming, you don't need to be concerned with the exact offsets of local variables. Simply using the name will include the correct offsets. However, it may be necessary to include appropriate WORD PTR, BYTE PTR, or other size overrides on assembly instruction. A DWORD PTR override is needed on LES or indirect far call instructions. -----------------Using C structure members -----------------You can reference structure members in an inline assembly statement in the usual fashion (that is, variable.member). In such a case, you are dealing with a variable, and you can store or retrieve values. However, you can also directly reference the member name (without the variable name) as a form of numeric constant. In this situation, the constant equals the offset (in bytes) from the start of the structure containing that member. Consider the following program fragment: struct myStruct { int a_a; int a_b; int a_c; } myA ; myfunc() { ... asm {mov ax, myA.a_b mov bx, [di].a_c } ... }

- 7 -

We've declared a structure type named myStruct with three members, a_a, a_b, and a_c; we've also declared a variable myA of type myStruct. The first inline assembly statement moves the value contained in myA.a_b into the register AX. The second moves the value at the address [di] + offset(a_c) into the register BX (it takes the address stored in DI and adds to it the offset of a_c from the start of myStruct). In this sequence, these assembler statements produce the following code: mov ax, DGROUP : myA+2 mov bx, [di+4] Why would you even want to do this? If you load a register (such as DI) with the address of a structure of type myStruct, you can use the member names to directly reference the members. The member name actually can be used in any position where a numeric constant is allowed in an assembly statement operand. The structure member must be preceded by a dot (.) to signal that a member name, rather than a normal C symbol, is being used. Member names are replaced in the assembly output by the numeric offset of the structure member (the numeric offset of a_c is 4), but no type information is retained. Thus members can be used as compile-time constants in assembly statements. However, there is one restriction. If two structures that you are using in inline assembly have the same member name, you must distinguish between them. Insert the structure type (in parentheses) between the dot and the member name, as if it were a cast. For example, asm -----------------Using jump instructions and labels -----------------mov bx,[di].(struct tm)tm_hour

You can use any of the conditional and unconditional jump instructions, plus the loop instructions, in inline assembly. They are only valid inside a function. Since no labels can be defined in the asm statements, jump instructions must use C goto labels as the object of the jump. If the label is too far away, the jump will be automatically converted to a long-distance jump. Direct far jumps cannot be generated.

- 8 -

In the following code, the jump goes to the C goto label a. int { a: x() /* This is the goto label "a" */ ... asm jmp a ... } Indirect jumps are also allowed. To use an indirect jump, you can use a register name as the operand of the jump instruction. Interrupt func- ======================================================= tions The 80x86 reserves the first 1024 bytes of memory for a set of 256 far pointers--known as interrupt vectors--to special system routines known as interrupt handlers. These routines are called by executing the 80x86 instruction int int# where int# goes from 0h to FFh. When this happens, the computer saves the code segment (CS), instruction pointer (IP), and status flags, disables the interrupts, then does a far jump to the location pointed to by the corresponding interrupt vector. For example, one interrupt call you're likely to see is int 21h which calls most DOS routines. But many of the interrupt vectors are unused, which means, of course, that you can write your own interrupt handler and put a far pointer to it into one of the unused interrupt vectors. To write an interrupt handler in Turbo C++, you must define the function to be of type interrupt; more specifically, it should look like this: void interrupt myhandler(bp, di, si, ds, es, dx, /* Goes to label "a" */

- 9 -

cx, bx, ax, ip, cs, flags, ... ); As you can see, all the registers are passed as parameters, so you can use and modify them in your code without using the pseudovariables discussed earlier in this online file. You can also pass additional parameters (flags, ...) to the handler; those should be defined appropriately. A function of type interrupt will automatically save (in addition to SI, DI, and BP) the registers AX through DX, ES, and DS. These same registers are restored on exit from the interrupt handler. Interrupt handlers all memory models. an 80x87 must save restore it on exit may use floating-point arithmetic in Any interrupt handler code that uses the state of the chip on entry and from the handler.

An interrupt function can modify its parameters. Changing the declared parameters will modify the corresponding register when the interrupt handler returns. This may be useful when you are using an interrupt handler to act as a user service, much like the DOS INT 21 services. Also, note that an interrupt function exits with an IRET (return from interrupt) instruction. So, why would you want to write your own interrupt handler? For one thing, that's how most memory-resident routines work. They install themselves as interrupt handlers. That way, whenever some special or periodic action takes place (clock tick, keyboard press, and so on), these routines can intercept the call to the routine handling the interrupt and see what action needs to take place. Having done that, they can then pass control on to the routine that was there. Using low-level ======================================================= practices You've already seen a few examples of how to use these different low-level practices in your code; now it's time to look at a few more. Let's start with an interrupt handler that does something harmless but tangible (or, in this case, audible): It beeps whenever it's called.

- 10 -

First, write the function itself. Here's what it might look like: #include <dos.h>

void interrupt mybeep(unsigned bp, unsigned di, unsigned si, unsigned ds, unsigned es, unsigned dx, unsigned cx, unsigned bx, unsigned ax) { int i, j; char originalbits, bits; unsigned char bcount = ax >> 8; /* Get the current control port setting */ bits = originalbits = inportb(0x61); for (i = 0; i <= bcount; i++){ /* Turn off the speaker for awhile */ outportb(0x61, bits & 0xfc); for (j = 0; j <= 100; j++) ; /* empty statement */ /* Now turn it on for some more time */ outportb(0x61, bits 2); for (j = 0; j <= 100; j++) ; /* another empty statement */ } /* Restore the control port setting */ outportb(0x61, originalbits); } Next, write a function to install your interrupt handler. Pass it the address of the function and its interrupt number (0 to 255 or 0x00 to 0xFF). void install(void interrupt (*faddr)(), int inum) { setvect(inum, faddr); } Finally, call your beep routine to test it out. Here's a function to do just that:

- 11 -

void testbeep(unsigned char bcount, int inum) { _AH = bcount; geninterrupt(inum); } Your main function might look like this: main() { char ch; install(mybeep,10); testbeep(3,10); ch = getch(); } You might also want to preserve the original interrupt vector and restore it when your main program is finished. Use the getvect and setvect functions to do this.

- 12 -

INDEX ___________________________________________________________________________

A asm (keyword) 2 braces and 2 assembler built in 1 assembly language inline 1 braces and 2 C structure members and 7 restrictions 8 calling functions 6 commenting 2 directives 6 goto in 8 jump instructions 5, 8 option (*B) 1 referencing data in 6 register variables in 7 semicolons and 3 size overrides in 7 syntax 2 variable offsets in 7 B braces asm keyword and 2 built-in assembler 1 C age command-line compiler options assembly language and 1 -B (inline assembler code) 1 inline assembler code 1 comments inline assembly language code 2

F floating point arithmetic interrupt functions and 10 functions calling in inline assembly code 6 G goto statements assembly language and 8 I INT instruction 9 interrupt (keyword) 9 interrupts beep example 11 functions example of 10 floating-point arithmetic in 10 handlers calling 11 installing 11 programming 9 J jump instructions, inline assembly langu table 5 using 8 L labels in inline assembly code 8

Index

13

M memory-resident routines 10 O opcodes 3 defined 2 mnemonics table 4 repeat prefixes 5 operands (assembly language) 2 P prefix opcodes, repeat 5 programs terminate and stay resident interrupt handlers and 10 R referencing data in inline assembly code 6 registers DI assembly language and 7 SI assembly language and 7 variables in inline assembly code 7

repeat prefix opcodes 5 S size overrides in inline assembly code 7 software interrupt instruction 9 sounds beep 11 structures members in inline assembly code 7 restrictions 8 syntax inline assembly language 2 T terminate and stay resident programs interrupt handlers and 10 Turbo Assembler 1 V variables offsets in inline assembly code 7

- 14 -