Previous | Contents | Next

The Arithmetic Subroutines

ARITHMETIC SUBROUTINES

This chapter is divided into two sections - one for the OLD, and one for the NEW ROM. We'll tackle the OLD ROM first because it's easier.

[OLD ROM ARITHMETIC]

Numbers are represented in two bytes, and as such it is possible to store them in register pairs BC, DE, and HL. First of all we shall take a look at the five major arithmetic routines.

1) Addition. The address to call is 0D3E, or more intelligibly, CALL ADD. The subroutine adds together the number stored in DE and the number stored in HL. The result is then placed in HL. This may be demonstrated by the following program:

113900    ADDDEMO   LD DE,0039
211100              LD HL,0011
CD3E0D              CALL ADD
C9                  RET

Here DE is loaded with the number fifty-seven, and HL with seventeen. On return to BASIC the result stored in HL should be fifty-seven plus seventeen, so the command PRINT USR(adddemo) should generate the number seventy-four.

2) Subtraction. Just the same - DE is subtracted from HL and the result stored in HL. The address is 0D39. Thus to prove it:

113900    SUBDEMO   LD DE,0039
211100              LD HL,0011
CD390D              CALL SUB
C9                  RET

3) Multiplication. Up until now we have ignored multiplication completely, since there is no simple instruction which will multiply two numbers together. However, thanks to Uncle C, the ROM will do it for us. Simply CALL MULT, which is stored at address 0D44, and as if by magic DE will be multiplied by HL, the result as usual being stored in HL. Watch out for what happens to BC and DE though! They're not unaltered.

4) Division. As you'd by now expect, the instruction CALL DIV will divide HL by DE (ignoring any remainder of course, since we are dealing in integers). The address of DIV is 0D90.

5) Powers. Is raising one number to the power of another going to be any more difficult? No of course not. With elegant simplicity the instruction CALL POWER (at 0D0C [0D70]) will do just that, raising HL to the power of DE, and putting the answer away in HL, using repeated multiplication to compute the answer.

One very important function is the RANDOM NUMBER GENERATOR. This is held at location 0BED. To generate a random number between one and six (say to simulate the roll of a die), simply load HL with six and CALL RND. This is of course the same thing as RND(6). The number in the brackets should be placed in HL, and the final answer will end up in HL.

See if you can work out what this program does. What we're interested in is the number that it returns to BASIC.

211400    START     LD HL,0014
CDED0B              CALL RND
110A00              LD DE,000A
CD440D              CALL MULT
116400              LD DE,0064
19                  ADD HL,DE
C9                  RET

Let's see if you got it right. HL is loaded with 14 and RND is called, so HL is replaced by a new value, RND(20) (note that 14 (hex) is 20 (dec)). 0A is stored in DE, and the two are then multiplied together. We then have 10*RND(20). Finally 64 (hex) is added, giving 10*RND(20)+100.

We could use this routine in a games program. Suppose we needed to jump to a random destination. We could use the by now famous Tim Hartnell method of GOTO 10*RND(20)+100. Alternatively, if the above machine code were in a REM statement, say at address 16427, we could instead simply say GOTO USR(16427). This would do exactly the same job, except a little bit faster.

We'll leave the OLD ROM now, and turn to the rather more complex field of arithmetic on the NEW ROM.

NEW ROM ARITHMETIC

The first and most important point to note is that NEW ROM numbers are stored as five bytes, not two, and so they can't fit into a register-pair as they stand. Nor are the numbers in simple form, for while it is true that zero is, as you'd expect, 00 00 00 00 00, it is not true that one is 00 00 00 00 01! In fact one is represented by 81 00 00 00 00. Here is a list of the Sinclair representaion of the first few integers.

Decimal   Sinclair Form
0         00 00 00 00 00
1         81 00 00 00 00
2         82 00 00 00 00
3         82 40 00 00 00
4         83 00 00 00 00
5         83 20 00 00 00
6         83 40 00 00 00
7         83 60 00 00 00
8         84 00 00 00 00
9         84 10 00 00 00
10        84 20 00 00 00
    ...

and so on. There is a kind of pattern, but it's not instantly recognisable. Take a look at the negative numbers:

Decimal   Sinclair Form
-1        81 80 00 00 00
-2        82 80 00 00 00
-3        82 C0 00 00 00
-4        83 80 00 00 00
-5        83 A0 00 00 00
-6        83 C0 00 00 00
-7        83 E0 00 00 00
-8        84 80 00 00 00
-9        84 90 00 00 00
-10       84 A0 00 00 00

