What is USR?

Len Golding explains ...


Issue 11

Sep/Oct 84

Next Article >>

<< Prev Article



USR is probably the least well-documented function in ATARI BASIC, yet it is potentially one of the most powerful. This introduction is in three parts. First we look at what USR is and the syntax it uses. This is for BASIC programmers who have come across it in program listings and just want a feel for what it does. The second part looks at the way USR works and outlines the general principles of inserting machine-code subroutines into BASIC. If you are not into machine-code and don't intend to start writing your own routines, you can comfortably skip this bit. Finally, we look at some examples you can experiment with, including a routine for copying the ROM character set into RAM at lightning speed.

Let's start with the simplest form a USR statement can take. This looks something like X=USR(1536). In English, this means 'Stop executing BASIC for a moment, go execute the machine-code routines which start at address 1536 and put the resulting number into variable X'. In the majority of cases you won't give two hoots what the value of X turns out to be, what is important is the execution of the subroutine along the way. If it is designed to move a player about on the screen, your only concern is whether the movement works. If it is a scrolling routine, then it is the actual scrolling that counts. Any hypothetical number generated at the end of the routine would probably have little relevance to the real world anyway and you would hardly ever use it for anything. So why bother assigning a variable to it?

The answer is that USR is not a command like GOSUB or POKE. It is a function, like PEEK or INT, so we can't simply type USR(1536), we have to give it a command to work with. Theoretically, we could use any command that works with a number. TRAP or RESTORE would do, provided we knew that the number would never exceed 32767 (the maximum allowed with these commands). PRINT would also work but would mess up your screen display. The most convenient command is LET using the format 'LET X=' or, more simply 'X=', since this does not place restrictions on the number following it and has no discernable effect on program execution.

You are not stuck with X as a variable name of course. Some programmers prefer statements like MOVE=USR(1536) or SCROLL=USR(1536) to give a clue about the subroutine's purpose. Similarly, the number in brackets need not be 1536 although that is a common one since it is the first location of an area (page 6) specially reserved for things like machine-code subroutines. It need not even be a 'raw' number. Variable names or expressions (like Z*3+5) are equally acceptable, provided they evaluate to the correct starting address. The thing to remember is that, however many numbers appear in the brackets, the first one is always the place where the machine-code routine starts.

Now a machine-code program is simply a long list of numbers, each representing either a command or an item of data, depending on its position. You can, if you like, see what the routine looks like by finding the place in your BASIC listing where the numbers are put into memory, starting at the address given in the USR statement. There are numerous ways of getting a list of numbers into RAM. Very large routines might be loaded from cassette or disk directly into the chosen memory area, using something known as a 'direct CIO call', but it is unlikely you will encounter this method in public domain BASIC programs. A very common technique is to POKE the numbers one at a time into RAM, using READ and DATA statements. A third approach is to DIMension a string to the length of the machine code routine, then store the list of numbers in that string as ATASCII symbols. In such cases, the USR statement will take the form of X=USR(ADR(A$)) and you will find A$ written out somewhere in the listing, looking like a meaningless jumble of characters and symbols. This method saves both space and time, since it eliminates the need for a machine-code loading program, but it is extremely vulnerable to typing errors and a single mistake can crash the system. One final, and little used, approach is to put very short machine code routines into the USR statement itself, either as extra numbers or ATASCII symbols. De Re Atari gives the example X=USR(ADR("hhh/*/LV/d"),16) but I have never seen it used anywhere else and most subroutines will be too long to encode in this fashion. My personal preference is for the POKE, READ and DATA technique. This is much kinder for anyone who has to copy the program from a listing and makes debugging a lot easier.

Let's now look at the other numbers you might find in a USR statement's brackets. How about X=USR(1536, 100, 20, 3000, PLR1, MEMTOP-10)? These extra numbers are known as 'parameters' to make the point that they are not addresses. They are just ordinary numbers which will be used somewhere in the machine-code routine called by that USR statement. A parameter can be a real number, a variable name or an expression, the only restriction is that it must evaluate to a number between 0 and 65536. It might indicate which joystick the routine should read, or which player to move, or which colour register to use, or where in memory to find some data, or where to store a result - almost anything in fact. It is even possible, by using variable names, to pass the result of an earlier calculation carried out in BASIC, like how much memory there is left at any given time, or where to put an explosion on the screen. A USR statement can contain up to 255 parameters, but you are not likely to encounter more than half a dozen or so.

Discovering what the parameters mean in any given instance is a thankless task unless the programmer has deliberately made it easy for you. Sometimes he or she will have used variable names whose function can be identified from a close inspection of the BASIC listing. Alternatively, there may be a REM statement close by explaining all. If neither of these applies, there is normally no easy way of discovering what the parameters mean, or how the machine code routine uses them. Just type them in and trust the programmer!

Now on to the second part, how USR works. I'll assume that if you are reading this section you know about converting decimal numbers to 2 byte integers and how a LIFO stack operates. If not skip the next couple of paragraphs. Better still, get hold of a decent book on machine code and find out!

When a USR call is made, the following things happen:

a) The processor notes where it is in the BASIC program, and pushes this location onto the stack for later use as a return address.

b) Any parameters passed are converted into 2 byte integers and pushed onto the stack, low byte first.

