Assembly Lines: The Complete Book

Chris Torrence — Mon, 22 Dec 2014 17:45:30 +0000

I am very excited to announce that Assembly Lines: The Complete Book is now available as a hardcover from Lulu press. Roger Wagner’s Assembly Lines articles originally appeared in Softalk magazine from October 1980 to June 1983. The first fifteen articles were reprinted in 1982 in Assembly Lines: The Book. Now, for the first time, all thirty-three articles are available in one complete volume. This edition also contains all of the appendices from the original book as well as new appendices on the 65C02, zero-page memory usage, and a beginner’s guide to using the Merlin Assembler. The book is designed for students of all ages: the nostalgic programmer enjoying the retro revolution, the newcomer interested in learning low-level assembly coding, or the embedded systems developer using the latest 65C02 chips from Western Design Center.

The book will be available in a few weeks from Amazon and other online retailers. I am currently working on an eBook version, which I hope to have finished in early 2015.

You can download disk images of all of the assembly-language programs from the Asimov ftp site in the pub/apple_II/images/programming/assembler directory:

AssemblyLinesWagnerDOS1.DSK contains DOS versions for chapters 1-17
AssemblyLinesWagnerDOS2.DSK contains DOS versions for chapters 18-30
AssemblyLinesWagnerProDOS1.DSK contains ProDOS versions for chapters 1-17
AssemblyLinesWagnerProDOS2.DSK contains ProDOS versions for chapters 18-30

Note that a few of the programs (in the DOS chapter) will only work in DOS, not ProDOS.

To create your own programs, you can download a copy of the Merlin assembler from the same directory:

merlin/Merlin-8 v2.48 (DOS 3.3).dsk
merlin/Merlin-8 v2.58 (ProDOS) Disk 1-2.dsk

