> # Chapter Two Hello, World of Assembly Language

> ## 2.1 Chapter Overview

> This chapter is a "quick-start" chapter that lets you start writing basic assembly language programs right away. This chapter presents the basic syntax of an HLA (High Level Assembly) program, introduces you to the Intel CPU architecture, provides a handful of data declarations and machine instructions, describes some utility routines you can call in the HLA Standard Library, and then shows you how to write some simple assembly language programs. By the conclusion of this chapter, you should understand the basic syntax of an HLA program and be prepared to start learning new language features in subsequent chapters.

> ## 2.2 Installing the HLA Distribution Package

> Before you can learn assembly language programming using HLA, you must first successfully install HLA on your system. Currently, HLA is available for the Linux and Windows operating systems. This section explains how to install HLA on these two systems. If HLA is already running on your system, you may skip to the next major section in this chapter.

> The latest version of HLA is available from the Webster web server at

> http://webster.cs.ucr.edu

> Go to this web site and following the HLA links to the "HLA Download" page. From here you should select the latest version of HLA for download to your computer. The HLA distribution is provided in a "Zip File" compressed format. Under Windows, you will need a decompressor program like PKUNZIP or WinZip in order to extract the HLA files from this zipped archive file; under Linux, you will use the GZIP and TAR programs to decompress and extract HLA. A detailed description of the use of these decompression products is beyond the scope of this manual, please consult the software vendor's documentation or their web page for information concerning the use of these products; this discussion will only briefly describe how to use them to extract important HLA files.

> This text assumes that you will unzip the HLA distribution into the root directory of your C: drive under Windows, or to the "/usr/hla" directory under Linux. You can certainly install HLA anywhere you want, but you will have to adjust the following descriptions if you install HLA somewhere else. If possible, you should install HLA using root/administrator priviledges; regardless, you should make sure the permissions are set properly on the files so everyone has read and execute access to the HLA files; if you are unsure how to do this, please consult your operating system's documentation or consult a system administrator.

> HLA is a console application. In order to run the HLA compiler you must run the command window program (this is "command.com" on Windows 95 and 98, or "cmd.exe" on Windows NT and Windows 2000; Linux users typically run "bash" or some other shell). This also means that you should be familiar with some simple "command line interface" (CLI) or "shell" commands.

> Most Windows distributions let you run the command prompt windows from the Start menu or from a submenu hanging off the start menu (you may also select "RUN" from the Start menu and type "cmd" as the program name). This text assumes that you are familiar with the Windows command window and you know how to use some basic command window commands (e.g., dir, del, rename, etc.). If you have never before used the Windows command line interpreter, you should consult an appropriate text to learn a few basic commands.

> Most Linux distributions run "bash" or some other shell program whenever you open up a terminal window (e.g., a GNOME or KDE terminal window or an X-TERM window). There are some minor differences between the shells running under Linux, this document assumes that you are using GNU's "bash" shell. Again, this text assumes that you are comfortable with a few commands like ls, rm, and mv. If you have never used a Unix shell program before, you should consult an appropriate text or the on-line documentation to learn a few basic commands.

> Before you can actually run the HLA compiler, you must set the system execution path and set up various environment variables. The following subsections explain how to do this under Windows and then Linux.

> ### 2.2.1 Installation Under Windows

> HLA is not a stand alone program. It is a compiler that translates HLA source code into a lower-level assembly language. A separate assembler, such as MASM, then completes the processing of this low-level intermediate code to produce an object code file. Finally, you must link the object code output from the assembler using a linker program. Typically you will link the object code produced by one or more HLA source files with the HLA Standard Library (hlalib.lib) and, possibly, several operating system specific library files (e.g., kernel32.lib under Windows). Most of this activity takes place transparently whenever you ask HLA to compile your HLA source file(s). However, for the whole process to run smoothly, you must have installed HLA and all the support files correctly. This section will discuss how to set up HLA on your Windows system.

> First, you will need an HLA distribution for Windows. The latest version of HLA is always available on Webster at http://webster.cs.ucr.edu. You should go there and download the latest version if you do not already possess it.

