www.cpcalive.com
Cliquer ici pour la documentation française
Pulsar aquí para la documentación en español

* CpcAlive V1.08L *
* ENGLISH DOCUMENTATION *




notes:
- This documentation relates about information necessary to use the CpcAlive emulator. A demonstration, utility softwares, a Z80 assembler, a X86 assembler, documentations about Cpc exploitation and Bios/Dos interruptions are available on the internet site: www.cpcalive.com
- 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

I - CpcAlive Initializations
II - CpcAlive commands syntax:
    CpcAlive [input_files[:X]] [CpcAlive commands] [Cpc commands] [>output_file]
    - 1 - Input files
        - 1a - Loading virtual diskettes files (.DSK) -
        - 1b - Loading Cpc roms files -
        - 1c - Loading intel hex files  -
        - 1d - Loading command files
        - 1e - Loading text files (KeyBoard simulation)
        - 1f - Loading binary files
    - 2 - Cpc commands from the Dos command line
    - 3 - Output_files
III - CpcAlive commands from the Cpc basic interpreter
IV - ACCENTUED CHARACTERS
V - BIOS AND DOS INTERRUPTIONS ACCESS TROUGH Z80
VI - X86 ENVIRONMENT
VII - UTILITY SOFTWARES
    - 1 - CreaDisc.bas: create a virgin virtual diskette. (data formatted)
    - 2 - AniCrea.exe: create a FLI animation file
    - 3 - Fli2Gif.exe: read a FLI animation file


                                                                                                                                                                  
                                                    

I - CpcAlive Initializations:
Create a CpcAlive
directory on your hard disk and decompress the file CpcAliveV1.08L.zip in this directory.

= Icon to launch CpcAlive
= Icon to launch the "Windows Dos" system.
You can create a short cut on
the desktop with the icon named CpcAlive.

If you launch CpcAlive and you obtain an "Ems error" message:
EMS memory is emulated with "Windows Dos" but it is not set by defect with some windows versions. ("Windows Dos" is the Dos name wich is provide with windows XP)
To correct the problem, close the window, click on the icon with right mouse bouton and select "Proprieties", "Memory", "EMS Memory>AUTO". Another solution is to do the same thing with the file "_default.pif" in the "WINDOWS" directory (it is the file named "_default" with the MS-DOS icon).

Notes:
    - Amstrad roms ares copyrighted, you cannot thus normally use CpcAlive only if you have a
n Amstrad Cpc 6128 computer in a position to function.
    - colors PAPER and PEN 1 were modified with initialization for
ergonomic reason  (less tiring for eyes).


II - CpcAlive commands syntax:

CpcAlive [input_files[:X]] [CpcAlive commands] [Cpc commands] [>output_file]
or
! [input_files[:X]] [CpcAlive commands] [Cpc commands] [>output_file]

- 1 - Input files
~~~~~~~~~~~~~~~
Files recognized by the emulator are:

Virtual diskette with format DSK     (see chapter - 1a -)
Cpc rom files                                 (see chapter - 1b -)
Intel hex files                                 (see chapter - 1c -)
CpcAlive command files                 (see chapter - 1d -)
Text documents                             (see chapter - 1e -)
Binary files                                    (see chapter - 1f -)

To load a file starting from the Dos command line:
CpcAlive filename[:X]
It is also possible to use the syntax: ! filename[:X]

The letter represented by the character "X" is optional, it depends on the type of file to load. It will be called "marker" and will have to be typed in capital letter.


To load
a file starting from a CpcAlive command file:
filename[:X]

To load
a file starting from the Cpc BASIC interpreter:
|INPUT,"filename[:X]"[,@er%]

