EXAMPLES

Here are some examples of what beebjit can do.

Any referenced .ssd file can be found on the Stairway to Hell archive:
https://www.stairwaytohell.com/bbc/archive/diskimages/reclist.php?sort=name
[NOTE: the .ssd file must be extracted from the .zip]

Any referenced .uef file can also be found there:
https://www.stairwaytohell.com/bbc/archive/tapeimages/reclist.php?sort=name
[NOTE: the .uef file must be extracted from the .zip AND further it must be
gunzip'ped to make a raw .uef]

The referenced EXILE.FSD file can be found inside a zip here:
https://stardot.org.uk/forums/download/file.php?id=4880

[NOTE: for the Windows port, you will use beebjit.exe in place of beebjit in
these examples, and you may also want to use Windows-style paths (\ instead of /
etc.)]


1) Running a classic from disc.
./beebjit -0 ~/Downloads/Acornsoft/StarshipCommand.ssd
[NOTE: the Break key is F12, so on a typical laptop the Shift + Break boot
command is hold Shift AND hold Fn AND while they are both held down, press and
release F12]

2) Running a classic from tape -- quickly!
./beebjit -tape ~/Downloads/Snapper-v1_B.uef -fasttape

beebjit boots up with the Disc File System selected. To load from a tape, type
these two commands in to the emulator on separate lines:
*TAPE
CH.""

[NOTE: the -fasttape option automatically turbocharges beebjit when the cassette
motor is switch on to load tapes, and resumes normal speed when the load is
done. You may be surprised how fast beebjit can complete the few minutes of
real time that elapse without the -fasttape option!]
[NOTE: the beeb keyboard is laid out differently to a modern PC / laptop, so
to get *, press Shift+' and to get ", press Shift+2]


3) Running the Exile protected disc -- enhanced sideways RAM version.
./beebjit -0 ~/Downloads/EXILE.FSD -swram 4
[NOTE: you'll need to find a copy of the Novella to answer the copy protection
question correctly! Perhaps try:
https://acorn.huininga.nl/pub/unsorted/scans/
]


4) Taking the terminal + headless mode for a spin.
./beebjit -terminal -headless
[NOTE: this is just a prototype. The main immediately apparent problem is that
Backspace doesn't erase any previous entered characters.]


5) Running Zalaga as if it had a 16MHz 6502, with other peripherals clocked as
normal.
./beebjit -0 ~/Downloads/Aardvark/Zalaga.ssd -opt bbc:cpu-scale-factor=8
[NOTE: a lot of software will behave strangely if you give it such an
out-of-spec BBC but Zalaga responds beautifully by rendering at a silky smooth
50Hz!]


6) Showing off beebjit's speed.
./beebjit -0 ~/Downloads/Acornsoft/Elite.ssd -log perf:speed

Press Alt-F to toggle fast mode when you're ready -- perhaps once the game's
start screen is visible with the classic rotating ship. There's more
optimization pending but beebjit is clearing 1GHz effective speed on my ancient
laptop.

Another good demo is Citadel's game start screen which cycles through different
rooms in the game. Press Alt-F there!


7) Writing to disc.
By default, discs are read-only. There are two levels of write that can be
activated:
a) Writeable virtual discs; changes not saved to host.
./beebjit -0 ~/Downloads/Acornsoft/Elite.ssd -writeable
b) Writeable virtual discs; changes saved to host.
./beebjit -0 ~/Downloads/Acornsoft/Elite.ssd -writeable -mutable
[NOTE: if you load an FSD format disc file while using -writeable and -mutable,
it will AUTOMATICALLY be converted to the HFE format. The FSD file will be
unchanged and a new .hfe file will be created and used.]


8) Checking out the fastest mode of beebjit.
So far, we've seen how to launch beebjit in its default mode (which is accurate
emulation), and press Alt+F to go as fast as possible while retaining cycle by
cycle accuracy.
There is another mode, which runs the virtual 6502 as fast as possible while
ticking hardware peripherals (timers, video etc.) at real time. This is not
a particularly accurate emulation but for highly compatible beeb code which
makes few timing assumptions, it works fine. For example, BASIC might be running
on a 2MHz 6502, a 2MHz 65c12, a 3MHz 6502 co-processor, etc., so it is not
picky.
./beebjit -fast -opt sound:off,bbc:cycles-per-run=10000000,video:frames-skip=5 -0 test/perf/clocksp.ssd
And then in the emulator:
CH."CLOCKSP"

Or you can combine this with the headless mode above:
echo 'CH."CLOCKSP"' | ./beebjit -fast -opt sound:off,bbc:cycles-per-run=10000000 -0 test/perf/clocksp.ssd -terminal -headless

Overall CLOCKSP is about 7GHz on my old slow laptop. I've seen individual tests
hit 10GHz but that was before the Intel meltdown / spectre fiasco and
slowdowns!
[NOTE: the long list of options is designed to get other subsystems out of the
way for maximum speed but it is unclear how much benefit they bring.]