As you can see, you can instantly change a number from positive to negative just by adding 80 to the second byte. This doesn't apply to zero by the way - zero is represented uniquely to help speed the ROM up a little.

Knowing how the Sinclair Form is built up will slightly help your understanding of the ROM, so I will give here a brief explanation of how to turn decimal numbers into Sinclair numbers. It only takes a few simple steps.

STEP ONE: If the number is zero, then its Sinclair representation is 00 00 00 00 00.

STEP TWO: Ignoring the sign of the number, write it in binary (but without any leading zeroes). For example:

  7        111
-10       1010
 -4.25     100.01
  0.325      0.011
  0.375      0.011

Notice that the binary form has a BINARY point, not a DECIMAL point! 100.01 means one 4 plus no 2's plus no 1's (here we reach the binary point) plus no halves plus one quarter. The next column would have been an eighth.

STEP THREE is to work out a quantity called the EXPONENT. This is done as follows:

  • If the part of the number to the left of the binary point is not zero then the exponent is the number of digits to the left of the point.
  • If the part of the number to the left of the point is zero and the first digit after the point is one then the exponent is zero.
  • If the part of the number to the left of the point is zero and the first digit after the point is zero, then count the number of zeroes between the point and the first 1 - the exponent is minus this number.

The first byte of the Sinclair representation is 80 plus this exponent.

Decimal   Binary    Exponent  Sinclair Form
  7        111      3         83
-10       1010      4         84
 -4.25     100.01   3         83
  0.325      0.011 -1         7F
  0.375      0.011 -1         7F

STEP FOUR: Now we can ignore the binary point altogether - that is what the exponent is for - to tell the computer where the point is supposed to go. So ignoring the point, write the binary form starting with the first 1 and then add sufficient zeroes to the right to make the whole thing thirty-two binary (bits) in length.

  7       1110 0000 0000 0000 0000 0000 0000 0000
-10       1010 0000 0000 0000 0000 0000 0000 0000
 -4.25    1000 1000 0000 0000 0000 0000 0000 0000
  0.325   1100 0000 0000 0000 0000 0000 0000 0000
  0.375   1100 0000 0000 0000 0000 0000 0000 0000

STEP FIVE: It is here that we remember the sign of the original number. If the original number was negative then do nothing. If the original number was positive then replace the first one by a zero. Thus:

  7       0110 0000 0000 0000 0000 0000 0000 0000
-10       1010 0000 0000 0000 0000 0000 0000 0000
 -4.25    1000 1000 0000 0000 0000 0000 0000 0000
  0.325   0100 0000 0000 0000 0000 0000 0000 0000
  0.375   0100 0000 0000 0000 0000 0000 0000 0000

STEP SIX - Now just change these numbers straight into hex, like so, making sure you remember to put the exponent byte at the start:

  7       83 60 00 00 00
-10       84 A0 00 00 00
 -4.25    83 88 00 00 00
  0.325   7F 40 00 00 00
  0.375   7F 40 00 00 00

This is the form in which the ROM will be working. The largest exponent you may have is FF, so the largest positive number that can be stored is FF 7F FF FF FF. This turns out to be 1.7014118E38 (if you can't understand the "E" notation the E means "with the decimal point shifted (in the above case) 38 places to the right"[)]. In other words the number 170,141,180,000,000,000,000,000,000,000,000,000,000 which is a pretty vast quantity. It can still only store ten decimal places accurately though. The smallest positive number you can have (apart from zero) is 01 00 00 00 00, which happens to represent 2.9387359E-39. To you and me that's 0.000,000,000,000,000,000,000,000,000,000,000,000,002,938,735,9 which I'd say was pretty microscopic.

You can check all of this with the following BASIC program.

10 LET A=0
20 LET B=PEEK 16400+256*PEEK 16401
30 FOR I=1 TO 5
40 INPUT A$
50 POKE B+I,16*CODE A$+CODE A$(2)-476
60 NEXT I
70 PRINT A

[Download available for 16K ZX81 -> chapter17-floatchk. I have heavily modified this downloadable version so that not only can you enter Sinclair Form numbers in one go, you can also convert from decimal to Sinclair Form too.]

The program sets up a variable A, and then overwrites its previous contents by POKEing into the variables area, one byte at a time (that's a letter I in line 50, not a number 1). If you run it and enter "82"/"40"/"00"/"00"/"00" (where / means newline) you'll find the number three printed. And so on.

An interesting little quirk is that if you input "00"/"80"/"00"/"00"/"00" (in theory this is minus-zero) the machine actually prints -C.6E-56 ! The letter C in mid-number, and an exponent of -56! Don't panic! This doesn't really happen in the ROM. We made it happen by POKEing something that doesn't make sense. The ROM does behave slightly more sensibly than human beings.

HOW TO USE FLOATING POINT NUMBERS PROPERLY

Having seen that a five byte number is too big to store in the registers, the next question is undoubtedly "Well where does it store them then?". Answer - it stores them in an area of RAM called the CALCULATOR STACK, which works very much like the ordinary stack except for two points: 1) It can store both floating point numbers and strings, and 2) it is the right way up, not upside down like the machine stack.

