ASSEMBLY TO HIGH-LEVEL INTERFACE

Sometimes it may be desirable to write certain subroutines in assembly language instead of BASIC because of speed, size, or other constraints. This section explains how to successfully combine BASIC programs with assembly language modules so that parameters are passed correctly between the BASIC program and the assembly language subroutine.

To understand this section fully, the reader should have a basic knowledge of the following:

1. The BASIC interpreter
2. The assembler
3. The register structure of the 8086/8088

In order to call an assembly language subroutine from an interpretive BASIC program, it is necessary to know the address of the assembly language routine. The routine must be resident in memory when BASIC is loaded, and its entry address must be known. The module containing the subroutine should also contain a short program that loads the module into memory, using the MS-DOS terminate and remain resident function (Int 27 Hex). When the program is run, it loads the subroutine into memory permanently. The program should also display the entry address of the subroutine, or store the entry address to some specific memory location that the BASIC program can PEEK in order to determine where the routine is. A possible location to store this information is an Interrupt Vector Table entry, but be very careful not to use an entry that is used by the operating system! Interrupt Vector Table entries available for use include 128 through 191 (80 - BF Hex). Since each entry is four bytes long, entry 128 is at memory address 0:200 Hex, entry 129 is at address 0:204 hex, and so on, with entry 191 at address 0:2FC Hex.

The BASIC program can then determine the address of the subroutine by PEEKing the four consecutive bytes that were saved by the assembly loader program. After the BASIC program has PEEKed these locations, it can set up the entry address of the assembly language subroutine. The following program segment shows how this is done.

After these statements have been executed, calls to the assembly language subroutine can be performed as follows:

The assembly language subroutine must follow some simple rules in order to work correctly.

1. It must be declared FAR.
2. Segment registers DS and ES must be restored to their entry values before returning to BASIC.
3. The general purpose registers (AX, BX, CX, DX, SI, DI, and BP) can have any value when when returning to BASIC.
4. The assembly language routine MUST NOT change the length of any BASIC strings.
5. The assembly language routine must perform a RET (where n = 2 times the number of parameters) to restore the stack pointer to its proper value.
6. Values can be returned to BASIC by passing a parameter that the result will be returned in.

It is necessary to understand how the various data types are represented in memory. When a subroutine is called, BASIC will pass the address of one of the following data representations.

1. Integer - two byte two's complement number
2. Single Precision Number - four byte binary floating point quantity. The most significant byte contains the value of the exponent minus 127. The remaining three bytes contain the mantissa. The most significant byte of the mantissa contains the sign bit, followed by the seven highest bits of the mantissa. A positive number is represented with a 0 as the sign bit, a negative number with a 1 as the sign bit. The binary point is to the left of the most signifi- cant bit of the mantissa. A 1 is always assumed to exist immediately to the left of the mantissa, although it is not represented. Thus the number is represented as
   
   ( 1. * 2) ^ (exponent-127)
   
   
3. Double Precision Number - eight byte binary floating point quantity. It is represented exactly the same as a single precision number, except that the mantissa is made up of 41 bits (7 bytes less the sign bit).
4. String - BASIC will pass a pointer to a 'string descriptor' which is a three byte data structure. The first byte of the string descriptor contains the length of the string. The second and third bytes contain the address where the actual ASCII string is located. The assembly language subroutine is allowed to modify the string, but must not change the string descriptor.
5. Array - arrays are made up of sequential elements of the array type. For example, an integer array containing twenty elements is represented as twenty sequential integers in memory.

BASIC passes all subroutine parameters by reference. The offset of each parameter's address is pushed onto the stack in the same order that the parameters are listed in the procedure call. Upon entry to the subroutine, the stack will be arranged as follows:

The parameters can then be referenced by using the BP register to get their address off of the stack. The following example shows how to do this.

This example shows how to call an assembly language routine from BASIC. The assembly language routine performs modulo arithmetic on two integers, returning the remainder that results when the first integer is divided by the second. The assembly language module consists of two procedures. The first procedure loads the module into memory, and puts the entry address of the second procedure into interrupt vector table entry 128. The second procedure is called from BASIC, and performs the modulo function. The BASIC program peeks the Interrupt Vector Table to get the entry address of the modulo function, and the performs the call with some sample data.

This example illustrates one other important point. All parameters must be variables, and they must be initialized before calling the assembly language subroutine. After assembling and linking the assembly language module, it is necessary to convert the resulting .EXE file into a .COM file in order for the terminate and remain resident function to work correctly. An easy way to do this is with the Microsoft debugger, using the following sequence of instructions:

