update doc to 2.2; improve pet graph kbd mapping

RELEASE.adoc

@@ -1,13 +1,16 @@
 
 = GECKOS RELEASE NOTES
 
-== GeckOS 2.2-b1
+== GeckOS 2.2
 
 === Applications
 * lsh got job control
 
 === Devices
 * new device for an NMI-driven ACIA-based RS232 (swiftlink)
+* the console device has been overhauled and got a better set of control character.
+	The C64 (and C128 VIC-II) now only have two consoles, but as a new feature they now include colour support.
+
 
 === Kernel
 * *GETINFO* now returns thread info, needs iterative calls (renamed to *GETINFO2*)
@@ -20,6 +23,9 @@
 
 ==== C128
 * There is a new port for the Commodore 128!
+	You can run it both from the VIC-II or the VDC screen of the Commodore BASIC.
+	This port uses the fast serial IEC bus when available (with a 1571/1581 disk drive),
+	and 2 MHz speed when started with the VDC display.
 
 === Build
 * Cleanup of build process, using a common dist folder for generic applications / disk images

arch/c128/devices/siec_c128.a65

@@ -225,7 +225,6 @@ atnin     jsr datalo
 */
 
 nodev     lda #$80
-;inc $d020
 error   pha
 	lda burst_flg
 	and #$7f
@@ -319,7 +318,6 @@ slowdrv
 
 	bit burst_flg
 	bpl txslow
-
 	lda byte
 	jsr fastout
 	jmp endtx

arch/cbm8x96/devices/con_pet.a65

@@ -33,12 +33,6 @@
 
 #define	MAX_SCREEN	3		/* number of supported virt. consoles */
 
-#ifdef PET_KEYB_GRAPHICS
-#define SWITCHKEY       79              /* graphics keyboard REV/OFF key */
-#else
-#define SWITCHKEY       39              /* business keyboard Tab key */
-#endif
-
 #define	SET_MMU		
 
 #define	BELLIRQ		jsr bellirq

arch/csa65/devices/con_csa.a65

@@ -32,11 +32,6 @@
 
 #define	MAX_ASCREEN	maxscr		/* soft limit (dep. on 40/80 cols) */
 
-#define	SWITCHKEY	79		/* Rev/off on graphics keyboard */
-; for VICE?
-;#define	SWITCHKEY	70		/* "@" */
-;#define	SWITCHNOSHIFT
-
 #define	SET_MMU		ldy #$10:sty MMU+VIDPAGE
 
 #define	BELLIRQ		jsr bellirq

arch/pet32k/devices/con_pet.a65

@@ -31,12 +31,6 @@
 
 #define	MAX_SCREEN	2		/* number of supported virtual consoles */
 
-#ifdef PET_KEYB_GRAPHICS
-#define	SWITCHKEY	79		/* graphics keyboard REV/OFF key */
-#else
-#define	SWITCHKEY	39		/* business keyboard Tab key */
-#endif
-
 #define	SET_MMU		
 
 #define	BELLIRQ		jsr bellirq

arch/pet32k/devices/kbd_pet.a65

@@ -21,6 +21,12 @@
 
 ****************************************************************************/
 
+#ifdef PET_KEYB_GRAPHICS
+#define SWITCHKEY       79              /* graphics keyboard REV/OFF key */
+;#define SWITCHKEY       70              /* graphics keyboard @ key */
+#else
+#define SWITCHKEY       39              /* business keyboard Tab key */
+#endif
 
 /**************************************************************************
  * Bell handling
@@ -132,18 +138,19 @@ ix1
           ldy #0
 #ifdef PET_KEYB_GRAPHICS
 	  tax
-          and #%00100000  ; right shift only
-          bne noshift
+          and #%00100001  ; right + left shift
+          cmp #%00100001
+          beq noshift
 #else
           and #%01000001
           cmp #%01000001
           beq noshift
 #endif
           iny
-noshift    ; no CTRL on graphics keyboard
+noshift   
 #ifdef PET_KEYB_GRAPHICS
-	  txa
-	  and #%00000001  ; left shift
+	; use both shifts together as Ctrl
+          cmp #0	; both bits are zero = both Shift
 #else
           inc PIO	; 7 for business
 x0        lda PIO+2
@@ -155,14 +162,14 @@ x0        lda PIO+2
           iny
           iny
 noctrl    
-#ifdef VICE		/* VICE bug that automatically sets both shift keys when only left is used */
+;#ifdef VICE		/* VICE bug that automatically sets both shift keys when only left is used */
 #ifdef PET_KEYB_GRAPHICS
 	  cpy #3
 	  bne novice
 	  dey
 novice
 #endif
