PCjs Machines
Home of the original IBM PC emulator for browsers.
MS MASM 6.0 White Paper
The following document is from the Microsoft Programmer’s Library 1.3 CD-ROM.
Microsoft Macro Assembler - White Paper
────────────────────────────────────────────────────────────────────────────
Microsoft (R) Macro Assembler - White Paper
Version 6.0
────────────────────────────────────────────────────────────────────────────
For MS (R) OS/2 and MS-DOS (R) Operating Systems
Microsoft Corporation
This technical overview is for informational purposes
only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS SUMMARY.
(C) Copyright Microsoft Corporation, 1991.
All rights reserved.
Printed in the United States of America.
Microsoft, the Microsoft logo, MS, MS-DOS, and CodeView
are registered trademarks and Making it all make sense and
Windows are trademarks of Microsoft Corporation.
U.S. Patent No. 4,955,066
i486 is a trademark of Intel Corporation.
IBM is a registered trademark of International Business
Machines Corporation.
Table of Contents
────────────────────────────────────────────────────────────────────────────
Product Overview
Revolutionary New Assembler
Programmer's WorkBench
Integrated Documentation
The MASM 6.0 Assembler
Faster Assembly
Built-In Jump Extensions and Optimizations
Convenient Format for Procedures and Procedure Prototypes
Automatic Conversion of C Header Files to MASM Include Files
New Data Types
Enhanced Macro Capabilities
Easy-To-Use Decision and Loop Constructs
Expanded DOS and OS/2 Support
New 80486 and FLAT Model Support
Improved Support for Multiple-Module Programming
Complete BNF Language Definition
Programmer's WorkBench
Full-Featured Editor
Enhanced CodeView(R) Debugger
Powerful Source Browser
Information-Packed Online Reference System
Integrated Documentation
Microsoft Advisor Online Reference System
Installing and Using the Professional Development System
Microsoft Macro Assembler Programmer's Guide
Microsoft Macro Assembler Reference
Conclusion
System Requirements
Product Overview
────────────────────────────────────────────────────────────────────────────
The Microsoft Macro Assembler has long been the industry standard for fast
and efficient assemblers. Writing assembly-language code, however, has been
slow and tedious work. The new features of the Microsoft Macro Assembler
version 6.0 Professional Development System (hereafter referred to as MASM
6.0) make it easy for you to be fast and efficient when you program. For the
first time, you get the convenience of high-level language coding as well as
the 50 to 300% performance boost that assembly language provides over
high-level language routines.
Why? Because MASM 6.0 is not an evolutionary product that adds a few new
features. Instead it is a revolutionary new version of MASM that reduces
your coding time, simplifies code maintenance, and delivers exceptional
performance.
Revolutionary New Assembler
Further details on these and other time-saving new features begin on page 5.
MASM 6.0 boosts your productivity by handling numerous repetitive
programming tasks for you, making other tasks easier, and providing many new
capabilities. For example, MASM 6.0
■ Increases assembly speed, eliminates phase errors and unnecessary NOP
statements, and generates optimal code for jumps by using n-pass
assembly technology
■ Checks argument types and automatically generates the code to push
arguments when you use PROTO to define a procedure prototype and
INVOKE to call the procedure
■ Simplifies external symbol declaration and include-file development
■ Allows macro functions, macros with variable numbers of arguments, and
other powerful new macro capabilities
■ Increases the functionality of structures and types by allowing nested
structures, pointer types, and unions
■ Converts your C-language header files to MASM include files with the
H2INC utility
■ Introduces intuitive language constructs─.IF, .WHILE, and .REPEAT─that
automatically generate optimized instructions for run-time decisions
and loops
■ Generates DOS* or OS/2= module-initialization code automatically
■ Provides new extensions to simplified segment directives that make it
easier to set up complicated segment models
■ Implements the 80486 instruction set and supports flat model for
32-bit operating systems
■ Supports tiny memory model so you can produce .COM executable files
■ Automates assembling and linking with a one-step build process
■ Allows Windows programs to relocate code segments, since you can use
the new LROFFSET operator to generate a loader-resolved offset
■ Includes the Microsoft Advisor with online help for MASM and utilities
* DOS refers to the MS-DOS(R) and PC DOS operating systems. = Herein
OS/2 refers to the operating system jointly developed by Microsoft and IBM.
Programmer's WorkBench
The Programmer's WorkBench (PWB) is a complete, self-contained development
environment. With PWB, you can write, edit, get help on, build, debug, and
execute your programs without ever leaving the environment. PWB provides
access to all your Microsoft utilities and compilers such as Microsoft C
version 6.0, Basic version 7.1, and COBOL version 4.0. See Figure 1.
(This figure may be found in the printed book.)
PWB includes the Source Browser for navigating through your program's code
and data structures. The powerful keyboard or mouse-driven editor has
extensive macro capabilities. And the Microsoft Advisor provides online
help. See page 11 for more about PWB.
The Microsoft CodeView(R) window-oriented debugger, also accessible from
within PWB, can debug larger programs than before. You can also view several
source-code and memory locations simultaneously.
Integrated Documentation
MASM 6.0 includes three manuals and online help.
MASM 6.0 provides both online and printed documentation. The Microsoft
Advisor, the online reference system, contains information on how to use
MASM 6.0, PWB, CodeView, LINK, NMAKE, the editor, and all other utilities.
For a quick start on using MASM 6.0 and PWB, read Installing and Using the
Microsoft Professional Development System. This manual shows how to install
the assembler, manage multiple-module projects with PWB, and access online
help.
The documentation also includes a revised Programmer's Guide. This manual
illustrates all the new language features of MASM 6.0 and explains the
advanced features of CodeView, PWB, and other MASM 6.0 utilities.
The Microsoft Macro Assembler Reference provides quick access to syntax and
command-line options for the assembler and utilities. See page 14 for more
information about MASM 6.0 documentation.
The MASM 6.0 Assembler
────────────────────────────────────────────────────────────────────────────
The MASM 6.0 assembler increases your productivity in several ways. The
highlevel-language interface for procedures simplifies multiple-module,
mixed-language, and OS/2 programming. Macros are more straightforward to
write and maintain. Code-generating directives shorten programming time. And
new options maximize compatibility with MASM 5.1.
MASM 6.0's new features are designed to be as intuitive as
high-level-language statements. With MASM 6.0, your code will be noticeably
easier to write, read, and maintain.
Faster Assembly
More efficient assembling means greatly improved performance.
MASM 6.0 eliminates phase errors and assembler-generated NOP statements by
using n-pass assembly and highly efficient memory-management techniques.
With n-pass assembly, the first pass is similar to that of traditional
assemblers. During this pass, however, MASM 6.0 keeps enough information on
each instruction so that, should any instruction change size on subsequent
passes, the assembler can make appropriate adjustments. Because this
algorithm allows instructions to shrink or grow, MASM 6.0 never generates
NOP statements or phase errors.
MASM 6.0 continues passing over internal representations of code until every
instruction is of optimal length. As a result, it generates optimized code
for all instructions, including jumps. And because it references the source
files only once, it assembles two to three times faster than MASM 5.1.
Built-In Jump Extensions and Optimizations
MASM 6.0 generates optimal encodings.
Built-in "smart" jump extensions and optimizations simplify your
programming. You do not have to specify a distance operator to take
advantage of automatic optimization for unconditional jumps. The assembler
automatically determines the smallest encoding possible for the direct
unconditional jump. Additionally, MASM 6.0 optimizes far calls when the
destination is in the current segment by pushing the CS register and
generating a NEAR call. This is functionally equivalent, but is faster and
one byte smaller.
MASM 6.0 also lengthens conditional jumps automatically. If the conditional
jump specifies or implicitly requires a distance other than SHORT, MASM
automatically generates the necessary comparison and unconditional jump to
the destination. You can control these optimizations with the OPTION
directive and with menu or command-line options.
For example, the destination for this jump is more than 128 bytes away:
mov ax, cx
jz skip
.
. ; (More than 128 bytes of code here)
.
skip:
Note the unconditional jump in the assembler-generated code:
mov ax, cx
jnz temp$1
jmp skip
temp$1:
.
. ; (More than 128 bytes of code here)
.
skip:
The listing file shows the generated instructions and the resulting warning
message:
002C 8B C1 mov ax, cx
002E 75 03 E9 00C0 jz skip
jumptest.asm(63): warning A6003: conditional jump lengthened
Convenient Format for Procedures and Procedure Prototypes
The new INVOKE and PROTO directives create a high-level interface for
procedures to simplify your MASM, OS/2, mixed-language, and Microsoft
Windows(tm) graphicalenvironment programming. The PROTO directive defines
procedure prototypes. Like C-language function prototypes, MASM prototypes
inform the assembler of types and numbers of arguments so the assembler can
check for errors in the procedure call. The INVOKE directive calls the
procedure, converting arguments to the expected type and pushing parameters
according to the correct calling conventions. The VARARG keyword allows a
variable number of arguments to be passed to the procedure (see Figure 2).
(This figure may be found in the printed book.)
In addition to the new directives for procedure prototypes and procedure
calls, MASM 6.0 provides new support for the customizing of setup and
teardown for procedure stack frames. You can write procedure prologue and
epilogue code for Windows programs or for other special calling conventions,
and call them repeatedly─as easily as you can call a macro.
Automatic Conversion of C Header Files to MASM Include Files
H2INC helps port a program prototyped in C to MASM.
The H2INC utility translates C header files into MASM-compatible include
files. Now you can more easily write programs that mix C code and MASM code
with global data structures. H2INC translates data declarations, function
prototypes, and simple #define directives, but not C statements that compile
into data or executable code.
This example shows several C declarations and the MASM code that H2INC
produces:
C Code H2INC Translation
────────────────────────────────────────────────────────────────────────────
#define CORNERS 4 CORNERS EQU 4t
int my_var; EXTERNDEF C my_var:SWORD
struct tagName { tagName STRUCT 2t
int i; i SWORD ?
}; tagName ENDS
long pascal my_func3 (int x); @proto_0 TYPEDEF PROTO PASCAL :SWORD
my_func3 PROTO @proto_0
Because MASM supports many new high-level data types, data-type information
is not lost when you translate C data to MASM, as the next section explains.
New Data Types
New MASM data types resemble those in high-level languages.
Now you can use high-level data types in assembly language. Types and
pointers can be defined with TYPEDEF in the same way they can be defined in
C. In addition, the CodeView debugger recognizes all MASM 6.0 data types, as
well as pointers and the type of data they point to.
MASM 6.0 also supports signed types defined with SBYTE, SWORD, and SDWORD;
floating-point data types defined with REAL4, REAL8, and REAL10; and
binary-coded decimals defined with TBYTE. CodeView displays values of type
REAL4, REAL8, and REAL10 as floating-point numbers, not hexadecimal fields.
Enhanced syntax for defining and using structures, and implementing nested
structures and unions, mean these types closely mirror their C counterparts.
Enhanced Macro Capabilities
Macros are more straightforward to write and maintain.
The new directives in MASM 6.0 make complex macros cleaner and easier to
write by accommodating variable numbers of arguments, macro functions,
definitions of text equates, and loop constructs:
■ Variable, required, and default arguments. MASM 5.1 ignores extra
arguments passed to macros. MASM 6.0 provides the VARARG keyword for
simplifying macro calls by allowing a macro to process any number of
arguments. Specifying required or default arguments allows better
error checking.
■ Macro functions. At assembly time, macro functions can return a text
value using EXITM. Predefined macro string functions can concatenate
strings, return the size of a string, find a substring in a string, or
return the position of a substring within a string.
■ Text equates. The TEXTEQU directive for defining text macros allows
greater functionality and consistency than EQU provides. For example,
TEXTEQU can assign the value returned by a macro function to a text
equate.
■ Directives for loops in macros. Now there are more ways to implement
loops inside macros. Within a macro definition, WHILE repeats assembly
as long as a condition remains true. Other macro loop directives─FOR,
FORC, and REPEAT─also generate loops in macros.
This macro function takes one required argument and accepts a variable
number of arguments:
@ArgI MACRO index:REQ, arglist:VARARG
LOCAL count, retstr
count = 0
FOR arg, <arglist>
count = count + 1
IF count EQ index
retstr TEXTEQU <arg>
ENDIF
ENDM
EXITM retstr
ENDM
Easy-To-Use Decision and Loop Constructs
Code-generating directives shorten programming time.
The high-level control structures new to MASM 6.0─.IF, .WHILE, and .REPEAT─
automatically generate MASM loop and compare instructions. These new
directives are similar to the if, while, and repeat statements of C or
Pascal. They make your assembly modules easy to code, read, and maintain.
You can also use the new .BREAK and .CONTINUE directives to interrupt loop
execution. See Figure 3.
(This figure may be found in the printed book.)
In the listing file, asterisks mark the automatically generated code:
0017 B9 000A mov cx, 10
.REPEAT
001A *@C0001:
001A B4 08 mov ah, 08h
001C CD 21 int 21h
.BREAK .IF al == 13
001E 3C 0D * cmp al, 00Dh
0020 74 10 * je @C0003
.CONTINUE .IF (al < '0') || (al > '9')
0022 3C 30 * cmp al, '0'
0024 72 0A * jb @C0002
0026 3C 39 * cmp al, '9'
0028 77 06 * ja @C0002
002A 8A D0 mov dl, al
002C B4 02 mov ah, 02h
002E CD 21 int 21h
.UNTILCXZ
0030 *@C0002:
0030 E2 E8 * loop @C0001
0032 *@C0003:
Expanded DOS and OS/2 Support
You no longer have to write repetitive module-initialization code.
The new .STARTUP and .EXIT directives eliminate the need to write repetitive
module-initialization and exit code for DOS and OS/2 modules. If you specify
OS_DOS or OS_OS2 as your target operating system in the .MODEL statement,
the assembler automatically generates the appropriate code.
Also new to MASM 6.0 is tiny-model support for producing .COM executables
under DOS. And for Windows programming, the LROFFSET operator generates a
loaderresolved offset to allow Windows to relocate code segments.
New 80486 and FLAT Model Support
You can design code for the next generation of systems today.
MASM 6.0 supports all the new i486 instructions. And for 32-bit operating
systems, the assembler provides flat memory model. Flat model provides four
gigabytes of linear addressing space, eliminating the need for segmentation
considerations when programming for 386-compatible operating systems.
Improved Support for Multiple-Module Programming
One directive replaces PUBLIC and EXTRN.
MASM 6.0 simplifies external declarations for shared data and procedures in
multiple-module and mixed-language programs. The new EXTERNDEF directive
declares procedures and symbols as both public and external. EXTERNDEF makes
it easy to maintain global definitions in include files shared by all source
modules within a project.
Complete BNF Language Definition
The BNF clearly defines MASM syntax.
MASM 6.0 includes a complete language grammar in an augmented BNF format.
BNF stands for Backus-Naur Form, a standard format for language grammars.
You can use the BNF to determine the exact syntax for any language
component. The BNF grammar clearly defines recursive definitions and shows
all the available options for each language element.
An excerpt from the grammar:
╓┌─────────────────────────────────┌─────────────────────────────────────────╖
────────────────────────────────────────────────────────────────────────────
procDir procId PROC « pOptions » « <
macroArgList > »
« usesRegs » « procParmList »
procId id
────────────────────────────────────────────────────────────────────────────
id alpha
| id alpha
| id decdigit
pOptions « distance » « langType » « oVisibility
»
distance nearfar
| NEAR16 | NEAR32 | FAR16 | FAR32
langType C | PASCAL | FORTRAN | BASIC
| SYSCALL | STDCALL
oVisibility PUBLIC | PRIVATE | EXPORT
macroArgList macroArg
| macroArgList , macroArg
macroArg % constExpr
────────────────────────────────────────────────────────────────────────────
macroArg % constExpr
| % textMacroId
| % macroFuncId ( macroArgList )
| string
| arbitraryText
| < arbitraryText >
usesRegs USES regList
regList register
| regList register
procParmList « « , « ;; » » parmList »
« « , « ;; » » parmId :VARARG»
Programmer's WorkBench
────────────────────────────────────────────────────────────────────────────
Now you can write, edit, build, debug, and run programs in one environment.
The PWB environment provides an intuitive interface and easy access to the
assembler, to your MASM 6.0 files, to utilities, to other Microsoft
compilers, and to online reference documentation. You can switch from
editing to debugging to looking up statement syntax by selecting a menu or
dialog-box item.
With PWB 1.1, you select the main source language of your project from
languages you have installed under PWB. The main language you choose
determines the build options available. PWB then simplifies program
assembling and building by providing background assembly (under OS/2),
automatic makefile generation, and automatic dependency checking.
Predefined defaults for build options include DOS executable files, Windows
applications, OS/2 Presentation Manager applications, and OS/2 dynamic-link
libraries (DLLs).
Figure 4 shows how easily you can set MASM assembler options from within
PWB. Notice that you can select target options instead of typing a series of
command-line options.
(This figure may be found in the printed book.)
PWB minimizes editing and debugging time, as well as build time, by
incorporating an editor, debugger, source browser, and online reference
system.
Full-Featured Editor
The PWB Editor is a full-featured programmer's editor with all the
capabilities that professionals expect:
■ Multiple windows
■ Mouse and keyboard support
■ Fast file navigation and bookmarks
■ Convenient and powerful search capability
■ Multiple levels of Undo/Redo
■ Flexible configuration options
■ Recordable macros
You can select any of these editor functions from menus or with key
combinations. The Microsoft Advisor provides instructions for using the
editor.
Enhanced CodeView(R) Debugger
In addition to its improved user interface, the CodeView debugger gives you
a dynamic record and replay feature for recreating debugging sessions. It
reduces debugging effort by providing complete access to pointers, arrays,
structures, and coprocessor status.
CodeView adds other key improvements:
■ Multiple source and memory windows
■ Improved debugging for DLLs and multithread programs
■ New capability for debugging .COM files under DOS
■ No restrictions on sizes of DOS programs for debugging under CodeView
A system with an 80286 or 80386 processor and at least 384K of extended
memory can now run CodeView in extended memory, using less than 12K of
conventional memory. CodeView also supports the LIM 4.0 Expanded Memory
Specification (EMS) and can use Virtual Control Program Interface (VCPI)
memory if it's available. VCPI is an applications programming interface
(API) provided by various drivers, including HIMEM.SYS, which is included
with MASM 6.0.
Powerful Source Browser
MASM 6.0 includes the Source Browser made popular with the Microsoft C 6.0,
Basic 7.1, and COBOL 4.0 compilers. You can use the Browser to find any
symbol definition, find all references to that symbol, and see where
variables are used or from where functions are called. See Figure 5.
(This figure may be found in the printed book.)
With the Browser's View Relationship menu option, you can easily determine
information about a module such as which module calls it and what data it
uses.
The Source Browser provides far more information about your program than the
CREF utility (available with previous versions of MASM) provides. And, as
you browse through the structure of your code, the Source Browser creates a
browse history. At the end of the process, you can see where you have been.
Information-Packed Online Reference System
All online help can be accessed from one location.
The productivity benefits of detailed online documentation are now available
to MASM 6.0 users. In addition to extensive indexes and cross-references,
the Microsoft Advisor online reference system provides hypertext links
between related concepts. It includes information on all phases of project
development, from editing to using the OS/2 programming interface. The
Advisor is available either through PWB or from the command line with
QuickHelp.
The Microsoft Advisor includes
■ Information on using PWB's integrated development environment
■ Explanations of PWB dialog boxes and menu choices
■ How-to and quick-reference information for all installed languages and
utilities (see Figure 6)
■ Complete explanations of error messages for all utilities
(This figure may be found in the printed book.)
The next section describes the online information available for the
assembler.
You can add your own information to the online database using the HELPMAKE
utility included in MASM 6.0. Similarly, vendors who develop tools for
Microsoft language products can add the documentation for those tools to the
Advisor.
Integrated Documentation
────────────────────────────────────────────────────────────────────────────
The MASM 6.0 documentation provides comprehensive information to get you
started, how-to information on all the tools, examples of the new language
features, and topical information for advanced users. The documentation set
includes three manuals and the online reference system, the Microsoft
Advisor.
Microsoft Advisor Online Reference System
You can access the Microsoft Advisor from the PWB environment or from
QuickHelp using the command line. Figure 7 shows the Advisor table of
contents screen. In addition to the features listed on page 13, the Advisor
includes MASM-specific information such as
■ Syntax and timing information for all instructions
■ Complete documentation for DOS and BIOS function calls
■ Sample code you can insert into your programs
■ Help on all error messages
Help is context-sensitive─you can look up any item by placing the cursor on
the word and pressing the F1 key or clicking a mouse button.
(This figure may be found in the printed book.)
Installing and Using the Professional Development System
Read Installing and Using the Professional Development System to get started
using MASM 6.0. This short book includes information on installing the
Professional Development System, configuring your system, using PWB and the
CodeView debugger, building multiple-module programs, and navigating through
the Advisor.
Microsoft Macro Assembler Programmer's Guide
The Programmer's Guide is a complete guide to new MASM features.
The Programmer's Guide provides the information you need to write
assemblylanguage programs for this new assembler. New language features are
discussed throughout the Programmer's Guide rather than in a separate update
manual.
The Programmer's Guide shows how to use NMAKE, HELPMAKE, CodeView, and
H2INC. It also explains how to customize the PWB editor, develop OS/2 and
dual-mode applications, create dynamic-link libraries, write memory-resident
(TSR) software, and create mixed-language programs.
Appendix A explains how to update MASM 5.1 code. Other appendixes cover the
BNF grammar, assembly listings, reserved words, error messages, and default
segment names. The glossary defines language and utility terminology.
Microsoft Macro Assembler Reference
The popular Microsoft Macro Assembler Reference again furnishes complete
information on all MASM instructions (including those for the i486
processor) with syntax, timings, and encoding information. It also includes
a quick reference for directives, operators, predefined symbols, keycodes,
and command-line syntax for the assembler and all utilities. Figure 8 shows
an excerpt from the Reference containing information on BSF/BSR
instructions.
(This figure may be found in the printed book.)
Conclusion
────────────────────────────────────────────────────────────────────────────
MASM 6.0 can revolutionize your approach to assembly-language programming.
Never before has there been an assembler that decreases your programming
time and effort so significantly while enhancing your productivity and
providing faster assembly.
Simplified programming means greater productivity.
This new assembler simplifies assembly-language programming─from declaring
external symbols, writing procedure calls, and developing multilanguage
programs to coding macros, loops, and decision constructs.
MASM 6.0 sets new standards in virtually every area important to the
professional developer who needs to write, debug, and maintain assembly
routines or modules. The full-featured editor, debugger, and source browser
of this multilanguage development system can significantly increase your
productivity.
The improvements in speed and capability over previous versions of MASM are
substantial. The clear advantage in ease of use and increased productivity
makes MASM 6.0 the obvious choice for your assembly-language projects.
System Requirements
────────────────────────────────────────────────────────────────────────────
Microsoft Macro Assembler version 6.0 requires the following configuration:
■ A personal computer running DOS version 3.0 or later or OS/2 version
1.1 or later.
■ 640K (kilobytes) of available memory (RAM) for operating under DOS (1
megabyte of RAM is recommended).
■ 3 megabytes of RAM for operating under OS/2 (4 megabytes are
recommended).
■ At least 384K of extended memory to debug large DOS programs.
■ One hard-disk drive with at least 4 megabytes of free space.
Installation of all files provided with MASM 6.0 requires
approximately 6.2 megabytes of disk space. The setup program checks to
see if there is enough space available, and also prompts you to decide
whether or not to install online help and sample code.
■ One floppy-disk drive. For OS/2, either a 1.2 megabyte, 5.25-inch
drive or a 720K, 3.5-inch drive. For DOS, either a 1.2 megabyte,
5.25-inch drive; a 360K, 5.25-inch drive; or a 720K, 3.5-inch drive.
(1.2 megabyte disks and 720K floppy disks are shipped in separate
boxes. 360K floppy disks are available on request.)