zymosis: renamed "SLL" to "SLS"

[zymosis.git] / dox / zxemut_console.txt

some Tcl API procs:


consetstr
=========
set console input string (used in aucomompleter, for example)
usage:
  consetstr "str"

returns 1


cputs
=====
print string to console
usage:
  cputs ?-nonewline? string

returns 1


errputs
=======
print error string to console
usage:
  errputs ?-nonewline? string

returns 1


load
====
load and execute Tcl script from disk file.
the file will be first searched in current directory, and
then in ZXEmuT tcl/ directory.

returns 1


softload
====
load and execute Tcl script from disk file.
won't fail if the file is absent.
the file will be first searched in current directory, and
then in ZXEmuT tcl/ directory.

returns 1


z80
===
various command to manipulate Z80 CPU from Tcl
subcommands:
  getreg <name> -- get register value
  setreg <name> <value> -- set register value, returns old register value



-------------------------------------------------------------------------
brief explanation of some console commands of ZXEmuT.
please, note that all console commands are also Tcl procs.


quit
====
the most important command. quits emulator.

returns 1


reset
=====
resets emulated machine. it can also change machine type.
usage:
  reset [forced] <model> <issue> <memory> [trdos]

"forced" is used to force machine type reinit even if it wasn't changed.
it is optional.

<model> is machine type:
  48k
  128k
  plus2
  plus2a
  pentagon
  scorpion

<issue> is ZX Spectrum issue for 48k:
  issue2 (or2) (default)
  issue3 (or3)

<memory> is memory amount (in kilobytes) for Pentagon:
  128
  512
  1024

"trdos" is used to resed to TR-DOS. optional.

returns model name (string, same as "model") or 0


model
=====
simply prints current machine type (model).

returns model name (string)


nmi
===
generated Z80 NMI signal.

returns 1


grab
====
grab/ungrab mouse.
usage:
  grab "set"|"reset"|"toggle"

returns string ("on" or "off")


maxspeedugly
============
use simplified screen update for "max speed" mode?
usage:
  maxspeedugly "on"|"off"|"toogle"

ZXEmuT updates Spectrum screen with 4T precision. this guarantees that the
screen will look exactly as on real Spectrum, but for maxspeed mode it may
be not necessary. so you can switch to "ugly" updates once per frame.

returns string ("on" or "off")


fps
===
show/hide FPS counter.
usage:
  fps "on"|"off"|"toogle"

returns string ("on" or "off")


trdos
=====
enable/disable TR-DOS.
usage:
  trdos "on"|"off"|"toggle"

returns string ("on" or "off")


kmouse
======
enable/disable Kempston Mouse emulation.
usage:
  kmouse "on"|"off"|"toggle"|"normal"|"absolute"

returns string ("on" or "off").

there are two modes for kempston mouse: normal, with delta changes,
and absolute, when the corresponding port values are absolute screen
coordinates (in pixels, from the top left pixel).

i introduced absolute mode to make my life easier, there is no such
hardware. ;-)


swapbuttons
===========
enable/disable Kempston Mouse button swapping.
usage:
  swapbuttons "on"|"off"|"toggle"

there wasn't a definitive standard which bit corresponds to "left"
Kempston Mouse button, so you may need to swap buttons for some software.

returns string ("on" or "off")


kjoystick
=========
enable/disable Kempston Joystick.
usage:
  kjoystick "on"|"off"|"toggle"

returns string ("on" or "off")


speed
=====
change emulation speed.
usage:
  speed <option>

<option> can be one of:
  max -- maximum speed, no sound
  normal -- real-time speed, with sound
  toggle -- toggle between max and normal
  <number> -- percents of real-time speed

additional options:
  shade|noshade -- use shading to mark unupdated screen areas when the speed is <100%

returns integer number (percents), "max" or "normal"


pause
=====
pause/unpause emulation.
usage:
  pause "set"|"reset"|"toggle"

returns string ("set" or "reset")


temppause
=========
"secondary" pause. used for some internal housekeeping.
usage:
  temppause "set"|"reset"|"toggle"

returns string ("set" or "reset")


timings
=======
set ULA timings to "early" or "late".
usage:
  timings "early"|"late"|"toggle"

returns string ("early" or "late")


console
=======
show/hide console, or set console opacity.
usage:
  console <option>

<option> can be one of:
  show
  hide
  toggle
  number -- opacity; 0 is fully transparent, 255 is fully opaque

returns string ("show" or "hide"), or new alpha


kbleds
======
show/hide keyboard leds icon.
usage:
  kbleds "on"|"off"|"toggle"|<alpha>

returns string ("on" or "off"), or new alpha


kbreset
=======
reset ("unpress") virtual ZX keyboard.

returns true


ayreset
=======
reset AY.

returns true


debugger
========
show/hide debugger.
usage:
  debugger "on"|"off"|"toggle"|<alpha>

returns string ("on" or "off"), or new alpha


memview
=======
show, hide, setup memory viewer.

usage:
 memview [on|off|toggle|hex|text|32|42|51|64|max|7bit|cp-866|cp-1251|addr]


sprview
=======
show, hide, setup sprive viewer.