c) A one-byte value containing the number of parameters passed (even if it is 0) is pushed onto the stack.

d) the machine code routine is executed.

e) On encountering the final RTS instruction, the top two bytes are pulled off the stack and used as the return address. All being well, this transfers control back to BASIC, at the next statement after the USR call.

Note that I say 'all being well'. A number of things can go wrong if we're not careful. First of all, there is that byte mentioned at c), sitting on top of the stack ready to foul things up. Unless we get rid of it, the processor will think it is part of the return address and, when the final RTS is encountered, will bounce off into the lower reaches of operating system RAM instead of returning to BASIC. Consequently it is a good idea to do a PLA right at the start of your routine to be sure you don't forget it. For exactly the same reason, all parameters have to be pulled off the stack before the final RTS. They can be left there until you need them in your routine of course, but newcomers to machine-code programming may find it safer to retrieve them at the start of the routine. They can always be stored in a less critical location until you need them.

Remember that all parameters are converted into 2 byte integers, even if their value could be contained in a single byte, so to retrieve a one byte parameter, you have to do two PLAs and discard the high byte. Also, don't forget that parameters come back off the stack with their high byte first. This can be a bit confusing if you are used to the conventional 'low/high' order of storing 2 byte numbers. Lastly, do make sure that your routine ends with an RTS. I know this sounds obvious, but it is easy to forget, especially if the routine uses a lot of JSRs (e.g. accessing ROM routines).

On now to the third section, where we get down to some practical examples. Here is the simplest machine code routine I can think of

PLA     ;Get rid of the number of parameters byte

LDA 20

STA 710 ;Store 20 in the address controlling screen colour

RTS     ;Return to BASIC

In decimal form, this routine translates to 104,169,20,141,198,2,96. Before we can do a USR call though, these numbers have to be put into some safe area of memory. Let's use address 1536 onwards. Here is my favourite way of loading machine code subroutines into RAM, though it is not necessarily the best.

10 X=0:RESTORE 40

20 READ D:IF D=-1 THEN 100

30 POKE 1536+X,D:X=X+1:GOTO 20

40 DATA 104,169,20,141,198,2,96,-1

100 X=USR(1536)

As with any machine-code routine, SAVE it before you RUN it, since the slightest error in the DATA line could lock up your system. When you RUN it, you should find that the screen turns orange. Okay, it's a trivial example, you could have achieved the same effect by POKE 710,20, but at least it's a start. Notice the 96 at the end of the routine. This is the RTS instruction which we need to get back into BASIC.

How about an example with a parameter? This slightly modified routine allows you to specify the screen colour within the USR statement.

PLA      ;Discard the number of parameters byte

PLA ;Discard the parameters
high byte

PLA      ;Get the parameters low byte

STA 710  ;Store it in the colour register

RTS      ;Return to BASIC

Subroutine writers note: even though this particular parameter can only be a one-byte number (you can't put more than 255 into a colour register), the USR call will still push two bytes onto the stack, so we have to pull the high byte off and throw it away. To load this more flexible subroutine, change lines 40 and 100 of the BASIC loader program above to read:

40 DATA 104,104,104,141,198,2,96,-1 

100 X=USR(1536,90)

This time the screen should turn red, but you can choose whatever colour you like, simply by altering the 50 in the brackets.

Finally (and at long last) something useful. Anyone who has used redefined character sets in their programs knows that, before any redefinition can be done, the character set has to be copied from ROM into RAM. This takes about 10 to 15 seconds in BASIC, depending on the method used. The following machine-code routine does it in the blink of an eye! Alter the BASIC loader program as follows

40 DATA 104,104,133,204,104,133,203,169,224

50 DATA 133,206,160,0,132,205,162,4

60 DATA 177,205,145,203,136,208,249,230

70 DATA 204,230,206,202,208,242,96,-1 

100 X=USR(1536,10240)

The parameter 10240 is, in this case, the address where the copied character set will start. It need not be 10240 of course, you might prefer to calculate where the top of your useable memory is and put the new character set up there, remembering to leave enough space for the screen memory and display list and 1024 bytes for the characters. Try changing line 100 to read

100 START=256*(PEEK(106)-20):X=USR(1536,START)

When you run it for the first time, the routine does not look particularly fast. This is because of the time taken to load the numbers into memory, but, once there, the routine can be called as many times as you like and will execute very quickly indeed. To see it at full speed, RUN it once then type GOTO 100. The real benefits arrive, of course, when you use the routine more than once. You can copy the character set three or four times over (to different locations of course) in a couple of seconds. This is useful if you want several incarnations of your redefined characters to get animation effects of the kinds used in Space Invaders. That subject, however, deserves another article all of its own.

In conclusion, let's look at some of the reasons for going to all this bother. There are two main ones. Firstly machine-code can do some things BASIC can't manage at all, and secondly, it executes up to 200 times faster. On the other hand, machine-code takes longer to write, is far more exacting and makes complicated tasks out of some things BASIC finds easy. The USR function gives us the best of both worlds. We can use BASIC to do all the things which would be very tedious in machine-code, like complex arithmetic, or setting up screen displays, or using peripherals and employ machine-code for tasks which need to be executed at high speed like moving player/ missiles vertically, or reading light pens, or fine scrolling.

All in all, it's well worth making friends with USR.