nolist      ;Source for Maxam assembler - 'OS-LIB.MAX'
nocode
org   &8000 ;File has   / org &8000 only for testing purposes
limit &9FFF ;669 lines /  Please change in a way you like it


; FutureOS LIBrary (to program a CPC and to access OS features)
; a collection of little functions, free to be used by everybody ;-)
;
; How to use this Library?
; Copy & paste functions in your own source code!
;
; Provided functions don't have a RETurn command, because you will probably
; put them directly in your source code (like a MACRO)

; **********************
; *                    *
; * Every Bit coded by *
; *                    *
; * >>The Future Man<< *
; *   of Future Soft   *
; *                    *
; * Ver. 0.4 12/1/2024 *
; *                    *
; **********************


;General EQUates

BB EQU &88 ;any 8 Bit value &00-&FF /// Enter correct value for BB in Source!
NN EQU &88 ;any 8 Bit value &00-&FF /// Enter correct value for NN in Source!


;EQUates (from file #EQU-API.)

;RAM variables
;
RAMCHAR EQU &B847
AKT_ROM EQU &B84A
AKT_RAM EQU &B84C
TURBO_A EQU &B858
REG_PC  EQU &B8DA
REG08_4 EQU &B8E0
REG16_3 EQU &B8EA
KF_CPC  EQU &B976
MO_ST   EQU &B97F
BORDER  EQU &BB91
INK_0   EQU &BB92
INK_1   EQU &BB93
INK_2   EQU &BB94
INK_3   EQU &BB95


;ROM entrys (in all ROMs equal)
;
ROM_A   EQU &FF00 ;ROMs A-M
ROM_C   EQU &FF0C
ROM_D   EQU &FF12
ROM_A2C EQU &FF2A


;ROM A entries
;
H_ALLET EQU &C02F
TST_TS  EQU &C5FA
S64X32  EQU &D5A8
S80X25  EQU &D60E


;ROM C entries
;
LESC   EQU &C017
WATA   EQU &FD38
LADE_N EQU &FD5C


;ROM D entries
;
KLICK EQU &FE9A
TUR_E EQU &FE9D 
TUR_D EQU &FEA0 


;---=== Set screen MODE 0-3 // Set Lower ROM/RAM-Status ===---;

;Switch to screen mode 0
;
;changes AF, B

 LD  A,(RAMCHAR) ;actual mode
 AND A,&FC
 LD  (RAMCHAR),A ;set mode 0
 LD  B,&7F
 OUT (C),A


;Switch to screen mode 1
;
;changes AF, B

 LD  A,(RAMCHAR)
 SET 0,A
 RES 1,A
 LD  (RAMCHAR),A
 LD  B,&7F
 OUT (C),A


;Switch to screen mode 2
;
;changes AF, B

 LD  A,(RAMCHAR)
 RES 0,A
 SET 1,A
 LD  (RAMCHAR),A
 LD  B,&7F
 OUT (C),A


;Switch to SECRET screen mode 3
;
;changes AF, B

 LD  A,(RAMCHAR)
 OR  A,&03
 LD  (RAMCHAR),A
 LD  B,&7F
 OUT (C),A


;Switch RAM char set on = lower RAM on
;
;changes AF, B

 LD  A,(RAMCHAR) ;actual RAM/ROM state
 RES 2,A
 LD  (RAMCHAR),A ;set L-RAM on
 LD  B,&7F
 OUT (C),A


;Switch ROM char set off = lower ROM off
;
;changes AF, B

 LD  A,(RAMCHAR) ;actual RAM/ROM state
 SET 2,A
 LD  (RAMCHAR),A ;set L-ROM off
 LD  B,&7F
 OUT (C),A


;---=== Set Screen Colors of Border, Paper and Pens // CLear Screen ===---;

;For selecting a COLOR please use hardware numbers, see table HWFW

;set BORDER color
;
;changes AF, BC

 LD  BC,&7F10 ;border
 OUT (C),C
 LD  A,NN       ;new hardware border color &40-&5F
 OUT (C),A      ;see table
 LD  (BORDER),A ;write color in RAM


;set PAPER color
;
;changes AF, BC

 LD  BC,&7F00 ;INK 0
 OUT (C),C
 LD  A,NN       
 OUT (C),A
 LD  (INK_0),A ;new hardware paper color &40-&5F


;set PEN 1 color
;
;changes AF, BC

 LD  BC,&7F01 ;INK 1
 OUT (C),C
 LD  A,NN       
 OUT (C),A
 LD  (INK_1),A ;new INK 1 color &40-&5F


;set PEN 2 color
;
;changes AF, BC

 LD  BC,&7F02 ;INK 2
 OUT (C),C
 LD  A,NN       
 OUT (C),A
 LD  (INK_2),A ;new INK 2 color &40-&5F


;set PEN 3 color
;
;changes AF, BC

 LD  BC,&7F03 ;INK 3
 OUT (C),C
 LD  A,NN       
 OUT (C),A
 LD  (INK_3),A ;new INK 3 color &40-&5F


;CLear Screen CLS
;
;changes AF, BC, DE, HL, &C000-&FFFF

 LD   BC,(&FF0D)   ;Physical number of FutureOS ROM C
 OUT  (C),C
 LD   (AKT_ROM),BC ;switch ROM C on
 CALL LESC         ;clear screen


;Clear screen CLS -> then switch ROM A on
;
;changes AF, BC, DE, HL, IX, &C000-&FFFF

 LD   IX,LESC ;LESC is a routine in ROM C which clears the screen
 CALL ROM_A2C ;use other routines ROM_?2C to switch other ROMs after CLS


;---=== Keyboard and HID management ===---;

;Waits for the keyboard being free first,
;then wait for a pressed key
;
;Manipulated are AF, BC, DE, HL, XL and PIO + PSG
;
;Returns with...
;A = Pressed key

WAIT CALL TST_TS ;Wait until no key is pressed any longer

 JR Z,WATL ;Keyboard is free now!
 JR WAIT   ;Wait until keyboardis free...^

WATL CALL H_ALLET ;Read data from keyboard

 CP  A,&FF ;If A = &FF then NO key was pressed
 RET NZ    ;A = pressed key -> Return!
 JR  WATL  ;No key pressed -> Read keyboard again


;---=== RAM management ===---;

;Switch 16 KB expansion RAM on between &4000-&7FFF (first 512 KB E-RAM)
;
;NN = &C0 ==> standart RAM on, or...
;NN = &C4,&C5,&C6,&C7, &CC,&CD,&CE,&CF
;     &D4,&D5,&D6,&D7, &DC,&DD,&DE,&DF, &E4,..,&FF
;     for one of 32 Expansion-RAMs of a 512 KB block
;
;changes F, BC, RAM status (&4000-&7FFF)

 LD  BC,&7F00 + NN ;new RAM (between &4000-&7FFF)
 LD  (AKT_RAM),BC  ;switch it on
 OUT (C),C


;Switch 16 KB expansion RAM on between &4000-&7FFF (first 512 KB E-RAM)
;
;BB = &7F, &7E, &7D, &7C, &7B, &7A, &79, &78 ... selects
;     one 512 KB E-RAM block out of eight blocks (if 4 MB E-RAM connected)
;
;NN = &C0 ==> standart RAM on, or...
;NN = &C4,&C5,&C6,&C7, &CC,&CD,&CE,&CF
;     &D4,&D5,&D6,&D7, &DC,&DD,&DE,&DF, &E4,..,&FF
;     for one of 32 Expansion-RAMs of a 512 KB block
;
;changes F, BC, RAM status (&4000-&7FFF)

 LD  BC,BB * 256 + NN ;new RAM (between &4000-&7FFF)
 LD  (AKT_RAM),BC     ;switch it on
 OUT (C),C


;---=== Routines for Storage Media ===---;

;------------------------------------------------------------------------------

;In this example a picture will be loaded from drive A
;The directory of drive A must have been read before!

;Load an example picture -> Wait for pressed key -> Return to OS

LADE_BILD LD HL,S80X25:CALL ROM_A ;Set 80 columns and 25 lines

 LD A,(REG_PC+1) ;A = Medium of which the main program was started

 ld a,0 ;In this example the source medium is set to drive A  #########
        ;This line ^ needs to be deleted in the final program #########

 LD (MEDIUM),A   ;Store Medium A..O (0-14) which contains the picture

 LD   DE,LBI ;Pointer to name of picture
 CALL LABI   ;Load the picture

 LD   HL,WATA ;Wait for pressed key
 CALL ROM_C

 LD   HL,S64X32 ;Set 64 columns and 32 lines
 CALL ROM_A

 LD HL,TUR_E ;-> Return to OS
 JP ROM_D


;Name of the picture to load
;
LBI DB &00,"TEST-PICSCR" ;User-Nummer + Name + Extension


;Number of the source medium of the picture
;
MEDIUM DB &00


;Load Picture to &C000!
;
;Jump in
;-------
;      DE = Pointer to User + Name + Extension of the Picture
;(MEDIUM) = Source-Medium of the Picture 0-14 (A-O)
;
;Jump back
;---------
;A  = &FF --> Picture was loaded just fine
;A <> &FF --> An error occured while loading the picture

LABI LD A,&02:LD (REG08_4),A ;Load to Main RAM

 LD HL,&C000:LD (REG16_3),HL ;Target Address is &C000 = Video RAM

 LD A,(MEDIUM) ;Source Medium

 LD IX,LADE_N:CALL ROM_A2C ;Load Picture

 INC A:JR NZ,LB_ERR ;A<>&FF --> Error while Loading!

 LD BC,&FA7E:LD A,(MO_ST):OUT (C),A ;Switch Drive Motors off

 LD A,&FF:RET ;A = &FF --> Picture was loaded successfully

;Error while Loading

LB_ERR LD BC,&FA7E:LD A,(MO_ST):OUT (C),A:XOR A,A:RET

;------------------------------------------------------------------------------


;---=== Get and Set the Configuration of the System ===---;

;Check if using a CPC6128 or a 6128 Plus

 LD A,(KF_CPC) ;get CPC version
 CP A,&03
 JR C,CPOG ;CPC old generation 464,664,6128

 nop ;here the CPC+ routines follow

CPOG nop ;here the CPCog routines follow


;---=== To END an Application ===---;

;Jump back to the Desktop,
;The upper half of the screen (Icon area)
;wasn't changed through the program

 LD HL,KLICK ;entry of  Desktop
 JP ROM_D    ;in ROM D


;This is the STANDART ENTRY to jump back to FutureOS

 LD HL,TUR_E ;entry of OS / Desktop
 JP ROM_D    ;in ROM D


;This is nearly like a COLDBOOT

 LD HL,TUR_D ;restart OS
 JP ROM_D    ;in ROM D


;---=== Different routines and functions ===---;


;Generate Random Value (0-255)
;
;A returns random number between 0 and 255
;
;Manipulated AF, BC, HL

RND256 LD A,R

 ADD A,A
 LD  H,A
 SET 7,H
 LD  A,R
 LD  L,A
 LD  B,(HL)
 ADD HL,HL
 LD  C,(HL)
 LD  A,R
 ADD A,B
 ADD A,C
 RET


;Find the first tagged and active Medium A-M
;
;Return condition
;----------------
; C = Medium von &00-&0C (A-M)
;HL = Pointer to TURBO_A, _B ... _M (corresponding to medium in C)
;
;Manipulated
;AF, BC and HL

FML LD HL,TURBO_A:LD BC,&0800 ;HL = Pointer TURBO_A / B=&08 / E=0 = C = Drive A

FML_L1 LD A,(HL):RRCA:JR C,FML_FND ;Active Drive/Partition found

 LD A,L:CP A,H:JR Z,FML_EXIT ;HL = TURBO_M -> All media tested, no one tagged!

 ADD A,B:LD L,A
 INC C
 JR  FML_L1 ;Select and Test next Drive / Partition

;Active Drive / Partition found!
;
FML_FND ;...

;HL = TURBO_M -> All media tested, no one tagged!
;
FML_EXIT


;************ B I G G E R - R O U T I N E S ************

;--------- A MENUE system ---------

;the following 3 lines are an example, result is given in A

 ld   hl,M_UPKT ;Text of different choices
 call M_DISP    ;call Menue routine
 ret            ;A = selected point/choice

;Demo-Text for Menue-system
;
;start at M_DISP (look below)
;
;Menue-Data

M_UPKT DB &04 ;Number of points/choices/lines, 2-14 maximal!

 DW M_US ;Address of Menue hit-line

 DW M_00 ;a Vector for every choice/line
 DW M_01 ;4 in this case
 DW M_02 ;every choice consists of a line of text
 DW M_03

 DB &00 ;actual choice

;Texts of the Menues. A line can have up to 30 chars, not more!

M_US DB &1E,&00, -M_00+M_US+4/2+16 ,"This is the hit line",0 ;Pen 3

M_00 DB &1E,&04, - M_01 + M_00 +4/2+16 ,"Choice 1",0 ;Pen 2
M_01 DB &1E,&06, - M_02 + M_01 +4/2+16 ,"Possibility 2",0
M_02 DB &1E,&08, - M_03 + M_02 +4/2+16 ,"Whats about this ??",0
M_03 DB &1E,&0A, - M_ED + M_03 +4/2+16 ,"last but not least",0

M_ED DB &12 ;Text-End, any value

;----------------------------;
; Menue in Mode 1, 32*32 Z*Z ;
;----------------------------;
;the routine itself is equal
;for all sets of data and/or text (for example M_UPKD)
;
;IN
;--
;HL = Start Address of Text/Dataset
;
;OUT
;---
;A = YL = selected Menue point / choice
;FutureOS ROM-A selected
;
;Manipulated
;-----------
;look at TER_BB

M_DISP LD (M_DATA),HL

 LD IX,LESC:CALL ROM_A2C ;CLS

 CALL S64X32 ;32 chars, 32 lines

 LD BC,&7F81:OUT (C),C ;MODE 1, ROM charset (&7F85 for RAM charset)

;display hitline on screen

 LD HL,(M_DATA):INC HL
 LD E,(HL):INC HL
 LD D,(HL):EX DE,HL ;HL has hitline address

 CALL TER_RR ;write hitline with PEN 3

;write all choices on screen

 LD HL,(M_DATA):LD A,(HL):DB &FD:LD L,A ;YL=Anz. Menuepunkte
 INC HL:INC HL:INC HL

MD_L0 LD E,(HL):INC HL:PUSH HL ;Vector or 1./next Menue point to Stack

 LD D,(HL):EX DE,HL ;HL targets first or next Menue point

 CALL TER_GG

 POP HL:INC HL ;select next Menue point

 DB &FD:DEC L:JR NZ,MD_L0 ;show next MP
 LD A,(HL)

;show aktual choice/line menue-point(MP) using PEN 1

 DB &FD:LD L,A ;YL = A = akt. MP

MD_L1 LD D,&00 ;DE=&00XX

 ADD A,A:ADD A,&03:LD E,A ;DE = aM * 2 + 3
 LD HL,(M_DATA):ADD HL,DE ;HL = DE + M_DATA(=Start Data)

 LD E,(HL):INC HL
 LD D,(HL):EX DE,HL ;HL = akt. MP
 LD (M_MPAA),HL

 CALL TER_BB ;show actuel MP/choice/line

;Tastaturabfrage

MD_LT CALL XWART
MD_LH CALL H_JC ;asks for Joystick 0, 1 and Cursor + Copy

 RRCA:JR NC,MD_AU
 RRCA:JR NC,MD_AB
 BIT 2,A:JR Z,MD_F0
 JR MD_LH

;Up

MD_AU DB &FD:LD A,L:OR A,A:JR Z,MD_LH ;first choice is actual, ignore

 DB &FD:DEC L               ;YL = MP - 1
 LD HL,(M_MPAA):CALL TER_GG ;old choice/line
 DB &FD:LD A,L:JR MD_L1     ;next upper choice/line

;Down

MD_AB DB &FD:LD A,L:INC A ;A = MP + 1

 LD HL,(M_DATA):CP A,(HL):JR Z,MD_LH ;lowest MP, ignor.
 LD HL,(M_MPAA):CALL TER_GG          ;old MP off
 DB &FD:INC L:DB &FD:LD A,L:JR MD_L1 ;MP down

;Fire 0

MD_F0 DB &FD:LD A,L:RET ;A = YL = selected Menuepoint/choice/line

;Menue-internal Variables

M_DATA DW &0000 ;vector to dataset
M_MPAA DW &0000 ;old/last choice/line

;EQUates for M_DISP

ROM_A2C EQU &FF2A
XWART EQU &C671
TER_BB EQU &CD4C
TER_GG EQU &CE80
TER_RR EQU &CF2A
S64X32 EQU &D5A8
H_JC EQU &FE6B
LESC EQU &C017

;------------ +++++++++ ------------


; tables
;========

;hardware color values, equivalent to
;BASIC colors from 0 to 26(31) ordered.
;
;Hardware-Farbwerte, entsprechend den
;OS Farben von 0 bis 26(31) geordnet.

HWFW

   ;  0   1   2   3   4   5   6   7
 DB &54,&44,&55,&5C,&58,&5D,&4C,&45

   ;  8   9  10  11  12  13  14  15
 DB &4D,&56,&46,&57,&5E,&40,&5F,&4E

   ; 16  17  18  19  20  21  22  23
 DB &47,&4F,&52,&42,&53,&5A,&59,&5B

   ; 24  25  26 *27 *28 *29 *30 *31
 DB &4A,&43,&4B,&44,&4D,&59,&47,&4F


;BASIC color values from 0 to 26, ordered
;through hardware color values &40-&5F
;
;OS Farbwerte von 0 bis 26, nach den
;Hardware-Farbwerten &40-&5F geordnet

OSSW DB 13 ;&40

 DB 27 ;&41 ***
 DB 19 ;&42
 DB 25 ;&43
 DB 01 ;&44
 DB 07 ;&45
 DB 10 ;&46
 DB 16 ;&47
 DB 28 ;&48 ***
 DB 29 ;&49 ***
 DB 24 ;&4A
 DB 26 ;&4B
 DB 06 ;&4C
 DB 08 ;&4D
 DB 15 ;&4E
 DB 17 ;&4F
 DB 30 ;&50 ***
 DB 31 ;&51 ***
 DB 18 ;&52
 DB 20 ;&53
 DB 00 ;&54
 DB 02 ;&55
 DB 09 ;&56
 DB 11 ;&57
 DB 04 ;&58
 DB 22 ;&59
 DB 21 ;&5A
 DB 23 ;&5B
 DB 03 ;&5C
 DB 05 ;&5D
 DB 12 ;&5E
 DB 14 ;&5F


LIST
DUMP