-#endif
+;#endif
 	  sty shiftfl
           tya
           asl
@@ -273,13 +280,13 @@ stab      .asc TC_CLFT,TC_CLR,"|(&%#!",TC_INS,TC_CUP,"^@)\\'$":.byt $22
           .asc "31",TC_LF,";MBCZ+2^@?,NVX"
           .asc "-0^@>^@}@^@=.^@",TC_ESC,"< {", TC_HT
 
-ctab      .asc TC_WRU,TC_WCLS,"~(&%#!",TC_DEL,TC_WLO,"^@)\\'$",$22
+ctab      .asc TC_WRU,TC_WCLS,"~(&%#!",TC_DELL,TC_WLO,"^@)\\'$",$22
           .asc "97^^^o^u^t^e^q/8^@^p^i|^r^w"
           .asc "64^@^l^j^g^d^a*5^@:^k^h^f^s"
           .asc "31",TC_EOL,";^m^b^c^z+2^@?,^n^v^x"
           .asc "-0^@>^@]@^@=.^@",TC_CLL,"< [", TC_HT
 
-sctab     .asc "^@^@|(&%#!^H^@^@)\\'$":.byt $22
+sctab     .asc "^@^@|(&%#!", TC_INSL, "^@^@)\\'$":.byt $22
           .asc "97^^O^U^T^E^Q/8^@^P^I^Y^R^W"
           .asc "64^@^L^J^G^D^A*5^@:^K^H^F^S"
           .asc "31^m;^M^B^C^Z+2^@?,^N^V^X"

doc/c128.p.adoc

@@ -11,6 +11,11 @@ The Commodore 128 (C128) has two banks of 64k memory.
 The C128 port is based in parts on the C64 port (mostly devices), and the CS/A port due to the ability to 
 handle multiple environments.
 
+== Quickstart
+
+In the downloaded GeckOS directory, run *make runc128* to automatically build the *geckos128.d64* disk image in the *arch/c128/boot* directory, and autostart it in the VICE *x128* emulator, in 40 column mode.
+Alternatively, use *make runc128f* to build and run it in 2 MHz, 80 column mode with 1571 disk drive (enables fast serial IEC).
+
 == Memory Map
 
 The C128 uses shared memory on the top of memory, containing the kernel code, the kernel variables, and

doc/c64.p.adoc

@@ -7,24 +7,30 @@ c64 - describes the GeckOS port to the C64
 == DESCRIPTION
 The C64 is a machine that has a single environment with almost 60k usable RAM, and no memory management unit.
 
+== Quickstart
+
+In the downloaded GeckOS directory, run *make runc64* to automatically build the *gecko64.d64* disk image in the *arch/c64/boot* directory, and autostart it in the VICE *x64* emulator.
 
 == BUILDING
 To build the program, you have to have the 6502 cross assembler 'xa' in version 2.4.1 or later.
 Current testing takes place on 'VICE' (x64), the versatile Commodore emulator.
 
+You can just run *make runc64* to directly build it and start GeckOS in the VICE x64 emulator.
+This option builds a 'geckos64.d64' disk image and autostarts the emulator with it.
+
+Alternatively, go to the arch/c64/boot directory and type "make" this will build
+all necessary files in this directory, including links to all
+important applications. 
 In the file c64rom/c64rom.a65, a few options can be set by setting
 the defines appropriately. See doc/build.html.
 
-Go to the arch/c64/boot directory and type "make" this will build
-all necessary files in this directory, including links to all
-important applications. Typing "make osa.d64" will produce a
+Typing "make geckos64.d64" will produce a
 d64 disk image with all necessary files. This disk image can be
 transfered to a C64 and used.
 
 If you change something in the code and reassemble, check from the file65
-output that the data and bss segments don't overlap. Also the
-memory that is dynamically allocated starts at $1600 (see
-arch/c64/c64rom.a65). Only if nothing overlaps there is no danger.
+output that the data and bss segments don't overlap. 
+The memory that is dynamically allocated is automatically located at the end of the 'ROM' image.
 
 See also *build(7)*.
 