Then the assembly language module can be loaded by running the .COM program. After it has loaded, you can run your BASIC program which calls the assembly language module.

Occasionally, you may wish to write certain subroutines in assembly language instead of Compiled BASIC because of speed, size, or other constraints. This section explains how to combine compiled BASIC programs with assembly language modules so that parameters are passed correctly between the Compiled BASIC program and the assembly language subroutine.

To understand this section fully, the reader should have a basic knowledge of the following:

1. The MS-BASIC Compiler
2. The Microsoft assembler
3. The Microsoft linker
4. The register structure of the 8086/8088

Assembly language subroutines can be invoked from compiled BASIC using either the CALL statement or the CALLS statement. The CALL statement pushes the offset addresses of any parameters on the stack before it transfers execution to the subroutine, while the CALLS statement pushes both the segment and offset addresses of any parameters on the stack. The example later in this discussion will fully illustrate this difference.

The assembly language subroutine must follow some simple rules in order to work correctly.

1. It must be declared FAR.
2. It must be declared PUBLIC.
3. Segment registers DS and ES must be restored to their entry values before returning to Compiled BASIC.
4. The general purpose registers (AX, BX, CX, DX, SI, DI, and BP) can have any value when returning to Compiled BASIC.
5. The assembly language routine MUST NOT change the length of any Compiled BASIC strings.
6. The assembly language routine must perform a RET (where n = 2 times the number of parameters) to restore the stack pointer to its proper value.
7. Values can be returned to Compiled BASIC by passing a parameter that the result will be returned in.

In order to manipulate data passed to an assembly language subroutine, it is necessary to understand how the various data types are represented in memory. When a subroutine is called, Compiled BASIC will pass the address of one of the following data representations.

1. Integer - two byte two's complement number
2. Single Precision Number - four byte binary floating point quantity. The most significant byte contains the value of the exponent minus 127. The remaining three bytes contain the mantissa. The most significant byte of the mantissa contains the sign bit, followed by the seven highest bits of the mantissa. A positive number is represented with a 0 as the sign bit, a negative number with a 1 as the sign bit. The binary point is to the left of the most significant bit of the mantissa. A 1 is always assumed to exist immediately to the left of the mantissa, although it is not represented. Thus the number is represented as
   
   ( 1. * 2) ^ (exponent-127)
   
   
3. Double Precision Number - eight byte binary floating point quantity. It is represented exactly the same as a single precision number, except that the mantissa is made up of 41 bits (7 bytes less the sign bit).
4. String - Compiled BASIC will pass a pointer to a 'string descriptor' which is a four byte data structure. The first two bytes of the string descriptor contain the length of the string. The last two bytes contain the address where the actual ASCII string is located. The assembly language subroutine is allowed to modify the string, but must not change the string descriptor.
5. Array - arrays are made up of sequential elements of the array type. For example, an integer array containing twenty elements is represented as twenty sequential integers in memory.

Compiled BASIC passes all subroutine parameters by reference. In a CALL statement, the offset of each parameter's address is pushed onto the stack in the same order that the parameters are listed in the procedure call. It is important to note that all parameters to the assembly language subroutine must be variables. Upon entry to the subroutine, the stack will be arranged as follows:

The parameters can then be referenced by using the BP register to get their address off of the stack. The following example shows how to do this.

This example shows how to link an assembly language subroutine with a Compiled BASIC program. The assembly language routine performs modulo arithmetic on two integers, returning the remainder that results when the first integer is divided by the second. The example program is shown twice, once using a CALL statement and once using a CALLS statement.

After compiling and assembling the various modules, use the Microsoft linker to create the executable program. The compiled BASIC object modules should be listed before the names of the assembly language object modules. After your modules have been linked, your program is ready to run.

Assembly language subroutines can be invoked from GWBASIC using the CALL statement. The CALL statement pushes the offset addresses of any parameters on the stack before it transfers execution to the subroutine.

The assembly language subroutine must follow some simple rules in order to work correctly.

1. It must be declared FAR.
2. Segment registers DS and ES must be restored to their entry values before returning to Compiled BASIC.
3. The general purpose registers (AX, BX, CX, DX, SI, DI, and BP) can have any value when returning to GWBASIC.
4. The assembly language routine MUST NOT change the length of any GWBASIC strings.
5. The assembly language routine must perform a RET (where n = 2 times the number of parameters) to restore the stack pointer to its proper value.
6. Values can be returned to GWBASIC by passing a parameter that the result will be returned in.