> As noted earlier, HLA is not a stand alone assembler. The HLA package contains the HLA compiler, the HLA Standard Library, and a set of include files for the HLA Standard Library. If you write an HLA program with just this code, HLA will produce an "ASM" file and then stop. To produce an executable file you will need Microsoft's MASM and LINK programs, along with some Windows library files, to complete the process. The easiest way to get all the files you need is to download the "MASM32" package from http://www.pdq.com.au/home/hutch/masm.htm or any of the other places on the net where you can find the MASM32 package (Webster maintains a current link if this link is dead). Once you unzip this file, it's easy to install the MASM32 package using the install program it supplies. You must install MASM32 (or MASM/LINK/Win32 library files) before HLA will function properly.

> Here are the steps I went through to install MASM32 on my system:

> - I downloaded masm32v6.zip from the URL above (later versions are probably okay too, although there is a slight chance that the installation will be different.
> - I double-clicked on the masm32v6.zip file (which runs WinZip on my system).
> - I choose to extract "install.exe". I told WinZip to extract this file to C:\.
> - I double-clicked on the "install.exe" icon and selected the "C:" drive in the window that popped up. Then I hit the install button and waited while MASM32 extracted all the pertinent files. This produced a directory called "MASM32". MASM32 is a powerful assembly language development subsystem in its own right; but it uses the traditional MASM syntax rather than the HLA syntax. So we'll use MASM32 mainly for the assembler, linker, and library files. MASM32 also includes a simple editor/IDE and several other tools that may be useful to an HLA programmer. Feel free to check this software out and see if it is useful to you. For now, note that the executable files you will ultimately need are ML.EXE, ML.ERR, LINK.EXE, and a couple of DLLs. You can find them in the MASM32\BIN subdirectory. Leave them there for the time being. The MASM32\LIB directory also contains many Win32 library files you will need. Again, leave them alone for the time being.
> - Next, if you haven't already done so, download the HLA executables file from Webster at http://webster.cs.ucr.edu. On Webster you can download several different ZIP files associated with HLA from the HLA download page. The "Executables" is the only one you'll absolutely need; however, you'll probably want to grab the documentation and examples files as well. If you're curious, or you want some more example code, you can download the source listings to the HLA Standard Library. If you're really curious (or masochistic), you can download the HLA compiler source listings to (this is not for casual browsing!).
> - I downloaded the HLA1_32.zip file while writing this. Most likely, there is a much later version available as you're reading this. Be sure to get the latest version. I chose to download this file to my "C:\" root directory.
> - After downloading HLA1_32.zip to my C: drive, I double-clicked on the icon to run WinZip. I selected "Extract" and told WinZip to extract all the files to my C:\ directory. This created an "HLA" subdirectory in my root on C: with two subdirectories (include and lib) and two EXE files (HLA.EXE and HLAPARSE.EXE. The HLA program is a "shell" program that runs the HLA compiler (HLAPARSE.EXE), MASM (ML.EXE), the linker (LINK.EXE), and other programs. You can think of HLA.EXE as the "HLA Compiler".
> - Next, I created the following text file and named it "IHLA.BAT" (note that you may need to change the default drive letters if you want to install HLA on a drive other than "C:"):

>     path=c:\hla;c:\masm32\bin;%path%

>     set lib=c:\masm32\lib;c:\hla\hlalib;%lib%

>     set include=c:\hla\include;c:\masm32\include;%include%

>     set hlainc=c:\hla\include

>     set hlalib=c:\hla\hlalib\hlalib.lib

> - Be sure you've typed all the lines exactly as written or HLA will fail to run properly. You may use any reasonable TEXT editor (e.g., NOTEPAD.EXE) to create this file. Do not use a word processing program (since they generally don't save their data as a TEXT file). Be sure the file is named "IHLA.BAT" and not "IHLA.BAT.TXT" or some other variation.
> - This batch file tells the system where to find all the files you will need when running HLA. Advanced Win32 users should note that you can set all these environment variables up inside the Windows system control panel in the "Advanced->Environment Variables" area. This is far more convenient (ultimately) than using this batch file (for reasons you'll soon see). However, you can mess up you system if you don't know what you're doing when playing with the system control panel, so only advanced users who've done this stuff before should attempt this.
> - HLA is a Win32 Console Window program. To run HLA you must open up a console Window. Under Windows 2000, Microsoft has hidden this away in Start->Programs->Accessories->Command Prompt. You might find it in another location. You can also start the command prompt processor by selecting Start->Run and entering "cmd".
> - Once you've got the command prompt, ("C:>" or something similar), execute the IHLA.BAT file you've created by typing "IHLA" at the command line prompt. Hit the ENTER key to execute the command.
> - At this point, HLA should be properly installed and ready to run. Try typing "hla -?" at the command line prompt and verify that you get the HLA help message. If not, go back and figure out what you've done wrong up to this point (it doesn't hurt to start over from the beginning if you're lost).
> - Thus far, you've verified that HLA.EXE is operational. Now try the following command: "ML /?" This should run the Microsoft Macro Assembler (MASM) and display the help screen. You can ignore the information that appears; you will probably never need to know this stuff.
> - Next, let's verify the correct operation of the linker. Type "link /?" and verify that the linker program runs. Again, you can ignore the help screen that appears. You don't need to know about this stuff.
> - Now it's time to try your hand at writing an honest to goodness HLA program and verify that the whole system is working. Here's the canonical "Hello World" program written in HLA (we will revisit this program a little later in this chapter, don't worry about what it means just yet). Enter it into a text editor and save it using the filename "HW.HLA":

>     program HelloWorld;

>     #include( "stdlib.hhf" )

>     begin HelloWorld;

>     	stdout.put( "Hello, World of Assembly Language", nl );

>     end HelloWorld;

> - Make sure you're in the same directory containing the HW.HLA file and type the following command at the "C:>" prompt: "HLA -v HW". The "-v" option tells HLA to produce VERBOSE output during compilation. This is helpful for determining what went wrong if the system fails somewhere along the line. This command should produce the following output:

>     HLA (High Level Assembler)

>     Written by Randall Hyde and released to the public domain.

>     Version Version 1.32 build 4904 (prototype)

>     Files:

>     1: hw.hla

>     Compiling "hw.hla" to "hw.asm"

>     Assembling hw.asm via "ml /c /coff /Cp  hw.asm"

>     Microsoft (R) Macro Assembler Version 6.14.8444

>     Copyright (C) Microsoft Corp 1981-1997. All rights reserved.

>      Assembling: hw.asm

>     Linking via "link -subsystem:console  /heap:0x1000000,0x1000000
>     /stack:0x1000000,0x1000000 /BASE:0x3000000 /machine:IX86  -entry:?HLAMain @hw.link
>     -out:hw.exe kernel32.lib user32.lib  c:\hla\hlalib\hlalib.lib hw.obj"

>     Microsoft (R) Incremental Linker Version 5.12.8078

>     Copyright (C) Microsoft Corp 1992-1998. All rights reserved.

>     /section:.text,ER

>     /section:readonly,R

>     /section:.edata,R

>     /section:.data,RW

>     /section:.bss,RW

> - If you get all of this output, you're in business. You can run the "HW" program using the following CLI (command line interpreter) command:

>     		HW

> - One thing to remember is that unless you set the environment variables permanently in the System control panel, you will have to run the IHLA.BAT file every time you open up a new command prompt window. Since this is a pain, here are some instructions I've taken from the Internet that describe how to set up the environment variables (DO THIS AT YOUR OWN RISK!)

> 1) Open System Properties (Winkey-Break is a convenient shortcut) and go to Advanced tab, then Environment Variables. Add "c:\hla" to the Path in SYSTEM VARIABLES, not in "User variables for <your win2k login name>". Click OK, but keep the Environment Variables window open, we're not done.
> 2) Look at the contents of ihla.bat (ABOVE):
> 3) In "User Variables for <your login name>", you must end up with each of these settings. For example, to create hlainc, you click the "New..." button, type "hlainc" as the name of the variable, and type "c:\hla\include" as the Variable value (all without quotes of course). If there is already a path set, and it already has some value, add this immediately to the end: ";c:\hla;%path%" and that will preserve your existing User and System paths as well as adding c:\hla.
> For example, suppose you opened up your User Variables for <login name> and it already said "C:\Private
> Files\PantiePix;c:\winnt\system32;c:\winnt;c:\winnt\System32\Wbem;d:\lcc\bin;D:\PROGRA~1\ULTRAE~1;D:\4NT300;C:\msoffice\Office;c:/hla",
> you would click on Edit and type "C:\Private Files\PantiePix;c:\hla;%path%"
> (Same advice for preserving existing lib and include settings)
> 4) Once you reboot the computer, you should be all set for "Hello world of assembly language"! (without having to run the IHLA.BAT file.)