To push a number stored in the BC register onto the calculator stack all you need to do is call up a subroutine in the ROM. CALL STACKBC, as I've called it, will change BC into five byte form as described above and then push this number onto the top of the calculator stack. You can do the same for a number stored in A (i.e. a number between 0 and 255) by calling STACKA. The addresses to call are: 1519 151D (STACKA) and 151C 1520 (STACKBC).

CD1915              CALL STACKA
CD1D15              CALL STACKA       
CD1C15              CALL STACKBC
CD2015              CALL STACKBC       

Incidentally the first two instructions in the STACKA routine are LD C,A and LD B,00. It then leaps straight into STACKBC!

Conversely, to retrieve a number from the calculator stack we can CALL UNSTACK (address 0EA7), which removes a number from the calculator stack and stores it in the BC register.

[Thunor: 0EA7 is the 'FIND INTEGER' (->) subroutine which does actually call the 'FLOATING-POINT TO BC' (->) subroutine at 158A but it also quits to BASIC with an error code if there's a problem. Now this behaviour is not what you'd normally expect in machine code programs as they should be in control of these situations, and so I think that CALL UNSTACK should really be calling 158A directly and in fact it works because I've tried it in the 6 * 7 multiplication test below. I suggest that when you see CALL UNSTACK at 0EA7 you should bare in mind that calling 'FLOATING-POINT TO BC' at 158A might be a better idea.]

Arithmetic is quite straightforward. The addresses are:

ADD       1754      addition
ADD       1755      addition
SUB       174B      subtraction
SUB       174C      subtraction
MULT      17C5      multiplication
MULT      17C6      multiplication
DIV       1881      division
DIV       1882      division

They work like this: The five-byte number stored at an address specified by HL (this means the number is stored in locations (HL), (HL)+1, (HL)+2, (HL)+3, and (HL)+4) is added to, multiplied by, divided by, or has a second number subtracted from it. The second number is stored at an address specified by DE. After the calculation the result is stored in the five bytes beginning at address HL.

To multiply together the two numbers at the top of the calculator stack one method would be as follows:

2A1C40              LD HL,(STKEND)
11FBFF              LD DE,FFFB
19                  ADD HL,DE
E5                  PUSH HL
221C40              LD (STKEND),HL
19                  ADD HL,DE
D1                  POP DE
CDC517              CALL MULT
CDC617              CALL MULT

Can you follow exactly what is going on? HL is loaded with the contents of the system variable STKEND - which gives the address of the first byte after the end of the calculator stack. DE is loaded with minus five, thus HL is decreased by five. This new value is loaded back into STKEND because we start off with two items on the stack and want to end up with only one. This is the address of one of the numbers to be multiplied. If you follow the listing through carefully you'll see that DE ends up with this value. First though HL is decreased by five again, to find the start of the other number to be multiplied.

To check that it really does work, run this program.

3E06      START     LD A,06
CD1915              CALL STACKA
CD1D15              CALL STACKA
3E07                LD A,07
CD1915              CALL STACKA
CD1D15              CALL STACKA
2A1C40              LD HL,(STKEND)
11FBFF              LD DE,FFFB
19                  ADD HL,DE
E5                  PUSH HL
221C40              LD (STKEND),HL
19                  ADD HL,DE
D1                  POP DE
CDC517              CALL MULT
CDC617              CALL MULT
CDA70E              CALL UNSTACK
C9                  RET

Run it by typing PRINT USR start. What do you get?

But surely there must be easier ways to multiply six by seven. After all, the above program does look very complicated, and not something you'd easily remember. Well it's here that we really do start making full use of the ROM. The following program does exactly the same job, and I shall shortly explain why:

3E06      START     LD A,06
CD1915              CALL STACKA
CD1D15              CALL STACKA
3E07                LD A,07
CD1915              CALL STACKA
CD1D15              CALL STACKA
EF                  RST 28
04                  DEFB 04
34                  DEFB 34
CDA70E              CALL UNSTACK
C9                  RET

In the NEW ROM, RST 28 means "perform floating point arithmetic". The data that follows tells it precisely what calculations it's supposed to do. The byte 04 means multiply - all of the shuffling around of the calculator stack is done automatically. The byte 34 is used after a RST 28 instruction to indicate that there is no more data to come, and the next machine code instruction should follow.

The RST 28 data codes are:

ADD    0F
SUB    03
MULT   04
DIV    05

Don't forget you'll need a byte 34 as well though, to end the data.

You may be wondering what happens if the number on the top of the calculator stack is not an integer between 0 and 65535 (the maximum value any two byte register can hold). Well my first answer would be "try it for yourself and find out". Write a program that adds 8001 to 8001. Write a program that divides eight by three, then a program that divides seven by three. Write a program that subtracts five from zero, and another that subtracts a thousand from zero. But for those of you who are impatient I'll tell you anyway.

If the number at the top of the calculator stack is greater than 65535 then attempting to "unstack" it into BC will result in the program returning to command mode in fact - stopping with error code B (which means out of range).

If the number is a decimal then it will be rounded up or down (not just INTed) to the nearesr whole number. If the decimal part is less than 0.5 it will be rounded down, and if the decimal part is greater than or equal to 0.5 it will be rounded up.

If the number is negative then error B will result, causing an immediate return to BASIC and stopping the program, if there is one.

RST 28 allows you to do much, much more than just simple arithmetic. All of the functions of the ZX81 are available to you. The data code for any particular function is just the character code of that function minus AB. For instance, the character code of SIN is C7. C7 minus AB is 1C (if you don't believe me we'll do it in decimal - 199 minus 171 is 28). This means we can find the SIN of the number at the top of the calculator stack using the sequence:

EF                  RST 28
1C                  DEFB 1C (SIN)
34                  DEFB 34 (Exit)

To multiply two numbers (at the top of the calculator stack) together and then find the square root of the result we can use the sequence:

EF                  RST 28
04                  DEFB 04 (MULT)
25                  DEFB 25 (SQR)
34                  DEFB 34 (Exit)

If you're not absolutely convinced yet, run this program, which multiplies five by twenty, and then takes the square root.

3E05                LD A,05
CD1915              CALL STACKA
CD1D15              CALL STACKA
3E14                LD A,14
CD1915              CALL STACKA
CD1D15              CALL STACKA
EF                  RST 28
04                  DEFB 04 (MULT)
25                  DEFB 25 (SQR)
34                  DEFB 34 (Exit)
CDA70E              CALL UNSTACK
C9                  RET

You'll notice that this is the first time we've used more than one code in the RST 28 data. In fact you can use as many as you like, provided you end the list with 34.

To save you working it out for yourselves here is a list of the available functions that we are ready to use, together with their appropriate RST 28 code:

FUNCTION  CODE      FUNCTION  CODE
CODE      19        EXP       23
VAL       1A        INT       24
LEN       1B        SQR       25
SIN       1C        SGN       26
COS       1D        ABS       27
TAN       1E        PEEK      28
ASN       1F        USR       29
ACS       20        STR$      2A
ATN       21        CHR$      2B
LN        22        NOT       2C

Some of the entries in that list may surprise you. For instance we have the use of USR. This is very confusing - being allowed to use USR in the middle of a USR routine - but it's not really. Here's how it works. You've worked your way through a lot of RST 28 data, done a lot of calculation, and now you come across the code 29. What happens next is that the number at the top of the stack should be an integer between 0 and 65535 - or else you'll get an error B. This address is treated as a subroutine and CALLed. This subroutine will run exactly as you'd expect it to. When it's over (i.e. when a RET instruction is reached) the machine will go back to interpreting the RST 28 data from the next byte. USR will of course leave a new value at the top of the stack - the value held by BC at the end of the subroutine.

PEEK works in the same way, finding an address, PEEKing there, then pushing the result to the calculator stack.

All of the functions when used in this way will remove the number currently at the top of the calculator stack and replace it by a new one. For instance, if the number at the top of the stack is 3.5 and the function INT is called, the 3.5 will be removed and replaced by a new value, 3.

The string functions CODE, VAL, and LEN, also CHR$ and STR$ need a small amount of explaining. You see, as well as storing numbers, the calculator stack can also store strings, so if you start off with the number 2000 on the top of the stack, and you then call STR$ (by using code 2A in a RST 28 instruction) then the item at the top of the calculator stack will now be the string "2000". You can demonstrate this with the following:

01D007              LD BC,07D0
CD1C15              CALL STACKBC
CD2015              CALL STACKBC       
EF                  RST 28
2A                  DEFB 2A (STR$)
19                  DEFB 19 (CODE)
34                  DEFB 34 (Exit)
CDA70E              CALL UNSTACK
C9                  RET

This should produce the result of CODE STR$ 2000. Does it?

USING THE CALCULATOR'S MEMORY

If you take a quick glance at the manual you'll see that one of the system variables, MEMBOT, is thirty bytes long. This is the calculator's memory area. A quick calculation involving dividing by five, if you're up to it, shows that this leaves enough room to store six different five byte numbers. The six different areas of memory may each be used by RST 28 to store, or retrieve, numbers (but numbers only) from the top of the calculator stack. There are twelve different codes to achieve this - these are:

C0        stores number in memory location 0
C1        stores number in memory location 1
C2        stores number in memory location 2
C3        stores number in memory location 3
C4        stores number in memory location 4
C5        stores number in memory location 5

E0        recalls number from memory location 0
E1        recalls number from memory location 1
E2        recalls number from memory location 2
E3        recalls number from memory location 3
E4        recalls number from memory location 4
E5        recalls number from memory location 5

Storing a number copies it from the top of the stack, and recalling a number simply places it at the end of the stack - it doesn't overwrite the previous top item.

Let's see how we can use this. Suppose we want to find SIN X+COS X. We must use the following technique. Assume that X is at the top of the stack.

EF                  RST 28
C0                  DEFB C0 (STORE0)
1C                  DEFB 1C (SIN)
E0                  DEFB E0 (RCALL0)
1D                  DEFB 1D (COS)
0F                  DEFB 0F (ADD)
34                  DEFB 34 (Exit)

Note that the SIN routine changes X into SIN X. When we again recall X there are now two items on the stack: SIN X and X. The COS routine changes X into COS X, so that the two items on the stack, are now SIN X, and COS X. The ADD routine will replace both of these by one single number - the answer we want - SIN X plus COS X.

We have now performed a fairly complex trigonometric function in just eight bytes!

Let's see how we can remove a floating point number from the stack without restricting ourselves to integers less than 65536. The way the ROM does it is like this:

2A1C40              LD HL,(STKEND)
2B                  DEC HL
46                  LD B,(HL)
2B                  DEC HL
4E                  LD C,(HL)
2B                  DEC HL
56                  LD D,(HL)
2B                  DEC HL
5E                  LD E,(HL)
2B                  DEC HL
7E                  LD A,(HL)
221C40              LD (STKEND),HL

As you can probably see for yourself, a five byte number is removed from the stack and stored in the registers A, E, D, C, and B (in that order). You can CALL this routine from address 13E4 13F8.

If the first item in the variable store is X then having popped SIN X plus COS X from the stack you can then store the result back in X as follows:

2A1040              LD HL,(VARS)
23                  INC HL
77                  LD (HL),A
23                  INC HL
73                  LD (HL),E
23                  INC HL
72                  LD (HL),D
23                  INC HL
71                  LD (HL),C
23                  INC HL
70                  LD (HL),B
C9                  RET

You can see that it takes more bytes to store the answer than it does to find it in the first place!

Let's see what else we can do with RST 28. We can use the logical functions AND and OR (that is BASIC AND and BASIC OR). Both of these are available from RST 28, having byte codes 08 and 07 respectively. Also you can SWAP the two numbers at the top of the stack. Code 01 will do this.

The following sequence will raise one number to the power of another. Can you see why? After RST 28: 01 22 04 23 34.

[Thunor: Well that's it folks! After 61 days I've finally finished my HTML transcription of this book, on the same day that BBC4 showed the comedy docudrama Micro Men (->), dramatising the rivalry between Sir Clive Sinclair and Chris Curry of Acorn in the early 80s - fantastic stuff :)]

[ADDENDUM]

[Thunor: Just as I started to transcribe this chapter I received an email from tabbycat <tibbytab AT tesco DOT net> warning me about the forthcoming ROM address errors, therefore I was extra vigilant and I've (hopefully) flushed them all out; many thanks for the heads-up.]

Previous | Contents | Next