In order to manipulate data passed to an assembly language subroutine, it is necessary to understand how the various data types are represented in memory. When a subroutine is called, GWBASIC will pass the address of one of the following data representations.

1. Integer - two byte two's complement number
2. Single Precision Number - four byte binary floating point quantity. The most significant byte contains the value of the exponent minus 127. The remaining three bytes contain the mantissa. The most significant byte of the mantissa contains the sign bit, followed by the seven highest bits of the mantissa. A positive number is represented with a 0 as the sign bit, a negative number with a 1 as the sign bit. The binary point is to the left of the most significant bit of the mantissa. A 1 is always assumed to exist immediately to the left of the mantissa, although it is not represented. Thus the number is represented as
   
   ( 1. * 2) ^ (exponent-127)
   
   
3. Double Precision Number - eight byte binary floating point quantity. It is represented exactly the same as a single precision number, except that the mantissa is made up of 41 bits (7 bytes less the sign bit).
4. String - GWBASIC will pass the offset address of a 'string descriptor' which is a three byte data structure. The first byte of the string descriptor contains the length of the string. The last two bytes contain the address where the actual ASCII string is located. The assembly language subroutine is allowed to modify the string, but it must not change the string descriptor.
5. Array - arrays are made up of sequential elements of the array type. For example, an integer array containing twenty elements is represented as twenty sequential integers in memory.

GWBASIC passes all subroutine parameters by reference. In a CALL statement, the offset of each parameter's address is pushed onto the stack in the same order that the parameters are listed in the procedure call. It is important to note that all parameters to the assembly language subroutine must be variables. Upon entry to the subroutine, the stack will be arranged as follows:

The parameters can then be referenced by using the BP register to get their address off of the stack. The following example shows how to do this.

This example shows how to load an assembly language subroutine from a GWBASIC program. The assembly language routine performs modulo arithmetic on two integers, returning the remainder that results when the first integer is divided by the second. In this example, the assembly language module is loaded at address 1664:0 Hex, but this address will be different for different applications. The method of determining this address is explained after the example.

Occasionally, you may wish to write certain subroutines in assembly language instead of Cobol because of speed, size, or other constraints. This section explains how to combine Cobol programs with assembly language modules so that parameters are passed correctly between the Cobol program and the assembly language subroutine.

To understand this section fully, the reader should have a basic knowledge of the following:

1. The Cobol Compiler
2. The Microsoft MACRO Assembler
3. The Microsoft linker
4. The register structure of the 8086/8088

Assembly language subroutines can be invoked from Cobol using the CALL statement with the assembly language module name as a literal. Parameters can be passed to the assembly language routine with the addition of the USING clause. The CALL statement pushes the offset addresses of any parameters on the stack before it transfers execution to the subroutine. The examples later in this discussion will fully illustrate the calling procedure.

The assembly language subroutine must follow some simple rules in order to work correctly.

1. It must be declared FAR.
2. It must be declared PUBLIC.
3. Segment registers DS and ES along with register BP must be restored to their entry values before returning to Cobol.
4. The general purpose registers (AX, BX, CX, DX, SI, and DI) can have any value when returning to Cobol.
5. The assembly language routine must perform a RET (where n = 2 times the number of parameters) to restore the stack pointer to its proper value.
6. Values can be returned to Cobol by passing a parameter to the assembly language subroutine that the result be returned in.

In order to manipulate data passed to an assembly language subroutine, it is necessary to understand how the various data types are represented in memory. When a subroutine is called, Cobol will pass the address of one of the following data representations.

Cobol passes all subroutine parameters by reference. In a CALL statement, the offset of each parameter's address is pushed onto the stack in the same order that the parameters are listed in the USING clause. Upon entry to the assembly language subroutine, the stack will be arranged as follows:

The parameters can then be referenced by using the BP register to get their address off of the stack. The following example shows how to do this.

This example shows how to link an assembly language subroutine with a Cobol program. The assembly language routine performs modulo arithmetic on two Computational-0 variables, returning the remainder that results when the first variable is divided by the second.

After compiling and assembling the various modules, use the Microsoft linker to create the executable program. The Cobol object modules should be listed before the names of the assembly language object modules. After your modules have been linked, your program is ready to run.

1. The Pascal compiler
2. The assembler
3. The linker
4. The register structure of the 8086/8088

