diff --git a/doc/sym1.sgml b/doc/sym1.sgml index 565f11e43..b97f94720 100644 --- a/doc/sym1.sgml +++ b/doc/sym1.sgml @@ -15,21 +15,40 @@ An overview over the Sym-1 runtime system as it is implemented for the cc65 C co Overview

-This file contains an overview of the Sym-1 runtime system as it comes with the cc65 C compiler. It describes the memory layout, Sym-1 specific header files, available drivers, and any pitfalls specific to the platform. +This file contains an overview of the Sym-1 runtime system as it comes with the cc65 C compiler. +It describes the memory layout, Sym-1 specific header files, available drivers, and any pitfalls +specific to the platform. -Please note that Sym-1 specific functions are just mentioned here, they are described in detail in the separate . Even functions marked as "platform dependent" may be available on more than one platform. Please see the function reference for more information. +Please note that Sym-1 specific functions are just mentioned here, they are described in detail +in the separate . Even functions marked as +"platform dependent" may be available on more than one platform. Please see the +function reference for more information. Binary format

-The output format generated by the linker for the Sym-1 target is a raw binary BIN file, which is essentially a memory image. You can convert this to a HEX file using BIN2HEX, which is a popular open-source conversion utility program. A HEX file has ASCII representations of the hexadecimal byte values of the machine-language program. So the HEX file can be transferred to the Sym-1 using the RS-232 terminal port, just as if the machine-code was entered by hand. Enter 'm 200' in the monitor and start the HEX file transfer. +The output format generated by the linker for the Sym-1 target is a raw binary BIN file, which +is essentially a memory image. You can convert this to a HEX file using BIN2HEX, which is a +popular open-source conversion utility program. A HEX file has ASCII representations of the +hexadecimal byte values of the machine-language program. So the HEX file can be transferred +to the Sym-1 using the RS-232 terminal port, just as if the machine-code was entered by hand. +Enter 'm 200' in the monitor and start the HEX file transfer.

-Included with this distribution is a 4k configuration file and a 32k config file. The Sym-1 on-board memory is limited to 4 kbytes but system memory can be increased to 32 kbytes of contiguous RAM with aftermarket add-on boards. So choose the config file that matches your system configuration before compiling and linking user programs. +Included with this distribution is a 4k configuration file and a 32k config file. The Sym-1 +on-board memory is limited to 4 kbytes but system memory can be increased to 32 kbytes of +contiguous RAM with aftermarket add-on boards. So choose the config file that matches your +system configuration before compiling and linking user programs. Memory layout

-The ROMs and I/O areas are defined in the configuration files, as are most of the entry points for useful subroutines in the Sym-1 monitor ROM. cc65 generated programs compiled and linked using 4k config run in the memory range of $200 - $0FFF. The 32k config expands this range to $7FFF. Memory above 32K can be used to extend the heap, as described below. The starting memory location and entry point for running the program is $200, so when the program is transferred to the Sym-1, it is executed by typing 'g 200'. The system returns control back to the monitor ROM when the program terminates, providing the '.' prompt. +The ROMs and I/O areas are defined in the configuration files, as are most of the entry points +for useful subroutines in the Sym-1 monitor ROM. cc65 generated programs compiled and linked +using 4k config run in the memory range of $200 - $0FFF. The 32k config expands +this range to $7FFF. Memory above 32k can be used to extend the heap, as described below. +The starting memory location and entry point for running the program is $200, so when the +program is transferred to the Sym-1, it is executed by typing 'g 200'. The system returns control +back to the monitor ROM when the program terminates, providing the '.' prompt. Special locations: @@ -38,10 +57,12 @@ Special locations: Conio support is not currently available for the Sym-1. But stdio console functions are available.

@@ -51,7 +72,8 @@ Programs containing Sym-1 code may use the Hardware access

-The pseudo variables declared in the Loadable drivers

@@ -61,7 +83,9 @@ No graphics drivers are currently available for the Sym-1. Extended memory drivers