Micro Power Chess works nicely in fast mode: you can play against its
highest level (which, contrary to what its instructions say, is Level 6,
not Level 9, see http://ssb22.user.srcf.net/bchess.html ) without having to
wait hours for each of the computer's moves:

./beebjit -fast -opt bbc:cycles-per-run=10000000,video:frames-skip=5 -0 ChessMicroPower.ssd


9) Capture and replay.
./beebjit -0 ~/Downloads/Superior/Thrust.ssd -capture thrust.cap

Play the game a bit, then exit the emulator.
./beebjit -0 ~/Downloads/Superior/Thrust.ssd -replay thrust.cap

Enjoy watching yourself! Use the Alt-F toggle to make the replay go super fast.
To exit a replay at any moment and "take over", press Alt-E.
And you can take an existing capture file and write to a new one if you want
to exit the existing capture and splice in a new reality!
./beebjit -0 ~/Downloads/Superior/Thrust.ssd -replay thrust.cap -capture thrust2.cap


10) Troubleshooting parameters.
There may be corner case bugs in the JIT compiler so you can switch back to a
standard 6502 interpreter if you like:
./beebjit -0 ~/Downloads/Superior/Galaforce.ssd -mode interp

Don't worry -- the interpreter mode still rockets along compared to most
emulators, 500MHz+ can be expected.

beebjit, by default, drives the host system very hard even when running the
beeb at normal real-time speed. This is to try and get best-in-class low
latency of the keyboard and sound subsystems. Maybe on your system, it drives
too hard?
./beebjit -0 ~/Downloads/Superior/Galaforce.ssd -opt sound:buffer=2048,bbc:wakeup-rate=100


11) Built-in 6502 debugger.
./beebjit -debug

Type ? then Enter at the prompt to see some of the more common commands.


12) Loading raw flux streams.
beebjit loads SCP, KryoFlux RAW and DFI flux files.
It's common to capture a flux file as double sided and 80 track, even for a
surface with less data such as a single sided 40 track surface. There are
options to skip the upper side, and the interim odd tracks to help load such
files easily:
./beebjit -0 ~/Downloads/Indoor_Sports_FDD15E11.scp -opt disc:skip-upper-side,disc:skip-odd-tracks

When loading a raw flux file, it's nice to get a quick summary of the discbeast
fingerprint and any protection:
./beebjit -0 ~/Downloads/Elite_B88911B2_BF6048A8.scp -log disc:fingerprint,disc:protection

You might also be loading a slightly iffy disc where the pulses aren't as
fresh as they once were! For such a disc, where you know it is a standard
beeb single density encoded disc, a more brutal quantization of pulses might
get it loaded:
-opt disc:quantize-fm
or, perhaps try loading a different revloution of the disc, since these flux
file formats often capture multiple disc revolutions per track:
-opt disc:rev=1
(the number is zero-based)


13) Loading a ROM, and running something requiring E00 DFS.
./beebjit -swram d -rom d roms/E00DFS090 -fast -opt sound:off -0 test/perf/pi.ssd -log perf:speed

In the above command, the E00DFS090 file is loaded in to ROM slot hex 0xd, which
overrides the default DFS ROM in that same slot. Furthermore, this ROM actually
needs to be in a writeable sideways RAM bank to work, to the -swram d option
is also needed.
The pi.ssd test will calculate more digits if it detects $0E00 PAGE!


14) Other significant parameter examples.

If you have a high DPI display and the BBC window is too small,
you can try doubling the pixels (at a very small speed cost),
./beebjit -opt video:double-size
Still on the theme of display related options, you can turn on interlaced
rendering. beebjit will avoid rendering in a way that wobbles.
./beebjit -opt video:no-deinterlace-teletext -opt video:no-deinterlace-bitmap
And perhaps you'd like a smaller beebjit window, framed to the exact bounds of
the typical modes?
./beebjit -opt video:border-chars=0


15) Using double density (MFM) DFS's to format to an HFE.

cp test/empty/empty_80T_DS_DD.hfe testing.hfe
./beebjit -0 testing.hfe -1770 -opus -writeable -mutable
(Then *FORMAT for the Opus formatter.)


16) Command-line timed event control.

This example waits for the beeb to start up a bit, then injects some memory at
$1900 from file 'bmem' (the raw memory of a BASIC program), and then uses
further delays and commands to inject 'RUN<return>' to the keyboard.

./beebjit -commands 'breakat 1000000;c;loadmem bmem 1900;keydown 82;breakat 1100000;c;keyup 82;keydown 85;breakat 1200000;c;keyup 85;keydown 78;breakat 1300000;c;r;keyup 78;keydown 131;breakat 1400000;c;keyup 131;c'

(WARNING: the commands are those available in the debugger. The example above
runs even without -debug and the appeal of it is that it runs at full speed.
Certain debug commands won't work without -debug though, such as those that
require examining state at every instruction. Most notably, this includes
breakpoints.)


17) Keyboard remapping.

This example plays Thrust, but with the Z / X keys being usable for left / right
in addition to Caps Lock / Ctrl.
The constants for "normal" keys are defined by their ASCII codes.
The constants for special keys are defined here:
https://github.com/scarybeasts/beebjit/blob/master/keyboard.h

./beebjit -0 ~/Downloads/Superior/Thrust.ssd -key-remap 90 135 -key-remap 88 132