usage:
 sprview [on|off|toggle]


useplus3
========
enable/disable +3 contention scheme. NOT +3 model emulation!
usage:
  useplus3 "on"|"off"|"toggle"

returns string ("on" or "off")


genuine
=======
affects ULA emulation. this is internal debugging command.
usage:
  genuine "on"|"off"|"toggle"

returns string ("on" or "off")


contention
==========
enable/disable contended memory and ports emulation.
usage:
  contention "on"|"off"|"toggle"

returns string ("on" or "off")


memcontention
=============
enable/disable contended memory emulation.
usage:
  memcontention "on"|"off"|"toggle"

returns string ("on" or "off")


iocontention
============
enable/disable contended ports emulation.
usage:
  iocontention "on"|"off"|"toggle"

returns string ("on" or "off")


snow
====
enable/disable ULA snow emulation.
WARNING! this is not fully implemented yet.
usage:
  snow "on"|"off"|"toggle"

returns string ("on" or "off")


noflic
======
enable/disable "noflic" mode.
usage:
  noflic "on"|"off"|"toggle"

some demos and games quickly swaps 128K screens to create an illusion
of more colors. "noflic" mode mixes colors from current and previous
frames to emulate this effect. the emulation is not perfect, though.

returns string ("on" or "off")


brightblack
===========
enable/disable "bright black" mode.
usage:
  noflic "on"|"off"|"toggle"|value

some Speccy models (Timex, some Eastern clones) were rendering bright
black as gray. this option allows to emulate that. you can also set
default value for "gray black".

returns string ("on" or "off")


zxpalcolor
==========
get/set RGB for ZX colors.
usage:
  zxpalcolor index [rgb]

you can change default ZX Spectrum palette with this command. returns
previous rgb. rgb color is "#rgb" or "#rrggbb".


fullscreen
==========
switch fullscreen mode on/off.
usage:
  fullscreen "on"|"off"|"toggle"

returns string ("on" or "off")


keyhelp
=======
show/hide a picture with ZX Spectrum keyboard (so you can look for
BASIC tokens there).
usage:
  keyhelp "on"|"off"|"toggle"

returns string ("on" or "off")


allowother128
=============
allow loading snapshots for unknown/unsupported ZX Spectrum models.
usage:
  allowother128 "on"|"off"|"toggle"

returns string ("on" or "off")


keymatrix
=========
enable/disable keyboard matrix effect emulation.
usage:
  keymatrix "on"|"off"|"toggle"

on the original ZX Spectrum keyboard matrix could report some
additional keys as pressed when you press three or more keys.
this emulates the effect.

returns string ("on" or "off")


bad7ffd
=======
enable/disable broken Pentagon #FD port emulation.
usage:
  bad7ffd "on"|"off"|"toggle"

on Pentagons, #7FFD port decoding wasn't done properly, so programs
could use port #FD instead of full #7FFD to control memory banks.
you may need to emulate this effect for some Pentagon software.

returns string ("on" or "off")


ay
==
enable/disable AY-8912 emulation
usage:
  ay "on"|"off"|"toggle"

returns string ("on" or "off")


autofire
========
autofire emulation.
usage:
  autofire <args>

<args> are:
  "on"|"off"|"toggle"
  hold num -- number of frames fire should be hold
  delay num -- number of frames fire should be released
  key zxkeyname -- which key should be used (see keyname reference at the end of this file)

returns useless integer 1


usesound
========
enabble/disable sound.
usage:
  usesound "on"|"off"|"toggle"

this switches emulation modes between "with sound card", and
"without sound card". this is not the same as simply muting the
sound, because sound card is used for timings too. without a
sound card, the emulator will use system timer for synchronisation.

returns string ("on" or "off")


filter
======
screen filter.
usage:
  filter "off"|"tv"

returns string ("off" or "tv")


screenofs
=========
horizontal offset of the first Spectrum screen byte.
can be used to adjust border size.
usage:
  screenofs "none"|0..16|"speccy"

returns integer offset, or string ("normal" or "speccy")


colormode
=========
emulate various monochrome displays.
usage:
  colormode [0..4]|"normal"|"monochrome"|"green"|"yellow"

returns integer, or string ("normal", "monochrome", etc.)


brightborder
============
choose bit to "bright border" emulation.
usage:
  brightborder [0|5|6|7]

on Pentagons, it was possible to use 15 colors for border.
this command can be used to select which #FE bit should
be used for that. "0" means "disable bright border emulation".

returns string "off" or integer


sound
=====
sound control command.
usage:
  sound [off|beeper|ay|on|volume]
  sound volume [ay|beeper] [percents]
  sound ay <mono|acb|abc|on|off|query>
  sound filter <tv|beeper|none>
  sound restart

returns gibberish
"sound restart" does full sound system reinit (including sound card reinit)


issue
=====
select 48K issue to emulate.
usage:
  issue [2|3]

returns the corresponding integer


snapshot
========
snapshot i/o.
usage:
  snapshot <load|save|clear|reset> [name]

this command is used to save or load snapshots.

returns gibberish


rzx
===
RZX playback control. for now, you can only stop RZX playback.
usage:
  rzx <stop>

