Machine Code in SmartBASIC
by Mel Ostler


EDITOR'S NOTE: This is the first of a planned series of articles by Mel Ostler which were to appear in the Sprite Chaser newsletter, which is no longer published. We will do our best to continue this series by Mel, but if we can't for some reason, we would recommend the purchase of Mel's books: From Basics to Basic and his Hacker's Helper series: Learning to Read with ADAM Vol. I, Learning to Write with ADAM Vol. II and Learning to Draw with ADAM Vol. III.

I have been asked to do a series of articles for the newsletter concerning the art of entering machine language programs and CALLing them from SmartBASIC, and using them in turn to CALL EOS subroutines for the convenience of the user.

I agree that this is a very handy thing for even the beginning programmer to be able to do, for one is not long at the task of programming in Basic before he realizes that there are some things which he wants to do which one of the EOS subroutines have already been designed to do, if he just knew how to get them to work for him.

As an example of this; I was writing a program several years ago on my ADAM to take the daily transactions of a small businessman, (and I mean small, not what the "Small Business Administration" calls small, and to take the input directly from check registers, invoices, receipts, bills, etc. and to save them in a coded file. This program could easily be used daily by the businessman to file all of the information from business activity for the day.

Then other programs would be run against this ledger information to tell the owner at any point in time where he stood relative to debits or assets, individually or totally, net worth at any point in time, the financial status at any point in time for a job underway by a contractor, or any one of a myriad of other kinds of information that might help that businessman sleep better at night.

In the process of writing the program I found that the system by which ADAM 's Basic stores information on disks, (required for rapid access), was very wasteful. Looking through the programs of the EOS, I found that it was capable of storing the information about anyway that I wanted, if I selected the correct subroutine or combinations thereof.

In the process of doing my own CALLing I could get one disk to accept about 100 times as much of the limited amount of information that the small, small businessman would enter daily.

There are also many ways to make ones own utility programs, and speed up regular programs if one can access the EOS directly.

And perhaps the most intriguing of the things that can be done, is that one may access the video screen and sound generator, to give special, unique effects to his programs.

And finally, one of the best reasons that one might want to learn more about the accessing of the routines of the EOS, and the setup and operation of the video chip and sound generator; is that although these things are constantly being improved, more advanced models of these programs and hardware items generally rely upon models presently being used, and are therefore, more often than not an advancement of present things, as opposed to brand new, radically different systems or devices. Thus by the learning of the things available to one in the ADAM, (a very straight forward and well planned system), one prepares himself adequately for his future programming efforts if and when he moves on to other computer systems. It seems to be a kind of win / win situation, as most types of leaning tend to be. But first we need to lay a bit of groundwork so that as many readers as possible can be included in the understanding of these articles.

For some the things said here may be "old hat", but please bear with the discussion in-as-much as there may eventually be something which may be of benefit to all.

Similarly there may be some who would feel that they don't quite understand some thing or another, or perhaps several things. If this happens, please write to the editor, or directly to me, and we'll / I'll answer either in the next article, or by personal correspondence. I want all who wish to understand, to be able to understand and to be eager to share what they discover also. So correspondence is definitely invited.

Let me say at the outset, that those who have finished the first part of the "HACKERS HELPER" books, "PART I, A BEGINNER TEXT FOR NEW HACKERS", and have done fairly well at understanding it, should have little difficulty in following what we will discuss in these articles.

If the reader has read and been able to follow Volume I of the "HACKERS HELPER, FROM BASICS TO BASIC, LEARNING TO READ/ WRITE / DRAW WITH ADAM", he will certainly not have any difficulty, and may in fact be as qualified as I to write this series of articles. However, there are many who have learned the fundamentals which we will be discussing from other sources, and the above mentioned publications are in no way prerequisites to the reader. While on this subject though, when we need to discuss something which is readily found in print, whether in the above mentioned publications or in some other publication, I will not attempt to repeat in the articles what can be found other places. I guess that what I am trying to say is that programmers ought to build a library of reference books with time, and learn what can be found and how to find it in each one of his books.

And so let us begin with some definitions. We will define terms from time to time as we go along in the articles, and today we have already used the letters EOS with the assumption that all readers would certainly know what it means.

EOS (Extended Operating System), is the operating system originally designed for the ADAM computer. It is stored in a ROM, (Read Only Memory), chip within ADAM itself, and loads into the upper part of the standard 64K RAM (Random Access Memory).

OPERATING SYSTEM, is a group of subroutines, not necessarily interdependent, though some are, which do some of the chores which the designers of a computer know will have to be done by the computer's microprocessor. For example, generally speaking, a computer must have a keyboard type of input for the user to be able to communicate with it. Therefore, an Operating System could logically be expected to contain routines to transfer information from the keyboard to the RAM.

Similarly a computer must logically have at least one type of output device through which it can respond to the user, such as a printer, and / or video monitor or TV. The Operating System can be expected to contain programs to operate such output devices, etc. (note that the words Subroutine, Routine, and Program are constantly interchanged, and the reader should not try to attach too much importance to this. It is impossible to decide how long a subroutine should be to qualify as a routine. And it is equally impossible to define a limit to the length or complexity of a routine, so that anything larger or more complex than that can be defined as a program).

BASIC as used in the articles will refer to the "SmartBASIC" program which was delivered with the purchase of the new ADAM. "SmartBASIC" is the registered trademark name of the version of the Basic Language Programming program developed for Coleco by Lazar MicroSystems Incorporated. It is almost identical to all other versions of Basic written near the same time as it was written for Coleco, but fits the machine language of the ADAM microprocessor, (the Z80), and is configured to be stored initially from RAM address $0100 to $6130f, from whence It expands itself as it does additional self set-up, and later expands again when it receives particular instructions. The elements of the Basic program remain stored at the initial RAM locations, with only limited exceptions.

And now to begin our discussion, let us try to understand a little about the Basic which we are going to be using. We went through the process of loading (reading), Basic into memory in the "LEARNING TO READ WITH ADAM" Volume I of the "HACKERS HELPER". Let us get to know a bit about Basic by starting at the point where we left off there. Basic is loaded from the media (the disk or tape which we used); and then the last instruction of the "boot" routine which caused the "loading" to take place, set the PC register of the Z80 microprocessor to the value $0100, or 256d.

51261:$C83D E9  JP (HL)

where HL had just been loaded with the value of $0100

This means that the microprocessor will take it's next instruction from that address in RAM. Since this is the lowest address at which Basic was loaded, the Z80 begins to get subsequent instructions from the loaded Basic program.

00256:$0100 C3 9D 3E CALL $3E9D

The first instruction is the 3 address CALL instruction to $3E9D (16029), three addresses less than the beginning of the "central loop" as it is referred to in Hinkle's "HACKER'S GUIDE VOLUME II". The instruction encountered at these addresses is another CALL to $4061, which is an address within the region of Basic later to be used as the "Input Buffer".

16481:$4061 D9   EXX
16482:$4062 06 00  LD 13,00
16484:$4064 D9   EX X

This is the set-up routine, and it continues through subsequent addresses, through the regions of RAM later to be used for the "Length Of The Crunch Code Buffer", and ends in the mid part of the region later to be used as the "Crunch Code Buffer".

I included the disassembly of the regions being discussed, as they are discussed, but the reader would do well to get the disassembly of basic complete, both as it sits in his RAM as he uses it; and a disassembly of Basic as it is on the media. There are some important differences as the paragraph above indicates. A dump of the two forms of Basic is also handy, although I will indicate for those not interested in obtaining such, the values found wherever the discussion requires 't. These things really should be part of his reference library. Upon arriving at $4061, the alternate B register is loaded with a $00, and saved aside as alternate We will see the reason for this at a later time, so make a mental note of it. This takes us through address $4064.

16481:$4061 D9    EXX
16482:$4062 06 00  LD B,$00
16484:$4064 D9    EXX

Instructions $4065 through $4068 change the jump instruction at $0100, by which we arrived at this point, to a jump instruction in the Central Loop.

18485:$4085 21 A3 3E  LD HL,$3EA3
18488:$4088 22 01 01   LD ($0101),HL

This is logical enough since there will never again be a need to go through the set-up routine again, and in fact, this routine will soon be destroyed by input from the keyboard by the user when control is finally given to him. Instructions $4088 through $408F we two set-up instructions for a DJNZ loop, (ending at $408C), which we shall analyze in the next article.

16491:$406B 061 F        LD B,$1 F
16493:$406D 11 75 3F   LD DE,$3F75

To conclude this article, I want that the reader should note that the CALL instruction changes the PC register of the Z80 to the address of the instruction being CALLed. This is exactly what is done when a CALL is issued directly from Basic. The Basic program does some subroutine gymnastics which we will discuss later, but finally issues a machine language CALL for the Z80 to the address which we specify in the Basic CALL instruction.

For example, if I write in the immediate mode:

CALL 0 (this is the first address in RAM)

in the program, Basic will hesitate one split second, and return control to me. That is because the instruction I gave for Basic to go through it's series of internal instructions and ultimately set the Z80 PC register to $0000 causes it to do just that. But when the Z80 reads the instruction at $0000, it sees a RETurn instruction, which returns the Z80 to the Basic instruction set. Basic then interprets this action as the end of the routine, (or subroutine, whichever you wish), that I CALLed (Why the RETurn instruction is located at this location is obvious enough, but is not within the scope of discussion).

And so the Basic program CALLed the instruction as I requested. If on the other hand I CALLed the address:

CALL 64743

in the program, Basic would again turn the CALL over to the Z80 microprocessor. The Z80 would go to the routine in the EOS, and would read the instructions which put the SmartWRITER program into effect, from which there is no return to Basic. If you try this one you will have to reset the computer to get back to Basic.

And so you see that one may CALL any address in RAM from Basic that he wishes, but he must live with the consequences. The computer will do what you tell it to do, and if not careful, you will be required to reset to get back to Basic.

Some interesting CALLS that one may use directly are:

CALL 63538 which will cause the computer to go through the computer reset process without pulling the computer reset switch. If your Basic media is still in the drive, it will reload the Basic program as if you had manually pulled the reset switch.

CALL 64655 which will cause the system to recognize a disk drive that wasn't turned on when Basic was loaded, but was later switched on.

These are most of the CALLS to EOS that can be used without prior Z80 register set-up. Many of the others, and the way to set them up and use them, will be discussed in later articles.

We have made these CALLS in the immediate mode, but CALLS will be made more commonly within a Basic program. These are examples with which you may use to test the CALL command from Basic, which we will be using considerably in the articles.

Back to Top