-There are no extended memory drivers for the Sym-1. However, there is a way to access memory beyond the 32k boundary, if memory is physically present in the system. See the example program, symExtendedMemory, in the samples directory. +There are no extended memory drivers for the Sym-1. However, there is a way to access memory beyond the +32kb boundary, if extended memory is physically present in the system. See the example program, +symExtendedMemory, in the samples directory. Joystick drivers

@@ -73,7 +97,8 @@ No mouse drivers are currently available for the Sym-1. RS232 device drivers

-No communication port drivers are currently available for the Sym-1. It has only the "master console" e.g. stdin and stdout. +No communication port drivers are currently available for the Sym-1. It has only the "master console" +e.g. stdin and stdout. Limitations

@@ -94,23 +119,32 @@ To be more specific, this limitation means that you cannot use any of the follow Other hints

sym1.h

-This header exposes Sym-specific I/O functions that are useful for reading and writing its ports and front panel. See the Limited memory applications

-As stated earlier, there are config files for 4KB and 32KB systems. If you have 32KB RAM, then you will probably want to use the sym1-32k configuration, but if not - if you are using the sym1-4k configuration - then you may want to use functions like getchar, putchar, gets and puts rather than functions like scanf and printf. Printf, for example, requires about 1KB because it needs to know how to process all the format specifiers. +As stated earlier, there are config files for 4kb and 32kb systems. If you have 32kb RAM, then you will probably +want to use the sym1-32k configuration, but if not - if you are using the sym1-4k configuration - then you may +want to use functions like getchar, putchar, gets and puts rather than functions like scanf and printf. +Printf, for example, requires about 1KB because it needs to know how to process all the format specifiers. Using extended memory

-Memory may be physically present that is addressed at locations above the monitor ROM at $8000. This extended memory is accessible by adding to the heap, as described in the symExtendedMemory sample program. +Memory may be physically present that is addressed at locations above the monitor ROM at $8000. This extended +memory is accessible by adding to the heap, as described in the symExtendedMemory sample program. Sample programs

-All the samples will run on the "stock" 4KB Sym-1, except for symIO and symNotepad, which require 32KB. Additionally, symExtendedMemory shows how to access memory above 32KB, so it expects more than 32KB. These sample programs can be found in the samples/sym1 directory: +All the samples will run on the "stock" 4kb Sym-1, except for symIO and symNotepad, which require 32kb. +Additionally, symExtendedMemory shows how to access memory above 32kb, so it expects more than 32kb. +These sample programs can be found in the samples/sym1 directory: -symHello prints "Hello World!" and then inputs characters, which are echoed on the screen. It also makes a "beep" sound. -symTiny does the same as symHello, but does it with puts() rather than printf() to show the difference in compiled binary size. +symHello prints "Hello World!" and then inputs characters, which are echoed on the screen. + It also makes a "beep" sound. +symTiny does the same as symHello, but does it with puts() rather than printf() to show the difference + in compiled binary size. symDisplay allows entry of a message, which is then displayed by scrolling it across the front panel display. symIO allows access to the Sym-1 digital I/O ports. symNotepad is a simple text entry/retrieval program that uses tape storage. @@ -119,9 +153,11 @@ All the samples will run on the "stock" 4KB Sym-1, except for symIO an License