> Installing HLA is a complex and slightly involved process. Unfortunately, this is necessary because I don't have the rights to distribute MASM, LINK, and other Microsoft files. Fortunately, HUTCH has collected all of these files together so they are easy to download. If you are concerned about possible legal issues with the download, you may legally download MASM and LINK from Microsoft's site. A link on Webster (at the URL above) describes how to do this. At the time this was being written, work was progressing on HLA to produce TASM compatible output and plans were in the works to produce NASM and Gas versions as well. However, you will still have to obtain the Microsoft library files from some source if you intend to produce a Win32 application. Versions of HLA may appear for other Operating Systems as well. Check out Webster to see if any progress has been made in this direction.

> The most common two problems people have running HLA involve the location of the Win32 library files and the choice of linker. During the linking phase, HLA (well, link.exe actually) requires the kernel32.lib, user32.lib, and gdi32.lib library files. These must be present in the pathname(s) specified by the LIB environment variable. If, during the linker phase, HLA complains about missing object modules, make sure that the LIB path specifies the directory containing these files. If you're a MS VC++ user, installation of VC++ should have set up the LIB path for you. If not, then locate these files (they are part of the MASM32 distribution) and copy them to the HLA\HLALIB directory (note that the ihla.bat file includes c:\hla\hlalib as part of the LIB path).