To call an assembly language subroutine from a Pascal program, it is necessary to declare the assembly language subroutine as an external procedure or function. The format of an external procedure declaration in Pascal is exactly like that of a standard Pascal procedure declaration with the addition of the external directive and no procedure body. See the section on directives in the 'Reference Manual for MS-Pascal' for detailed information.

The assembly language subroutine must have the far attribute in its 'proc' statement, since Pascal assumes that all external procedures are far. Pascal also requires assembly language rout- ines to have identical class names to Pascal routine class names. The acceptable class names can be found in the file ENTX6L.ASM, found on the Pascal compiler diskette. For example, code of an assembly language routine should have the class name 'CODE' and data used by an assembly language routine should have the class name 'DATA'. In addition, the name of the subroutine must be declared public in the assembler code. This must be the same name that is declared as an external procedure in Pascal. The two examples later in this chapter illustrate the relationship between the external declaration in Pascal and the public declar- ation in assembler.

The user written subroutine can modify the AX, BX, CX, DX, DI, SI, and ES registers. The SP, BP and DS registers can also be modified, but their values must be restored before returning to Pascal. The SS register should NEVER be modified. The user should also pop all parameters off of the stack by using a ret N state- ment, where N equals the number of bytes on the stack used by the parameters.

When a procedure is called in Pascal, either the address or the value of any parameters are passed to the procedure on the stack. The address of a parameter is pushed on the stack when the formal parameter is declared as a VAR, VARS, CONST, or CONSTS type. The value of a parameter is passed on the stack if the for- mal parameter in the procedure declaration does not have one of these types. The following example code should clarify this dis- tinction.

The declaration for procedure gamma defines gamma as having two parameters: x and y. The first parameter is passed by address (this is also known as 'passing by reference'), while the second parameter is passed by value. When gamma is actually called, the address of alpha is pushed onto the stack, while delta is passed by having its value (21 in this case) pushed onto the stack.

In the 8086, addresses can be one of two types: near or far. A near address consists of the sixteen bit offset address in the current segment, while a far address consists of a full twenty bit address made up of specified segment and offset values. In Pascal, the user has the ability to specify which form of addres- sing to use for parameters (in relation to the data segment) when they are passed by reference. In the declaration of a procedure or function, near addresses are specified by declaring formal parameters as VAR or CONST, while far addresses are specified by declaring parameters as VARS or CONSTS. In the above example, the address of alpha is passed to the procedure by pushing the seg- ment address (i.e. the value of the DS register) of alpha on the stack, followed by its offset address. The segment address of a parameter is the value contained in the DS register. If the for- mal parameter x in the procedure declaration had been declared as VAR instead of VARS, then only the offset address of alpha would have been pushed onto the stack. Note that the declared type of the variable does not affect the way that the parameter address is passed.

When a parameter is passed by value, the actual value of the variable at that time is pushed onto the stack. For variables of large size (such as large arrays, records, etc.), this causes the stack to grow quickly and potentially overflow. It is usually preferable to pass structured variables by reference to prevent this occurrence.

1. Byte - simple 1 byte unsigned value.
2. Char - 1 byte ASCII character representation.
3. Boolean - 1 byte value. FALSE is represented with a 0 in the low order bit (bit 0). TRUE is represented with a 1 in bit 0. Bits 1-7 should be 0.
4. Word - Normally, a 2 byte unsigned value. However, Word subranges in the range 0..255 are represented by a one byte unsigned value.
5. Integer - Normally, a 2 byte two's complement number. Subranges in the range -128..127 are represented using one byte only.
6. Integer4 - 4 byte two's complement number.
7. Real4 - 4 byte IEEE standard real format. The most sig- nificant bit is the sign bit, followed by an 8 bit expo- nent with a bias of 127. This is followed by a 23 bit mantissa. The mantissa has a 'hidden' most significant bit that is always a 1, so the mantissa is actually a 24 bit quantity that represents a number greater than or equal to 1.0 but is less than 2.0.
8. Real8 - 8 byte IEEE format. The sign bit is followed by a 11 bit exponent with bias of 1023, followed by a 52 bit mantissa. As in Real4, the mantissa has a 'hidden' most significant bit that is always a 1.
9. arrays and records - the internal format of arrays and records is composed of the internal forms of the compo- nents, in the same order as in the array or record dec- laration.
10. super arrays - like arrays, super arrays are composed of the form of its declared component type. In a procedure declaration, a super array type can be defined as an address parameter. When the procedure is called, the actual parameter is substituted for the formal paramater and the size of the super array is pushed onto the stack before its address is pushed. This allows the procedure to be more general, as it can operate on arrays of dif- ferent lengths. If the formal parameter is a dimensioned super array type, then the length of the super array is not passed on the stack. It is important to note that an undimensioned super array type cannot be passed by value and cannot be a function return type.
11. string - the string type is a predeclared super array, and as such has the same restrictions as a super array. The string itself is just a sequential array of type Char, with each element represented by its ASCII value.
12. lstring - the lstring type is also a predeclared super array. It is exactly like the string type, except that the first byte of the array contains the length of the string. This allows lstrings to have variable lengths but limits their maximum length to 255 characters.
13. Enumerated types - If there are 256 or fewer values in the enumerated type, 1 byte is required. If the enumer- ated type has more than 256 possible values, two bytes are required. The values are numbered from 0 to n-1, in the order declared (i.e. the value returned by the ord function on the type).
14. Address types - the ADR type is represented by a 2 byte value containing the offset address of the value. The ADS type is a 4 byte value containing both the segment and offset addresses of the value.