returns gibberish


peek
====
print memory byte at the given address.
usage:
  peek addr [bank-not-yet]

returns value


wpeek
=====
print memory word (two bytes) at the given address.
usage:
  wpeek addr [bank-not-yet]

returns value


poke
====
change byte at the given memory address.
usage:
  poke addr value

returns gibberish


wpoke
=====
change word (two bytes) at the given memory address.
usage:
  wpoke addr value

returns gibberish


scrattrfill
===========
full ZX Spectrum attributes with the given value.
usage:
  scrattrfill value

returns gibberish


tape
====
tape control center.
usage:
  tape cmd [args...]
    insert filename -- insert new tape
    save filename -- not implemented yet
    eject -- remove inserted tape
    clear -- insert empty tape
    start -- start tape playback
    stop -- stop tape playback
    rewind -- rewind tape; won't stop playback
    list -- not yet implemented
    option -- tape loader options

tape options:
  maxspeed "on"|"off"|"toggle"
    activate "maximum speed" mode when tape loader detected
  detectloader "on"|"off"|"toggle"
    try to detect tape loading code
  autopause "on"|"off"|"toggle"
    pause when tape loading complete
  flashload "on"|"off"|"toggle"
    use "instant loading" for some known loading schemes

please, note that loader detection is not 100% reliable. it works
most of the time, though.

returns gibberish


disk
====
disk control center.
usage:
  disk cmd [args...]
    insert filename
    save filename
    eject
    format [il=interleave] [sofs=sector_offset] (options are not supported yet)
    option autoadd_boot
    boot add [name] | remove | replace [name]
    protect
    unprotect
    info
    list
    extract
    add

"extract" will extract the file from TR-DOS disk, and will save it as HoBeta.
"add" will add HoBeta file to TR-DOS disk.
"format" formats TR-DOS disk.
supported disk formats:
  trd, scl: fully working
  udi, fdi: read/write, may have bugs
  td0: only read, may have bugs

returns gibberish


bp
==
debugger breakpoints control.
usage:
  bp [type] cmd [args...]

types:
  exec
  read
  write
  portin
  portout

commands:
  set addrlist
  unset addrlist
  toggle addrlist
  clear
  xsave fname
  xload fname

exec breakponts will open the debugger *BEFORE* executing Z80 instruction.
all other breakpoints will open the debugger *AFTER* Z80 instruction was
executed.

port i/o breakpoints will set bp on the exact port, and on low 8 bits.
i.e. port 0x7ffd will trigger breakpoint on accessing port 0x7ffd, and
on accessing port 0x00fd.

port 0 means "any port".

returns gibberish


label
=====
debugger label management.
usage:
  label cmd [args...]

commands:
  set addr name
  del addr-or-name
  goto addr-or-name
  get addr-or-name -- this doesn't error on missing label
  clear

with this command you can add or remove labels for debugger disassembly.
"goto" will change disassebly starting address.

returns label value or empty string


reffile
=======
load/save UrAsm .ref files.
usage:
  reffile <load|save|clear> [name]

UrAsm assembler can generate "reference files" (files with labels).
you can use this command to load those files, so the debugger will
show labels.

returns gibberish


fldebug
=======
internal command to help debugging FlashLoader(utm).
usage:
  fldebug "on"|"off"|"toggle"

returns string ("on" or "off")


opense
======
use OpenSE ROM instead of standard one?
usage:
  opense "on"|"off"|"toggle"

returns bool


gluck
=====
use Mr.Gluck Reset Service in Pentagon mode?
usage:
  gluck "on"|"off"|"toggle"

returns bool


quickcommander
==============
use Quick Commander ROM instead of 128 Basic on Pentagon?
usage:
  quickcommander "on"|"off"|"toggle"

returns bool


tsmark
======
start t-state profiler.
usage:
  tsmark [force]

"force" can be used to restart already started profiler.
see also: "tsdiff" command.

returns gibberish


tsdiff
======
stop t-state profiler, show info.
usage:
  tsdiff [keep]

this will stop t-state profiler (or won't stop, if "keep" is given).
the command will also print number of t-states passed since "tsmark".

this can be used to measue t-states used by some routines. open the
debugger, set breakpoint at routine entry, and breakpoint on routine
exit. then use "tsmark" on the first breakpoint, and "tsdiff" on the
second one.

returns number of t-states


vid_scale
=========
set window scale.
usage:
  vid_scale [1..4]

returns old scale.



ZX Spectrum Key Names
=====================
normal keys are named with their corresponding letter or digit.

special keys are:
  cap -- caps shift
  cs -- caps shift (the same as "cap")
  sym -- symbol shift
  ss -- symbol shift
  ent -- enter
  enter -- enter
  spc -- space
  space -- space

special names for Kempston Joystick:
  kright
  kleft
  kdown
  kup
  kfire


ZX Keyboard Bindings
====================
zxbind <pc-key-name> <zx-key-name>
zxunbind <pc-key-name>
  bind ZX Spectrum key to PC key.

bind <pc-key-name> "action"
unbind <pc-key-name>
  bind action to PC key.