> Another common problem with running HLA is the use of the wrong link.exe program. Microsoft has distributed several different versions of link.exe; in particular, there are 16-bit linkers and 32-bit linkers. You must use a 32-bit segmented linker with HLA. If you get complaints about "stack size exceeded" or other errors during the linker phase, this is a good indication that you're using a 16-bit version of the linker. Obtain and use a 32-bit version and things will work. Don't forget that the 32-bit linker must appear in the execution path (specified by the PATH environment variable) before the 16-bit linker.

> ### 2.2.2 Installation Under Linux

> HLA is not a stand alone program. It is a compiler that translates HLA source code into a lower-level assembly language. A separate assembler, such as Gas (as), then completes the processing of this low-level intermediate code to produce an object code file. Finally, you must link the object code output from the assembler using a linker program. Typically you will link the object code produced by one or more HLA source files with the HLA Standard Library (hlalib.a). Most of this activity takes place transparently whenever you ask HLA to compile your HLA source file(s). However, for the whole process to run smoothly, you must have installed HLA and all the support files correctly. This section will discuss how to set up HLA on your system.

> First, you will need an HLA distribution for Linux. The latest version of HLA is always available on Webster at http://webster.cs.ucr.edu. You should go there and download the latest version if you do not already possess it.

> As noted earlier, HLA is not a stand alone assembler. The HLA package contains the HLA compiler, the HLA Standard Library, and a set of include files for the HLA Standard Library. If you write an HLA program with just this code, HLA will produce an "ASM" file and then stop. To produce an executable file you will need GNU's as and ld programs (these come with any Linux distribution that supports compiling C/C++ programs). Note that HLA only works with Gas v2.10 or later. The Gas assembler is part of the Binutils package. If you don't have version 2.10 or later, download an appropriate binutils package from the internet. HLA will generate errors when it attempts to assemble its output via an invocation of the as (Gas) executable if you don't have Gas v2.10 or later installed in your system.

> Here are the steps I went through to install HLA on my Linux system:

