8086asm user's manual

8086asm User’s Manual

The latest version of this manual is available at 8086asm user's manual
Open source repository address: https://github.com/hyan23/8086asm

中文

Introduction

TODO: Introduction

Table of Contents

1 Use this library

To use the functions defined in this library, there are two ways:

  1. Copy the function library *.inc file you need to use to your personal working directory, and insert a line in the blank area of ​​the code snippet
    1
    include filename.inc

to include a single library file;

  1. Find the original function definition in the corresponding library file by looking up the user’s manual - function list, copy all the contents of the code from (include)
    1
    function-name proc near

to

1
function-name endp

into the blank area of ​​the code segment. When copying, also pay attention to whether the function calls other functions(this is rare, I also stated the file name of the called function for each cross-file call), and copy the called function into your personal code as well.

Note: The second method is recommended. By this way, the library function interface will not affect the written programs when it changes.

2 Programming specifications

  1. In general, the ax register is used as the argument and returned value of the function.
  2. For address parameters of a function, unless particularly specified, the segment register is assumed to be ds, i.e., if an address parameter is declared as dx, the function will get its data from ds:dx
  3. Use the dx register to point to the read-only memory area and the bx register to the writable memory area.
  4. The string ends with the ‘$’ symbol
  5. 32-bit register combination: dx:ax, 64-bit register combination: dx:ax:cx:bx
  6. When calling a subroutine in file.inc, you must also include common.inc, which contains the constant definitions used by file.inc
  7. There are also functions that return a boolean type, which will use the @TRUE and @FALSE constants defined in common.inc
  8. There are other functions that operate on arrays that use the @WORD constant defined in common.inc

The constants defined in common.inc are described as follows:

constant name value meaning
@WORD 2 word size
@TRUE 1 logical true
@FALSE 0 logical false

This set of constants listed below is for the open function in file.inc, passed as the second argument with ax, used to indicate how the file is opened, @ORD for read-only, @OWR for write-only, @ORDWR represent readable and writable

1
2
3
4
; file.inc.open
@ORD equ 0
@OWR equ 1
@ORDWR equ 2

This set of constants listed below is for the seek function in file.inc, passed as the second argument with cx, used to indicate the movement mode, @SEEK_SET means the movement relative to the beginning of the file, @SEEK_CUR means the movement relative to The current position, @SEEK_END indicates that the movement is relative to the end of the file. For specific usage, refer to the c language fseek function.

1
2
3
4
; file.inc.seek
@SEEK_SET equ 0
@SEEK_CUR equ 1
@SEEK_END equ 2

3 Function list

Note: The function name which preceded by a ‘*’ flag is to indicate that the function is used internally by the library. Users should not call these functions separately.

3.1 Basic input and output

Source code file name: iopt.inc

Function Name Description Parameter List Return Value/Result Notes
clear Clear the screen      
cursor Set cursor position ah: line number, al: column number   Parameter description: line number, column number value starts from 0, the range of values ​​depends on the current display mode. The default display mode is: 25* 80, therefore ah has a value ranged 0-24, and al has a value ranged 0-79
putc Print a character at the cursor position with specified attribute al: character to be printed, bl: attribute value    
space Print a space at the cursor position      
crlf Print carriage return (CR, 0dh), line feed (LF, 0ah), which will cause the cursor to jump to the beginning of the next line      
getch Enter a character from the keyboard   ax: character entered 1. This function does not require input confirmation, that means you do not need to type an extra ‘carriage return’ or ‘space’ blank character to complete the input after the input is completed, so whitespace characters are also read in. 2. Left most 8 bits of returned value ax are always zero
gets Enter a string from the keyboard, end with ‘carriage’, and append the ‘$’ end tag bx: buffer address bx: string entered  
iptpwd Enter a password string from the keyboard, end with ‘carriage’, and append the ‘$’ end tag. Unlike gets, this function does not echo what the user has typed to screen bx: buffer address bx: passwork entered  
pause Print a line of prompts, waiting for the user to type ‘carriage’      
optch Print a character at the cursor position al: character to be printed    
iptch Enter a character from the keyboard, type ‘carriage’ or ‘space’ blank character to confirm   ax: character entered The left most 8 bits of the returned value ax are always zero
optstr Print a string ending with the ‘$’ symbol at the cursor position dx: string to be printed    
optstrq Print a string ending with the ‘$’ symbol at the cursor position and add quotation marks at both sides dx: string to be printed    
puts Print a string ending with the ‘$’ symbol at the cursor position, add carriage return, line feed dx: string to be printed    
putsq Print a string ending with the ‘$’ symbol at the cursor position, add quotation marks at both sides, add carriage return, line feed dx: string to be printed    
optdec Print a number in decimal at the cursor position ax: number to print   Range: 0-65535
optdecdw Print a number in decimal at the cursor dx:ax number to print   Range: 0-4294967295
iptdec Enter a decimal number from the keyboard, type ‘carriage return’ or ‘space’ blank character to confirm   ax: number entered  
optdecs Print a signed decimal number at the cursor position ax: number to print   Range: -32768-32767
iptdecs Enter a signed decimal number from the keyboard, type ‘carriage return’ or ‘space’ blank character to confirm   ax: number entered  
*hex2ascii       Internal use
*opt0x       Internal use
opthex Print a number in hexadecimal at the cursor position ax: number to be printed    
opthexb Print a byte in hexadecimal al: byte to be printed   With leading ‘0x’
opthexw Print a word in hexadecimal ax: word to be printed   With leading ‘0x’
opthexdw Print a double word in hexadecimal dx:ax double word to be printed   with leading ‘0x’
opthexqw Print a quadra-word in hexadecimal dx:ax:cx:bx quadra-word to be printed   with leading ‘0x’
*ascii2hex       Internal use
ipthex Enter a hexadecimal number from the keyboard   ax: number entered  
optbin Print a number in binary at the cursor position ax: number to be printed    
iptbin Enter a binary number from the keyboard   ax: number entered  
optbcd Print a number in compressed BCD code at the cursor position ax: number to be printed   Max digits: 4 digits
iptbcd Enter a number from the keyboard in BCD code, store as compressed BCD form   ax: number entered Max digits: 4 digits
printArray Print an unsigned word array separated by spaces at the cursor position dx: array address, cx: number of elements    
printArrayS Print a signed word array separated by spaces at the cursor position dx: array address, cx: number of elements    