These disk images can be opened in any of the Apple II emulators, such as Virtual ][ for the Mac or AppleWin for Windows. You could also use ADTPro to transfer the disk images to an actual Apple II.

I would love to get your feedback on the new book. If you have any questions or comments on the new book or the original articles, please post them below.

Here's a video explaining more about how the book was created...

Assembly Lines by Roger Wagner - Part 16

Chris Torrence — Wed, 14 May 2014 00:54:01 +0000

Assembly Lines, Part 16 was first published in Softalk in January 1982. This was the first article in what was supposed to be "Volume 2" of "Assembly Lines: The Book". Unfortunately, Volume 2 remained unpublished when Softalk went bankrupt in August 1984. Part 16 is actually the first of three parts where Roger Wagner explains how to interface assembly language with Applesoft Basic.

Everyone's Machine Language Guide, Part 16

One useful application of machine language programming is in the enhancement of your existing Applesoft programs. Some people are inclined to write all their programs in machine language, but it may be more efficient on occasion to write “hybrids”—programs that are a combination of Applesoft and machine language. In this way, particular functions can be done by the operating system best suited to the particular task.

If you had to write a short program to store ten names, it would be best to do it in Applesoft:

10 FOR I = 1 TO 10
20 INPUT N$(l)
30 NEXT I

This is much simpler than the equivalent program in machine language. In cases where neither speed nor program size is a concern, Applesoft is a completely acceptable solution.

However, if you had to sort a thousand names, speed would become a concern, and it would be worth considering whether the job could best be done in machine language.

If you have ever done a call in one of your Basic programs, then you have already combined Applesoft with machine code. For example:

10 HOME
20 PRINT "THIS IS A TEST"
30 PRINT "THIS IS STILL A TEST"
40 GET A$
50 VTAB 1: HTAB 5: CALL-958

In this program, a line of text is printed on the screen. After you press a key, all text on the screen after the first word “THIS” is cleared.

Now although it might be possible to accomplish the same effect in Applesoft by printing many blank lines, it would not be as fast or as efficient in terms of code as the call -958.

In executing the above program, the Applesoft interpreter goes along carrying out your instructions until it reaches the call statement. At that point a JSR is done to the address indicated by the call. When the final RTS is encountered, control returns to the Basic program. In between, however, you can do anything you’d like!

Calling routines is hardly complicated enough to warrant an entire article on the subject. The real questions are, how do you pass data back and forth between the two programs, and how can the problem of handling that data be made easier for the machine language program?

Simple Interfacing. The easiest way to pass data to a machine language routine is simply to poke the appropriate values into unused memory locations, and then retrieve them when you get to your machine language routine. To illustrate this, let’s resurrect the tone routine from the May 1981 issue of Softalk.

To use this, assemble the code and place the final object code at $300. Then enter the accompanying Applesoft program.

1 **********************
2 * SOUND ROUTINE #3A *
3 **********************
4 *
5 *
6 OBJ $300
7 ORG $300
8 *
9 PITCH EQU $06
10 DURATION EQU $07
11 SPKR EQU $C030
12 *
13 BEGIN LDX DURATION
14 LOOP LDY PITCH
15 LDA SPKR
16 DELAY DEY
17 BNE DELAY
18 DRTN DEX
19 BNE LOOP
20 EXIT RTS

From the Monitor, this will appear as:

*300L
0300- A6 07 LDX $07
0302- A4 06 LDY $06
0304- AD 30 CO LDA $C030
0307- 88 DEY
0308- DO FD BNE $0307
030A- CA DEX
030B- DO F5 BNE $0302
030D- 60 RTS

This Applesoft program is used to call it:

10 INPUT "PITCH, DURATION? ";P,D 20 POKE 6,P: POKE 7,D 30 CALL 768 40 PRINT 50 GOTO 10

The Applesoft program works by first requesting values for the pitch and duration of the tone from the user. These values are then poked into locations 6 and 7 and the tone routine called. The tone routine uses these values to produce the desired sound, and then returns to the calling program for another round.

This technique works fine for limited applications. Having to poke all the desired parameters into various comers of memory is not flexible, and strings are nearly impossible. There must be an alternative.

The Internal Structure of Applesoft. If you’ve been following this series for long, you’ve no doubt figured out by now that I’m a great believer in using routines already present in the Apple where possible, to accomplish a particular task. Since routines already exist in Applesoft for processing variables directly, why not use them?

To answer this, we must take a brief detour to outline how Applesoft actually “runs” a program.

Consider this simple program:

10 HOME: PRINT "HELLO"
20 END

After you’ve entered this into the computer, typing list should reproduce the listing given here. An interesting question arises: “How does the computer actually store, and then later execute, this program?”

To answer that, we’ll have to go to the Monitor and examine the program data directly.

The first question to answer is, exactly where in the computer is the program stored? This can be found by entering the Monitor and typing in: 67 68 AF B0 and pressing return.

The computer should respond with:

67- 01
68- 08
AF- 18
B0- 08

The first pair of numbers is the pointer for the program beginning, bytes reversed of course. They indicate that the program starts at $801. The second pair is the program end pointer, and they show it ends at $818. Using this information let’s examine the program data by typing in:

801L

You should get:

*801L
0801- 10 08 BPL $080B
0803- 0A ASL
0804- 00 BRK
0805- 97 ???
0806- 3A ???
0807- BA TSX
0808- 22 ???
0809- 48 PHA
080A- 45 4C EOR #$4C
080C- 4C 4F 22 JMP $224F
080F- 00 BRK
0810- 16 08 ASL $08,X
0812- 14 ???
0813- 00 BRK
0814- 80 ???
0815- 00 BRK
0816- 00 BRK
0817- 00 BRK
0818- F9 A2 00 SBC $00A2,Y
08IB- 86 FE STX $FE

This is obviously not directly executable code. Now type in: 801.818

This will give:

0801- 10 08 0A 00 97 3A BA
0808- 22 48 45 4C 4C 4F 22 00
0810- 16 08 14 00 80 00 00 00
0818- 8C

To understand this, let’s break it down one section at a time. When the Apple stores a line of Basic, it encodes each keyword as a single byte token. Thus the world print is stored as a $BA. This does wonders for conserving space. In addition, there is some basic overhead associated with packaging the line, namely a byte to signify the end of the line, and a few bytes at the beginning of each line to hold information related to the length of the line, and also the line number itself.

To be more specific:

0801- 10 08 0A 00 97 3A BA
0808- 22 48 45 4C 4C 4F 22 00
0810- 16 08 14 00 80 00 00 000
818- 8C

The first two bytes of every line of an Applesoft program are an index to the address of the beginning of the next line. At $801,802 we find the address $810 (bytes reversed). This is where line 20 starts. At $810 we find the address $816. This is where the next line would start if there were one. The double 00 at $816 tells Applesoft that this is the end of the Basic listing. It is important to realize that the 00 00 end of the Applesoft program usually, but not always, corresponds to the contents of $AF,B0. It is possible to hide machine language code between the end of the line data and the actual end as indicated by $AF,B0—but more on that later.

The next information within a line is the line number itself:

0801- 10 08 0A 00 97 3A BA
0808- 22 48 45 4C 4C 4F 22 00
0810- 16 08 14 00 80 00 00 00
0818- 8C

The 0A 00 is the two-byte form of the number ten, the line number of the first line of the Applesoft program. Likewise, the 14 00 is the data for the line number twenty. The bytes are again reversed. After these four bytes, we see the actual tokens for each line.

0801- 10 08 0A 00 97 3A BA
0808- 22 48 45 4C 4C 4F 22 00
0810- 16 08 14 00 80 00 00 00
0818- 8C

All bytes with a value of $80 or greater are Applesoft keywords in token form. Bytes less than $80 represent normal ASCII data (letters of the alphabet, for example). Examining the data here we see a $97 followed by $3A. $97 is the token for home, and $3A the colon. Next, $BA is the token for print. This is followed by the quote ($22) and the text for HELLO (48 45 4C 4C 4F) and the closing quote ($22). Last of all, the 00 indicates the end of the line.

In line number twenty, the $80 is the token for end. As before, the line is terminated with a 00.

When a program is executed, the interpreter scans through the data. Each time it encounters a token, such as the print token, it looks up the value in a table to see what action should be taken. In the case of print, this would be to output the characters following the token, namely “HELLO”.

This constant translation is the reason for the use of the term interpreter for Applesoft Basic.

Machine code on the other hand is directly executable by the 6502 microprocessor and hence is much faster, since no table lookups are required.

In Applesoft, a syntax error is generated whenever a series of tokens is encountered that is not consistent with what the interpreter expects to find.

Passing Variables. So, back to the point of all this. The key to passing variables to your own machine language routines is to work with Applesoft in terms of routines already present in the machine. One of the simplest methods was described in the October 1981 issue of Softalk, wherein a given variable is the very first one defined in your program (see the input routine). This is okay, but rather restrictive. A better way is to name the variable you’re dealing with right in the call statement.

The important points here are two components of the Applesoft interpreter: TXTPTR and CHRGET (and related routines).

TXTPTR is the two-byte pointer ($B8, B9) that points to the next token to be analyzed. CHRGET ($B1) is a very short routine that actually resides on the zero page and that reads a given token into the accumulator. In addition to occasionally being called directly, many other routines used CHRGET to process a string of data in an Applesoft program line.

Here then is the revised tone routine :

1 **********************
2 * SOUND ROUTINE #3B *
3 **********************
4 *
5 *
6 OBJ $300
7 ORG $300
8 *
9 PITCH EQU $06
10 DURATION EQU $07
11 SPKR EQU $C030
12 *
13 COMBYTE EQU $E74C
14 *
15 ENTRY JSR COMBYTE
16 STX PITCH
17 JSR COMBYTE
18 STX DURATION
19 *
20 BEGIN LDX DURATION
21 LOOP LDY PITCH
22 LDA SPKR
23 DELAY DEY
24 BNE DELAY
25 DRTN DEX
26 BNE LOOP
27 EXIT RTS

This would list from the Monitor as:

*300L

0300- 20 4C E7 JSR $E74C
0303- 86 06 STX $06
0305- 20 4C E7 JSR $E74C
0308- 86 07 STX $07
030A- A6 07 LDX $07
030C- A4 06 LDY $06
030E- AD 30 CO LDA $C030
0311- 88 DEY
0312- DO FD BNE $0311
0314- CA DEX
0315- DO F5 BNE $030C
0317- 60 RTS

The Applesoft calling program would then be revised to read:

10 INPUT "PITCH DURATION? ",P,D
20 CALL 768,P,D
30 PRINT
40 GOTO 10

This is a much more elegant way of passing the values and also requires no miscellaneous memory locations as such (although for purposes of simplicity the tone routine itself still uses the same zero page locations.)

The secret to the new technique is the use of the routine COMBYTE ($E74C). This is an Applesoft routine which checks for a comma and then returns a value between $00 and $FF (0-255) in the X register.

It is normally used for evaluating pokes, hcolor=t and so forth, but does the job very nicely here. It also leaves TXTPTR pointing to the end of the line (or a colon if there was one) by using CHRGET to advance TXTPR appropriate to the number of characters following each comma. Note also that any legal expression--such as (X-5)/2--can be used to pass the data.

To verify the importance of managing TXTPTR, try putting a simple RTS ($60) at $300. Calling this you will get a SYNTAX ERROR, since upon return, Applesoft’s TXTPTR will be on the first comma, and the phrase “,P,D” is not a legal Applesoft expression.

Now what about two-byte quantities? To do this, a number of other routines are used. For example, this routine will do the equivalent of a two-byte pointer poke. Suppose for instance you wanted to store the bytes for the address $9600 at locations $1000, 1001. Normally in Applesoft you would do it like this:

50 POKE 4096,0: POKE 4097,150

Where 4096 and 4097 are the decimal equivalents of $1000 and $1001 and 0 and 150 are the low-order and high-order bytes for the address $9600 ($96 = 150, $00 = 0).

A more convenient approach might be like this:

50 CALL 768, 4096, 38400

or perhaps:

50 CALL 768, A, V

The routine for this would be:

1 **************************
2 * POINTER SET UP ROUTINE *
3 **************************
4 *
5 *
6 OBJ $300
7 ORG $300
8 *
9 CHKCOM EQU $DEBE
10 FRMNUM EQU $DD67
11 GETADR EQU $E752
12 LINNUM EQU $50 ; ($50,51)
13 *
14 PTR EQU $3C
15 *
16 ENTRY JSR CHKCOM
17 JSR FRMNUM; EVAL FORMULA
18 JSR GETADR ; PUT FAC INTO LINNUM
19 LDA LINNUM
20 STA PTR
21 LDA LINNUM+1
22 STA PTRH-1
23 *
24 JSR CHKCOM
25 JSR FRMNUM
26 JSR GETADR
27 *
28 LDY #$00
29 LDA LINNUM
30 STA (PTR),Y
31 INY
32 LDA LINNUM+1
33 STA (PTR),Y
34 *
35 DONE RTS

which will list from the Monitor as:

*300L

0300- 20 BE DE JSR $DEBE
0303- 20 67 DD JSR $DD67
0306- 20 52 E7 JSR $E752
0309- A5 50 LDA $50
030B- 85 3C STA $3C
030D- A5 51 LDA $51
030F- 85 3D STA $3D
0311- 20 BE DE JSR $DEBE
0314- 20 67 DD JSR $DD67
0317- 20 52 E7 JSR $E752
031 A- AO 00 LDY #$00
031C- A5 50 LDA $50
031E- 91 3C STA ($3C),Y
0320- C8 INY
0321- A5 51 LDA $51
0323- 91 3C STA ($3C),Y
0325- 60 RTS

The special items in this routine include CHKCOM, a syntax-checking routine that serves two purposes. First it verifies that a command follows the call address, and secondly it advances TXTPTR to point to the first byte of the expression immediately following the comma. If a comma is not found, a syntax error is generated.

FRMNUM is a routine that evaluates any expression and puts the real floating-point number result into Applesoft’s floating-point accumulator, usually called FAC. This is a six-byte pseudo register ($97-9C) used to hold the floating-point representation of a number. It includes such nifties as the exponential magnitude of the number and the equivalent of the digits of the logarithm of the number stored.

At this stage you’d have to be something of a masochist to want to deal with the number in its current form, so the next step is used to convert it into a two-byte integer.

GETADR does this by putting the two-byte result into LINNUM, LINNUM+1 ($50,51).

Even if this is not exactly an in-depth explanation of all the most precise details of the operation, the bottom line is that the three JSRs (CHKCOM, FRMNUM, and GETADR) will always end up with the low-order and high-order bytes of whatever expression follows a comma in LINNUM and LINNUM+1.

These simple subroutines should be quite adequate for many applications. Next month, however, we’ll look at string passing, some of the various other routines available, and how to pass data back to the calling Applesoft program.

The Softalk Apple Project - Roger Wagner

Assembly Lines: The Complete Book

Assembly Lines by Roger Wagner - Part 16

Everyone's Machine Language Guide, Part 16