8086asm user's manual

发表于 2018-10-06 分类于文档本文字数： 16k

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

8086asm User’s Manual

1 Use this library

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

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;
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

In general, the ax register is used as the argument and returned value of the function.
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
Use the dx register to point to the read-only memory area and the bx register to the writable memory area.
The string ends with the ‘$’ symbol
32-bit register combination: dx:ax, 64-bit register combination: dx:ax:cx:bx
When calling a subroutine in file.inc, you must also include common.inc, which contains the constant definitions used by file.inc
There are also functions that return a boolean type, which will use the @TRUE and @FALSE constants defined in common.inc
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

; 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.

; 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
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

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?

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

“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.

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
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