BRACKENRIDGE%USC-ISIB@sri-unix.UUCP (12/20/83)
From: Billy <BRACKENRIDGE@USC-ISIB> The following are excerpts from IBM Personal Computer Seminar Proceedings "The Publication for Software Developers of the IBM Personal Computers" Published by International Business Machines Corporation Entry Systems Division. This is Volume 1, Number 3. No copyright notice is given. We came by this through PCjr magazine. A local software developer here who is a regular advertiser in PC magazine refused to take advertising space in this new magazine until he was sure his software would run on the PCjr. The staff at PCjr sent him this publication in hopes of convincing him to purchase space. I can't understand what possessed me to stay up all night typing this in over the objections of a nearly disasterous PARITY CHECK 2. Much of the material here will be in the Technical Reference manual, but who knows when we will ever see one. This is an important document, not particularly for its content, as we will all be able to take apart our PCjrs in another month or so when we take delivery, but because it exists at all, and IBM makes quite clear what "IBM compatibility" really means. If anyone has issues 1, 2 or later please let us know. If anyone knows how to get on IBM's list of chosen developers, I would like to know that as well. There was no author or address other than "Entry Systems Division". As this publication is thirty pages of closely printed notes and extensive diagrams I can only give a summary. I have left out a few details and have tried to mark my editorializing accordingly. --------------------------------------------------------------------------- The IBM Entry Systems Division is pleased to provide the Proceedings of the IBM Personal Computer seminar, designed for independant developers of software for the IBM Personal Computer. The purpose of these proceedings is to aid you in your software development efforts by providing relevant information about new product announcements and enhancements to existing products...... PURPOSE What is our purpose in putting out a publication such as this? it is quite simple. The IBM Personal Computer family is a resounding success. We've had a lot of help in achieving this success, and much of it came from the independant software developers. As you proceed with your software development, do you at times wish for some bit of information or direction that would make the job easier? Information which IBM can provide? This is the type of information we want to make available to you. TOPICS The following list gives a general indication of the topics we plan to cover in future seminars and include in the IBM Personal Computer Seminar Proceedings: o Information exchange forum -- letters to the editor format o Development tools -- languages, database offerings o New devices -- capacities and speeds o System capacities -- disk and memory o Enhancements in maintenence releases o Tips and techniques o New system software o Hardware design parameters o Tips on organizing and writing documents for clear and easy reading o Changes to terms and conditions Comparisons between DOS 2.1, 2.0 and 1.1 [DOS 2.1 appears to differ from DOS 2.0 only in features necessary to support the PCjr. -ed] DOS 2.1 was written to take advantage of the differences in the PCjr, such as: o minimum memory configuration o IBM PC compact printer o diskette characteristics o BASIC interface Thus all DOS commands are supported on the 64KB entry environment of the PCjr. IBM PCjr Architecture o 8088 Microprocessor The 8088 Microprocessor in the PCjr is the same microprocessor used in the IBM Personal Computer and XT. The 8088 runs at the same speed in all three machines. o 64KB Read Only Memory (ROM) The system board contains 64KB ROM. The ROM contains BIOS, power on diagnostics, customer level diagnostics, cassette Basic, and the keyboard adventure program that teaches how to use the 62-key keyboard. o 64KB RAM and 64KB Memory and Display Expansion The PCjr comes with 64KB RAM. The system board also has a connector for a 64KB memory and display expansion option, which increases the total RAM to 128KB. The 128KB of RAM is shared between the processor and video circuitry. o 128KB Cartridge interface The PCjr has a 128KB cartridge interface to allow ROM programs to be inserted in the system. o Video Graphics Subsystem The functions of the IBM PC Color/Graphics adapter have been moved, with some enhancements to the IBM PCjr subsystem. o Sound Subsystem Four sound inputs are available on the PCjr sound subsystem -- a complex sound generator, 8253 timer sound, cassette audio input and audio input from the I/O channel. o Game adaptor Comes standard joystick extra, compatible with PC. o Serial Port The serial port is compatible with the PC at card two address (2F8H). The serial port will support the following speeds: -- 4800 bits per second transmitting -- 1200 bps for receiving with overlapped keyboard operation -- 4800 bps for receiving with no keyboard overlap The transmission rate divisors are different from the PC because the PCjr uses an input clock of 1.7895 MHz. o Keyboard Interface Consists of infared receiver or cable interface. This signal causes a non maskable interupt (NMI) to the 8088 which then deserializes the data to obtain the scan code data. [ They must have saved themselves 35 cents production cost on this crock! -ed] o Modem and Diskette Interface The internal modem is 300 bps Bell 103 compatible with auto answer auto dial capability. It is direct connect and the serial port is at card one address (3F8H). A single half hight diskette can be installed on the PCjr. Because the PCjr has no DMA controller, diskette operations can not be overlappped with keyboard or asynchronous communication operations! o Nine level Interrupt The PCjr provides nine levels of interrupt. All but three are used on the system board for diskette, modem, serial port, vertical retrace, timer, and keyboard operations. The remaining three are available on the I/O expansion bus. o I/O expansion bus Contains "many of the same lines as the PC and XT I/O channel". VIDEO GRAPHICS SUBSYSTEM Unlike the PC and XT the PCjr includes the video system on the system board. This is an enhanced version of the Color/Graphics adaptor. The 64KB RAM on the system board is shared between the processor and video every 1.1 micro seconds. Two fetches are made for the display and one for the processor. Each fetch is 8 bits wide. This is sufficient to support 40 column alpha, 160 X 200 16 color graphics, 320 x 200 4 colour graphics and 640 x 200 2 color graphics. If a 64Kb memory and display expansion option is installed, the memory is reconfigured so that even bytes reside on the system board and odd on the expansion card. This allows the video adaptor to fetch 16 bits at a time. This supports 80 column alpha, 320 x 200 16 color graphics, 640 x 400 4 colour graphics. Logic has been added so that reads and writes directed at B8000H will appear to be the same as a PC color/graphics card. The PCjr also has CRT page register so any 16KB region can be mapped to display memory. This will aid in animation when coupled with the vertical retrace interrupt. The PCjr has a custom Video Gate Array (VGA) which contains a 16 X 4 color pallette. This allows a program to quickly change colors on the screen by changing the pallette rather than changing memory. The pallette also controls the border color. The video subsystem supports RGB, composite video, and TV connector. SOUND SUBSYSTEM The nucleus of the sound subsystem is an analog multiplexor which allows one of four different sound sources to be amplified and sent to the audio outputs. The sound sources are: Complex sound generator chip SN76496N -- three programmable frequencies can make chords as well as white noise. Each of the sources can be attenuated to 16 levels. 8253 timer chip is compatible with the PC and can be used as a sound source. The other two sources are the I/O expansion channel and cassette input. Data and voice can be stored on the cassette. The I/O channel allows easy addition of things like speech synthesizers or telephone answering machines which can use the audio amplifier and speaker already attached to the system. ROM CARTRIDGE INTERFACE 128K of ROM can be accessed by the cartridge interface. Each slot can hold 64KB. It doesn't matter which slot is used as the cartridge configures where it will be in the memory map. Inserting a cartridge causes a system reboot. Two signals in the cartridge interface called - BASE 1 ROM IN CARTRIDGE and BASE 2 ROM IN CARTRIDGE allow the system ROM to be overridden by the code provided in the cartridge. This feature can be used to gain control at system boot time and completely replace DOS. I/O EXPANSION CHANNEL The expansion channel is available on the right side of the system unit. Expansion modules can be daisy chained and screwed together so that they appear to be part of the system unit. Subject to power restrictions pretty much anything that can be added to a PC or XT can be added to the PCjr expansion slot. There are only three interrupt request lines brought out to the expansion slot as the other six are reserved for the system chassis. The main difference between the PCjr I/O bus and the PC is that the PCjr has no DMA. You can add DMA to the PCjr in an expansion unit and even run the onboard diskette adaptor in a DMA mode using the DACK0 and DRQ0 lines. [ The paper goes on to give great technical detail on how to add external DMA capability. Suffice it to say it can be done and will be documented in the technical reference manual when it is released -ed] The I/O bus also extends the audio line mentioned in the sound section above. It also has provisions for adding wait state so the PCjr could be connected to an expansion cabinet. [ The bus appears to be an improvement over the PC/XT bus -ed] IBM PCjr COMPATIBILITY All PC BIOS calls are preserved, but of course the code is not identical so don't depend on any absolute addresses being the same. Programs running in RAM will run slower than on a PC or XT. Programs running in ROM will run faster. Diskette performance will be slower. IBM advises the programmer not to depend on instruction execution timing. If you need to time short intervals use the system timer. IBM warns that estimation of memory usage is a complex matter. The display subsystem can use varying amounts of memory depending on the application. Cartridge Basic vs Cassette Basic vs Disk or Advanced Basic complicate the issue further as does the use of DOS vs standalone cartridge software. The cordless keyboard can generate all of the scan codes generated by the standard 83 key keyboard. The highest level of compatibility to interface to keyboards is through BIOS interrupt 16H (read keystroke). Below that level is risky since there are hardware differences between the PCjr keyboard and PC keyboard. The PCjr system uses the nonmaskable interrupt (NMI) to deserialize the scan codes and pass them to interrupt 48H for compatible mapping to the 83 key format. Interrupt level 9 remains a compatible interface for 83-key scan code handeling. It is not reccommended to replace interrupt level 9 even though a high degree of compatibility is maintained. If necessary analyze this architecture carefully. COMPATABILITY GUIDELINES FOR APPLICATION DEVELOPMENT [following is verbatim modulo my typing errors] This article summarizes the compatability guidelines for application development. IBM suggests that you use these guidelines in your program development. These are guidelines only. They are not guarentees to ensure compatability nor are prohibitions of any kind. You may write a program in any manner you wish. However, if you follow these guidelines, your program will have a much better chance of running correctly on the different systems in the IBM Personal Computer family. This article emphasizes how the PCjr affects application programs. For the purpose of simpler notation all references to the PC also apply to the XT. One distinction between the PC and XT appears at the end of the article. [ I am abbreviating to PC and XT I am sure to the horror of the IBM legal staff. I also sometimes refuse to capitalise a few IBMisms -ed] 1. High Level Languages IBM-supported languages - BASIC, FORTRAN, COBOL and Pascal are the best choice for writing compatible programs. IBM will make every effort to ensure that these high level languages continue to work on all systems in the PC family. The Pascal and FORTRAN compilers will not run on the PCjr because there is not enough memory. However programs that were compiled will run on the PCjr, as long as they do not exceed the memory capacity of PCjr. This means you can do program development on an IBM PC, and then transfer the resulting program to an PCjr. A high level language program must be well-behaved. If a program directly uses features of the hardware, that program may not be transportable. For example, if you use hardware specific commands like IN, OUT, PEEK, and POKE, or you use assembly language subroutines, you should follow the assembly language rules given below. Any program that requires precise timing information should obtain it through a DOS or language interface (e.g. TIME$ or TIMER in BASIC). If the program requires greater precision it should uste the assembly techniques shown below. Using program loops for timing may prevent a program from migrating to an otherwise compatible system with different performance. Because system memory is shared with display memory in the IBM PCjr, a program in PCjr RAM will probably run slower than the same program running on the IBM PC. This means that all timing dependant programs intended for both the IBM PC and the IBM PCjr must use external timing information. 2 ASSEMBLY LANGUAGE PROGRAMMING Assembly language programs should perform I/O through ROM BIOS or through DOS function calls. A program should use software interrupts to access these functions. This removes absolute addressing from the program, and only the interrupt number is required. The IBM PCjr has retained the physical address of most of the IBM PC's ROM BIOS entry points, but your program should not rely on them. The BIOS and the operating system can hide hardware differences. As new devices are added to the system, IBM may modify the ROM BIOS to maintain a consistant programming environment. For example the IBM PCjr does not have a DMA memory controller. if your program directly controlls the diskette adaptor, and with it the DMA controller, it won't work on the PCjr. However, the diskette BIOS routine (interrupt 13H) has the same calling interface. A program that uses the BIOS interrupt for the diskette will still run correctly. At system initialization time, the ROM BIOS builds I/O parameter tables for some of the devices. (The diskette and video adapters are two examples.) If you want to modify a BIOS table for use by your program you should first make a copy of the table ,make your changes in the copy, and then change the vector table to point to the modified table. When your program finishes you should restore the vector table to its original value. This will maintain a consistant structure for BIOS, and will allow your program to restore the system correctly before it terminates. IBM has changed the BIOS tables in support of the PCjr. For example, some of the BIOS video parameters dealing with horizontal and vertical timings have changed. Unless you copy the existing table before making changes, you may unintentionally change other portions of the table. ROM BIOS and DOS do not provide for all devices and functions. Following is a list of the allowable I/O operations, that IBM will attempt to keep compatible in future systems. A program can control the sound by using port 61H and the sound channel of the Timer/Counter (see bleow) -- A program can control the 8253 Timer/Counter channels 0 and 2, ports 40H, 42H and 43H. Under no circumstances should a program change the value in port 41H of the IBM PC, since this channel of the timer controls dynamic memory refresh. The IBM PCjr uses a different method of refreshing memory, and channel 1 is used for extended timing and keyboard deserialization. Channel 0 provides the time of day interrupt, and can also be used for timing short intervals. Channel 2 of the timer/counter is the output for the speaker and cassette ports. This channel may also be used for timing short intervals, although it can't interrupt at the end of the period. The PCjr uses the same input clock frequency to these timer channels as does the IBM PC. Assembly language programs that require the measurement od short intervals should use these timers. -- A Program can use port 201H to control the game control adapter. This applies to both the IBM PC and the PCjr. Note: Programs should use the timer, rather than a program loop, to determine the delay on a resistive input. -- You can use the video status port (3BAH or 3DAH) to determine horizontal and vertical retrace times. The PCjr video controller is significantly different in its implementation than the IBM pC Color/Graphics adapter. This means that the programming for special display effects such as animation, will be different for the PCjr. In most cases the PCjr has extended capabilities to help the programmer. These facilities are unique to the PCjr, and are not available on other IBM presonal computers. -- You can program the asynchronous communications adapter and the 8250 chip for interrupt driven communication. You should use ROM BIOS for the initialization of the 8250 -- baud rate, parity stop bits and data bits. The input clock on the IBM PCjr is not identical to the input clock on the IBM PC. If you use BIOS for initialization, you are guarenteed that the correct baud rate will be set. If you set it yourself, it may be incorrect on the IBM PCjr. All other functions are identical on the PCjr. -- A program can use the Interrupt Mask Register (IMR), port 21H to selectively mask and unmask the hardware features. The IBMPCjr has maintained all of these hardware compatibility requirements. o Absolute Memory Locations -- Interrupt vectors (0H) -- A program may change the interrupt vectors to point at different processing routines. When a program changes an interrupt vector, it should retain the original value. If the interrupt (hardware or software) is not directed toward this device handler, the request should be passed on to the original interrupt handler. You can build a chain of interrupt handlers in this fashon. -- Video display buffers (B0000H and B8000H) -- For each mode of operation defined by the video display BIOS, the memory map will remain the same. For example, the bit map for 320x200 medium adressibility graphics mode of the color/graphics adapter will be retained on any future card that supports that mode. If the bit map is modified, a different mode number will be used. All IBM pCjr video modes that are identical to the Color/Graphics modes have an identical bit map and an identical BIOS interface. The new PCjr display modes have new mode values assigned to them (Refer to the discussion of the COLOR statement in the IBM PCjr BASIC manual, page 4-63). Notice that the PCjr hardware provides a display paging mechanism that lets your program write display information into segment B8000H, even though the refresh buffer is located in the system memory. This feature lets you do direct display control in your program identically on both the IBM PC and PCjr. -- ROM BIOS data area (40:0) -- Any variables in this data area will retain their current defenitions as long as it is reasonable to do so. However, it is possible that someday a variable may someday no longer have meaning in the system, and IBM may use the data area it occupies for other purposes. Therefore you should access all ROM BIOS data variables through BIOS calls and not by direct addressing. The ROM BIOS data area has changed in the IBM PCjr to include some new variables. All the old variables have retained their previous meanings. o Timing Dependencies A program that requires timing information should use either the time-of-day clock or the timing channels of the 8253 timer. The input frequency to the timer will be maintained at 1.19 MHz, providing a constant time reference. Program loops should be avoided. The IBM PCjr timer/counter has identical characteristics to those of the IBM PC. o Copy Protection Programs which use copy protection schemes should use the ROM BIOS diskette calls to read and verify the diskette. You can use any method to create the diskette. However you should also consider how you are going to modify a large number of replicated diskettes if you have to add a copy protection methodology. The verifying program can look at the diskette controller status bytes in the ROM BIOS data area for further information about any embedded errors. The IBM PCjr uses a diskette controller similar to the one used on the IBM Personal Computer. However, since the PCjr has no DMA, the diskette programming is done differently. ROM BIOS effectively masks these differences. Notice also that a copy protection scheme that relies on instruction timing (rather than diskette rotation timing) will not work correctly on the PCjr. o Program Relocatibility DOS programs must be relocatable. They should be insensitive to the size of DOS or their own load address. [ I wonder if Microsoft has fixed the FORMAT command so that it is now relocatable? -ed] A program's dynamic memory requirement should be known, and should be contiguous with the load module. Don't assume that all of memory is available to your program -- DOS 2.1 has memory allocation function calls that you can use. Also you should verify that your load module has sufficient memory in which to operate. 3. Machine Sensitive Code o Programs may use machine specific features, with the understanding that they will then be machine dependant. This may be a very reasonable choice for a program that desires the ultimate in performance or special effects. However, such a program will no longer be transportable to other machines in the IBM Personal Computer family. o You can write a program that uses machine specific features and still retains its compatibility. You can do this by writing the program for all types of machines that you intend to use it on. The program can test to determine which machine it is running on, and then configure itself appropriately. IBM has embedded a machine identification value in the ROM BIOS which is different for each machine: At absolute address FFFFE FFH IBM PC FEH IBM XT FDH IBM PCjr o You can also use this same technique for I/O adapters in the system. The BIOS call which determines machine type can also tell you what devices are attached to the system. In the future, if IBM adds new machines and I/O devices to the family, IBM will continue to provide methods for determining the specific machine type or I/O feature. -------