The error return parameter @er% is facultatif. If it is put, the significance of the values recovered in the variable er% are:
0 = ok
1 = error number parameters
2 = way not found
(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.
The vertical bar present in front of the order INPUT is obtained by actuating in same time the key [AltGr] and the key [6] located in top of the keyboard.

- 1a - Loading virtual diskettes files (.DSK
) -
Make follow the file name of the
":A" or ":B" markers to choose the Cpc drive destination.(drive A by defect)

example starting from the Dos command line:

! disc.dsk:A
example starting from a CpcAlive command file:
disc.dsk:A
example starting from the Cpc BASIC interpreter:
|input,"disc.dsk:A"

This command launch the emulator and load the virtual diskette "disc.dsk" in drive A.

note:
don't put spaces betwen the file name and the marker.


- 1b - 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 zone 0 to 03FFFh (lower rom). The two other blocks (BASIC and disc system) are connected in the zone 0C000h to 0FFFFh (higher roms). The system can exploit in this zone 252 blocks of 16Ko each one. An interesting characteristic of these roms is that they can receive BASIC programmable instructions 
(Resident System eXtension).

To load a rom file in the emulator, make follow the file name by the ":R" marker. CpcAlive will seek the first area available. The file can be binary or intel hex formated.

Loading starting from the Dos command line:
! Z80ROM.ROM:R
Loading starting from a CpcAlive command file:
Z80ROM.ROM:R
Loading starting from the Cpc BASIC interpreter:
|INPUT, "Z80ROM
.ROM:R":call 0

If it is necessary to have a fixed area number, you can replace the letter "R" with an area number (0<area number <256).
example starting from the Dos command line:  ! Z80ROM.ROM:R: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 BASIC rom and 7 for 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 principal repertory.

note: - All markers must be write with capital letters.

Sample coding of an Amstrad Cpc Rom containing programmable basic instructions (Resident System eXtension)


- 1c - Loading intel hex files  -

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:
starting from the Dos command line:
!  FILENAME.HEX:10
starting from a CpcAlive command file:
FILENAME.HEX:10     for loading in rom number 10
starting from the Cpc BASIC interpreter:
|input,"FILENAME.HEX:10"

If the destination rom does not exist, CpcAlive create it. In this case it is possible to use the :R marker (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

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. The BASIC programs are loaded by the system starting from the address 0170h. The binary data can beings loaded starting from the address defined using the Basic instruction "MEMORY". If they are executable programs, they 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 are:
0C0h, 0C1h, 0C2h, 0C3h, 0C4h, 0C5h, 0C6h and 0C7h

By defect, the loading is done in RAM with 0C0h configuration.

example starting from the Cpc BASIC interpreter
|input,"FILENAME.HEX"
In this case, the file "file.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.
- Put values in RAM blocks 0,1,2 ou 3 before the Cpc system initialization is useless because this blocks are cleared with starting. To put values in RAM from the Dos command line, the system could be launched and put in sleeping mode previously.
- All markers must be write with capital letters.


- 1d - Loading command files

The intern emulator valid commands starting from the Dos system command line or a CpcAlive command file are:

CpuFast                    ; set maximum speed
CpuSlow                   ;
set normal speed (speed of the original Cpc computer)
Sleep                        ;
put the emulator on sleeping state [AltGr][S]
Exit                          ; to leave emulator
[Ctrl][Alt][End]
ROM=X                   ; select ROM X (256 for the Cpc bios)
RAM=X                   ; select RAM X type
                                ;
see chapter II paragraph - 1c - "Loading in ram"
                                ; for ram configuration values.

:LLAAAA00DDDD   ; intel hex line:
                                ; ':' = start character (colon)
                                ; LL = block size (2 hex digits)
                                ; AAAA = starting adress (4 hex digits)
                                ; 00 = record type (00)
                                ; DDDD = data bytes (a pair of hex digits for each byte of data)

The Intel Hex Object Format is line oriented and uses only printable ASCII characters. The check sum (2 hex digits) normally present at the end of a standard intel hex line is not obligatory here.
EndCde                     ; indicate the end of a command file. (facultatif)
Keyboard                  ; going from the COMMAND mode to the KEYBOARD 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" to go back in COMMAND mode.


example starting from the Dos command line
To select the BIOS rom and poke the value 2 in 0B13h adress (start screen mode) 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 "keyboard" command).

example:

! ROM=256 :010B130002 CpuSlow PRINT"OK"

note:
- put values in RAM blocks 0,1,2 ou 3 before the Cpc system
initialization is useless because this blocks are cleared with starting. To put values in RAM from the Dos command line, the system could be launched and put in sleeping mode previously.


command files

These files are intended, as their name indicates it, to command the emulator from a file. This file must start with
"CDE:" sequence without guillemets (header).
                  
example 1:
Select the BIOS rom and poke the value 2 in 0B13h adress (start screen mode) and select slow speed:

CDE:                ; header
ROM=256        ; select rom bios
:010B130002    ; poke the value 2 in 0B13h adress (start screen mode)
CpuSlow          ; speed selection
EndCde            ; close the command file

example 2:
CDE:                ; header
ROM=256        ; select rom bios
:010B130002    ; poke the value 2 in 0B13h adress (start screen mode)
CpuSlow          ; speed selection
Keyboard         ; swap in keyboard mode
                       ;
(starting from here each character is transmitted
                       ; directly to the Cpc keyboard manager)

PRINT"OK"

example 3:
PRINT"OK1"
|COMMAND    ;
going from the KEYBOARD mode to the COMMAND mode.
ROM=256        ; select rom bios
:010B130002    ; poke the value 2 in 0B13h adress (start screen mode)
CpuSlow          ; speed selection
Keyboard         ; swap in keyboard mode
                       ;
(starting from here each character is transmitted
                       ; directly to the Cpc keyboard manager)

PRINT"OK2 "

It is also possible to load from a CpcAlive command file the following types of files:
virtual diskettes with format DSK , Cpc rom files , intel hex files , command files , text documents and binary 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 the command "KeyBoard" in the file ROM.INI).The command file CPC.INI located in the CpcAlive repertory is a user file which can receive configuration commands.