@@ -51,7 +57,7 @@ their places and jumps to the kernel RESET routine.
 When using osa.d64 in VICE, you have to enable the true1541 emulation.
 
 == USAGE
-The video device is able to handle up to three screen output windows.
+The video device is able to handle up to two screen output windows.
 The C= key switches between the different windows (You can change the
 switch key in arch/c64/devices/con_c64.a65, but when you're using
 the "C=" key, don't try to use the Ctrl-Alt-Fx keys in XFree when the
@@ -125,21 +131,23 @@ lsh::
 
 	$0300 		data/bss for ROM-based code 
 			(incl. kernel and lib6502)
-	$1680		start of malloc'able free memory
-	$81ff 		end of free memory
 
-	$8200		start of boot ROM
+	~$1790		end of data/bss for ROM code, i.e.
+			start of malloc'able free memory
+			(set as needed during build)
+	 ---
+	$8dff 		end of free memory
+
+	$8e00		start of boot ROM
 			devices
 			init
 			fsiec
-			mon
-			(slipd)
 			lsh
 			lib6502 code
 	$d000		I/O area
 	$e000		screen buffer 1
 	$e400		screen buffer 2
-	$e800		screen buffer 3
+	$e800		colour buffer for not displayed screen
 	$ec00		kernel
 	$ffff		end of ROM
 ----
@@ -174,11 +182,13 @@ The C64 kernel uses the VIC-II raster timing interrupt as a 50Hz interrupt sourc
 This section describes the devices supported by GeckOS.
 
 === VIDEO
-The video device provides three virtual consoles.
+The video device provides two virtual consoles.
 
 ==== VIDEO OUTPUT
 Video output is taken from the video buffers at $exxx (see memory map above), with a 40 column, 25 rows display,
 using the C64's built-in VIC-II chip.
+Since GeckOS 2.2, the console has colour support, i.e. the character foreground colour can be set
+using terminal control codes, see 'include/tcdefs.i65'.
 
 ==== KEYBOARD MAPPING
 The keyboard is mapped such that it can run on the real hardware, but also in the real machine.
@@ -198,8 +208,8 @@ Here is a comparison of the real machine, VICE and what GeckOS uses.
 |GeckOS|C64|VICE on PC (3.4+)
 |Ctrl | Ctrl | Left Ctrl 
 |Tab  | C=   | Tab
-|Console switch | Ctrl + C= | Left Ctrl + Tab 
-|Console mode | Shift + C= | Shift + Tab 
+|Console switch | Ctrl + C= | Shift + Tab 
+|Console mode | Shift + C= | Left Ctrl + Tab 
 |Logoff  | Shift + Ctrl + C= | Shift + Left Ctrl + Tab 
 |\| | Pound | \| 
 |====

doc/cbm8x96.p.adoc

@@ -2,15 +2,19 @@
 :doctype: manpage
 
 == NAME
-OS/A65 CBM 8x96 Notes
+GeckOS/A65 CBM 8x96 Notes
 
 == DESCRIPTION
 The Commodore PET 8096 and 8296 (also known as CBM 8096 and CBM 9296) computers
 have at least 96 kByte of RAM and can remap the ROM area with RAM. This 
-makes them a nice base for OS/A65. Although they don't have many I/O devices
+makes them a nice base for GeckOS/A65. Although they don't have many I/O devices
 at least they provide an 80 columns screen.
 
-The CBM8296 port is based on the PET 32k port regarding the types of devices and interrupt handling. But the memory management is considerably different, as shown in the next section.
+The CBM8296 port is based on the PET 32k port regarding the types of devices and interrupt handling. But the memory management is considerably different, as shown in a later section.
+
+== Quickstart
+
+In the downloaded GeckOS directory, run *make runcbm8x96* to automatically build the *geckos8x96.d64* disk image in the *arch/cbm8x96/boot* directory, and autostart it in the VICE *xpet* emulator.
 
 == Memory Map
 

doc/console.7.adoc

@@ -0,0 +1,105 @@
+= GeckOS/A65 Consoles
+Version 2.2 (c) 1989-2024 André Fachat 
+
+== Introduction
+
+GeckOS provides multiple virtual consoles on all architectures that support it (i.e. usually have a screen output device).
+
+The console provides two screen modes, and a number of terminal control codes that are explained below.
+
+== Console modes
+
+The first mode is *direct mode* - all key presses are directly send to the program, and only program output is printed on the screen.
+
+The second is *full screen mode*. The cursor can be moved freely on the screen, and keyboard control codes are directly executed in the console. Only when pressing the enter key the content of the line is sent to the stream.
+
+The modes can be switched with a specific input key combination.
+
+== Keyboard codes 
+
+These are common functions for the keyboard input of the console.
+
+=== Switch key
+
+The console defines a so-called *switch key* that is used for various console functions, together with *shift*, *ctrl*, or *shift+ctrl*:
+
+* *Shift* + switchkey: switch between the console
+* *Ctrl* + switchkey: switch console modes
+* *Shift* + *Ctrl* + switchkey: logoff (close the device streams from the device side)
+
+=== Keyboard control code input
+
+Normal key characters can be entered without modifier as lower case ASCII. With *Shift* the keys result in upper case ASCII. With *Ctrl* the keys are masked to the lower 5 bits, i.e. *Ctrl* +A results in code *1* to be sent to the stream.
+
+The keyboard allows to enter a number of control codes. In direct mode, these are directly sent to the stream, and the connected program can / needs to handle them itself. In full screen mode, these are printed and executed on the console and not sent to the screen:
+
+* *Home* - position the cursor in the top left corner of the window
+* *Shift* + *Home* - clear the screen
+* *Backspace* - delete character left of cursor
+* *Shift* + *Backspace* = *Insert* - insert a character
+* *Ctrl* + *Backspace* - delete a line
+* *Shift* + *Ctrl* + *Backspace* - insert a line
+
+* *Ctrl*-Down - defined the upper left window corner as the current cursor position
+* *Ctrl*-Right - defined the lower right window corner as the current cursor position
+* *Ctrl*-Home - clear the window definition
+
+Note that some ports (mainly the PET32k with graphics keyboard) do not provide the capability to
+use *Shift* and *Ctrl* together.
+
+== Output control codes
+
+The following codes are defined in *include/tcdefs.i65*:
+
+----
+/*        Terminal Commands        */
+
+TC_BEL          =7              ; ring the bell tone
+TC_BS           =8              ; backspace
+TC_HT           =9              ; horizontal tab (4 chars)
+TC_LF           =10             ; line feed
+TC_VT           =11             ; vertical tab
+TC_FF           =12             ; form feed (clear scr)
+TC_CR           =13             ; carriage return
+TC_ESC          =27             ; escape
+
+TC_CLFT         =$80            ; cursor left
+TC_CRGT         =$81            ; cursor right
+TC_CUP          =$82            ; cursor up
+TC_CDWN         =$83            ; cursor down
+TC_HOME         =$84            ; cursor home (top left of window)
+TC_CLR          =$85            ; clear window (FF)
+TC_DEL          =$86            ; delete char under cursor
+TC_INS          =$87            ; insert space under cursor
+TC_WLO          =$88            ; define cursor pos as top left win corner
+TC_WRU          =$89            ; define cursor pos as bottom right win corner
+TC_WCLS         =$8a            ; clear window definition
+TC_EOL          =$8b            ; move behind last non-space in line
+TC_CLL          =$8c            ; clear from cursor to end of line
+TC_DELL         =$8d            ; delete line where cursor is
+TC_INSL         =$8e            ; insert empty line under cursor
+
+TC_ECHO         =$8f    	; device shall echo: terminal = full screen 
+TC_NOECHO       =$90    	; appl. echos: full appl. control 
+
+TC_CPOS         =$91            ; set cursor pos - next chars are row and col
+
+TC_ATTR         =$92            ; next byte is attribute for display
+
+TC_FGCOL        =$93            ; next byte is foreground colour
+
+TC_HELP         =$9c            ; C128 HELP key
+TC_ALT          =$9d            ; C128 ALT key
+TC_NOSCRL       =$9e            ; C128 NO SCROLL key
+
+----
+
+=== Window definition example
+
+The consoles have a single layer of sub-window definition handling.
+I.e. once a window is defined, all operations like scrolling are restricted to the console window.
+
+
+
+
+Last modified 20 may 2024 by A. Fachat