********* Welcome to Project 64! The goal of Project 64 is to preserve Commodore 64 related documents in electronic text format that might otherwise cease to exist with the rapid advancement of computer technology and declining interest in 8- bit computers on the part of the general population. Extensive efforts were made to preserve the contents of the original document. However, certain portions, such as diagrams, program listings, and indexes may have been either altered or sacrificed due to the limitations of plain vanilla text. Diagrams may have been eliminated where ASCII-art was not feasible. Program listings may be missing display codes where substitutions were not possible. Tables of contents and indexes may have been changed from page number references to section number references. Please accept our apologies for these limitations, alterations, and possible omissions. The author(s) of the original document and members of Project 64 make no representations about the accuracy or suitability of this material for any purpose. This etext is provided "as-is". Please refer to the warrantee of the original document, if any, that may included in this etext. No other warranties, express or implied, are made to you as to the etext or any medium it may be on. Neither the author(s) nor the members of Project 64 will assume liability for damages either from the direct or indirect use of this etext or from the distribution of or modification to this etext. ********* The Project 64 etext of the ~Double Quick Brown Box~, converted to etext by Raj Wurttemberg . DQBB.TXT, Aug 2002, etext # # ********* THE DOUBLE QUICK BROWN BOX INSTRUCTIONS By S. Brown Pulliam Rev. 1 June 1987 Copyright 1987 by Brown Boxes, Inc. Bedford, MA. 1.0 WARRANTY: The DOUBLE QUICK BROWN BOX is designed, manufactured and sold by BROWN BOXES, INC. 26 Concord Rd., Bedford, MA. 01730, USA. THIRTY DAY REFUND: If it has not been abused, the DQBB may be returned for any reason within 30 days of the date of shipment for a refund of the purchase price, return postage, and any prepaid tax. ONE YEAR REPAIR or REPLACEMENT: If the DOUBLE QUICKBROWN BOX has any electrical or mechanical failure within ONE YEAR of shipment, it will be replaced or repaired (at the option of Brown Boxes, Inc.) at no cost except postage one way. Written material and program source listings may be copied for individual, non- commercial use only. Any software contained within the DOUBLE QUICK BROWN BOX when delivered is not included in the purchase price. Such software is copyright by, but is neither supported nor guaranteed by Brown Boxes Inc. 1.1 CAUTION: The memory contents of the DOUBLE QUICK BROWN BOX, although protected, can be readily altered. It is recommended that users insure the security of programs in memory by backing up all such software to floppy disk or tape. Brown Boxes Inc. assumes no liability for the loss or malfunction of any program stored in the DOUBLE QUICK BROWN BOX. 2.0 INTRODUCTION The DOUBLE QUICK BROWN BOX is a novel plug-in memory cartridge which brings new levels of convenience and flexibility to your Commodore 64 or C-l28 computer. The cartridge contains 16 kilobytes (16K) of non-volatile RAM. It behaves as part of your computers normal memory and you can store up ------ Page 2 to 16K of Basic and machine language programs in it. The big difference is that when you turn off the computer, your programs don't disappear. They are stored unchanged, unless you wish to change them, for as long as 10 years. DQBB memory contents are instantaneously available when you turn on your computer and can be plugged into any other C64/ The DOUBLE QUICK BROWN BOX is supplied already loaded with several utility programs which you may find useful. 2.0.1 Commodore designed both the C64 and the C128 to allow the use of plug in cartridges. In general, the cartridges are used in place of some of the internal computer memory, and are limited to the addresses that the Commodore operating system allows them to use. An experienced programmer can easily structure his/her programs to reside at the appropriate memory address in the cartridge. Programs that have already been written to reside in other areas of memory that are not normally accessible by cartridge can also be stored. To make this possible, we have included loader utilities in the DQBB to enable even inexperienced computerists to transfer BASIC or machine language programs from their normal running space into the DQBB for safe keeping. Then, when the program is to be run, a couple of key strokes are all that is required to move the program out of the box, into its normal location, and have it running, all within a fraction of a second. 2.0.2 There is no practical limit to the number of programs that may be stored in the DQBB at one time, except that the total size of all programs combined may not exceed 16 kilobytes (about 65 disk blocks). This is one reason why very few commercial programs would load and run from the box. Most would exceed 16K. Commercial software may also need some of the same memory address space that the box would use, without making provision to switch the box in or out as needed. 2.0.3 The DQBB is compatible with the Commodore 1700, 1750, and 1764 RAM Expansion Units provided a ------ Page 3 suitable socket expander is available to allow both devices to be connected to the computer expansion port at the same time. Refer to Section 9 for information about multiple cartridge operation. 2.1 INSTALLATION and OPERATION As with any other cartridge: PLUG IT IN ONLY WHEN THE COMPUTER IS OFF. LIKE MOST COMPUTER ATTACHMENTS THE DQBB CAN BE HURT BY STATIC ELECTRICITY. WEEN NOT IN USE, KEEP IT IN THE ANTI-STATIC BAG IT CAME IN. BEFORE INSERTION, DISCHARGE YOUR ACCUMULATED STATIC BY TOUCHING THE REAR TV CONNECTOR. SWITCHES: On the face of the cartridge are a 2 position slide switch and a push button switch. The slide switch selects either the C-64 or the C128 mode of operation. If you are using the cartridge with the Commodore 64 computer, always keep the switch in the C64 position. Placing the slide switch in the 128 position will make the cartridge invisible to the computer. When using the C-128 computer, the switch should be placed in whichever mode you intend to use the computer. If the switch is in the C64 position, it forces the C-l28 to operate in the C64 mode. 2.1.1 The push button RESETS the computer and initializes the DQBB to a Read Only mode. This RESET is useful if the computer crashes with a non functioning keyboard. It allows you to regain control without losing program material you may have entered into the computer. If the cartridge is used with the C-128, the push button function is identical to the C-l28 RESET. 2.1.2 The DQBB has a Check Sum utility to allow you to verify that once you have loaded a particular combination of programs or data into the box, the box contents have not changed. When we ship the box, we do a check sum and write the number on the sticker tag you will see on the back of the box. To be sure the box contents have not been impaired during shipment, run the Check Sum program ------ Page 4 as soon as you receive your DQBB. Make sure your computer is turned off, then plug the box in. Set the slide switch on the DQBB to the 64 position (even if you are using it in a C-128), turn on the computer, and a menu should be displayed on the screen. Enter *H then press RETURN and the check sum number should be displayed on the screen. If the number is correct, you should immediately save the entire box contents to a disk as described in Section 2.2. 2.1.3 If the cartridge appears to have a problem when it is turned on, (no menu appears or the wrong checksum is displayed), there are a few simple tests you can make that may save having to send the cartridge back. Refer to Section 11. 2.2 SAVING INSTALLED UTILITIES The DQBB is supplied with a number of utilities designed to simplify storage of your programs. These utilities are loaded in the DQBB for convenient delivery but they are designed to be stored on disk, not in the DQBB cartridge where they use space that you will want to devote to your own pro grams. Before attempting to store any new programs in the DQBB, these utilities should be saved to disk for your future use. 2.2.1 With the computer turned OFF, plug the DQBB into the cartridge port and place the slide switch in the 64 position. The disk drive should be connected normally and turned on, then turn on the computer. The DQBB menu will appear showing a list of programs. These programs are the DQBB utilities which you will later replace with your own pro grams. Normally, each program on the DQBB menu can be loaded into memory and run by pressing two keys, the * and the identifying letter which appears on the menu next to the program name, and then by pressing RETURN. The utilities that come with the box are loaded in a special way so that some of them will NOT run the first time that they are called from the menu. Those which might endanger the contents of the box will be moved out into ------ Page 5 memory so that they can be saved to disk, but they will not run automatically. 2.2.2 The DQBB LOADER, the first utility listed on the menu will load and run automatically when you type *L and press RETURN. It is used to Store programs in the box, but it can also be used when ever you wish to save the entire contents of the cartridge to disk as a single unit. We shall use it for that purpose before we safe the Loader it self to disk. It may be helpful to read the description of the Loader at 3.2.3 before continuing. Place a formatted disk with at least 95 free blocks in your disk drive. Type *L and press RETURN to load and run the DQBB Loader. The Loader menu will appear on the screen. Press S (for save) and you will be prompted to enter a name for the file that you are about to save. Enter an appropriate name (use no quotes) followed by the RETURN. The disk drive will become active for 20 or 30 seconds to complete the save. A new file of 65 blocks, the entire contents of the cartridge, will be found on your disk directory after the save. If you need to reload the DQBB with its original contents you can load this file using the BOOT program. See section 3.4 below. 2.2.3 Now the individual utilities can be saved as separate programs on your disk the same way that you save any normal Basic programs. Start by saving the DQBB Loader program that you just used. Exit from the Loader by pressing the E key and save it by typing SAVE "DQB LOADER",8 and RETURN. 2.2.4 If you would like to see the DQBB menu again, press the RESET button on the box. The menu doesn't have to be visible, however, in order to call the utilities. 2.2.5 The second utility listed on the DQBB menu, the 128 BASIC move (MOV128), should be saved to disk and then immediately deleted from the box. DO NOT RUN IT AT THIS TIME! When it is RUN it in stalls itself in the DQBB, destroying access to other utilities currently stored there. Call the program from the DQBB by typing *M (RETURN). It ------ Page 6 will not run automatically. When the READY prompt appears type: SAVE "BASIC MOVE.128",8 (RETURN). When the save is completed type NEW (RETURN) to clear the program out of Basic memory. Now, reactivate the DQB LOADER by typing *L. Select the DELETE command by pressing D. You will be asked for an identifying symbol for the program to be deleted. Press H. The DQBB menu will be displayed without MOV128, indicating that it has been deleted from the box. 2.2.6 The 128 LOADER (LDR128 on the DQBB menu) and the BOOT utility (BOOT) should also be saved separately. The 128 LOADER is loaded and run from the DQBB menu by typing *O. It will produce a menu identical to that of the DQB LOADER. Press the B key to exit, and then save the program to disk by entering SAVE "128 DQB LOADER",8. Finally, enter *B for the BOOT utility. When this utility is called, you will see the Basic READY prompt. It will not run automatically. Save the program to disk with SAVE "BOOT",8 (Return) then type NEW to clear it out of memory. Both these utilities may now be deleted from the box by reactivating the loader with the *L (RETURN) command, then using the Delete option. 2.2.7 At this point, if you choose the VIEW option to view the current box contents, you will see that only three entries remain: the DQB LOADER; loader INSTRUCTIONS; and Supermon. The first two of these can be deleted as above, and Supermon also, if you don't think you will be using it. The only remaining utility will then be the Check Sum. You now have almost the full l6 avail able for your own programs. Note, we did not suggest saving Instructions and Supermon because the material in Instructions is covered by this booklet, and when and if you need Supermon, most user groups have it in their libraries of public domain software. ------ Page 7 3.0 USING THE DQBB UTILITIES Once you have saved the DQBB utilities and deleted most of them from the cartridge, you are ready to store your own programs in the box. If your main application for the DQBB is to save and run programs that are already written, most of the information you need will be in this section. If you intend to write your own programs for use in the box, the additional sections are provided to give information about the inner workings of the DQBB. 3.1 128 BASIC MOVE If you choose to store a single Basic 7.0 program to be used in the C-l28, you will wish to install the BASIC MOVE.128. The installation is done in the 64 mode with the slide switch on the DQBB in the 64 position. From the disk, do a LOAD "BASIC MOVE.128",8 (RETURN) and when the load is completed, enter RUN. As explained above, when RUN the BASIC MOVE.l28 will install itself in the DQBB, making it impossible to gain access to previously stored programs. Place the slide switch in 128 position and press the RESET button. The computer will switch to the 128 mode, displaying the BASIC MOVE.128 choices: * = Store Program $ = Run Program These choices will not be available in 64 mode and are not appropriate for storing 64 mode programs. To use the DQBB as it is now set up, LOAD a 128 Basic 7.0 program (or a machine language program with a Basic loader) from tape or disk, or enter it by hand. Instead of RUNning it, press # (RETURN), and a copy of the program will be moved into the DQBB. The computer may be turned off and the cartridge removed if necessary. When the computer is turned on again with the cartridge in place, pressing $ RETURN will RUN the program that you have stored. The program will remain in the DQBB until you replace it with something else. When you do wish to store another program in the cartridge, ------ Page 8 load the new program into computer memory and press # RETURN. The new program will be written into the cartridge over the old one. Now pressing $ RETURN will run the new program. 3.1.1 A small change to the BASIC MOVE.128 program will make it very useful when you are writing Basic 7.0 programs. You can use the BASIC MOVE.128 to keep a copy of your program safe in the DQBB while you test what you have written. Update your old version by pressing # RETURN, and your new version will be written into the box. It's a lot easier than remembering to do periodic SAVEs to disk. However, since you probably won't want your unfinished program to run automatically when you press S, you will have to create a new version of BASIC MOVE, 128 which will simply put your stored program back into memory without running it. Load the copy of BASIC MOVE.128 that you previously saved to disk, and in the immediate mode, enter: POKE 33l54,76:POKE 33l55,139:POKE 33156,128 (RETURN) Now SAVE the program with a new name and when you want to use it as described above, LOAD and RUN it so it can install itself in the DQBB. 3.2 DQBB LOADERS When you wish to Store several programs in the DOUBLE QUICK BROWN BOX, with a menu that enables you to choose among them, you will need to use the appropriate LOADER program. The LOADER reads your program directly from the disk and stores it in the DQBB with its own entry on the DQBB menu. The LOADER sets up the DQBB with menus and tables (INITIALIZING THE DQBB) so that your programs can be sent to their normal running space and booted into action on demand. Once the DQBB has been initialized and loaded with your chosen programs the LOADER program itself is no longer needed unless you decide to change the box contents by adding a new program or deleting an old one. You can keep it stored in the cartridge with your other programs if you are using it frequently, but you ------ Page 9 will probably prefer to keep your copy on disk. 3.2.2 After it has been INITIALIZED by the LOADER, each time the DQBB is turned on it displays a menu listing each program stored in the box by a single letter symbol and a six character name or mnemonic. Empty places on the menu are marked by a "?". This menu display appears when the computer is turned on or is RESET. To RUN one of the programs, all you need to do is press * followed by the letter identifying the program and RETURN. Your program will be moved into the area of memory for which it was written, Basic or machine language, and will be run. 3.2.3 If the LOADER is still in the cartridge as you received it, you can put it into action by entering *L (RETURN). Otherwise LOAD it from disk just as you would any other Basic program by entering LOAD "DQB LOADER",8 (RETURN) and type RUN. When it is ready to operate, you will see a new menu: View QBB Menu (of stored programs) Load New Program (from disk) Delete Program (from QBB) Initialize QBB (ready for all new) Save QBB to Disk (on box load) Available Memory (bytes unused) Memory Used (bytes used by each Prg.) Read Disk Directory Exit (back to Basic READY) The first letter of each menu line when entered on the keyboard will initiate that action. 3.2.4 If you wish to begin a new box load of programs, choose the Initialize option. This will wipe out anything that is currently stored in the box. Use the Read Disk Directory option to browse through your disks. View QBB Menu to find out what is already stored in the DQBB and what identifying letters have been used. When you find a program in the disk directory that you would like to Store in the DQBB, return to the main menu (by pressing ------ Page 10 RETURN) and press the L key (LOAD). You will be prompted to enter the name of your chosen program. Don't include quotes, but you may use the * as a wild card. Complete your entry with RETURN. The LOADER program will read your program from the disk and compare it with the space available in the cartridge. If your program fits into the box it will be transferred from disk to the DQBB and you will be asked to provide a single identifying letter (followed by RETURN) and then a name with a maximum of six characters (and RETURN again). The new identification then will be entered on the menu. If the program was too long, you would have been informed and returned to the main menu to choose another program or perhaps to delete one that was already stored to make more room in the box. 3.2.5 You can use the Available Memory option to see just how many bytes are available in the DQBB, and the Memory Used option to see how much space is used by each program in the box. To do a rough calculation, remember that each disk block holds approximately 254 bytes. When you decide to delete a stored program, press D and you will be asked to supply the identifying letter for the program you wish to delete. The deleted program will be re moved from the menu and the space it occupied will be added to the space available in the DQBB. 3.2.6 The Save option of the LOADER will be most useful when you have set up a box that satisfies some special need or taste. If you have gathered together a perfect set of programming utilities, or word processing aids and now want to start another collection for a different purpose, use the Save option as you did in section 2.2 to save the entire contents of the box as a unit. Then when you wish to reload the cartridge with that particular collection of programs, you won't have to load each one separately. To use the SAVE option, press S. You will be asked to place a formatted disk in the drive before you continue. When you are ready, you will be asked to supply an appropriate name and the ------ Page 11 65 blocks of the DQBB will be saved to disk. 3.3 128 DQB LOADER A version of the DQB LOADER is also available for the C-128. The LOADER 128 is loaded and run in the 64 mode, with the slide switch of the DQBB in the 64 position despite the fact that it stores Basic 7.0 programs for use in the 128 mode. The menu of the LOADER 128 appears identical to that of the DQB LOADER but it has some limitations not shared by the 64 version. It will only store Basic programs and machine language programs with Basic loaders. Since that currently describes most programs written for the C-l28 it is not a terribly serious drawback. 3.3.1 You may experience a problem if a C-128 program that you are attempting to Store in the DQBB is located on the second side of a 1571 disk. This version of the 128 DQB LOADER works in the 64 mode, so your drive will be in 1541 mode, not 1571. The 1541 disk drive can read the entire directory of a double sided disk, but it can't read a program from the second side of the disk. The simplest solution may be to load the problem program into the computer in 128 mode and re-save. Use a fresh disk so that the program will be saved to the first side of the disk. Now back to the 64 mode, reload the LOADER 128, and store your program in the DQBB. 3.3.2 When you have finished storing your C-128 program in the DQBB, place the slide switch in the 128 position and press the RESET button. The computer will enter the 128 mode and you will be able to operate the DQBB in 128 mode. The contents menu that you will see in standard 128 colors has one addition to that which is displayed for the 64 mode. The % key will enable you to toggle back and forth between READ ONLY and READ/WRITE modes, a convenience if you want to use the monitor to make changes to the DQBB. ------ Page 12 3.4 BOOT UTILITY With this utility, a complete change of your DQBB contents can be done in less than half a minute. It will take care of all the details when you are ready to reload the DQBB with one of the cartridge configurations that you saved to disk. Just enter LOAD "BOOT",8 (RETURN) and RUN as you would any Basic program. Be sure you are in the 64 mode even if you are loading a cartridge that will run in 128 Basic. You will be prompted to supply the name of your new cartridge file (and RETURN) and then the screen will blank and your disk drive will become active for about 18 seconds. A Fast Load is built into the BOOT. When the READY prompt appears, you can place the slide switch of the DQBB in whichever position is appropriate to the contents that you have just loaded, and press the RESET button. The menu for the newly loaded DQBB should then appear on the screen. 3.4.1 Refer to paragraph 11.4 for a step by step example of the use of this utility. 3.5 SUPERMON+64 We find Jim Butterfield's SUPERMON+64 to be an indispensable aid to our programming. A comparable machine language monitor is included as part of the C-128, but for C-64 users we have included a nonrelocatable version in the DQBB. To activate SUPERMON, enter "*S" (RETURN) and you should see the Supermon register values displayed. The SYS 50471 indicates that this version is located at $C527 when set to run. It uses the remaining memory up to $CFPP, so caution must be exercised if you are dealing with other programs or wedges that were designed to use the high end of the $C000 block. We have included in Section 10 a short summary of the Supermon commands. 3.6 CHECK SUM Normally, once you have loaded something into the DQBB, it is placed in the Read Only mode and its contents should be inviolate. However, there ------ Page 13 are some hazards to the box contents, such as static electricity, inadvertent re-programming, or a crash due to having two cartridges turned on at the same time. Thus, it is useful to have the Check Sum utility available in the box to be called when ever you make any change in the box contents. When called by entering *H (RETURN), it will display a new number, which you can write on a piece of tape on the box. Then, whenever you wish to be reassured that the box contents haven't changed, just enter "*H" then press RETURN and the checksum number should again be displayed on the screen. This utility can only be loaded into a 64 version of the DQBB, and runs starting at location $7500. 4.0 PROGRMMING THE DQBB The cartridge RAM has addresses from $8000 to $BPFF (Decimal 32768 to 49151). Its operating modes are set by a Write Only control register whose address is $DE00 (Decimal 56832). Depending on the state of certain bits that are stored in the register, the cartridge is Read Only or Read/write, 8K or 16K, C64 or Cl28 mode, and connected or disconnected. A hardware RESET or power up clears all bits, setting Read Only, 16K, 128 mode, cartridge connected. The slide switch overrides the C64 bit when it is in the 64 position, forcing the 64 mode with 8K at RESET. In the 128 mode, the cartridge always has the full 16K available. There is no way to read which bits of the control register are set or cleared, so it is up to the programmer to keep track of all four of the control bits, so that each write operation to $DE00 will invoke the desired operating conditions. 4.0.1 In order to do any programming in the box, the first step would be to put the box in the Read/Write mode. This Can be done from the Basic Immediate mode by a POKE 56832,16. A machine language routine to do the same thing would be: LDA #$l0 STA $DE00 ------ Page 14 The more useful control register ($DE00, 56832) settings are summarized in the following table: 64 MODE FUNCTION HEX DEC (Poke) 8K Read Only $8000-9FFF 0 0 RESET 16K Read Only $8000-BFFF $04 4 NO BASIC 8K R, 16K W $10 16 16K Rd/Write $8000-BFFF $14 20 NO BASIC Disconnect Box $80 128 128 MODE 16K Read Only $8000-BFFF 00 0 RESET 16K Read/Write $10 16 Disconnect Box $80 128 4.0.2 Since the DQBB runs as part of the C-64 or C-128, a programmer could, in theory, program the cartridge in any language that is presently available for use in these computers. In practice, the fixed address space of the cartridge, $8000 to $BFFF, may not coincide with the work space allotted to the programmer by currently available implementations of Pascal, Forth, C, Logo, or Comal. Thus, we shall restrict our consideration to BASIC and Machine Language. BASIC is native to these Commodore computers, a machine language monitor is part of the C-128, and we have included a machine language monitor, Supermon, in the cartridge for the C-64. Some machine language assemblers, such as PAL or MAE adapt easily to the DQBB environment so that the assembler itself and a large work space can reside simultaneously in the cartridge. 4.1 PROGRAMMING IN C-64 MODE Normally, you would write your program as though the cartridge were not there, and then use the appropriate loader utility to store it in the DQBB. Such a program, either in BASIC or Machine Language, could be up to 16 kilobytes long. If you wish to avail yourself of the non-volatility of the DQBB memory, that is, to write directly into the box, so that what you are writing is immediately ------ Page 15 protected from any sudden power glitches, things are a little more complicated. If you wish to program in Basic, you are restricted to space from $8000 to $9FFF so as not to conflict with the Basic ROM which overlaps the upper 8K of the DQBB (see paragraph 4.3). For machine language programming, assuming your program will not require access to any Basic subroutines, you can use the whole 16K. 4.1.1 If you don't need the whole 16K for your program, and would like to keep the convenience of the menu and ease of use of the DQB LOADER, you can keep the loader intact and still introduce some space for creating a machine language program. The location $81DE holds a number indicating the number of free pages (a page is 256 bytes) remaining in the box. Determine how many pages you wish to re serve for your own program and subtract that from the number in $81DE, putting the result back in $81DE. For example, if you wish to open up a space of 512 bytes, you would reduce the number stored at S81DE by two. The space you set aside will be under the Basic interpreter extending down from $C000 the number of pages you asked for, so your program would begin at $BE00. Before attempting to do any programming there, you will need to store $14 in $DE00 to give you Read/Write access. If you intend the program to run at the same location some preliminary set up will be necessary. You cannot SYS to a location under the Basic ROM, so a load of $04 in $DE00 and the call to your program will have to be made from another M.L. program or from a M.L. monitor. 4.2 If you are primarily interested in working on one large machine language program, it is probably better to devote the whole box to the program. If the program is to extend into the area under the Basic ROM (above $A000) it must write $04 to $DE00 as well as writing 00 to the same address at its completion, so that a return to Basic can take place. ------ Page 16 4.3 It is possible to write or load Basic programs up to 8K in size directly into DQBB memory and run them in the DQBB. The Basic pointers (low memory $2B to $38) which normally assign the beginning of Basic memory to $0800 (2048) can be altered to Start Basic memory at $8000 (32768) which coincides with DQBB memory. The pointers can be changed by poking new values. This changing of the pointers can get a little sticky, and a utility is available on the Brown Boxes utilities disk that converts a DQBB to this application. In addition, the box must be kept in the Read/Write mode when a Basic program in it is running. It is important to note that some Basic programs which seem to fit nicely into the DQBB may not run well because they require an unusual amount of space for strings and variables. 4.4 The most complicated use of the DOUBLE QUICK BROWN BOX is the AUTO START mode. The DQBB can be programmed to take control of the computer upon power up and execute a machine language program prior to (or instead of) entering the normal Basic monitor. The AUTO START section (6.0 and 6.1) describes how this may be done. 4.5 WARNING. The DQBB uses a portion of RAM that is normally allotted to Basic. When it is plugged in there are only 30719 bytes in the regular Basic space instead of the usual 38911 bytes. This may not be enough for some programs to run while the DQBB is in place. One solution is to switch the DQBB to the 128 mode, and then push the RESET. A program can do the same thing by writing a one to bit 7 of the DQBB control register, but be careful to restore the Basic error vector at $0300 and $0301 because many DQBB utilities alter it to point to the box, which would be bad news if the box were disabled. ------ Page 17 5.0 PROGRAMMING THE DQBB (C-128 MODE) One nice thing about a battery backed cartridge such as the DQBB is its non-volatility which protects its contents from inadvertent or accidental loss of power. It is a nice environment in which to do programming since you don't have to worry about frequent saving of your work before a particular module is done and tested. A problem when using the DQBB in the 128 mode is that the Basic 7.0 ROM uses the same address space. There is, therefore, no simple way to write or run a Basic program in the box. You can, of course, write a Basic program in regular Basic space and store it in the box, as described in paragraph 3.1.1. We are left then with machine language programming, for which the box is well suited. 5.1 As you must know, if you are going to tackle M.L. programming in the C-128, this computer is designed to allow the memory to be partitioned into 16 so called 'banks'. The bank of greatest interest when using the DQBB is bank $0D (13), because it is the only bank that allows the cartridge to coexist with the Kernal. 5.1.1 As mentioned previously, before you can begin to build a program in the DQBB, you need to have the box in the Read/Write mode. You can write the appropriate bits to the DQBB control register ($DE00) in any bank except banks 0-3 and 14. It is often more convenient to have written a few short routines that can call the desired DQBB mode. The cassette buffer at $0300 is a good place to store such routines. After calling the 128 MONITOR you could assemble the following: A F0B00 LDA #00 READ ONLY F0B02 STA DE00 F0305 RTS F0B06 LDA #10 READ/WRITE F0B08 STA DE00 F0B0B RTS F0B0C LDA #80 DISCONNECT F0B0E STA DE00 F0B11 RTS ------ Page 18 Once these are assembled, if you wish to load or write into the box, just enter (from the MONITOR) J F0B06 and that will put it in the R/W mode. J F0B00 would put it back in Read Only, though a RESET would do that as well. 5.1.2 When the box has been placed in R/W you can begin your assembly to any address in the box by using that address preceded by a "D". If you want to be able to use Kernal routines in your program, you would early in the program have it establish the configuration for Bank 13 by writing: LDA #0A STA FF00 5.2 There are several excellent books that you may wish to consult for more information about programming the C-128. Three of the best are: COMMODORE 128 INTERNALS published by Abacus Software. COMMODORE 128 PROGRAMMING SECRETS by Wiese, published by Osborne McGraw-Hill COMPUTE!'s 128 PROGRAMMER GUIDE published by COMPUTE Publications. 5.3 When you read about the 128 Kernal routines such as JMPFAR, JSRFAR and FETCH that were designed to simplify cross-bank code manipulations, you will find that they can all be useful to you in the DQBB. However, be aware that all these routines were designed to be used from Bank 15. You may need to make minor changes to use a given routine from Bank 13. 5.3.1 JSRPAR, for example, is set to return to bank 15. When you use it from bank 13, you will do the normal set-up but in addition you will need to add the following code: LDA #0A ; Configuration for Bank 13 STA 2DE ; Page 2 address that holds return configuration JSR FF6E ; JSR JSRFAR LDA #00 ; Configuration for Bank 15 STA 2DE ; Restore previous Config. ------ Page 19 On occasion, it is helpful to disable the interrupts before crossing banks, then restore interrupts when you return. 5.4 There are a greater variety of machine language assemblers available for the C-64, and if one of these is available, it is perfectly feasible to write the actual code using the box in the 64 mode even though it will be run in the 128 mode. 6.0 AUTO-START, 64 MODE The first storage device to get a crack at having its program contents run when the computer is turned on is a cartridge. Upon power-up, or a RESET, the computer checks for the presence of a cartridge before it attempts to do any other initialization. It does this by looking to see if locations $8004 through $8008 hold the consecutive bytes C3 C2 CD 38 30. If you put these bytes into the QUICK BROWN BOX at that address the computer will transfer control by a jump indirect to what ever address is specified at locations $8000, $8001 in low byte-high byte order. Usually that address will be $8009, so 09 will be in $8000, and 80 in $8001, and your program would be set to begin at $8009. The processor status conditions in effect at that point are Decimal mode cleared and Interrupt Disable set. 6.0.1 When running an Auto-Start program, if it crashes and hangs up the computer, just put the slide switch in the 128 position and press RESET. The computer will have a normal Basic start up, from which you may load a machine language monitor and then begin to fix the problem. 6.1 CUSTOM AUTO START When you program the Auto-Start mode, you are really letting the computer know that you are the boss! You may wish to begin with just a modest assertion of your authority, such as choosing your own colors for characters and background, after ------ Page 20 which you could give control back. To do this in the easiest manner, your cartridge routine would have to duplicate some of the computer's initialization routines. Relevant DQBB code begins: $801B JSR $FDA3 ;Initialize CIA I/O $801E JSR $FD50 ;RAM test, set pointers $8021 JSR $FD15 ;Set vectors for RERNAL $8024 JSR $FF5B ;Init. Video Controller $8027 CLI ;KERNAL init. finished $8028 JSR $E453 ;Set Basic vectors $802B JSR $E3BF ;Initialize zero page At this point you can insert a jump to subroutine call to your own program. If you don't need to use Basic, the call to your program can be a JMP. If Basic is to be called, as it is in the DQBB, the following additional steps initialize Basic without undoing whatever set-up had already been done in your program. $8032 JSR $A644 ;does CLR and NEW $8035 JMP $E394 ;gives control to Basic. 6.2 RESTORE KEY The RESTORE key initiates a Non-Maskable Interrupt which will vector directly to the cartridge, and if the bytes at $8004-$8008 call the Auto-Start mode, control will pass to the location held at $8002-$8003. 6.3 RESET Under certain circumstances it may be desireable to hold the DQBB in a mode different from its normal start up mode while resetting the computer. This cannot be done using the RESET button, because that would reset the DQBB control register. A "SYS 64738" cold start call would work, since it sends the computer through all of its initialization, but wouldn't affect the DQBB. ------ Page 21 7.0 AUTO-START 128 The AUTO-START mode for the C-l28 is similar to that of the C-64. On power-up or RESET, the computer looks for a sequence of bytes that indicate the presence of a C-l28 cartridge. These bytes are the ASCII code for CBM and the computer looks for them starting at $8007. Unlike the C-64 routine, the most significant bits of the letter bytes are not set. A more significant difference, however, is that you have a choice that is not available in the C-64 mode. The byte at $8006 is a special identifier. If it is 01, the computer immediately yields control to the cartridge and jumps through the cartridge cold start vector, which in another departure from the 64, is a JMP direct from $8000 at which the code $4C L.B. H.B. will have been written. If you want to exercise this option, you will have to take over the rest of the computer initialization, as you do for the 64. If you would like to avoid taking on the responsibility for completing the initialization, you place any number greater than 1 and smaller than $PF in location $8006. In this case, the computer will note the presence of the cartridge, complete its own initialization, and then return to the cartridge to execute your code, taking its JMP from the warm start vector located at $8003. This is the system we use for all the 128 cartridges: $8000 4C 0A 80 JMP $800A ; Could be omitted $8003 4C 0A 80 JMP $800A ; Warm Start Vector $8006 11 ; Identifier byte $8007 43 42 41 ; "CBM" $800A Our code begins here. It is important, if you wish to use Kernal routines in your own machine language program, to establish the configuration for Bank 13 immediately. The computer, when it identified the cartridge, assumed it was in Bank 8. Therefore our first instruction at $800A is always: $800A LDA #0A $800C STA FF00 ------ Page 22 From this point on you are free to experiment on your own. If your efforts are not completely successful, a crash in the 128 mode is not a disaster. Flip the slide switch to the 64 position and press RESET. You can then load a monitor or assembler and make changes to your code, put the switch back to 128 position, and try again. 8.0 THEORY OF OPERATION The important operating modes of the DQBB are selected by the slide switch and a control register whose address is $DE00 (56832). This is a Write Only register, using bits 2,4,6 and 7. The slide switch pulls /EXROM LOW when in the 64 position, and leaves it to the discretion of bit 6 when in the 128 position. The only other action of the slide switch is to select whether the Read Enable of the upper 8K is controlled by /ROML (128 position) or /ROMH. 8.1 When the computer is turned on, or the RESET button is pushed, the control register is reset to a predetermined mode. If the slide switch is in the C64 position, the DQBB comes on in the Read Only mode, with just the lower half ($8000 to $9FFF) accessible so that the normal computer Basic will run. In the Cl28 position, the box still comes on in the Read Only mode, but all 16K (from $8000 to $BFFF) are accessible. In the C-128 computer Basic and external cartridges have to compete for the same address space so special procedures are necessary to gain access to the DQBB. These are described in Section 5. 8.2 The Control Register is a write only register, using only four of the eight available data bits. They must all be written in each write operation, so it is necessary to keep track of what bits are already set when you are ready to make a change, and make sure the new word affects only the bit (or bits) you wish to change. A summary of the bit values required for each operating mode is ------ Page 23 contained in paragraph 4.0.1. The effects of each bit are as follows: BIT 7 if a HIGH (1) disables the DQBB memory (but not the control register) so that just about any other program or cartridge can run, just as if the DQBB were not plugged in. An important exception to this is any cartridge, such as some Fast Load and special copying cartridges that also use $DE00 (56832) as a control register. Writing a zero at this bit turns the DQBB back on. Thus, if you are in Basic, a POKE 56832,128 would turn the cartridge OFF and POKE 56832,0 turns it back on. BIT 6 when HIGH causes the /EXROM line to be pulled LOW. The /EXROM line is the one that must be pulled LOW to cause the computer to know that a C64 cartridge is plugged in, and the slide switch al ready holds /EXROM LOW when in the C64 position. Thus this bit will only have an effect if the switch is in the C128 position, and if set to a 1 will force the Cl28 computer into the C64 mode. The reverse, writing a zero to this bit will not bring the computer back in to the 128 mode. The only way to accomplish that without destroying whatever is stored in RAN is to push the RESET button BIT 4 controls whether the DQBB acts as RAM (Read/Write mode) or ROM (Read Only mode). A HIGH (1) selects R/W and 0 selects RO. Whenever you have finished programming with the DQBS, it is important to make sure the box is left in the Read Only mode, that is, with this bit cleared. BIT 2 controls the /GAME line, the other C-64 cartridge control line. When it is brought HIGH it causes /GAME to go LOW. It would not normally be used in the Cl28 mode. If the slide switch is in the C64 position, or if bit 6 is HIGH, causing /EXROM to be LOW, and you then cause /GAME to also go LOW, Basic will be disabled, and the upper 8K of ------ Page 24 the DQBB ($A000-$BFFF) can be read. If you just wish to write to that part of the DQBB, it doesn't matter whether /GAME is asserted or not, but the cartridge does have to be in the Read/Write mode. In the C-128 mode the /EXROM and /GAME lines are not used, but they can be set high or low. So that the DQBB would not interfere with any possible future uses of these lines, their outputs are open collectors, so when bits 2 and 6 are low, those lines see an open circuit. 8.3 The /DE00 input to the cartridge writes into the control register U4 whenever an address from $DE00 to $DEFF is programmed. Since we have not provided a read lockout, a READ to $DE00 will attempt to write random garbage to the control register. Therefore, any attempt to read the register value, which is impossible anyway, will instead write indeterminate data into it. Treat it as a WRITE ONLY register. 8.4 When the DQBB is plugged into the computer, and the computer is turned on, there is no drain on the internal 3 volt lithium battery. When the computer is off, or the cartridge unplugged, the drain is about 1 microampere. The battery is rated at 160 milliampere-hours, so assuming the worst case, the battery should last its expected shelf life of 10 years. 9.0 OPERATION WITH EXPANSION RAM AND OTHER CARTRIDGES CAUTION IF YOU USE THE DQBB ON AN EXTENDER CARD: There are a number of extender cards available that allow several cartridges to be plugged into your C-64 or C-128 at the same time. Most of these have individual slot switches that allow you to turn on or off each cartridge individually. If you have the DQBB on at the same time as another cart ridge, you run a risk of corrupting the contents of ------ Page 25 the DQBB, though we have never had an instance where this mishap caused any permanent damage to the box. Thus, be sure to back up your box con tents on disk or tape before using it with other boxes on an extender. 9.1 If a DQBB and one or more other cartridges are connected to the expansion port at the same tine, and have power applied, they each may try to place data on the eight lines of the Data Bus. Since some data lines will be trying to go HIGH while others will pull LOW, the odds are that at any one time, half of the lines are in concert, and half will be in contention. Those in contention will draw excessive current, and might thereby cause the corruption of some of the data in the DQBB. 9.1.1 If bit 7 is HIGH in the DQBB control register, it keeps the cartridge from placing data on the Data Bus, so even if powered up at the same time as another cartridge, the DQBB data should be safe and protected from any contention problems. 9.2 Another problem may arise since some other cartridges also use $DE00 as a register address. Even if the DQBB control register has bit 7 set, if the computer were attempting to write the control register of another cartridge, that data would also be written into the DQBB control register, perhaps putting it in the Read/Write mode, or clearing bit 7 and allowing bus contention. 9.3 The DQBB was designed to be compatible with the Commodore 1700, 1750, and 1764 RAM Expansion Units. These units use $DF00 as their control address, so control commands will not interact. 9.4 It is not a good practice to leave the DQBB plugged into an expander card for extended periods of time when the computer is on, but with the slot switch for the DQBB turned off. This causes a drain on the internal lithium battery about 25 ------ Page 26 times higher than normal. When the computer is turned OFF, there is no such problem. 10.0 SUPERMON+ COMMANDS NUMBER BASE CONVERSION $ + & % R REGISTER DISPLAY M MEMORY DISPLAY (With ASCII) X EXIT TO BASIC MONITOR D DISASSEMBLY D hhhh A ASSEMBLY A aaaa LDA hhhh F FILL MEMORY F ssss ffff bb G GO (Begin to run program) G ssss J JUMP TO SUBROUTINE J ssss H HUNT H ssss ffff 'word H ssss ffff bb bb bb bb (32 max.) L LOAD L "FILENAME",08 or ,0l (Disk or Tape) S SAVE S "FILENAME",08,ssss,ffff+l T TRANSFER T ssss ffff nnnn C COMPARE (memory) C ssss ffff nnnn DISK COMMANDS @ Gets disk Status message @9 Gets unit 9 status @,$0 (number zero) Displays Dir. Drive 0 @,S0:filename deletes that file from disk @,N0:filename,ID formats disk SYS 50471 Calls DQBB version after it is in place. ------ Page 27 11.0 PROBLEMS AND TROUBLESHOOTING We at Brown Boxes have extended ourselves to bring you a useful and reliable product. Each Brown Box is given a complete memory test, then loaded and allowed to sit a few days. Just prior to shipping, we do the Check Sum to make sure its contents have not changed. 11.1 If the DQBB has arrived giving the wrong checksum, or even worse, unable even to call the sum, the first order of business is to see whether the box has just temporary amnesia, or is brain damaged. If the diagnosis is amnesia, we will send you a disk with the box contents so that you can load the box from scratch. If the box has an electrical malfunction, you will need to send it back for repair or replacement. 11.2 With the computer turned OFF, and nothing else connected to the computer except the power supply and display monitor, plug the DQBB directly into the cartridge port. Place the slide switch in the 128 position and turn ON the computer. 11.2.1 If you get the normal computer start up message on the screen, proceed to the next test. If you get anything else, turn off the computer and unplug the cartridge, then turn it back on. If the correct message is now present, the cartridge is bad and must be sent back. If the message is still incorrect, the computer is bad. 11.2.2 Assuming the normal computer Basic start up message is showing, switch the slide switch to the 64 position, and press the RESET button. You should get one of four possible displays: the normal C-64 Basic start up message, with 30719 bytes free; a DQBB menu with the READY prompt and flashing cursor; a DQBB menu, but no READY prompt; or any other screen display and no READY prompt. If there is no READY prompt, go to 11.3 ------ Page 28 11.2.3 If you are getting a READY and cursor, enter the following (with RETURN after each line): POKE 56832, 16 POKE 32772, 85 POKE 32773, 170 Then push the RESET button and turn off the computer. 11.2.4 Turn the computer back on, and the C-64 Basic message, with 30719 bytes free should be showing. Now enter: ?PEEK (32722) and 85 should show, then ?PEEK (32773) and 170 should show. If these numbers are not correct, the cartridge is brain damaged, and must be sent back. If they are OK, there is an excellent chance that when you get a disk with the correct box load, it will load, and the box should work fine. Follow the instructions in 11.4 when you get the disk. 11.3 If your computer is a C-64, switch the slide switch to the 128 position, press RESET, and then repeat the steps listed in 11.2.3 above. Now place the slide switch in the 64 position and follow the steps listed in 11.2.4. 11.3.1 If your computer is a C-l28, put the slide switch in the 128 position and press the RESET button. After the Commodore message is showing, enter MONITOR (RETURN) and then type the following lines, each followed by RETURN: A F0B00 LDA #10 STA DE00 LDA #55 STA 8004 LDA #AA STA 8005 RTS (extra RETURN) J F0B00 Put the slide switch in the 64 position, press RESET and turn off the computer. Now follow the steps listed in 11.2.4 ------ Page 29 11.4 As outlined in paragraph 3.4, the fastest way to load a DQBB with a preassembled set of programs is to use the BOOT utility first. To load the standard utilities that are shipped with the box, follow these steps: 1. Put the slide switch in the 64 position. 2. Put the disk in the disk drive. 3. Enter LOAD "BOOT",8 (RETURN) 4. Enter RUN 5. When the boot program asks for a file enter DQB DEMO BOX (RETURN) (no quotes) 6. When drive stops, push RESET. 11.4.1 If you didn't have the BOOT program, the last few steps would be: 3. Enter POKE 56832,16 (RETURN) 4. Enter LOAD "DQB DEMO BOX",8 (RETURN) 5. When the disk drive is no longer active push the RESET button. This takes somewhat longer because it does not use a fast load. ------ INDEX PARAGRAPH ASSEMBLER .......................... 5.4 AUTO-START ......................... 4.4 6.0 7.0 AVAILABLE MEMORY ................... 3.2.5 4.1.1 BANKS .............................. 5.1 5.3 7.0 BASIC Box storage ..................... 3.3 4.3 4.5 Disable ......................... 4.1.1 Move 128 ........................ 2.2.5 3.1 Pointers ($2B-$38) .............. 4.3 BATTERY ............................ 8.4 9.4 BOOKS on C128 ...................... 5.2 BOOT Utility ....................... 3.4 CHECK SUM .......................... 2.1.2 3.6 COMMERCIAL SOFTWARE ................ 2.0.2 CONTROL REGISTER Bit Table ....................... 4.0.1 Operation ....................... 8.2 Programming ..................... 5.1.1 DELETE ............................. 2.2.5 3.2.5 DIRECTORY .......................... 3.2.4 3.3 DISCONNECT BOX ..................... 2.1 5.1.1 8.2 DISK DRIVE ......................... 2.2.1-2.2.6 3.2.4 3.3.1 DQBB ADDRESS ....................... 4.0 4.1 4.2 8.1 8.2 DQBB LOADER ........................ 2.2.1 2.2.3 ERROR VECTOR ....................... 4.5 EXIT ............................... 2.2.3 2.2.6 FAST LOAD .......................... 3.4 INITIALIZE ......................... 2.2.1 3.2 6.1 7.0 8.1 INTERRUPT, Non-maskable ............ 6.2 ------ KERNAL ............................. 5.1.2 5.3 7.0 LOADER (Utility) ................... 2.2.1 2.2.6 3.2 3.3 MACHINE LANGUAGE ................... 4.1.1 4.2 5.0 MEMORY SIZE ........................ 2.2.1 MENU DQBB .......................... 2.2.4 3.2.2 3.2.3 Loader .......................... 3.2 MALFUNCTIONS ....................... 2.1.3 9.2 11.0-11.3 MONITORS ........................... 4.0 PROGRAMMING THE DQBB ............... 4.0 PROGRAM SIZE, NUMBER ............... 2.0.2 POINTERS ........................... 4.3 READ ONLY .......................... 3.0 3.3 3.4 4.0.1 5.1.1 8.1 8.2 RAN EXPANSION UNITS ................ 2.03 9.3 READ/WRITE ......................... 3.0 3.3 3.4 4.1.1 4.3 5.1.1 RELOADING BOX CONTENTS ............. 3.4 RESET ......................... 2.2.1 2.2.4 3.1 3.3 6.0.1 6.3 7.0 8.2 RESET BUTTON ....................... 2.1.1 2.2.4 RESTORE Key ........................ 6.2 RUN (and RUN disable) .............. 3.1 3.1.1 8.2 SAVE ............................... 2.2 2.2.2 2.2.6 3.2.6 SPACE (Reserve) .................... 4.1.1 STATIC ELECTRICITY ................. 2.1 STORE (in box) ..................... 3.0 3.1 3.2 3.2.4 SUPERMON (Location $C527-$CFFF ..... 3.5 9.0 SWITCH, Slide ...................... 2.1 2.2.1 3.1 3.3 3.4 4.0 ...................... 6.0.1 7.0 8.0 8.1 [End]