New usrrom.asm from MartinR

- MartinR has contributed a new usrrom.asm that prints a nice RomWBW logo and does a better job with the messages.

Source/HBIOS/std.asm

@@ -862,7 +862,7 @@ APP_BNKS	.SET	0
 ;;;BID_ROMDN	.EQU	BID_ROMD0 + ROMD_BNKS - 1	; LAST ROM DRIVE BANK
 ;;;BID_APPN	.EQU	BID_APP0 + APP_BNKS - 1		; LAST APP BANK
 ;
-#IF TRUE
+#IFDEF SYSINFO
 	.ECHO "------------- CAPACITY -----------------\n"
 	.ECHO "ROMBANKS:  " \ .ECHO ROMBANKS  \ .ECHO "\n"
 	.ECHO "RAMBANKS:  " \ .ECHO RAMBANKS  \ .ECHO "\n"

Source/HBIOS/usrrom.asm

@@ -1,34 +1,107 @@
 ;
-; USRROM	TEMPLATE FOR A CUSTOM USER ROM
+;=============================================================================
+; USRROM.ASM - SAMPLE CUSTOM ROM USER APPLICATION
+;=============================================================================
 ;
-#INCLUDE	"std.asm"
+; VERSION 1.1	BY - MARTINR	31-MAY-2024
 ;
-CR	.EQU    0DH
-LF	.EQU    0AH
+; THIS IS AN EXAMPLE USER ROM APPLICATION THAT IS AUTOMATICALLY INCLUDED
+; IN THE ROMWBW ROM.  IT IS INVOKED FROM THE BOOT LOADER USING THE
+; 'U' (USER APPLICATION) OPTION.  YOU MAY REPLACE THIS SOURCE CODE WITH
+; YOUR OWN CUSTOM CODE.  IT WILL BE ASSEMBLED AND INCLUDED WITH YOUR
+; CUSTOM ROM BUILD.  REFER TO THE ROMWBW USER GUIDE FOR MORE INFORMATION.
 ;
-	.ORG    USR_LOC
+; THANKS AND CREDIT TO MARTIN R. FOR PROVIDING THIS APPLICATION!
 ;
-	LD	SP,USR_END
+; - THE SOURCE IS ASSEMBLED WITH THE TASM ASSEMBLER.
+; - THE APPLICATION MUST START (ORG) AT USR_LOC ($100)
+; - THE APPLICATION MUST BE EXACTLY USR_SIZ BYTES.  THIS IS AUTOMATICALLY
+;   ENFORCED AT THE END OF THE FILE.
+; - AT EXIT, THE APPLICATION SHOULD RETURN TO THE BOOT LOADER USING THE
+;   HBIOS WARM RESET FUNCTION AS DEMONSTRATED BELOW.
+; - THE APPLICATION MAY MAKE HBIOS FUNCTION CALLS WITHOUT RESTRICTION,
+;   BUT CANNOT USE ANY OS (CP/M) FUNCTIONS BECAUSE NO OS IS LOADED.
 ;
-	LD	HL,BOOTMSG		; INTRODUCTION
+; INCLUDE STD.ASM WHICH DEFINES SOME KEY EQUATES USED BELOW.  MOST
+; IMPORTANT ARE USR_LOC, USR_SIZ, AND USR_END.  IT ALSO DEFINES EQUATES
+; FOR THE HBIOS FUNCTION CALLS.
+;
+#INCLUDE "std.asm"
+;
+	.LIST
+;
+CR	.EQU	0DH
+LF	.EQU	0AH
+;
+ROWS	.EQU	008H		; NUMBER OF PIXEL ROWS PER CHARACTER
+COLS	.EQU	008H		; NUMBER OF PIXEL COLUMNS PER CHARACTER
+;
+; APPLICATION WILL WILL BE LOADED AT USR_LOC.  THEREFORE, THE CODE
+; MUST "ORG" AT THIS ADDRESS.  TO CHANGE THE LOAD LOCATION OF THIS
+; CODE, YOU CAN UPDATE USR_LOC IN STD.ASM.
+;
+	.ORG	USR_LOC
+;
+; PLACE STACK AT THE TOP OF AVAILABLE RAM (JUST BELOW THE HBIOS PROXY).
+;
+	LD	SP,HBX_LOC
+;
+;*****************************************************************************
+;
+; DISPLAY BANNER
+;
+	LD	A,CR
+	CALL	COUT
+	LD	A,LF
+	CALL	COUT		; COUT PRESERVES AF, BC, DE, & HL
+	CALL	COUT
+	CALL	COUT
+;
+	LD	HL,BANNER+1	; POINTER TO THE 8X8 CHARACTER BITMAPS
+	LD	D,ROWS		; D=ROWS PER CHARACTER
+;
+NXTLIN:	LD	A,(BANNER)	; FETCH THE NUMBER OF CHARACTERS IN THE BANNER
+	LD	E,A
+;
+NXTCHR:	LD	C,(HL)		; FETCH THE BIT PATTERN FOR THE CHARACTER-LINE
+	LD	B,COLS		; 8 COLUMNS PER CHARACTER-LINE
+NXTBIT:	SLA	C		; SHIFT-LEFT THE NEXT BIT INTO THE CARRY FLAG
+	JR	C, DOT
+	LD	A,' '		; IF NO-CARRY THEN PRINT A 'SPACE'
+	JR	GAP
+DOT:	LD	A,'X'		; IF A CARRY THEN PRINT AN 'X'
+GAP:	CALL	COUT		; COUT PRESERVES AF, BC, DE, & HL
+	DJNZ	NXTBIT		; GO ROUND AND PRINT ALL 8 BITS FOR THE CHARACTER-LINE
+;
+	INC	HL		; POINT TO NEXT CHARACTER-LINE
+	DEC	E
+	JR	NZ,NXTCHR	; GO ROUND AND PRINT THE NEXT CHARACTER
+;
+	LD	A,CR		; REACHED THE END OF A LINE, SO PRINT CRLF
+	CALL	COUT		; COUT PRESERVES AF, BC, DE, & HL
+	LD	A,LF
+	CALL	COUT
+;
+	DEC	D
+	JR	NZ,NXTLIN	; GO ROUND AND PRINT THE NEXT LINE
+;
+;*****************************************************************************
+;
+; FINISHED DISPLAYING THE BANNER, NOW END THE 'APP' TIDILY
+;
+	LD	HL,MESSAGE		; PRINT A MESSAGE
 	CALL	PRTSTR