3.2 String

Source code file name: string.inc

Note: C-style string, that is, a string with the number 0 as the terminator; DOS-style string, that is, a string with the character ‘$’ as the terminator, in this function library, the functions related to file operation require C-style string, and other functions require DOS-style string.

Function Name Description Parameter List Return Value/Result Notes
convert Convert a C-style string to a DOS-style string bx: the string to be converted bx: the converted string  
convertC Convert a DOS-style string to a C-style string bx: string to be converted bx: converted string  
lower converts all English letters in a given string to lowercase bx: string to be converted bx: converted string  
upper converts all English letters in a given string to uppercase bx: string to be converted bx: converted string  
strlen Calculate the length of the string dx: the string to be calculated ax: the length of the string Can be applied to two styles of strings
strequ See if two strings are equal dx: string 1, bx: string 2 ax: boolean result  
strcmp Compare two strings in ASCII order dx: string 1, bx: string 2 ax: signed integer result Return value description: 0 means two strings are equal, -1 means string 1 is lower than string 2, 1 means string 1 is greater than string 2
strcpy String copy dx: source string, bx: destination string bx: copied string Applicable to two styles of strings
concat String concatenation dx: source string, bx: destination string bx: concatenated string Can be applied to two styles of strings, or mixed, but the style of the resulting string depends on the style of source string
index String lookup dx: source string, bx: string to be searched ax: signed integer result Return value description: -1 means that the string to be found is not found in the source string, positive number represents the index of the first occurrence of the string to be found in the source string
rands Generate a random string bx: buffer address, cx: length of string to be generated bx: random string  

3.3 Arithmetic

Source code file name: arith.inc

Note: In the 8086 architecture, when div or idiv instruction is executed. If the operand (divisor) is one byte, the dividend is considered to be a word stored in the ax register. After the instruction is executed, the quotient is stored in al as one byte, the remainder is stored in ah as one byte. However, to divide a word, the quotient is likely to be larger than one byte, especially when the divisor is small, consider 1000 / 2, In this case, al is not enough for this “big quotient”, this is the so-called “division overflow”. The operand (divisor) has a similar situation for a word.

Function Name Description Parameter List Return Value/Result Notes
bcd2dec Converts 4 digit compressed BCD code to 8421 code ax: 4 digit BCD code to be converted ax: converted data  
mul32 Performs 32-bit unsigned multiplication, multiplier and multiplicand are 32 bits dx:ax multiplicand, cx:bx multiplier dx:ax:cx:bx product  
div32 Perform 32-bit safe unsigned division dx:ax dividend, cx: divisor dx:ax quotient, bx: remainder  

3.4 File

Source code file name: file.inc

  1. The string type parameter received by the function defined in this file is required to be a C style string, What is a C style string?
  2. Relative path can be used
