VBXE FX and GTIA cores v1.27.2 - package, issue 2
==================================================

Tomasz Piórek / electron, 2026-10-31

VBXE cores v1.27.2 for VBXE 1.x and 2.x, the Atari tools to install and run
them, their sources, test programs, demos, the PAL and NTSC palettes and older
examples by other authors.

Changes since the first issue (2026-10-16)
------------------------------------------

  - Cores (cores/*.xbf): all eight cores are updated to v1.27.2. The
    identification string in the core reads "FX v1.27.2" or "GTIA v1.27.2".
    Software cannot tell them apart from v1.27 (the same VERSION value) and
    their functionality is exactly the same. Internal improvements: more
    reliable synchronisation with the computer after RESET and better
    cooperation of the MEMAC with other devices on the bus.
  - Programmer's Manual: revision 10 (31 October 2026) instead of revision 7.
    Corrections and clarifications: Overlay data fetch in the forbidden
    OV_HR + OV_LR combination; raycasting container (accumulators are not
    reloaded during a blit, texture wrapping, reserved size values); XCOLOR
    and VIDEO_CONTROL; palette selection with the Attribute Map; notes and
    cautions reviewed; new chapter "Compatibility and hardware notes"
    (EXTSEL pull-up resistor for problems with devices on the parallel bus,
    SUBcart and its 1 MB PORTB mode, turbo systems replacing the 6502).
  - Programmer's Manual also as PDF.
  - New test program VBXE DOCTOR v1.4 (tests/vdoctor.xex, tests/vdoctor.zip):
    diagnostic of the VBXE core registers, VRAM access through MEMAC-A and
    MEMAC-B, and Blitter access to VRAM.
  - Disk images contain the v1.27.2 cores and VDOCTOR.XEX.
  - Tools, other test programs, demos and palettes are unchanged.

NOTE: Upgrade the core in your VBXE with FC (FC.XEX), which is on the disk
images in images/ (VBXE_FX_127_MYDOS.ATR, VBXE_FX_127_SDX.ATR) together
with the core files. How to do it step by step is described in the user
manual tools/FC_and_DCFG_User_Manual.md ("Install a core from disk").

Compatibility
-------------

Compatibility has to be provided by all the devices connected to the
computer at the same time. There are situations in which VBXE works
correctly on its own, but does not in combination with another device,
either internal or connected externally to the bus of the computer.

SUBcart with its 1 MB PORTB memory extension enabled is not compatible with
VBXE (checked on SUBcart firmware v012 and v013 beta 1). In this mode
SUBcart puts its own memory in place of the computer's RAM at $A000-$BFFF in
every CPU access (it pulls the REF line low, so the computer disables its
memory there). MEMAC windows placed over $A000-$BFFF then do not work: reads
return SUBcart's memory and writes go there, not to VRAM. This is a
limitation of SUBcart, not a VBXE malfunction: VBXE gives the bus to the
device that took it, exactly as it does for ROM and cartridges. The smaller
PORTB modes of SUBcart (128, 192, 320 and 576 KB), and SUBcart with the
extension off, work with VBXE. Limited compatibility with VBXE is also
suspected when some of the cartridge emulation modes of SUBcart are used
(running programs from .car files).

Turbo systems (6502 replacements) change the architecture of the computer
in various, often quite radical ways, with consequences for compatibility
that are hard to predict and different for each device. VBXE works in such
an environment on a best-effort basis. See chapter 2 of the Programmer's
Manual.

Core files (cores/*.xbf)
------------------------

  v1f127a1.xbf
  | ||  ||
  | ||  |+-- 1 = PAL, 2 = NTSC
  | ||  +--- a = no RAMBO extended memory
  | |+------ 127 = core version 1.27
  | +------- f = FX core, g = GTIA core
  +--------- v1 = VBXE 1.x, v2 = VBXE 2.x

Choose the file for your board (VBXE 1.x or 2.x) and your TV system.
Install it into a FLASH bank with FC (key L) or load it once with DCFG.
See tools/FC_and_DCFG_User_Manual.md.

Requirements
------------

  FC, DCFG, VQREBOOT, VXREBOOT  any VBXE 1.x / 2.x
  VHCLIP                        FX or GTIA core v1.27
  vbxe240p                      FX core v1.26 or newer
  blitter1, blitter2            FX core v1.26 (tests 1-88) or v1.27 (all 150 tests)
  SIGS, Wolfette                FX core v1.27
  VBXE DOCTOR (vdoctor)         FX or GTIA core v1.26 or newer, 64 KB RAM

All programs are Atari DOS executables (.xex) for an Atari XL/XE with VBXE.
The disk images in images/ contain all .xex and .xbf files of the package:
  VBXE_FX_127_MYDOS.ATR  bootable MyDOS 4.55 Beta 4, 1.25 MB, 256-byte sectors
  VBXE_FX_127_SDX.ATR    SpartaDOS file system for SpartaDOS X 4.50,
                         1.25 MB, 256-byte sectors, not bootable
                         (SpartaDOS X starts from its cartridge)
  On the disks the Blitter tests are BLITTER1.XEX and BLITTER2.XEX.

Building the tools
------------------

MADS 2.1.7, in the mads directory:
  mads fc.mads -x -i:include -o:fc.xex
  mads dcfg.mads -x -i:include -o:dcfg.xex
  mads vqreboot.mads -x -i:include -o:vqreboot.xex
  mads vxreboot.mads -x -i:include -o:vxreboot.xex
  mads vhclip.mads -x -i:include -o:vhclip.xex
These commands build the files in tools/.
The test programs and demos are built with llvm-mos, see the README in
their source archives (tests/vdoctor.zip holds only the program and its
manual, without sources).

Palettes
--------

palettes/ holds the PAL and NTSC palettes of the cores:
  PAL.act        PAL palette, 256 colors x RGB, 8 bits per component
  NTSC.act       NTSC palette, the same format
  palettes.mads  both palettes for MADS: separate 256-byte tables of the
                 R, G and B components (pal_r, pal_g, pal_b, ntsc_r,
                 ntsc_g, ntsc_b), index = Atari color
The VBXE uses bits [7:1] of each component (CR, CG, CB registers), so the
values can be written to the registers directly.

Old examples
------------

old_examples/ contains older VBXE example programs and sources by other
authors, one directory per author: Candle, Electron, Fox, KMK,
LAMERS_Group, Rybags, TeBe. They are included as they are, without
changes, and are not described further here; see the readme files in the
author directories (KMK, Fox) where present.

File list
---------

  README.txt                                                    this file
  VBXE_FX_and_GTIA_cores_v1.27_Programmers_Manual.md    125660  Programmer's Manual of the FX and GTIA cores v1.27
  VBXE_FX_and_GTIA_cores_v1.27_Programmers_Manual.pdf   776469  the same manual as PDF
  cores/v1f127a1.xbf                                     98062  FX core v1.27.2, VBXE 1.x, PAL
  cores/v1f127a2.xbf                                     98062  FX core v1.27.2, VBXE 1.x, NTSC
  cores/v1g127a1.xbf                                     98062  GTIA core v1.27.2, VBXE 1.x, PAL
  cores/v1g127a2.xbf                                     98062  GTIA core v1.27.2, VBXE 1.x, NTSC
  cores/v2f127a1.xbf                                     98062  FX core v1.27.2, VBXE 2.x, PAL
  cores/v2f127a2.xbf                                     98062  FX core v1.27.2, VBXE 2.x, NTSC
  cores/v2g127a1.xbf                                     98062  GTIA core v1.27.2, VBXE 2.x, PAL
  cores/v2g127a2.xbf                                     98062  GTIA core v1.27.2, VBXE 2.x, NTSC
  tools/fc.xex                                            9439  FC - Flash Configurator v1.20
  tools/dcfg.xex                                          5182  DCFG - Direct Configurator v2.15
  tools/vqreboot.xex                                       580  VQREBOOT - restart the BootBank core, silent
  tools/vxreboot.xex                                       798  VXREBOOT - restart the BootBank core, with messages
  tools/vhclip.xex                                          61  VHCLIP - persistent hard clipping (CLIP + PXGF)
  tools/FC_and_DCFG_User_Manual.md                       11558  user manual of FC and DCFG
  tools/VQREBOOT_and_VXREBOOT_User_Manual.md              2761  user manual of VQREBOOT and VXREBOOT
  tools/VHCLIP_User_Manual.md                             1639  user manual of VHCLIP
  mads/fc.mads                                           50287  FC source
  mads/dcfg.mads                                         20068  DCFG source
  mads/vqreboot.mads                                      8649  VQREBOOT source
  mads/vxreboot.mads                                     10223  VXREBOOT source
  mads/vhclip.mads                                        2089  VHCLIP source
  mads/include/atarihw.mads                              11682  Atari hardware registers
  mads/include/atarios.mads                               8207  Atari OS variables and routines
  mads/include/filebox.mads                              42449  file selection box, windows, I/O routines
  mads/include/macros.mads                                9551  memory copy / fill macros
  mads/include/vbxefx.mads                               39002  VBXE FX core registers and macros
  tests/blitter1.xex                                     17158  Blitter test: all tests once, waits for keys
  tests/blitter2.xex                                     16966  Blitter test: endless loop, stops at the first failure
  tests/blitter.zip                                      54427  Blitter test sources (llvm-mos C) and test list
  tests/vbxe240p.xex                                     11253  VBXE 240p Test Suite v1.0
  tests/vbxe240p.zip                                     52262  VBXE 240p Test Suite sources (llvm-mos C) and user manual
  tests/vdoctor.xex                                      37829  VBXE DOCTOR v1.4 - VBXE diagnostic (registers, VRAM, Blitter)
  tests/vdoctor.zip                                     335871  VBXE DOCTOR program and user manual (MD, PDF)
  demos/sigs.xex                                        124749  SIGS - Strong Independent Girls Demo
  demos/sigs.zip                                        872814  SIGS sources (llvm-mos C, Python asset tools)
  demos/wolfette.xex                                     29534  Wolfette - raycasting demo
  demos/wolfette.zip                                     57341  Wolfette sources (llvm-mos C)
  images/VBXE_FX_127_MYDOS.ATR                         1310352  bootable MyDOS 4.55 disk with all programs and cores
  images/VBXE_FX_127_SDX.ATR                           1310352  SpartaDOS X disk with all programs and cores
  palettes/PAL.act                                         768  PAL palette (ACT)
  palettes/NTSC.act                                        768  NTSC palette (ACT)
  palettes/palettes.mads                                  9968  PAL and NTSC palettes as MADS data tables
  old_examples/                                                 older examples by other authors (573 files, see above)