- 1e - Loading text files (KeyBoard simulation)

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 transmit by this function a BASIC file with text format 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 or a path
directory. If the file does not exist, the chain "exemple.bas" will be transmitted to the Cpc keyboard manager and will probably cause a "Syntax error" message.

example starting from the Cpc BASIC interpreter:
mode 2
10 |Input,"FILE_ID.DIZ"
20 line input a$:if a$="" then |STOP:end else goto 20
run

This example load the document "FILE_ID.DIZ" until it meet one blank line. The order |STOP close the file.

The text files overlap is authorized with the limits of 15 files maximum (command files included).


- 1f - 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,address block in file,load address in cpc memory"
(think to protect the loaded block with the order: MEMORY load_address - 1)
from a CpcAlive command file:
filename:D,block lenght,address block in file,load address in cpc memory

It is thus possible to treat any type of file. The example below load an image BMP (option OS/2 format, 16 colors, 180*100 max.) and posts it on the Cpc screen.

10 memory &3FFF:adr=&4000
20 ximg=0:yimg=0:nameimg$="image.bmp":' <<<< X,Y,IMAGE NAME
30 |input,nameimg$+":D,&4100,0,&4000"
40 if peek(adr+&E)+256*peek(adr+&F)<>12 then mode 2:?"OS/2 format only accepted":end
50 x=peek(adr+&18)+256*peek(adr+&19)
60 if x<>4 then mode 2:?"16 colors in image only accepted.":end
70 mode 0:x=0:for i=0 to 45 step 3:|ink,x,peek(adr+&1C+i),peek(adr+&1B+i),peek(adr+&1A+i):x=x+1:next
80 largeur=peek(adr+&12)+256*peek(adr+&13)
90 hauteur=peek(adr+&14)+256*peek(adr+&15)
100 reste=largeur mod 2:x=int(largeur/2)+reste:while x mod 4 <> 0:x=x+1:wend:larbloc=x
110 adr=adr+peek(adr+&A)+256*peek(adr+&B):'adresse image dans fichier
120 for i=0 to hauteur*4 step 4:x=0
130 for j=adr to adr+(int(largeur/2)+reste)
140 pencil=(peek(j) and &F0)/16:plot ximg+x,yimg+i,pencil:plot ximg+x,yimg+i+2,pencil:x=x+4
150 pencil=peek(j) and &F:plot ximg+x,yimg+i,pencil:plot ximg+x,yimg+i+2,pencil:x=x+4
160 next j:adr=adr+larbloc:next i
run


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 as been developed to easily treat datas from a file with the Cpc BASIC interpreter.