Function Name Description Parameter List Return Value/Result Notes
mkdir Create folder dx: folder name with path ax: boolean result  
rmdir Delete folder dx: folder name with path ax: boolean result  
mkfile Create an empty file dx: filename with path ax: boolean result  
rmfile Delete a file dx: file name with path ax: boolean result  
exists See whether a file is existed dx: filename with path ax: boolean result  
open Open a file dx: file name with path, ax: mode ax: file handle 1. Mode: @ORD means open in read-only mode, @OWR means open in write-only mode, @ORDWR means read and write mode. Constant definition location; 2. Return value description: If the file handle is -1, it means that the file is failed to open
close Close file ax: file handle ax: boolean result  
properties Get file properties ax: file handle ax: file attribute File attribute: Bit 0 - read only bit, Bit 1 - implicit bit, Bit 2 - system bit, Bit 3 - volume label, Bit 5 - archive , other bits are reserved, set to 1
read Reads a number of bytes from an open file and stores them in the specified buffer ax: file handle, cx: number of bytes to read, bx: buffer address ax: boolean result, cx: number of bytes actually read, bx: data read if the remaining number of bytes in the file is less than the number of bytes specified by cx, cx is updated to the actual number of bytes read, ax is updated to @FALSE (unverified)
write Writes several bytes of data to an open file ax: file handle, cx: number of bytes to write, dx: first address of the data to be written ax: boolean result, cx: actual number of bytes written (failed condition not verified)
seek Move file pointer ax: file handle, cx: mode, dx: signed displacement ax: boolean result mode: @SEEK_SET indicates that the offset is relative to the beginning of the file, @SEEK_CUR indicates the offset is relative to the current position, @SEEK_END indicates that the offset is relative to the end of the file. Constant Definition Location
rewind Rewind the file pointer back to the begining of the file ax: file handle ax: boolean result  
tell Get file pointer position     Unimplemented
mvfile Move file dx: source file name with path, bx: target file name with path ax: boolean result If the target file already existed, the function will silently overwrite this file
mvdir Move folders     Unimplemented
cpfile Copy file dx: source file name with path, bx: target file name with path ax: boolean result If the target file already existed, the function will silently overwrite this file
cpdir copy folder     Not implemented

3.5 System

Source code file name: sys.inc

Function Name Description Parameter List Return Value/Result Notes
exit Exit the user program, transfer control to the DOS system al: set the status code    
reside Exit user program in resident mode dx   I don’t quite understand
memory Get memory capacity   ax: system memory capacity (in K)  
date Get system date   dx: year, ah: month, al: day  
time Get system time   dx: hour, ah: minute, al: second  
get_interrupt Get an interrupt vector cx: interrupt number dx:ax segment address:offset address  
set_interrupt Install an interrupt vector cx: interrupt number, dx:ax segment address:offset address    
pspseg Get the current program PSP segment   ax: PSP segment address  
cmdlen Get the length of the command line arguments   ax: the length of the command line arguments  
cmdline Get command line arguments bx: buffer address bx: command line arguments  
arg Gets each space-separated parameter in turn dx: command line parameter address, bx: buffer address used to store the parameter ax: processed dx 1. Since the return value ax is dx after processing, should transfer ax to dx and make another call to get the next parameter; 2. After calling this function, if [ax]=’$’ or strlen(dx)=0, indicates the command line parameters have been processed.
drive Get the drive letter of the program’s current working path   ax: drive number  
pwd Get the current working path of the program bx: buffer address bx: current working path  
alloc Allocate memory     Unimplemented
free Free memory     Not implemented
memcpy Memory copy dx: source address, bx: destination address, cx: number of bytes to copy bx: copied data  
dump Print read time CPU status     “Real Time” refers to the time before the call instruction to call the dump function is officially executed, ip should point to the next instruction of call dump

3.6 Utility Routines

Source code file name: util.inc

Function Name Description Parameter List Return Value/Result Notes
srand Initialize random number seed      
rand Generate a random number   ax: random number  
sort Sort an array of signed words, in ascending order bx: address of the array, cx: number of array elements bx: sorted array  
*swap       Internal use
*partition       Internal use
*quick_sort       Internal use
qsort Quick sort a signed word array, in ascending order bx: array address, cx: array element number bx: sorted array  
reverse Reverse a word array bx: array address, cx: array element number bx: reversed array This function can be used after sort, qsort to invert array order
shuffle Disorganize the order of a word array bx: the address of the array, cx: the number of array elements bx: shuffled array  

3.7 Macro Library

Source code file name: macros.inc

  1. “Macro” is like a function based on macro substitution and macro expansion. During source code compilation, the assembler replaces the call statement with the expanded macro function body. The macro function is more flexible than the function, usually also faster than function.
  2. Instructions for use: Copy the macro function body or insert include macros.inc to user code, the assembler must see its definition before expanding a macro
  3. How to call the macro function (using WriteString as an example):
    1
    WriteString 'hello world'
Macro Name Description Parameter List Return Value/Result Notes
WriteString Print a string at the cursor position 1: a string    

4 Common assembly instructions and their introductions

Mnemonic Features Usage Notes
mov      
如果这篇文章对您有用,可以考虑打赏:)