> - First, if you haven't already done so, download the HLA executables file from Webster at http://webster.cs.ucr.edu. On Webster you can download several different ZIP files associated with HLA from the HLA download page. The "Linux Executables" is the only one you'll absolutely need; however, you'll probably want to grab the documentation and examples files as well. If you're curious, or you want some more example code, you can download the source listings to the HLA Standard Library. If you're really curious (or masochistic), you can download the HLA compiler source listings to (this is not for casual browsing!).
> - I downloaded the HLA1_39.tar.gz file while writing this. Most likely, there is a much later version available as you're reading this. Be sure to get the latest version. I chose to download this file to my root directory; you can put the file whereever you like, though this documentation assumes that all HLA files wind up in the "/usr/hla/..." directory tree. If you do not already have a "/usr/hla" subdirectory, you can create one with the "mkdir" command (it's best to do this using the "root" or "superuser" account; if you do not have superuser priviledges, you should have your system administrator do this for you.
> - After downloading HLA1_39.tar.gz to my root directory, I executed the following shell command: "gzip -d HLA1_39.tar.gz". Once decompression was complete, I extracted the individual files using the command "tar xvf HLA1_39.tar". This extracted a couple of executable files ("hla" and "hlaparse") along with two subdirectories (include and hlalib). The HLA program is a "shell" program that runs the HLA compiler (hlaparse), Gas (as), the linker (ld), and other programs. You can think of "hla" as the "HLA Compiler". It would be a real good idea, at this point, to set the permissions on "hla" and "hlaparse" so that everyone can read and execute them. You should also set read and execute permissions on the two subdirectories and read permissions on all the files within the directories (if this isn't the default state). Do a "man chmod" from the Linux command-line if you don't know how to change permissions.
> - Next, (logged in as a plain user rather than root or the super-user), I edited the ".bashrc" file in my home directory ("/home/rhyde" in my particular case, this will probably be different for you). I found the line that defined the "path" variable, it originally looked like this on my system
>   "PATH=$DBROOT/bin:$DBROOT/pgm:$PATH"
>   I edited this line to add the path to the HLA directory, producing the following:
>   "PATH=$DBROOT/bin:$DBROOT/pgm:/usr/hla:$PATH"
>   Without this modification, Linux will probably not find HLA when you attempt to execute it unless you type a full path (e.g., "/usr/hla/hla") when running the program. Since this is a pain, you'll definitely want to add "/usr/hla" to your path.
> - Next, I added the following four lines to ".bashrc" (note that Linux filenames beginning with a period don't normally show up in directory listings unless you supply the "-a" option to ls):
>   hlalib=/usr/hla/hlalib/hlalib.a
>   export hlalib
>   hlainc=/usr/hla/include
>   export hlainc
>   These four lines define (and export) environment variables that HLA needs during compilation. Without these environment variables, HLA will probably complain about not being able to find include files, or the linker (ld) will complain about strange undefined symbols when you attempt to compile your programs.
>   After saving the ".bashrc" shell, you can tell Linux to make the changes to the system by using the command:
>   source .bashrc
>   Note: this discussion only applies to users who run the BASH shell. If you are using a different shell (like the C-Shell or the Korn Shell), then the directions for setting the path and environment variables differs slightly. Please see the documentation for your particular shell if you don't know how to do this. Also note that Linux does not normally display files whose name begins with a period when you use the "ls" command; to see such files, use the "ls -a" shell command.
> - At this point, HLA should be properly installed and ready to run. Try typing "hla -?" at the command line prompt and verify that you get the HLA help message. If not, go back and figure out what you've done wrong up to this point (it doesn't hurt to start over from the beginning if you're lost).
> - Now it's time to try your hand at writing an honest to goodness HLA program and verify that the whole system is working. Here's the canonical "Hello World" program written in HLA (we'll discuss this program in detail a little later in this chapter). Enter it into a text editor and save it using the filename "hw.hla":

>     program HelloWorld;

>     #include( "stdlib.hhf" )

>     begin HelloWorld;

>     	stdout.put( "Hello, World of Assembly Language", nl );

>     end HelloWorld;

> - Make sure you're in the same directory containing the "hw.hla" file and type the following command at the prompt: "hla -v hw". The "-v" option tells HLA to produce VERBOSE output during compilation. This is helpful for determining what went wrong if the system fails somewhere along the line. This command should produce the following output:

>     HLA (High Level Assembler) Parser

>     Written by Randall Hyde and released to the public domain.

>     Version Version 1.39 build 6845 (prototype)

>     -t active

>     File: t.hla

>     Compiling "t.hla" to "t.asm"

>     HLA (High Level Assembler)

>     Copyright 1999, by Randall Hyde, all rights reserved.

>     Version Version 1.39 build 6845 (prototype)

>     ELF output

>     Using GAS assembler

>     GAS output

>     -test active

>     Files:

>     1: t.hla

>     Compiling 't.hla' to 't.asm'

>     using command line [hlaparse  -v -sg -test "t.hla"]

>     Assembling "t.asm" via [as -o t.o  "t.asm"]

>     Linking via [ld   -o "t"  "t.o" "/usr/hla/hlalib/hlalib.a"]

> Installing HLA is a complex and slightly involved process; though take heart, it's a lot simpler to install HLA under Linux than Windows! (See the previous section if you need proof.) Versions of HLA may appear for other operating systems (beyond Windows and Linux) as well. Check out Webster to see if any progress has been made in this direction. Note a very unique thing about HLA: Carefully written (console) applications will compile and run on all supported operating systems without change. This is unheard of for assembly language! So if you are using multiple operating systems supported by HLA, you'll probably want to download files for all supported OSes.

> Note: to run the HelloWorld program, a Linux user would type "hw" (or possibly "./hw") at the command line prompt.

> ### 2.2.3 Installing "Art of Assembly" Related Files

> Although HLA is relatively flexible about where you put it on your system, this text assumes you've installed HLA in the "hla" directory on your C: drive under a Win32 operating system or in "/usr/hla" under Linux. This text also assumes the standard directory placement for the HLA files, which has the following layout

> - HLA directory
> - AoA directory
> - Doc directory
> - Examples directory
> - hlalib directory
> - hlalibsrc directory
> - include directory
> - Tests directory

> The "Art of Assembly" (AoA) software distribution has the following directory tree structure:

> - AoA directory
> - volume1
> - ch01 directory
> - ch02 directory
> - etc.
> - volume2
> - ch01 directory
> - ch02 directory
> - etc.
> - etc.

> The main HLA directory contains the executable code for the compiler. This consists of two files, HLA.EXE/hla and HLAPARSE.EXE/hlaparse (Windows/Linux). These two programs must be in the current execution path in order to run the compiler. Under Windows, it wouldn't hurt to put the ml.exe, ml.err, link.exe, mspdbX0.dll (x=5, 6, or greater), and msvcrt.dll files in this directory as well. Under Linux, the "as" and "ld" programs are already in the execution path, assuming your Linux system supports C/C++ development.

> The Doc directory contains reference material for HLA in PDF and HTML formats. If you have a copy of Adobe Acrobat Reader, you will probably want to read the PDF versions since they are much nicer than the HTML versions. These documents contain the most up-to-date information about the HLA language; you should consult them if you have a question about the HLA language or the HLA Standard Library. Generally, material in this documentation supersedes information appearing in this text since the HLA document is electronic and is probably more up to date.

> The Examples directory contains a large set of HLA programs that demonstrate various features in the HLA language. If you have a question about an HLA feature, you can probably find an example program that demonstrates that feature in the Examples directory. Such examples provide invaluable insight that is often superior to a written description of the feature. Note that some of these programs may be specific to Windows or Linux, not all will compile and run under either operating system.

> The hlalib directory contains the object code for the HLA Standard Library. As you become more competent with HLA, you may want to take a look at how HLA implements various library functions by checking out the library source code in the hlalibsrc subdirectory.

> The include directory contains the HLA Standard Library include files. These special files (that end with a ".hhf" suffix, for "HLA Header File") are needed during assembly to provide prototype and other information to your program. The example programs in this chapter all include the HLA header file "stdlib.hhf" that, in turn, includes all the other HLA header files in the standard library.

> The Tests directory contains various test files that test the correct operation of the HLA system. HLA includes these files as part of the distribution package because they provide additional examples of HLA coding.

> The AoA directory contains the code specific to this textbook. This directory contains all the source code to the (complete) programs appearing in this text. It also contains the programs appearing in the Laboratory Exercises section of each chapter. Therefore, this directory is very important to you. Within this subdirectory, the information is further divided up by volume and chapter. The material for Chapter One appears in the "ch01" subdirectory of the "volume1" directory in the AoA directory tree, the material for Chapter Two appears in the "ch02" subdirectory of the "volume1" directory, etc..