Here, a small program whose function is reading some bytes of ROM.INI file and print them in hexadecimal format:

10 mode 2:window#0,1,80,2,25:window#1,1,80,1,1
20 |Input,"ROM.INI:D"
30 for i=0 to 100
40 input#1,a:Print hex$(a,2)" ";
50 next i
60 |STOP
run


The command |GO, "numerical chain"[,@er% ] move the file pointer.
In this case, "chain" represent the
displacement value compared to the file beginning. The error return parameter @er% is facultatif. If it is put, the values significance recovered in the variable er% are:
0 = ok
1 = error
(don't forget to initialize er% at the program beginning or before the command)

example starting from the Cpc BASIC interpreter:
|GO,"&100"

Moves the file pointer to the position &100. The maximum value is &FFFFFFFF. The file pointer position can be write with decimal format.


- 2 - Cpc commands from the Dos command line
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Cpc commands must always be placed at the last of the command line.

ex: ! PRINT"ok"
Launch the emulator and places the order PRINT"ok" through the Cpc keaboard manager.

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 and place the order |DISC in Cpc keyboard manager.

There are other reserved characters by Dos like ' < ' or ' > ' which can't be used for Cpc commands from the Dos command line. For more information read the Dos system documentation.


- 3 - Output files
~~~~~~~~~~~~~~~~
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 starting from the Dos command line by adding the character '>' to the end of the line followed the desired file name.

example:
! PRINT#8, "OK"                 register word "OK" in the file
Cpc.prn
! PRINT#8, "OK">test.prn    register 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. (There does not exist at time equivalent CpcAlive command from the Cpc BASIC interpreter)

example:
! PRINT#8, "OK1":§Exit>test.prn         register word "OK1"in the file test.prn
! PRINT#8, "OK2":§Exit>>test.prn       register 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, "output_file"[,@er% ]

The error return parameter @er% is facultatif. If it is put, the significance of the values recovered in the variable er% are:
0 = ok
1 = error number parameters
3 = way not found
4 = no more handle available
5 = refused access
(don't forget to initialize er% at the beginning of the program or before the order)

A 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 emptied with each launching of the emulator.

III - CpcAlive commands  from the Cpc basic interpreter:

The CpcAlive commands starting from the interpreter BASIC must be preceded by the vertical bar " | ".


|CpuFast                    = maximum speed
|CpuSlow                   = normal speed (speed of the Cpc computer)
|Sleep                        = emulator in sleeping mode
[AltGr][S]
|Exit                          = to leave emulator
[Ctrl][Alt][End]
|Command                 = going from the KEYBOARD mode to the COMMAND mode.
                                   (see chapter II paragraph - 1d - )
|INPUT, "file_name[:X]"[,@er% ]
                                 = see chapter II paragraph - 1 -
|STOP                       = see chapter II paragraph - 1e -
|GO, "numerical chain"[,@er% ]
                               = see chapter II paragraph - 1f -
|OUTPUT, "output_file"[,@er% ]
                                = see chapter II paragraph - 3 -
|OUTASCDOS          = see chapter IV
|OUTASCWIN          = see chapter IV
|OUTASCOFF           = see chapter IV
|PRINT, "chains"       = output character string towards output_file.
                                   (Order equivalent to the order PRINT#8,"chains";)
|LPRINT, "chains"     = output character string towards output_file followed by a carriadge return.
                                   (Order equivalent to the order PRINT#8,"chains")
|INK,PEN,R,G,B       = change PEN color. Letters R,G,B représents Red,Green and Blue values (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 (inks by defect)
                                   The pallet is the same as the standard pallet Cpc but with less
                                   luminosity, and
values Paper and PEN 1 are modified with starting.
|OBMP, "nom_de_fichier"[,@er% ]
                                = create a file image of the Cpc screen (
BMP format).
                                    - see |OUTPUT command for
error codes significance.
|DEBUG,adresse       = launch the debugger when the Z80 processor meet the specified adress.
|DEBUGOFF            = stop the debugger
|DUMP,adress           = initialize the dump memory first address of the debuggor
CALL 0                    = réinit System Cpc [Ctrl][Alt][Home]


IV -
ACCENTUED CHARACTERS

See french or spanish documentation


V - 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.
Correspondences table:             Z80 registers     
X86 registers
                                               F                 >   Flags
                                               A                 >   AL
                                               BC               >   CX
                                               DE               >   DX
                                               HL               >   BX
                                               IX                >   SI
                                               IY                >   DI

CpcAlive adds a Z80 register named AH corresponding to the X86 register AH, and three new opcodes.

opcode:             mnemonics:     function:
040h, 052h        LD AH, A
          load the value of register A in pseudo register AH
040h, 05Bh        LD A, AH          load the value of pseudo register AH in register A
040h, 049h, 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 049h \ 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 register A in
                                              ; pseudo 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 except for the registers IX and IY which are never modified. If segments ES and DS are necessary in entry, they refer to the RAM (or Rom) of the cpc. The rare Bios functions returns values in the segment registers or registers DI and SI are not usable.
- The standard output peripheral is always the screen.
- 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 //

notes: -
the palette registers correspond to the 16 Cpc pens and DAC registers correspond to the 32 Cpc inks.
          - the border always correspond to the Pen 0 with CpcAlive.

It should be also known that the cpc Ram is located in the EMS memory segment.
(in case where some equilibrists would venture touching ems functions).

The Z80IOPix.bas file located in the "EX" directory is an
orders RSX example using the Bios interruptions. This file is a text file éditable with a text editor. Explanations and listing are included.
command starting from the Dos command line:       ! EX\Z80IOPix.bas
command starting 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 with co-ordinates X and Y.

                                                                                                                                                                   
                                                    
note: Documentations about Bios and Dos interruptions and the Z80 assembler "tasm" are available on onternet site: www.cpcalive.com
                                                                                                                                                                                                                       


VI - X86 ENVIRONMENT

It is possible to program the CpcAlive emulator with X86 instructions.
CpcAlive accept 256 modules X86. The maximal lenght of a module is 64K.
A module is a .EXE or .COM format program with a table located at the address 0200h in the program code. This table must be made like this:

org 0200h
                db ' X86CPC'               ; 0200h mark
                dw 0                             ; 0206h version
                dw offset X86Vec          ; 0208h entry vectors table
                dw 0                             ; 020Ah reserved system
                dw 0                             ; 020Ch reserved system
                dw 0                             ; 020Eh reserved system
                dw offset MnemoTb      ; 0210h offset mnemonics
                db -1                             ; 0212h
(*) receipt the X86 module area number
                db -1                             ; 0213h 
reserved system
                db -1                             ; 0214h (*) reçeipt the Z80 rom number associated
                db -1                             ; 0215h reserved system
                dw 0                              ; 0216h
(*) reçeipt the first Cpc accessible adress (0=no adress accessible)
                db 0                               ; 0218h reserved system
                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
(*) receipt the number of 16K pages allocated to the module
                db 0100h-01Eh dup (0)   ; 021Eh 
reserved system

(*) = value generated by the system

; mnemonics table
MnemoTb db "MNEMO","1" or 080h          ; |MNEMO1
                db "MNEMO","2" or 080h          ; |MNEMO2
                db 0


; entry vectors table
X86Vec    dw offset program1           ; 00 1st program
                dw offset program2           ; 01 2nd program
                ;... 128 vectors maximum

; X86 programs must be declared in "far"
program1 proc far    ; ** CALLED BY THE BASIC INSTRUCTION |MNEMO1 **
                ;... code X86
                retf
program1 endp
program2 proc far    ; ** CALLED BY THE BASIC INSTRUCTION |MNEMO2 **
                ;... code X86
                retf
program2 endp

Operation: On presence of the MnemoTb vector to the address 0210h, the emulator generates a Z80 rom interpretable by the Cpc system integrating the mnemonics table (MnemoTb) with its X86 call vectors. The first vector of the table "X86Vec" corresponding to the first mnemonics is the vector of initialization which is called with each initialization of the Cpc system. Each mnemonics corresponds to a vector of this table (in the order). The end of each mnemonics is indicated with the bit 7 on the last letter of the mnemonics. The table should not exceed 128 mnemonics and must be finished by a null byte.
Note: It is also possible also to call the X86 routines from the Cpc memory through Z80 opcodes (see below). If mnemonics are not necessary, replace the vector "MnemoTb" by a null word (address 0210h).

The file X86IOPix.asm located in directory "EX" is a complete example. It has generate the module X86IOPix.com in the same directory but it can also be compilated with format .EXE

command starting from the Dos command line:
       ! EX\X86IOPix.com
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 co-ordinates X and Y.

To load a module in the emulator: 3 solutions

- Loading starting from the Dos command line:
       ! MODULE.COM
- Loading starting from a CpcAlive command file:
      
MODULE.COM
- Loading starting from the Cpc BASIC interpreter:
       |INPUT, "
MODULE.COM":call 0


To call a X86 program from the Z80 memory:


The call of a X86 program from the Cpc RAM (or ROM) 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

notes:

- The X86 module area number is indicated to the address 0212h of the X86 environmental 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 operation becomes similar than a "JP" instruction.


The Z80 registers values are retransmitted with the X86 programs like this:
Z80 registers      X86 registers
  F                  >   Flags
  A                 >   AL
  BC               >   CX
  DE               >   DX
  HL               >   BX
  IX                >   SI
  IY                >   DI

The pseudo Z80 register AH is also transfered.
CS,DS and ES registers address the Cpc memory.
FS and GS registers are undefined.
X86 registers values returned by the program will be retransmitted to the Z80 with the same way.
The Cpc memory access depends about the module size because modules are activated in the same area.
The first Cpc accessible adress is indicated to the address 0216h in the environmental table X86.

notes:
- The Cpc addresses lower than 04000h are never accessible from a X86 module.
- 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).



VII - UTILITY SOFTWARES

- 1 - CreaDisc.bas: create a virgin virtual diskette. (data formatted)

Order starting from the Dos command line:

! CreaDisc.bas>
diskette_name.dsk


- 2 - AniCrea.exe: create a FLI animation file

Dos syntax: AniCrea input_file [output_file]
input_file=Basic file generator (.BAS)
output_file=Animation file result (.FLI)

Basic syntax:
|ANICREA,OUTPUT_NAME$[,@er%]     -     start output file
The error return parameter @er% is facultatif. If it is put, the significance of the values recovered in the variable er% are:
0 = ok
1 = error number parameters
3 = way not found
4 = no more handle available
5 = refused access
6 = refused handle
(don't forget to initialize er% at the beginning of the program or before the order)

|ANISPEED,animation play speed between 0 to 65535

|FRAMEOUT[,@er%]             -     generate a frame
The error return parameter @er% is facultatif. If it is put, the significance of the values recovered in the variable er% are:
0 = ok
1 = error number parameters
2 = file not open
3 = output file write error

|ANICLOSE[,@er%]               - close output file
The error return parameter @er% is facultatif. If it is put, the significance of the values recovered in the variable er% are:
0 = ok
1 = error number parameters
2 = acces file error

The command "AniCrea demo.bas" from the Dos command line create the file DEMO.FLI


- 3 - Fli2Gif.exe: read a FLI animation file (for more information read the Fli2Gif.doc file)




If  you have the idea to develop some softwares or little demonstrations for CpcAlive, I would be enjoy to include them in next version or on the site of CpcAlive . You can post them here: cpcalive@aol.com .You'ld be informed about CpcAlive new versions. Thank you.

CpcAlive is now shareware. People who wish to take part can make a free gift here: Office Chrétien des personnes Handicapées (Handicaped People Christian Office - association without bond with the author of the CpcAlive software). The registered version removes the logo on the outputs screen files (BMP & FLI). To receive it, return a scan image of the tax receipt here: cpcalive@aol.com.






Acknowledgements to the Cpc conceptors and to the many authors of documentations who made that this work succeed.