 |
 CpcAlive is a programming environment Amstrad CPC compatible for graphics animations creation. |
 |
"I invite you to open
yourselves to me, and become an... ...instrument in my hands for the salvation of the world. |
| * CpcAlive V1.19b * DOCUMENTATION (V2025) | ||
| Last
review (DosBox Version) V1.19b- 19/02/2025 - corrections V1.19a- 09/02/2025 - corrections and C++ programming implementation V1.18 - 27/01/2025 - create GIF animations 320*200*256 colors+corrections V1.17 - 07/01/2024 - New screen mode 1024*768*256colors(MODE 3) V1.16 - 16/12/2014 - Z80 assembler correction - adds a point (".") before LISTHEX,NOLIST,DEBUG,DUMP,TAB V1.15 - 30/11/2014 - corrections V1.14 - 20/11/2014 - display ASM sources in Z80 debugger - adds IF, IFDEF, IFNDEF directives in Z80 assembler - corrections V1.13 - 20/9/2014 - BASIC command TRON improvement (BASIC debugger) and corrections V1.12 - 02/3/2014 - include a "Basic source files with labels" loader and corrections Suivre @CpcAlive |
||
|
|
note:
- This documentation uses two types of hexadecimal values notation. The first notation adds the sign "&" in front of the value, ex:&3F. The second notation adds the letter "h" behind the value, ex:3Fh.
TABLE OF CONTENTS (Click in the margin left to come back here)
I - Presentation of the emulator CpcAlive
II - Files recognized by the emulator
II - 1 - Basic source files with labels
II - 2 - Z80 assembler source files
II - 3 - Intel hex files
II - 4 - CpcAlive commands files
II - 5 - Text files
II - 6 - Binary files
II - 7 - Virtual diskettes files (.DSK)
II - 8 - Cpc roms files
II - 9 - AMSDOS files
III - CpcAlive commands from the Cpc basic interpreter
IV - CpcAlive commands from the Dos command line
CpcAlive [input_files[:X]] [CpcAlive commands] [Cpc commands] [>output_file]
V - Accentued characters
VI - Bios and Dos interruptions access trough Z80
VII - X86 environment
VIII - Utility softwares
- 1 - CreaDisc: create a virgin virtual diskette usable by the emulator (data formatted).
- 2 - Extract: extract files from virtual diskettes
- 3 - AniCrea: adds screen recording commands and create GIF graphics animations files. (screen MODE 1 - 320*200*256colors)
- 4 - GIF to MP4 conversions
- 5 - Full keyboard for use on Android
- 6 - Dza is a z80 disassembler for Dos and Windows
- 7 - Merge multiple files into one file
I - Presentation of the emulator CpcAlive
CpcAlive is a programming environment Amstrad CPC compatible for graphics animations creation. The originality of the emulator is that it can work with all media wich accept the Dos emulator "Dosbox".
CpcAlive Specificities:
* basic sources with labels management
* screen resolutions 320*200*256, 160*200*16, 640*200*16 and 1024*768*256
* X86 programming environment (16Mo)
* Bios and Dos interruptions access trough instructions added to the Z80
* outputs screens in BMP images and GIF animations (256 colors)
* programmable BASIC
* possibility to treat from the Cpc BASIC interpreter any file present on the hard drive or another support.
* create executable environment safeguards.
* include a Z80 assembler/debugger and a BASIC debugger
* management of files created with the C compiler PhrozenC
|
Settings
for
DosBox
in
the
file
INI\DOSBOX\DOSBOX.CONF
If
the "full
screen"
mode is
non-functional
or
too
slow,
modify
the
command
fulldouble=false/true. If
the launch time
of
the
emulator is
excessive
or
if
the
launch
fail
(blue screen),
modify
the
command
cpuspeed=max
by
replacing
"max"
with a
value (ex: cpuspeed
=16000)
Installation on android and linux |
II - Files recognized by the emulator
To load a file from the Dos command line:
CpcAlive directory\filename[:X]
It is also possible to use the syntax: ! filename[:X]
- FileName = 8 characters maximum + 3 characters extension
- The letter represented by the character "X" is optional, it depends on the type of file to load. It will be called "marker". Note: don't put spaces betwen the file name and the marker.
To load a file from a CpcAlive command file:
directory\filename[:X]
To load a file from the Cpc BASIC interpreter:
|INPUT,"directory\filename[:X]"[,@er%]
The error return parameter @er% is optional. If it is put, the significance of the values recovered in the variable er% are:
0 = ok
1 = error number parameters
2 = file not found
3 = file or directory not found
4 = no more handle available
5 = refused access
(don't forget initialize er% at the program beginning or before the command)
ex: 10 er%=0
20 |INPUT,"Disc.dsk:A",@er%
30 if er%<>0 then PRINT"ERROR":STOP
It is possible to put several file names at the continuation. They must be separated by a space character. In this case, the error code er% will relate to the last file mentioned. It is also possible to obtain informations about the last file loaded with the following command:
info$=string$(12,"X"):|INFO,@info$:PRINT info$
II - 1 - Loading Basic source files with labels
These files must start with the four characters "BAS:" (header) and first line is reserved.
from the Dos command line:
! PROGRAM.BAS
from a CpcAlive command file:
PROGRAM.BAS
from the Cpc BASIC interpreter:
|INPUT,"PROGRAM.BAS"
or
|RUN,"PROGRAM.BAS"
The command |RUN launches the program automatically.
notes:
- if the file is loaded before the Cpc initialization (from the Dos command line for example), the emulator will load the file at the boot end and will launch it automatically.
- the header BAS:REMOFF prevents loading REMs in memory
- sources with line numbers are also accepted.
- the basic command TRON switch to a debug mode. Key [F12] to come back to the normal state or with a command TROFF in the program.
- you can see below how use commands files for loading basic files with different parts.
(see chapter CpcAlive commands files for more information about commands files)
CMD:WAITSYS (** CpcAlive command file - WAITSYS=wait end of cpc boot **)
INC\MAINJUMP.BAS ;This file contain just a jump to the first line of the last file loaded. The "goto" line address will be defined by the loader.
FILE1.BAS ;** PROGRAM FILE 1 **
FILE2.BAS ;** PROGRAM FILE 2 **
;in this file, labels can only be called by files loaded before (FILE1.BAS)
(.... ....)
MAIN.BAS ;** MAIN FILE **
; !! THE MAIN FILE MUST BE PLACED IN LAST PLACE !!
TEXT ;Text mode. After this command, this file will be interpreted trough the cpc keyboard
RUN
(example loading from the Dos command line: ! demo)
| CMD:WAITSYS (** CpcAlive
command file - WAITSYS=wait end of cpc boot **) INC\MAINJUMP.BAS ; never remove this line. This file contain just a jump to the first line of the last file loaded. The "goto" line address will be defined by the loader. ;(do not load commands files between basic files) INC\IBMP.BAS ;** DISPLAY BMP IMAGES 16/256 COLORS NOT COMPRESSED ** ;in this file, labels can only be called by files loaded before ;Basic lignes will be numbered greater than 1000 in cpc if no files loaded before is larger than 1000 lines EX\STAR.BAS ;** STAR LOADER ** ;in this file, labels can only be called by files loaded before ;Basic lignes will be numbered greater than 2000 in cpc if no files loaded before is larger than 1000 lines EX\ANI.BAS ;** DEMO ANIMATION (MAIN FILE) ** ; !! THE MAIN FILE MUST BE PLACED IN LAST PLACE !! ;Basic lignes will be numbered greater than 3000 in cpc if no files loaded before is larger than 1000 lines TEXT ;Text mode. After this command, this file will be interpreted trough the cpc keyboard RUN |
- Others BASIC programs examples: Display BMP images , Intel hex to binary conversion , Merge multiple files into one file
II - 2 - Loading Z80 assembler source files -
The emulator uses the sequence "org &" in small letters on the first line of the file to determine that is a Z80 assembler source created with the compiler C PhrozenC. For other sources, the emulator will seek the sequence ".org" or "org " in small or capital letters on the four first letters of the file.
The internal compiler uses the following standard words:
DB, DEFB, DW, DEFW, DS, DEFS, END, EQU, ORG, IF, IFDEF, IFNDEF, ELSE, ENDIF
and:
.LISTHEX : list the program in Intel Hex form in the output file
.NOLIST : stop the listing
.DEBUG : start the debugger (BreakPoint)
.DUMP address : init the debugger dump address
.TAB value : sets the tabs to the ASM source files display in the debugger (default 8)
It is possible to define macros-instructions in this form:
Ex:
MACRO ADD(X, Y)
LD HL, X
LD DE, Y
ADD HL,DE
ENDM
The internal compiler recognizes the Tasm (8bits) following directives:
.BYTE, .DB, .DW, .DS, .END, .EQU, .FILL,.ORG, .WORD, #IF, #IFDEF, #IFNDEF, #ELSE, #ENDIF, #INCLUDE, #DEFINE and #DEFCONT and the following operators: =, +, -, *,/, |, &
Mathematical operations does not manage mathematical priorities or brackets.
For assembly a Z80 source file in Ram, make follow the file name with the marker :X where X represents the Ram memory configuration type recipient followed by the loading address. By defect, the loading is done in memory with the configuration 0C0h to the address indicated by the command ORG. (see Loading in Ram memory to see the various Ram memory configurations)
Loading in Ram memory with standard configuration:
from the Dos command line:
! PROGRAM.ASM
from a CpcAlive command file:
PROGRAM.ASM
from the Cpc BASIC interpreter:
|INPUT,"PROGRAM.ASM"
or
|RUN,"PROGRAM.ASM"
The command |RUN launches the program automatically and is effective only if the file is loaded with standard Ram configuration. The command |RUN, "PROGRAM.ASM:0C0h, 02000h" redefined the directive ORG with 02000h and launches the program. It is possible to obtain the address memory following the loaded block like this:
info$=string$(20,"X"):|INFO,@info$:EndBloc=val("&"+mid$(info$,17,4)):?hex$(EndBloc)
If the file is loaded in RAM blocks 0,1,2 ou 3 before the Cpc initialization (from the Dos command line for example), the emulator will load the file at the boot end and will launch it automatically.
For assembly a Z80 source file in rom, make follow the file name by the ":R" marker. CpcAlive will seek the first area available.
Loading from the Dos command line:
! ROM.ASM:R
Loading from a CpcAlive command file:
ROM.ASM:R
Loading from the Cpc BASIC interpreter:
|INPUT, "ROM.ASM:R"
The rom site number can be obtained with the following way:
info$=string$(16,"X"):|INFO,@info$:RomPlace=val("&"+mid$(info$,15,2)):PRINT RomPlace
If it is necessary to have a fixed area number, you can replace the letter "R" with an area number. (Allowed values: 0 to 191)
example from the Dos command line: ! ROM.ASM:10
The address memory following the loaded block can be obtained in the same way that for loading in RAM. It is also possible to redefined the ORG address by indicating it in second parameter.
Amstrad Cpc Rom code sample with programmable basic instructions (Resident System eXtension)
II - 3 - Loading intel hex files -
The Intel Hex Object Format is line oriented and uses only printable ASCII characters.
Intel Hex line:
:LLAAAA00DDDD...CC ; ':' = start character (colon)
; LL = block size (2 hex digits)
; AAAA = starting address (4 hex digits)
; 00 = record type (00)
; DDDD = data bytes (a pair of hex digits for each byte of data)
; CC= check sum (2 hex digits)
file example:
:18A600000109A62111A6C3D1BC15A6C31EA6C335A6000000004F5049A2
:18A61800D8495049D800DD5603DD5E02DD4605DD4E043E0C4052DD7E97
:18A6300000404810C9D5DD5603DD5E02DD4605DD4E043E0D40524048AD
:07A6480010D11213AF12C97B
:00000001FF
In this example, the first line contains 018h data bytes (01h,09h,0A6h... 049h) which will be loaded starting from the address 0A600h. The check sum of this line is equal to 0A2h. The check sum normally present at the end of a standard intel hex line is not necessary with CpcAlive. Note the record type equal to 1 indicating the last line of the file. This line is not necessary in files loaded by the emulator.
Loading in rom:
To load an intel hex file in rom, make follow the file name by the ":X" marker where X represent the rom recipient number.
Example for loading in rom number 10:
from the Dos command line:
! FILENAME.HEX:10
from a CpcAlive command file:
FILENAME.HEX:10 for loading in rom number 10
from the Cpc BASIC interpreter:
|input,"FILENAME.HEX:10"
If the destination rom does not exist, CpcAlive create it. It is also possible to use the :R marker , CpcAlive will seek the first rom area available. (see chapter "Loading Cpc roms files")
Loading in ram:
The 6128 has a 128 KB memory (RAM) divided into eight blocks of 16 KB each one, numbered from 0 to 7. Only four blocks can beings connected simultaneously.
Table showing ram blocks positioning in foncion of the configuration type:
Value on port &7F blocks position
&C0 0,1,2,3 <= standard Cpc configuration memory
&C1 0,1,2,7
&C2 4,5,6,7
&C3 0,3,2,7
&C4 0,4,2,3
&C5 0,5,2,3
&C6 0,6,2,3
&C7 0,7,2,3
Allowed values added to the emulator:
&C8 0,8,2,3
&C9 0,9,2,3
...
&FF 0,&3F,2,3
The Cpc system exploits only the first configuration. In this configuration, block 0 occupies memory space 0 to 03FFFh, block 1 space 04000h to 07FFFh, block 2 space 08000h to 0BFFFh and block 3 space 0C000h to 0FFFFh. The screen exploits block 3. The higher part of block 2 contains the system variables. The lower part of block 0 is used by the system. BASIC programs are loaded by the system starting from the address 0170h. Binary data can be loaded starting from the address defined using the Basic instruction "MEMORY". If it is an executable program, it could be called with the instruction "CALL".
To load an intel hex file in ram, make follow the file name by the ":X" marker where X represents the ram recipient configuration type. Valids hexadecimal values for loading in RAM go from 0C0h to 0FFh. By defect, the loading is done in RAM with 0C0h configuration.
example from the Cpc BASIC interpreter
|input,"FILENAME.HEX"
In this case, the file "FILENAME.HEX" is loaded with the standard Cpc configuration memory.
notes:
- It is possible to see the Cpc memory with CpcAlive with the command |DEBUG,&f from the BASIC interpreter.
- If the file is loaded in RAM blocks 0,1,2 ou 3 before the Cpc initialization (from the Dos command line for example), the emulator will load the file at the boot end. (possible only for one file)
- The Z80 assembler "tasm" generates intel hex files.
II - 4 - Loading command files
The intern emulator valid commands from the Dos command line or a CpcAlive command file are:
| CpuFast | set maximum speed - [F12] |
| CpuSlow | set speed
of the original Cpc
computer
- [F11] (sound timing is preserved) |
| Sleep | put the emulator on sleeping state - [AltGr][S] |
| Exit | to leave the emulator - [Ctrl][Alt][End] |
| ROM=X | select ROM X (256 for the Cpc bios) |
| RAM=X | select
RAM
X configuration see chapter "Loading in ram" for ram configuration values. |
| :LLAAAA00DDDD... | loading data. (Intel Hex line) |
| MakeCont | continue a file created with the command |MAKE |
| Debug:address | start the debugger when the Z80 processor meet the specified address (ram) |
| Debug:rom,address | start the debugger when the Z80 processor meet the specified address in the specified rom (high roms) |
| Z80 | going
from the "Commands" mode to the "Z80 compiler" mode. The interpretation of the file will be restored in mode "Commands" with the End or .End instruction. |
| PhrozencOrg=ADR | ADR=loading address by defect of the sources files generated by the compiler C PhrozenC. |
| End | indicate the end of a command file. |
| Text | going from the "Commands" mode to the "Text" mode. After this command, the file will not be interpreted any more like a command file but like a text file . Use the keyword |Command or |CMD to go back in "Commands" mode. The commands "End" and "Text" restore the memory configuration if this one were modified with the commands "Rom" or "Ram". |
example from the Dos command line
To select the BIOS rom and put the value 2 in the memory address 0B13h (screen mode of starting) and select slow speed emulation:
! ROM=256 :010B130002 CpuSlow
Don't forget spaces between commands.
If a CpcAlive command is not reconized, this command and the rest of the line is interpreted like a Cpc command. You can by this way adding one or more Cpc commands at the end of the line. (Only from the Dos interpreter. From CpcAlive commands files, use the "Text" command).
example:
! ROM=256 :010B130002 CpuSlow PRINT"OK"
note:
- put values in RAM blocks 0,1,2 ou 3 before the Cpc initialization is useless because this blocks are cleared by the system. To put values in RAM from the Dos command line, the system could be launched and put in sleeping mode previously.
CpcAlive command files:
These files are intended, as their name indicates it, to command the emulator from a file. This file must start with the four characters "CMD:" (header) and first line is reserved.
Loading from the Dos command line:
! FILENAME.CMD
Loading from a CpcAlive command file:
FILENAME.CMD
Loading from the Cpc BASIC interpreter:
|INPUT, "FILENAME.CMD"
example 1:
Select the BIOS rom and poke the value 2 in 0B13h address (screen mode of starting) and select slow speed:
CMD: ; header
ROM=256 ; select rom bios
:010B130002 ; poke the value 2 in 0B13h address (screen mode of starting)
CpuSlow ; speed selection
End ; close the command file
example 2:
CMD: ; header
ROM=256 ; select rom bios
:010B130002 ; poke the value 2 in 0B13h address (screen mode of starting)
CpuSlow ; speed selection
Text ; swap in text mode
PRINT"OK"
example 3:
PRINT"OK1"
|CMD ; going from the TEXT mode to the COMMAND mode.
ROM=256 ; select rom bios
:010B130002 ; poke the value 2 in 0B13h address (screen mode of starting)
CpuSlow ; speed selection
Text ; swap in text mode
PRINT"OK2 "
notes:
- It is also possible to load from a CpcAlive command file the following types of files: Basic sources, Z80 assembler sources, intel hex files, command files, text documents, binary files , virtual diskettes with format DSK and Cpc rom files. The command files overlap is authorized with the limits of 15 files maximum (text files included). A good example is the ROM.INI file which is a command file intended for the emulator initialization. It is from this one that for example the Cpc roms are loaded. Note the separator ';' for comments. (!do not use "Text" mode in the file ROM.INI).The command file CPC.INI located in the CpcAlive repertory is a user file which can receive configuration commands.
- The header "CMD:WAITSYS" wait the end of the Cpc boot to load the file. (A single file at a time is possible)
II - 5 - Loading text files
If the file type is not recognized by CpcAlive as being one of files detailed higher, CpcAlive considers that it is a text file. CpcAlive treats these files like this: each character of the document is read and sent to the Cpc keyboard manager. You can thus, for example, transmit by this function a BASIC file text formated (without header "BAS:") or pilot a software running into the emulator.
Loading from the Dos command line:
! example.bas
Loading from a CpcAlive command file:
example.bas
Loading from the Cpc BASIC interpreter:
|input,"example.bas"
These commands load the text named "exemple.bas" through the Cpc keyboard manager. This file must be in text format. In this example it must be in the CpcAlive directory. If the file does not exist, the string "exemple.bas" will be transmitted to the Cpc keyboard manager and will probably cause a "Syntax error" message.
example from the Cpc BASIC interpreter:
MODE 2
10 |INPUT, "SETASM.BAT"
20 LINE INPUT a$:IF INSTR(a$,"hardware")<>0 THEN |INPUT,":CLOSE":END ELSE GOTO 20
run
This example displays the document "SETASM.BAT" until it encounters a line containing the word "hardware". The command |INPUT,":CLOSE" stops the loading of the file across the keyboard.
The text files overlap is authorized with the limits of 15 files maximum (command files included).
It is also possible to load texts in the CpcAlive emulator with the Windows XP copy/paste function. See instructions.
II - 6 - Loading binary files
It is possible to use the marker ":D" (like 'D'atas) to load data in the Cpc memory by using the following syntax:
from the Cpc BASIC interpreter:
|INPUT,"filename:D,block lenght,source address block in file,destination address in cpc memory"
from a CpcAlive command file:
filename:D,block lenght,source address block in file,destination address in cpc memory
Don't forget to protect the loaded block with the BASIC command: MEMORY load_address - 1. The real size of the block loaded can be obtained with the following way:
info$=string$(16,"X"):|INFO,@info$:BlockLenght=val("&"+mid$(info$,13,4))
It is thus possible to treat any type of file. The example here load an image BMP and display it on the Cpc screen.
The ":D" marker alone following the file name indicates to the emulator that it must transmit the value in decimal format of each byte of the file through the Cpc keyboard manager.This function has been developed to easily treat datas from a file with the Cpc BASIC interpreter.
Here, a small program wich display some informations from a bitmap image (BMP):
BAS:
10 '** INFO BMP IMAGE **
20 mode 2:|Input,"IMAGE.BMP:D"
30 |GO,"&12":'go to address &12 in file = width/height image
40 input a:input b:imgwith=a+256*b
50 input a:input b:imgheight=a+256*b
60 print"image width=";imgwidth
70 print"image height=";imgheight
The command |GO, "numerical string"[,@er% ] move the file pointer.
In this case, "numerical string" represent the displacement value compared to the beginning of the file. The error return parameter @er% is optional. If it is put, the values significance recovered in the variable er% are:
0 = ok
1 = error
(don't forget to initialize er% before the command)
example from the Cpc BASIC interpreter:
|GO,"&100"
Moves the file pointer to the position &100. The maximum value is &FFFFFFFF. This can be also write in decimal.
II - 7 - Loading virtual diskettes files (.DSK) -
Make follow the file name with ":A" or ":B" to choose the Cpc drive destination.(drive A by defect)
example from the Dos command line:
! disc.dsk:A
example from a CpcAlive command file:
disc.dsk:A
example from the Cpc BASIC interpreter:
|input,"disc.dsk:A"
This command load the virtual diskette "disc.dsk" in the drive A of the emulator.
note: - Slow speed (CpuSlow) is selected automaticaly if there was not CpuFast command before.
II - 8 - Loading Cpc roms files -
There is three 16Kb roms blocks in the Cpc 6128 (48Ko). One of these blocks contains the operating system which is connected in the memory area 0 to 03FFFh (low rom). The two other blocks (BASIC and disc system) are connected in the memory area 0C000h to 0FFFFh (high roms). The system can exploit in this memory area 252 blocks of 16Ko each one. An interesting characteristic of these roms that is they can receive BASIC programmable instructions (Resident System eXtension).
To load a rom file in the emulator, make follow the file name with the ":R" marker. CpcAlive will seek the first rom area available. The file can be binary or intel hex formated.
Loading from the Dos command line:
! Z80ROM.ROM:R
Loading from a CpcAlive command file:
Z80ROM.ROM:R
Loading from the Cpc BASIC interpreter:
|INPUT, "Z80ROM.ROM:R":call 0
The rom area number can be obtained with the following way:
info$=string$(16,"X"):|INFO,@info$:RomPlace=val("&"+mid$(info$,15,2)):PRINT RomPlace
If it is necessary to have a fixed area number, you can replace the letter "R" with the rom area number. (Allowed values: 0 to 191)
example from the Dos command line: ! Z80ROM.ROM:10
Roms will be recognized by the Cpc system only after a rebootstrapping for example with a CALL 0 or by actuating keys [Ctrl][Alt][Home] in the same time. The emulator takes RSX instructions with all highers roms. The areas numbers used by the Cpc system are 0 for the BASIC rom and 7 for the DISC rom. The X86 modules (see chapter "X86 Environment") with mnemonics use also Z80 roms sites. The highers roms with a specific site number must be loaded before the X86 modules. The best way is to indicate them at the beginning of the command file ROM.INI located in the main repertory.
When a program is executed in ROM, CpcAlive redirects by defect the Z80 writing accesses into the RAM. The command |UNLOCK,rom_site_number authorizes the writing accesses of the Z80 microprocessor in the specified ROM. The ROM works then similarly than a RAM.
Amstrad Cpc Rom code sample with programmable basic instructions (Resident System eXtension)
II - 9 - Loading AMSDOS files
It's files .BIN or .BAS that can be extracted from a virtual floppy .DSK using for example "Extract".
from the Dos command line:
! PROGRAM.BIN or .BAS
from a CpcAlive command file:
PROGRAM.BIN or .BAS
from the Cpc BASIC interpreter:
|INPUT,"PROGRAM.BIN or .BAS"
or
|RUN,"PROGRAM.BIN or .BAS"
The command |RUN launches the program automatically if executable.
notes:
- if the file is loaded before the Cpc initialization (from the Dos command line for example), the emulator will load the file at the boot end and will launch it automatically if executable.
III - CpcAlive commands from the Cpc basic interpreter:
The CpcAlive commands from BASIC interpreter must be preceded by the vertical bar " | "
| |CpuFast | set maximum speed - [F12] |
| |CpuSlow | set speed of the Cpc computer - [F11] (Sound timing is preserved) |
| |CpuSlow,speed | modify CpuSlow speed (0<speed<&FFFF) |
| |Sleep | put the emulator in sleeping mode - [AltGr][S] |
| |Sleep,"message" | set sleeping mode with message |
| |Sleep,ERRORLEVEL | set sleeping mode with exit code used in batch files |
| |Exit | leave the emulator - [Ctrl][Alt][End] or [Alt][X] |
| |Exit,"message" | leave the emulator with message |
| |Exit,ERRORLEVEL | leave the emulator with exit code (used in batch files) |
| |Command or |CMD | going from the TEXT mode to the
COMMAND mode. see chapter II - 4 - Loading command files |
| |INPUT, "file_name[:X]"[,@er% ] |
load
a file see chapter II - Files recognized by the emulator |
| |RUN, "file_name[:X][,ADR]"[,@er%] |
load
and execute a file if executable |
| |INFO,@info$ | load the information block of the last entered file with the function |INPUT or via a CpcAlive command file. ex: |INPUT, "Disk.dsk":info$=string$(12,"X"):|INFO,@info$:PRINT info$ |
| |CLOCK,@clock$ | clock$="HH:MM:SS":|CLOCK,@clock$ load time in the string clock$ |
| |UNLOCK,-rom_site_number- | authorizes
the writing accesses of
the Z80 microprocessor in the specified ROM. see chapter II - 8 - Loading Cpc roms files |
| |EJECT,"A" | eject the virtual diskette present in drive A |
| |EJECT,"B" | eject the virtual diskette present in drive B |
| |GO, "numerical_string"[,@er%] |
move a "binary file" pointer (see chapter II - 6 - Loading binary files) |
| |OUTPUT, "output_file"[,@er% ] | change the PRN file name (see chapter IV) |
| |OUTASCDOS | see chapter V - Accentued characters |
| |OUTASCWIN | see chapter V - Accentued characters |
| |OUTASCOFF | see chapter V - Accentued characters |
| |PRINT, "string" | output a character
string in the PRN file. (Command equivalent to the command PRINT#8,"string";) |
| |LPRINT, "string" | output a character string in the PRN file with carriage return (Command equivalent to the command PRINT#8,"string") |
| |INK,PEN,R,G,B | change
PEN color. R,G,B for Red,Green and Blue
values (range 0
to 255) ex: |INK,0,0,255,0 (change PAPER color) ex: |INK,1,255,0,0 (change PEN 1 color) |
| |INKRESTORE | restore originals Cpc inks. |
| |INKCPC | standard cpc inks |
| |INKSOFT | CpcAlive inks (by defect). The palet is the same as the standard palet Cpc but with less luminosity and values PAPER and PEN 1 are modified. |
| |OBMP, "filename.BMP" [,@er% ] |
create a bitmap of the screen- see |OUTPUT command for error codes significance. |
| |COPY,SpriteNumber |COPY,"SpriteName" |
saves pixels
displayed using the basic
PLOT/DRAW functions (or from
Bios X86) in a buffer or a file. A command |PASTE or
|FRAMEOUT
ends the record sequence. - SpriteName=8 characters maxi without extension - SpriteNumber between 0 and 255 - maximum sprite size = 100000 pixels |
| |PASTE,movX,movY,SpriteNumber |PASTE,movX,movY,"SpriteName" |
Displays the sequence recorded with |COPY with displacement. movX and movY are relative to the coordinates of record. |
| |DEBUG,address | start the Z80 debugger when the Z80 processor meet the specified address (ram) |
| |DEBUG,rom,address | start the Z80 debugger when the Z80 processor meet the specified address in the specified rom (high roms) |
| |DEBUGSYS,address | start the Z80 debugger when the Z80 processor meet the specified address (low rom) |
| |DEBUGOFF | stop the Z80 debugger |
| |DUMP,address | init the debugger dump address |
| |NODEBUG | prohibit the Z80 debugger |
| |NOSLEEP | prohibit the sleeping mode |
| |MAKE, "filename.EXE"[,@er%] |
create
an
executable environment safeguard. (Safeguard the environment when leaving the emulator) - see |OUTPUT command for error codes significance. |
| |MAKEMOVIE, "filename.EXE"[,@er%] |
create
executable graphics animations. (Safeguard the environment when leaving the emulator) - any keyboard movement stopped the execution of the produced file - see |OUTPUT command for error codes significance. |
notes:
- files created with commands |MAKE or |MAKEMOVIE cannot be renamed with the Dos function "rename". To rename these files, use their own intern function from the Dos system line: file_name.EXE rename:new_name or file_name.EXE ren:new_name
- to launch a file .EXE created with |MAKE or |MAKEMOVIE with Windows XP, click on the name of the program with the mouse right button and choose <properties><memory><Ems memory auto>
- the basic command CALL 0 initialize the Cpc system - [Ctrl][Alt][Home]
Basic commands added with the module AniCrea:
AniCrea is a CpcAlive module which adds screen recording commands and create GIF graphics animations.
(Screen MODE 1 - 320*200*256colors)
|ANICREA,"animation_name"[,@er%] - start output file
The error return parameter @er% is optional. If it is put, the significance of the values recovered in the variable er% are:
0 = ok
2 = refused access
(don't forget to initialize er% at the beginning of the program or before the command)
The name of the image to be created can also be defined from the Dos command line in second parameter.
|ANISPEED,animation play speed between 0 to 65535 (current values between 0 and 50)
|FRAMEOUT[,@er%] - generate a frame
The error return parameter @er% is optional. If it is put, the significance of the values recovered in the variable er% are:
0 = ok else error
|ANICLOSE[,@er%] - close output file
The error return parameter @er% is optional. If it is put, the significance of the values recovered in the variable er% are:
0 = ok else error
Notes:
- The command "! DEMO" from the Dos command line create the file DEMO.GIF
- See |COPY & |PASTE for sprites management.
IV - CpcAlive commands from the Dos command line
CpcAlive [input_files[:X]] [CpcAlive commands] [Cpc commands] [>output_file]
or
! [input_files[:X]] [CpcAlive commands] [Cpc commands] [>output_file]
The Cpc commands should be placed at the end of the command line. (before ">output_file" if presents)
ex: ! PRINT"ok"
Launch the emulator with the command PRINT"ok"
Particular case:
The character | is a Dos command. CpcAlive uses thus a substitution character which is the '§' than you can obtained with the [ALT][245] keyboard sequence from the Dos command line. If you obtain another character than '§' on your screen it is not important. The most important is the [ALT][245] keyboard sequence to obtain the ascii character number 245 in the Dos command line. ex: ! §DISC launch the emulator with the command |DISC
The character & is used by Dos too. You can use the character ² or [Alt][253] to replace it. ex: ! POKE ²C000,²FF launch the emulator with the command POKE &C000,&FF
There are other reserved characters by Dos like < or > which cannot be used with Cpc commands from the Dos command line.
By defect the Cpc printing output is done in file CPC.PRN located in CpcAlive directory. It is possible to change the name of the output file from the Dos command line by adding the character '>' to the end of the line followed the desired file name.
example:
! PRINT#8, "OK" output the word "OK" in the file Cpc.prn
! PRINT#8, "OK">test.prn output the word" OK "in the file test.prn
Only one character ' > ' before the output file name indicates to the Dos system that if the output file name already exists, this file will be recreate virgin before receiving datas. (the old one output file with the same name being delete without notice... warning). Two characters ' > > ' before the output file indicates to the Dos system that it must preserve the file and put new data to be followed.
example:
! PRINT#8, "OK1":§Exit>test.prn output the word "OK1" in the file test.prn
! PRINT#8, "OK2":§Exit>>test.prn output the word "OK2" follow in the file test.prn
The result in the file test.prn gives:
OK1
OK2
It is possible to change the output file name from the Cpc Basic interpreter by typing the following command: |OUTPUT, "directory\FILENAME"[,@er% ]
(FileName = 8 characters maximum + 3 characters extension)
The error return parameter @er% is optional. If it is put, the significance of the values recovered in the variable er% are:
0 = ok
1 = error number of parameters
2 = refused access
3 = way not found
4 = no more handle available
5 = refused access
(don't forget to initialize er% before the command)
|OUTPUT, ":GO,&100"[,@er% ] move the output file pointer to &100
|OUTPUT,":CLOSE" close the file (CPC.PRN is again the default output file)
An example of Files Concatenation associating commands |OUTPUT and |INPUT
Another small program which redirect the CATalogue output towards the output file:
10 POKE &BB5C,PEEK(&BD2D):POKE &BB5B,PEEK(&BD2C)
20 CAT
30 CALL &BD37:|DISC
RUN
note: The file CPC.PRN is cleared after each launching of the emulator by the first printing output.
V - ACCENTUED CHARACTERS
See french or spanish documentation
VI - BIOS AND DOS INTERRUPTIONS ACCESS TROUGH Z80
Bios and Dos interruptions are accessible with CpcAlive specifics opcodes through the emulated Z80 microprocessor and a correspondence between the Z80 and X86 registers. The table below indicates the registers correspondence established between the two processors:
Z80 registers X86 registers
F > Flags
A > AL
BC > CX
DE > DX
HL > BX
IX > SI
IY > DI
CpcAlive adds to the Z80 new opcodes and registers named AH, BP, DS and ES corresponding to the X86 processors registers.
Example:
opcode: mnemonics: function:
040h, 052h LD AH, A load the value of the Z80 register A in the X86 register AH
040h, 05Bh LD A, AH load the value of the X86 register AH in the Z80 register A
040h, 048h, xx INT(xx) call interruption number xx
example of macros (here for the assembler 8 bits tasm)
# define LD_AH_A db 040h \ db 052h
# define LD_A_AH db 040h \ db 05Bh
# define INT(xx) db 040h \ db 048h \ db xx
example:
; ** OUTPUT PIXEL THROUGH INT 010H **
OutPix: ld de, 12 ; coordinate Y
ld bc, 24 ; coordinate X
ld a, 0Ch ; FUNCTION 0CH = WRITE A GRAPHIC POINT
LD_AH_A ; load the value of the Z80 register A in the X86 register AH
ld a,3 ; color requested
INT(010h) ; CALL INTERRUPTION BIOS 010H
ret
notes:
- The Z80-X86 correspondence registers is respected with the return of the interruption.
- The standard output peripheral is always the screen.
- The cpc memory is located in the EMS memory segment.
- The Bios interruption INT 10H accept only the functions:
Function 02h // Set cursor position //
Function 03h // Read cursor position //
Function 09h // Write character with color at cursor //
Function 0Ah // Write character with color at cursor //
Function 0Bh // Set color palette //
Function 0Ch // Write graphics pixel at coordinate //
Function 0Dh // Read graphics pixel at coordinate //
Function 0Eh // Write text in teletype mode //
Function 10h - 00h // set individual palette register //
Function 10h - 02h // set all palette registers and border //
Function 10h - 07h // read palette register //
Function 10h - 09h // read palette registers and border //
Function 10h - 10h // set DAC color register //
Function 10h - 12h // set block of DAC color registers //
Function 10h - 15h // read DAC color register //
Function 10h - 17h // read block of DAC color registers //
Function 10h - 1Bh // sum color values to shades of gray //
Function 13h // Write string //
The palette registers correspond to the 16 Cpc pens. (With CpcAlive, the border always correspond to the Pen 0).
The file Z80IOPix.bas located in the "EX" directory is an example using Bios interruptions. This file is a text file wich can be read with a text editor. Explanations and listing are included.
command from the Dos command line: ! EX\Z80IOPix.bas
command from the Cpc BASIC interpreter: |input, "EX\Z80IOPix.bas"
These commands generate functions |OPIX,X,Y,PEN and |IPIX,X,Y,@pen which respectively write and read a graphic point on the screen to the coordinates X and Y.
List of instructions available added to the Z80:
#define LD_HL_CPCSEG .db 040h\ .db 047h ; RETURN SEGMENT ADDRESS OF CPC MEMORY
#define INT(xx) .db 040h\ .db 048h\ .db xx ; CALL BIOS/DOS INTERRUPTION XX
#define IN_A_DE .db 040h\ .db 04Ah ; IN A,(DE) (DE refer to I/O PC system)
#define OUT_DE_A .db 040h\ .db 04Bh ; OUT (DE),A (DE refer to I/O PC system)
#define LD_AH_A .db 040h\ .db 052h ; LD AH,A
#define LD_A_AH .db 040h\ .db 05Bh ; LD A,AH
#define LD_BP_HL .db 040h\ .db 05Ch ; LD BP,HL
#define LD_HL_BP .db 040h\ .db 05Dh ; LD HL,BP
#define LD_DS_HL .db 040h\ .db 05Eh ; LD DS,HL
#define LD_HL_DS .db 040h\ .db 05Fh ; LD HL,DS
#define LD_ES_HL .db 040h\ .db 060h ; LD ES,HL
#define LD_HL_ES .db 040h\ .db 061h ; LD HL,ES
#define PUSHA .db 040h\ .db 071h ; PUSH A,AH,BC,DE,HL,BP,IX,IY
#define POPA .db 040h\ .db 072h ; POP IY,IX,BP,HL,DE,BC,AH,A
BP, DS, ES and AH correspond to the X86 processor registers. By defect registers DS and ES pointed to the Cpc memory (Ems segment).
VII - X86 ENVIRONMENT
It is possible to program the emulator CpcAlive with X86 instructions. CpcAlive accept 256 X86 modules. A module is a .EXE program containing an installation table located to the address 0200h in the program code and a table being able to contain 128 X86 call vectors. The X86 vectors can be called from the Cpc basic interpreter or from Z80 opcodes. The maximum size of a X86 module is 64K. The installation table of a X86 module must be made up like this:
org 0200h
db ' X86CPC' ; 0200h mark
dw 1 ; 0206h version
dw offset X86Vec ; 0208h entry vectors table
dw 0 ; 020Ah reserved
dw 0 ; 020Ch reserved
dw 0 ; 020Eh reserved
dw offset MnemoTb ; 0210h offset names table for calls with Basic
db -1 ; 0212h (*) receipt the X86 module area number
db -1 ; 0213h module complement number or bank Cpc block number
db -1 ; 0214h (*) reçeipt the Z80 rom number associated
db -1 ; 0215h indicator for Cpc banks or modules complements connection
dw -1 ; 0216h (*) reçeipt the first Cpc accessible address (0=no address accessible)
db 0 ; 0218h reserved
dw 0 ; 0219h (*) receipt the ems handle associated to the module
dw 0 ; 021Bh (*) receipt the logical number of the first 16K page of the module
db 0 ; 021Dh reserved
dw 0 ; 021Eh address called when the emulator exit (0=no call)
dw 0 ; 0220h address called when the emulator is put in "sleep mode" (0=no call)
dw 0 ; 0222h address called when the emulator return from "sleep mode" (0=no call)
dw 0 ; 0224h address called when the module is load (0=no call)
dw 0 ; 0226h reserved
db 0 ; 0228h receipt the number of 16K pages allocated to the module (*)
; or number of pages to be allocated (if <>0 when the module is loaded)
; or number of connected pages (*)
; or number of pages to connect
db 0100h-029h dup (0) ; 0229h reserved
(*) = value generated by the system
; entry vectors table
X86Vec dw offset program1 ; 00 1st program
dw offset program2 ; 01 2nd program
;... 128 vectors maximum
; names table (mnemonics)
MnemoTb db "PROGRAM","1" or 080h ; |PROGRAM1
db "PROGRAM","2" or 080h ; |PROGRAM2
db 0
; ** CALLED BY THE BASIC INSTRUCTION |PROGRAM1 **
program1:
;... code X86
RETF ; VECTOR RETURN (FAR)
; ** CALLED BY THE BASIC INSTRUCTION |PROGRAM2 **
program2:
;... code X86
RETF ; VECTOR RETURN (FAR)
Operation: With the MnemoTb vector presence to the address 0210h, the emulator generates a Z80 rom interpretable with the Cpc system integrating the names table (MnemoTb) with its X86 call vectors. The first vector of the table "X86Vec" corresponding to the first name is the initialization vector which is called with each initialization of the Cpc system. Each name corresponds to a vector of this table (in order). The end of each name is indicated with the bit 7 on the last letter of the name. The table should not exceed 128 names and must be finished by a null byte. To use a command, it will be enough to type the name preceded by the "vertical bar | " from the Cpc BASIC interpreter.
It is also possible to call the X86 routines from the Cpc memory through Z80 opcodes (see below). If names are not necessary, replace the vector "MnemoTb" with a null word (address 0210h).
To call a X86 program from the Z80 memory:
The call of a X86 program from the Cpc memory is done using the opcode 049h followed module area number, then vector number. For example if you want to call "program2" (vector number 1) in the example above, considering that the system has load the X86 module in the area 010h, that will give the Z80 opcode: 049h, 010h, 001h.
The module area number can be obtained like Z80 Roms loading:
info$=string$(16,"X"):|INFO,@info$:RomPlace=val("&"+mid$(info$,15,2)):PRINT RomPlace
This number is also indicated in the byte of address 0212h of the X86 installation table. The vector number must be between 0 and 127. If the bit 7 is set, a "RET" will be simulated after the instruction. The instruction operate then similarly than a jump instruction (JP).
The Z80 registers values are retransmitted to the X86 programs like this:
Z80 registers X86 registers
F > Flags
A > AL
BC > CX
DE > DX
HL > BX
IX > SI
IY > DI
The X86 registers describe in the preceding chapter are also transferred.. FS and GS registers are undefined. X86 registers values returned by the program will be retransmitted to the Z80 with the same way.
Loading a module from the Dos command line: ! MODULE.EXE
Loading a module from a CpcAlive command file: MODULE.EXE
Loading a module from the Cpc BASIC interpreter: |INPUT, "MODULE.EXE":call 0
Cpc memory access from X86 environment
The file X86IOPix.asm located in the directory "EX" is a complete example. It has generate the module X86IOPix.exe in the same directory.
command from the Dos command line: ! EX\X86IOPix.exe
This command generates functions |OPIX,X,Y,PEN and |IPIX,X,Y,@PEN which respectively write and read a graphic point on the screen with coordinates X and Y. The file X86IOPix.bas located in the same repertory is an example wich use this module functions.
notes:
- The Bios interruption INT 10H accept only the functions described in the preceding chapter.
- The standard output peripheral is always the screen.
- If it is not necessary that the module be initialized by its first vector when the Cpc system start, it is possible to use the marker ":W" (Waggon) following the module name. The emulator will then load vectors and mnemonics of the module in the Z80 rom generated by the preceding module. One will use less Z80 roms areas. (if there was no module loaded previously, the emulator created a first vector "without effect" in the Z80 Rom associated).
- Example of a C++ module implementation.
VIII - UTILITY SOFTWARES
- 1 - CreaDisc: create a virgin virtual diskette (data formatted).
Command from the Dos command line: ! CreaDisc
- 2 - Extract: extract files from virtual diskettes.
Command from the Dos command line: Extract [diskette_name] [file_name]
- 3 - AniCrea is a CpcAlive module which adds screen recording commands and create GIF graphics animations.
- 4 - GIF conversions
GIF to MP4: ffmpeg (Windows)
ffmpeg.exe -r 15 -i "SrcFile.GIF" -s 320x200 "DstFile.MP4"
-r 15 for framerate
-s 320x200 for video resolution
- 5 - Full keyboard for use with Android
- 6 - Dza is a z80 disassembler for Dos and Windows Dza.zip
- 7 - Merge multiple files into one file
People who wish to take part can post their work here:
Thank you.