MediaWiki:Sitenotice:
2024-03-02: The wiki ran out of disk space, so things were not working. This has been resolved by adding another 5GB of quota ;-) Thanks to Tim Lindner for reporting the issues.
2020-05-17: If a page gives you an error about some revision not being found, just EDIT the page and the old page should appear in the editor. If it does, just SAVE that and the page should be restored. OS-9 Al (talk) 12:22, 17 May 2020 (CDT)
OS-9
| WELCOME |
|---|
| Looking for CoCo help? If you are trying to do something with your old Color Computer, read this quick reference. Want to contribute to this wiki? Be sure to read this first. This CoCo wiki project was started on October 29, 2004. --OS-9 Al |
See Recent Changes. | About this site. | Join the E-Mail List or Facebook Group. | Contact me with updates/questions.
This page was last updated on 11/26/2013. Total Pages: 744. Total Files: 994.
Home / Programming - OS-9
Programming the 6809 using OS-9
OS9 Assembly Language
The OS9 Level I Assembler
The actual machine instructions executed by a computer are sequences of binary numbers that are difficult and inconvenient for people to deal with directly. Creating a machine language program of any length ny hand is tedious, error prone, and time consuming, making it an almost impossible task. Assembly language bridges the gap between computers and people who must write machine-language programs. In assembly language, descriptive mnemonics (abbreviations) for each machine instruction are used which are much easier to learn, read, and remember, are used instead of numerical codes. The assembler also lets the programmer assign sybolic names to memory addresses and constant values. The assembler also has many other features to make assembly language programming easier
This assembler was designed expressly for the modular, multi-tasking enviroment of the OS-9 Operating System, and incorporates built-in functions for calling OS-9, generating memory modules, encouraging the creation of position-independant code, and maintaining seperate program and data sections. It has also been optimized for the use by OS-9 high-level language compilers such as Pascal and C, and can be used on either OS-9 Level 1 or OS-9 Level 2 systems.
Another noteworthy characteristic of this assembler is it's extremely fast assembly speed which is attributable to it's tree-structured symbol table organization. The tree structure dramatically reduces symbol table searching, which is the most time consuming operation performed bay an assembler
The OS-9 Level Two Relocatable Macro Assembler
RMA is a full-featured relocatable macro assembler and linkage editor designed to be used by advanced programmers or with compiler systems.
RMA lets you assemble sections of assembly-language programs independently to create relocatable object files. The linkage editor, RLINK, takes any number of program sections and/or library sections, and combines them into a single OS-9 memory module RMA's features include:
- OS-9 modular, multi-tasking environment support
- Built-in functions for calling OS-9 system routines
- Position-independent, re-entrant code support
- Creating of standard subroutine libraries by allowing programs to be written and assembled separately and then linked together.
- Macro capabilities
- OS-9 Level Two compatibility
- Automatic resolution of global data and program references
- Conditional assembly and library source file support
OS-9 Pascal
About 0S-9 PASCAL
From the OS-9 Pascal Manual
The internal operation of a language as powerful as Pascal must be relatively complex, and running Pascal programs can be quite demanding of the computer. Therefore, microcomputer versions of Pascal traditionally have been quite limited and much slower than their big computer cousins. The gap has been narrowed considerably in 0S-9 Pascal because of two factors. The first factor is the 6809 microprocessor, which was specifically designed to efficiently execute high-level languages such as Pascal. The second factor is the part of 0S-9 Pascal called "PascalS", which allows the Pascal system to utilize disk space as "virtual memory". Being able to utilize disk space as "virtual memory" means that you can run Pascal programs that are much larger than the actual memory size. Indeed, a Pascal compiler as complete as the 0S-9 Pascal compiler would otherwise be too big to fit in your computer's memory.
One other unusual characteristic of 0S-9 Pascal is its ability to compile and run programs in either "P-code" or "native code" forms. "P-codes" are instructions particularly created for an ideal , imaginary "Pascal Computer". The 6809 can't directly execute P-code instructions, so a program called a "P-code interpreter" is used to simulate the ideal "Pascal Computer". Most microcomputer versions of Pascal use the P-code concept because it simplifies the design of the compiler and makes most effic1ient use of a limited amount of memory. Another plus for P-code is that while programs are running, the P-code interpreter can perform thorough error checks and can give excellent diagnostic messages.
Using P-code, the execution speed of programs is relatively slow compared to true machine language. Each P-code instruction causes actual machine language instructions to be run in the interpreter program (which are "overhead" and not actually needed to carry out the original Pascal program). 0S-9 Pascal provides a unique solution to this problem by means of a program called a "native code translator". The native code translator takes a P-code program and translates it to 6809 assembly language (machine language) source code. Both the P-code and the native code forms of the program work exactly the same way - except that the native code version will run from four to ten times faster! And because the output of the translator is a text file that is processed by the standard 0S-9 assembler, you can examine or manually edit it if you wish.
Why even bother with P-code? One reason is that very big programs will only fit in your computer in P-code form. While Pcode is not as fast as native code, in many cases speed is not an important enough factor to bother with the optional translation step. Perhaps the main value of P-code is its use in program debugging because the P-code interpreter has more comprehensive error checking and diagnostics. Typically, 0S-9 Pascal users debug programs in p-code form and translate to native code as a final step.
OS-9 "C" Programming Language
Introduction
From The C Compiler's User Manual
C was originally developed at the Bel Telephone Laboratories as an implementation language for the UNIX operating system by Brian Kernighan and Dennis Ritchie. They also wrote a book titled The C Programming Language which is universally accepted as the standard for the language. It is an interesting reflection on the language that although no formal industry-wide "standard" was ever developed for C, programs written in C tend to be far more portable between radically different computer systems as compared to so-called "standardized" languages such as BASIC, COBOL, and PASCAL. The reason C is so portable is that the language is so inherently expandable that if some special function is required, the user can create a portable extension to the language, as opposed to the common practice of adding additional statements to the language. For example, the number of special-purpose BASIC dialects defies all reason. A lesser factor is the underlying UNIX operating system, which is also sufficiently versatile to discourage nonstandardization of the language. Indeed, standard C compilers and UNIX are intimately related. Fortunately, the 6809 microprocessor, the OS-9 operating system, and the C language form an outstanding combination. The 6809 was specifically designed to efficiently run high-level languages, and its stack-oriented instruction set and versatile repertoire of addressing modes handle the C language very well. As mentioned previously, UNIX and C are closely related, and because OS-9 is derived from UNIX, it also supports C to the degree that almost any application written in C can be transported from a UNIX system to an OS-9 system, recompiled, and corrected executed.
The Language Implementation
OS-9 C is implemented almost exactly as described in The C Programming Language by Kernighan and Ritchie (hereafter referred to as K&R). A copy of this book, which serves as the language reference manual, is included with each software package. Although this version of C follows the specification faithfully, there are some differences. The differences mostly reflect parts of C that are obsolete or the constraints imposed by memory size limitations.
Differences From the K&R Specification
- Bit fields are not supported.
- Constant expressions for initializers may include arithmetic operators only if all the operands are of type int or char.
- The older forms of assignment operators, =+ or =*, which are recognized by some C compilers, are not supported. You must use the newer forms, +=, *=, etc.
- "#ifdef (#ifndef) ... [#else...] #endif" is supported but "#if <constant expression>" is not.
- It is not possible to extend macro definitions or strings over more than one line of source code.
- The escape sequence for newline '\n' refers to the ASCII carriage return character (used by OS-9 for end-of-line), not linefeed (hex 0A). Programs which use '\n' for end-of-line (which includes all programs in K&R) will still work properly.
Enhancements and Extensions
The "Direct" Storage Class
The 6809 microprocessor instruction for accessing memory via an index register or the stack pointer can be relatively short and fast when they are used in C programs to access "auto" (function local) variables or function arguments. The instructions for accessing global variables are normally not so nice and must be four-bytes long and correspondingly slow. However, the 6809 has a nice feature which helps considerably. Memory, anywhere in a single page (256 byte block), may be accessed with fast, two byte instructions. This is called the "direct page", and at any time its location is specified by the contents of the "direct page register" within the processor. The linkage editor sorts out where this should be, and it need not concern the program, who only needs to specify for the compiler which variables should be in the direct page to give the maximum benefit in code size and execution speed. To this end, a new storage class specifier is recognized by the compiler. In the manner of K&R page 192, the sc-specifier list is extended as follows:
Sc-specifier:
- auto
- static
- extern
- register
- typedef
- direct (extension)
- extern direct (extension)
- static direct (extension)
The new keyword may be used in place of one of the other sc-specifiers, and its effect is that the variable will be placed in the direct page. direct creates a global direct page variable. extern direct references an external-type direct page variable and static direct creates a local direct page variable. These new classes may not be used to declare function arguments. "Direct" variables can be initialized but will, as with other variables not explicitly initialized, have the value zero at the start of program execution. 255 bytes are available in the direct page (the linker requires one byte). If all the direct variables occupy less than the full 255 bytes, the remaining global variables will occupy the balance and memory above if necessary. If too many bytes of storage are requested in the direct page, the linkage editor will report an error, and the programmer will have to reduce the use of direct variables to fit the 256 bytes addressable by the 6809.
It should be kept in mind that direct is unique to this compiler, and it may not be possible to transport programs written using direct to other environments without modification.
Embedded Assembly Language
As versatile as C is, occasionally there are some things that can only be done (or done at maximum speed) in assembly language. The OS-9 C compiler permits user-supplied assembly-language statements to be directly embedded in C source programs.
OS-9 Basic09
From the Basic09 manual: Basic09 is an enhanced structured BASIC language programming system specially created for the 6809 Advanced Microprocessor. In addition to the standard BASIC language statements and functions, Basic09 includes many of the most useful elements of the Pascal programming language so that programs can be modular, well-structured, and use sophisticated data structures. It also permits full access to almost all of the OS-9 Operating System commands and functions so it can be used as a systems programming language. These features make Basic09 an ideal language for many applications: scientific, business, industrial control, education and more.
Basic09 is unusual in that it is an Interactive Compiler that has the best of both kinds of language system: it gives the fast execution speed typical of compiler languages plus the ease of use and memory space efficiency typical of interpreter languages. Basic09 is truly a complete programming system that includes a powerful text editor, multi-pass compiler, run-time interpreter, high-level interactive debugger, and a system executive. Each of these components was carefully integrated so the user "sees" a friendly, highly interactive programming resource that provides all the tools and helpful "extra" facilities needed for fast, accurate creation and testing of structured programs.
Basic09 Comparisons
Basic09 RunB GFX GFX2 Inkey SysCall
============ ============ ========= ========== ======= =======
OS-9 Dragon Level 1 5AB5 (23221) <do not have any of these from the Dragon version>
OS-9 Level 1 5ACC (23244) 2F99 (12185) 1F5 (501) <N/A> 5E (94) <N/A>
OS-9 Level 2 5ACC (23244) 2F99 (12185) 1F5 (501) 8CA (2250) 5F (95) 63 (99)
NitrOS-9 Level 1 5A29 (23081) 2FA7 (12199) 1F5 (501) <N/A> 5F (95) 63 (99)
NitrOS-9 Level 2 6809 5A29 (23081) 2FA7 (12199) 1F5 (501) 8CA (2250) 5F (95) 63 (99)
NitrOS-9 Level 2 6309 5955 (22869) 2FA7 (12199) 1F5 (501) 8CA (2250) 5F (95) 63 (99)
============ ============ ========= ========== ======= =======
(Dragon) (6809) (6309)
OS9 Level 1 OS9 Level 1 NOS9 Level 1 OS9 Level 2 NOS9 Level 2 NOS9 Level 2
============ ============ ============ ============ ============ ============
Basic09 5AB5 (23221) 5ACC (23244) 5A29 (23081) 5ACC (23244) 5A29 (23081) 5955 (22869)
RunB ??? 2F99 (12185) 2FA7 (12199) 2F99 (12185) 2FA7 (12199) 2FA7 (12199)
GFX ??? 1F5 (501) 1F5 (501) 1F5 (501) 1F5 (501) 1F5 (501)
GFX2 ??? <N/A> <N/A> 8CA (2250) 8CA (2250) 8CA (2250)
Inkey ??? 5E (94) 5F (95) 5F (95) 5F (95) 5F (95)
SysCall ??? <N/A> 63 (99) 63 (99) 63 (99) 63 (99)
============ ============ ============ ============ ============ ============
Comparisons are between OS-9 Level 1 and OS-9 Level 2 versions. All values in hex in case I have it backwards: MSB LSB 10 00 20 00 BASIC09: ======= The difference between Level 1 and Level 2 Basic09 is a 4K data buffer. Level 1 Basic09 has a default workspace size of 4K, and Level 2 has a default workspace size of 8K. Module differences include the MSB of the module header Runtime Variable Storage Size field, the revision number bump to 1, and the module CRC. RUNB: ==== The Level 1 and Level 2 RunB has the same differences as Basic09. SYSCALL: ======= Level 1 did not include SysCall, and if it had, it would have been named with all caps (SYSCALL), as all of the modules on the disk are in all caps, including Basic09. INKEY: ===== The Level 1 Inkey subroutine has 4 bytes that are different from, plus the CRC, and is 1 byte smaller than the Level 2 version (name reference includes the hi- bit set last character): Header differences: Module Size changed from 005E to 005F Module Attributes/Revision changed from 81 to 80 1st field after Header Parity changed from 0012 to 0013 The Edition byte (the first byte after the module name) is a value of 01, and it is the reason the Level 2 version is 1 byte longer than the Level 1 version. It was inserted here in the level 2 version of Inkey. The CRC values differ: 1A6916 as compared to FE0637 GFX: === According to the module header definition, the 8th and 9th bytes are the Attributes/Revision byte and the Header Parity byte. They are changed from 81 and EC in the Level 1 version to 80 and ED in the Level 2 version. The CRC values differ: DDC98B as compared to C29373 This concludes the immediate comparisons of the Level 1 and Level 2 versions of Basic09. Other than the differences stated above, both versions are identical. SysCall was not included on the Level 1 Basic09 diskette as sold by Radio Shack/Tandy. It is my understanding that a assembly source listing for SysCall exists somewhere in the OS-9 manuals. I will modify this document when I have that listing.
CoCo OS-9 Level 1 Basic09 comparison to Dragon OS-9 Level 1 Basic09: (CoCo value is listed first) header differences: Module Size is changed from 5ACC to 5AB5 Module Header Parity changed from A8 to D1 1st int after Header Parity changed from 07C1 to 07AA 3rd int after Header Parity changed from 00DC to 00C5 4th int after Header Parity changed from 1CA5 to 1C8E 5th int after Header Parity changed from 255A to 2543 6th int after Header Parity changed from 31E8 to 31D1 7th int after Header Parity changed from 3C09 to 3BF2 8th int after Header Parity changed from 5084 to 506D 0039-52 RS VERSION 01.00.00. removed from Dragon version 00B7-C1 TANDY CORP changed at 009B-A9 to DRAGON DATA LTD 0822 DD changed at 080B to F4 082D DF changed at 0816 to F6 08A9 7A changed at 0892 to 91 08AF 6B changed at 0898 to 82 CRC value at 5AC9 C5054F changed at 5AB2 to E3C48D This concludes the CoCo and Dragon version comparisons. I do not understand the differences in the code as yet.
Source Listings: Inkey listing from Basic09 Level 1 Programming manual Revision F February 1983 Appendix A: Sample Programs: pp.107-108 (spacing between fields added by me) *************** * INKEY - a subroutine for BASIC09 by Robert Doggett * Called by: RUN INKEY(StrVar) * RUN INKEY(Path, StrVar) * Inkey determines if a key has been typed on the given path * (Standard Input if not specified), and if so, returns the next * character in the String Variable. If no key has been type, the * null string is returned. If a path is specified, it must be * either type BYTE or INTEGER. 0021 TYPE set SBRTN+OBJCT 0081 REVS set REENT+1 0000 87CD005E mod InKeyEnd,InKeyNam,TYPE,REVS,InKeyEnt,0 000D 496E6B65 InKeyNam fcs "Inkey" D 0000 org 0 Parameters D 0000 Return rmb 2 Return addr of caller D 0002 PCount rmb 2 Num of params following D 0004 Param1 rmb 2 1st param addr D 0006 Length1 rmb 2 size D 0008 Param2 rmb 2 2nd param addr D 000A Length2 rmb 2 size 0012 3064 InKeyEnt leax Param1,S 0014 EC62 ldd PCount,S Get parameter count 0016 10830001 cmpd #1 just one parameter? 001A 2717 beq InKey20 ..Yes; default path A=0 001C 10830002 cmpd #2 Are there two params? 0020 2635 bne ParamErr No, abort 0022 ECF804 ldd [Param1,S] Get path number 0025 AE66 ldx Length1,S 0027 301F leax -1,X byte available? 0029 2706 beq InKey10 ..Yes; (A)=Path number 002B 301F leax -1,X Integer? 002D 2628 bne ParamErr ..No; abort 002F 1F98 tfr B,A 0031 3068 InKey10 leax Param2,S 0033 EE02 InKey20 ldu 2,X length of string 0035 AE84 ldx 0,X addr of string 0037 C6FF ldb #$FF 0039 E784 stb 0,X Initialize to null str 003B 11830002 cmpu #2 at least two-byte str? 003F 2502 blo InKey30 ..No 0041 E701 stb 1,X put str terminator 0043 C601 InKey30 ldb #SS.Ready 0045 103F8D OS9 I$GetStt is there an data ready? 0048 2508 bcs InKey90 ..No; exit 004A 108E0001 ldy #1 004E 103F89 OS9 I$Read Read one byte 0051 39 rts 0052 C1F6 InKey90 cmpb #E$NotRdy 0054 2603 bne InKeyErr 0056 39 rts (carry clear) 0057 C638 ParamErr ldb #E$Param Parameter Error 0059 43 InKeyErr coma 005A 39 rts 005B 1A6926 emod 005E InKeyEnd equ *
Inkey listing from Level 2 Basic09 Reference
Appendix B: The Inkey Program: pp.B-1,B-2
This listing has differences from the listing in the Level 1 manual.
***************
* INKEY - a subroutine for BASIC09 by Robert Doggett
* Called by: RUN INKEY(StrVar)
* RUN INKEY(Path, StrVar)
* Inkey determines if a key has been typed on the given path
* (Standard Input if not specified), and if so, returns the next
* character in the String Variable. If no key has been type, the
* null string is returned. If a path is specified, it must be
* either type BYTE or INTEGER.
NAM INKEY
IFP1
USE /D0/DEFS/OS9DEFS
ENDC
0021 TYPE set SBRTN+OBJCT
0081 REVS set REENT+1
0000 87CD005E mod InKeyEnd,InKeyNam,TYPE,REVS,InKeyEnt,SIZE
000D 496E6B65 InKeyNam fcs "Inkey"
D 0000 org 0 Parameters
D 0000 Return rmb 2 Return addr of caller
D 0002 PCount rmb 2 Num of params following
D 0004 Param1 rmb 2 1st param addr
D 0006 Length1 rmb 2 size
D 0008 Param2 rmb 2 2nd param addr
D 000A Length2 rmb 2 size
000C E$Param equ $38
000E SIZE equ *
0012 3064 InKeyEnt leax Param1,S
0014 EC62 ldd PCount,S Get parameter count
0016 10830001 cmpd #1 just one parameter?
001A 2717 beq InKey20 ..Yes; default path A=0
001C 10830002 cmpd #2 Are there two params?
0020 2635 bne ParamErr No, abort
0022 ECF804 ldd [Param1,S] Get path number
0025 AE66 ldx Length1,S
0027 301F leax -1,X byte available?
0029 2706 beq InKey10 ..Yes; (A)=Path number
002B 301F leax -1,X Integer?
002D 2628 bne ParamErr ..No; abort
002F 1F98 tfr B,A
0031 3068 InKey10 leax Param2,S
0033 EE02 InKey20 ldu 2,X length of string
0035 AE84 ldx 0,X addr of string
0037 C6FF ldb #$FF
0039 E784 stb 0,X Initialize to null str
003B 11830002 cmpu #2 at least two-byte str?
003F 2502 blo InKey30 ..No
0041 E701 stb 1,X put str terminator
0043 C601 InKey30 ldb #SS.Ready
0045 103F8D OS9 I$GetStt is there an data ready?
0048 2508 bcs InKey90 ..No; exit
004A 108E0001 ldy #1
004E 103F89 OS9 I$Read Read one byte
0051 39 rts
0052 C1F6 InKey90 cmpb #E$NotRdy
0054 2603 bne InKeyErr
0056 39 rts (carry clear)
0057 C638 ParamErr ldb #E$Param Parameter Error
0059 43 InKeyErr coma
005A 39 rts
005B 1A6926 emod
005E InKeyEnd equ *