-;
-	CALL	CIN			; DO STUFF
+	CALL	CIN			; AND WAIT FOR A KEYPRESS
 ;
 	LD	B,BF_SYSRESET		; SYSTEM RESTART
 	LD	C,BF_SYSRES_WARM	; WARM START
-	CALL	$FFF0			; CALL HBIOS
-;       RET
+	RST	08			; CALL HBIOS (DOES NOT RETURN)
 ;
+;*****************************************************************************
 ;
+; SUPPORT ROUTINES
 ;
-; PRINT A STRING AT ADDRESS SPECIFIED IN HL
-; STRING MUST BE TERMINATED BY '$'
-; USAGE:
-;   LD	HL,MYSTR
-;   CALL PRTSTR
-;   ...
-;   MYSTR: .DB  "HELLO$"
+; PRINT A STRING OF CHARACTERS STARTING AT HL, ENDING WITH '$'
 ;
 PRTSTR:	LD	A,(HL)
 	INC	HL
@@ -43,8 +116,8 @@ COUT:	PUSH	AF
 	PUSH	BC
 	PUSH	DE
 	PUSH	HL
-	LD	B,01H
-	LD	C,80H
+	LD	B,BF_CIOOUT
+	LD	C,CIO_CONSOLE
 	LD	E,A
 	RST	08
 	POP	HL
@@ -58,8 +131,8 @@ COUT:	PUSH	AF
 CIN:	PUSH	BC
 	PUSH	DE
 	PUSH	HL
-	LD	B,00H
-	LD	C,80H
+	LD	B,BF_CIOIN
+	LD	C,CIO_CONSOLE
 	RST	08
 	LD	A,E
 	POP	HL
@@ -67,18 +140,60 @@ CIN:	PUSH	BC
 	POP	BC
 	RET
 ;
-BOOTMSG:.DB	CR,LF,CR,LF
-	.DB	"No User ROM Installed."
-	.DB	CR,LF,CR,LF
+;*****************************************************************************
+;
+; DATA SECTION
+;
+BANNER:
+	.DB 006H; THE NUMBER OF CHARACTERS IN THE BANNER
+;
+#IF FALSE
+	; UPPER CASE LOGO
+	.DB	%01111100, %00011100, %01000001, %01000001, %01111100, %01000001
+	.DB	%01000010, %00100010, %01100011, %01000001, %01000010, %01000001
+	.DB	%01000001, %01000001, %01010101, %01000001, %01000001, %01000001
+	.DB	%01000001, %01000001, %01001001, %00100010, %01111110, %00100010
+	.DB	%01111110, %01000001, %01000001, %00100010, %01000010, %00100010
+	.DB	%01000100, %01000001, %01000001, %00101010, %01000001, %00101010
+	.DB	%01000010, %00100010, %01000001, %00101010, %01000001, %00101010
+	.DB	%01000001, %00011100, %01000001, %00010100, %01111110, %00010100
+#ENDIF
+;
+#IF TRUE
+	; UPPER AND LOWER CASE LOGO
+	.DB	%00000000, %00000000, %00000000, %00000000, %00000000, %00000000
+	.DB	%01111000, %00000000, %00000000, %01000100, %01111000, %01000100
+	.DB	%01000100, %00000000, %00000000, %01000100, %01000100, %01000100
+	.DB	%01000100, %00111000, %00101000, %01000100, %01000100, %01000100
+	.DB	%01111000, %01000100, %01010100, %01010100, %01111000, %01010100
+	.DB	%01010000, %01000100, %01010100, %01010100, %01000100, %01010100
+	.DB	%01001000, %01000100, %01000100, %01101100, %01000100, %01101100
+	.DB	%01000100, %00111000, %01000100, %01000100, %01111000, %01000100
+#ENDIF
+;
+MESSAGE:
+	.DB	CR,LF,LF
+	.DB	"This is an example User Application - why not create your own?",CR,LF
+	.DB	"Please see the relevant User Guide section for more information."
+	.DB	CR,LF,LF,LF
 	.DB	"Press a key to return to Boot Loader.$"
 ;
 ; IT IS CRITICAL THAT THE FINAL BINARY BE EXACTLY USR_SIZ BYTES.
-; THIS GENERATES FILLER AS NEEDED.
-;				
+; THIS GENERATES FILLER AS NEEDED.  IT WILL ALSO FORCE AN ASSEMBLY
+; ERROR IF THE SIZE EXCEEDS THE SPACE ALLOCATED.
+;
 SLACK	.EQU	(USR_END - $)
-	.FILL	SLACK,00
+;
+#IF (SLACK < 0)
+	.ECHO	"*** USRAPP IS TOO BIG!!!\n"
+	!!!	; FORCE AN ASSEMBLY ERROR
+#ENDIF
+;
+	.FILL	SLACK,$00
 	.ECHO	"User ROM space remaining: "
 	.ECHO	SLACK
 	.ECHO	" bytes.\n"
-        .END
-
+;
+	.NOLIST
+;
+	.END