-This software is provided 'as-is', without any expressed or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. +This software is provided 'as-is', without any expressed or implied warranty. In no event will the authors be held +liable for any damages arising from the use of this software. -Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions: +Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter +it and redistribute it freely, subject to the following restrictions: The origin of this software must not be misrepresented; you must not diff --git a/samples/sym1/symExtendedMemory.c b/samples/sym1/symExtendedMemory.c index db0231236..cc01da353 100644 --- a/samples/sym1/symExtendedMemory.c +++ b/samples/sym1/symExtendedMemory.c @@ -26,12 +26,13 @@ #include #include -#define SEGMENT 0x9000 // First 4K segment of extended memory -#define SEG_END 0x0FFF // Last location of segment -#define BLOCK_SIZE 0x1000 // Size of segment -#define TOP_END 0x0F7F // Last location of memory -#define TOP_SIZE 0x0F80 // Size of top segment -#define UNAVAILABLE 0xA000 // System I/O area +#define STD_MEM 0x7FFF // Last address of standard memory +#define SEGMENT 0x9000 // First 4K segment of extended memory +#define SEG_END 0x0FFF // Last location of segment +#define BLOCK_SIZE 0x1000 // Size of segment +#define TOP_END 0x0F7F // Last location of memory +#define TOP_SIZE 0x0F80 // Size of top segment +#define UNAVAILABLE 0xA000 // System I/O area int main (void) { int error = 0; @@ -44,49 +45,54 @@ int main (void) { printf ( "Main memory has %u bytes available.\n", heap_size ); - while ( (int) segment < 0xEFFF ) { // Iterate through 4K memory blocks - if( (int) segment != UNAVAILABLE ) { - segment[0] = 0x00; // Check beginning of segment - if ( segment[0] != 0x00 ) - error = 1; - segment[0] = 0xFF; - if ( segment[0] != 0xFF ) - error = 1; - segment[SEG_END] = 0x00; // Check end of segment - if ( segment[SEG_END] != 0x00 ) - error = 1; - segment[SEG_END] = 0xFF; - if ( segment[SEG_END] != 0xFF ) - error = 1; - if ( ! error ) { // If memory found, add to the heap - printf ( "Memory found at location %p, ", segment ); - _heapadd ( segment, BLOCK_SIZE ); - heap_size = _heapmemavail(); - printf( "so the system now has %u bytes available.\n", heap_size ); - } else { - error = 0; - } - } - segment += 0x1000; // Increment to next segment - } + if ( heap_size > STD_MEM ) { + printf ( "Extended memory already installed.\n" ); + } else { - segment[0] = 0x00; // Check beginning of top memory segment - if ( segment[0] != 0x00 ) - error = 1; - segment[0] = 0xFF; - if ( segment[0] != 0xFF ) - error = 1; - segment[TOP_END] = 0x00; // Check end of usable memory - if ( segment[TOP_END] != 0x00 ) - error = 1; - segment[TOP_END] = 0xFF; - if ( segment[TOP_END] != 0xFF ) - error = 1; - if ( ! error ) { // If memory found, add to the heap - printf ( "Memory found at location %p, ", segment ); - _heapadd ( segment, TOP_SIZE ); - heap_size = _heapmemavail(); - printf( "so the system now has %u bytes available.\n", heap_size ); + while ( (int) segment < 0xEFFF ) { // Iterate through 4K memory blocks + if( (int) segment != UNAVAILABLE ) { + segment[0] = 0x00; // Check beginning of segment + if ( segment[0] != 0x00 ) + error = 1; + segment[0] = 0xFF; + if ( segment[0] != 0xFF ) + error = 1; + segment[SEG_END] = 0x00; // Check end of segment + if ( segment[SEG_END] != 0x00 ) + error = 1; + segment[SEG_END] = 0xFF; + if ( segment[SEG_END] != 0xFF ) + error = 1; + if ( ! error ) { // If memory found, add to the heap + printf ( "Memory found at location %p, ", segment ); + _heapadd ( segment, BLOCK_SIZE ); + heap_size = _heapmemavail(); + printf( "so the system now has %u bytes available.\n", heap_size ); + } else { + error = 0; + } + } + segment += 0x1000; // Increment to next segment + } + + segment[0] = 0x00; // Check beginning of top memory segment + if ( segment[0] != 0x00 ) + error = 1; + segment[0] = 0xFF; + if ( segment[0] != 0xFF ) + error = 1; + segment[TOP_END] = 0x00; // Check end of usable memory + if ( segment[TOP_END] != 0x00 ) + error = 1; + segment[TOP_END] = 0xFF; + if ( segment[TOP_END] != 0xFF ) + error = 1; + if ( ! error ) { // If memory found, add to the heap + printf ( "Memory found at location %p, ", segment ); + _heapadd ( segment, TOP_SIZE ); + heap_size = _heapmemavail(); + printf( "so the system now has %u bytes available.\n", heap_size ); + } } puts ("\nEnjoy your day!\n");