In Pascal, the returned value of a function is passed back to the calling module in specific registers. For small data types the actual value is returned, while for large data types the ad- dress of the result is returned. It is necessary for user written functions to follow the Pascal conventions.

Return values declared as one of the simple types Boolean, Byte, Char, Integer2, Word, or Integer4, or as one of the address types Adr or Ads, or an Enumerated type are returned by value in specified registers. The value of single byte types (Boolean, Byte, or Char) should be returned in the AL register. The value of single word types (Adr, Integer2, or Word) should be returned in the AX register. An enumerated type is returned in either the AL or AX register, depending on whether it has more or less than 256 declared elements. The value of double word types (Ads and Integer4) should be returned in the DX and AX registers, with the most significant word in DX.

Function return values of any other type (such as Real, Rec- ord, and Super Array based types) are returned by address. This address should be returned in the AX register. When a function with one of these types is called, a temporary variable is allo- cated by Pascal. The near address of this temporary variable is pushed onto the stack just before the return address (i.e. after all the parameters have been pushed). The user function should put the value to be returned in this variable, and return the address in the AX register. The second example below shows how this mechanism works.

This example (Figure 2) shows a user written assembly lan- guage routine that performs a sum function. The routine requires two input parameters - an integer super array of type vector and an integer value that contains the number of valid elements in the array. The function adds all of the valid elements in the array (which should be in array positions 1 to count) and returns the total of these values as an integer in the AX register.

It is important to note that the function has been declared external in the Pascal program and public in the assembler sub- routine. It should also be noted that the return statement in Pascal pops six bytes off of the stack, even though there are only two parameters. This is due to the fact that one of the for- mal parameters is an undimensioned super array type, so that when the function is called, the size of the actual super array para- meter is pushed onto the stack just before its address. The state of the stack just after the call to sum is shown here:

In the assembly language function below, the value of the BP register is pushed on the stack, and then BP is used to access the values on the stack. Note that the offsets from BP are two greater than the offsets in the above diagram, because the value of BP has been saved on the stack, increasing the stack size by two bytes.

This example illustrates how to return a value of a struc- tured type to a Pascal program. The Pascal program passes two strings to the subroutine, which returns the string that results from cancatenating the second string to the first.

Note that the function requires two lstrings (declared as type shortstring) as parameters, and returns a third lstring (of type longstring) to the calling program. Since the returned value is a structured type, Pascal passes the address of a temporary variable of this type on the stack immediately before calling the user function. The assembly language routine uses this temporary variable to build the concatenated string, and then returns this address to the caller in the AX register. Just after the call, the stack is structured as follows:

As in the first example, the BP register is used to access parameters passed on the stack. The temporary variable passed on the stack is used to build the new string, and then the address is returned in the AX register to the Pascal program.

It is important that the programmer of the assembler func- tion understands the data structures of any types being used by his routine. In this example, the structure of the lstring type needed to be known in order for the concatenated string to be correctly built and correctly interpreted by the Pascal program when it is returned.

After running the Pascal compiler and the macro assembler, it is necessary to link the object modules produced to create the executable .EXE file. The order of the object modules given to the linker is important - The Pascal program module must be the first module in the list of objects, with the assembly objects last. The order of the assembly objects does not matter, but they must come after all Pascal modules. Thus, the proper link command for the second example above is

	A>link myname+concat