Difference between revisions of "The Atari 7800 BEAD Executable Specification"

Latest revision as of 17:27, 19 July 2019

Overview

An Atari 7800 BEAD executable consists of a BEAD header, followed by regular executable code. The name "BEAD" is derived from the first two magic bytes within the header, that serve to identify the format - $BE $AD.

The BEAD header allows a 6502-based BEAD loader to easily determine the memory and hardware requirements of the executable. BEAD executables require only the most basic storage features, so they can be easily stored and loaded directly from various media sources, such as RAM, SaveKey, and online sources. When they reside on a filesystem, the extension for BEAD executables is *.b78.

Another notable feature of the BEAD executable, is the fact that the header is part of the program code, and completely executable by the 6502. ($BE $AD $## being the assembly comand "LDX $##AD,y".)

Minimal BEAD Header

A minimal BEAD header consists of the two identifying bytes, $BE $AD, and a format specifier byte.

$BE,$AD,[F1]

The [F1] bits are defined as %vHYPRDSS, where...

v == Reserved (set to '0')
H == High Score Cartridge
Y == Yamaha
P == Pokey @ $450
R == ROF @ $4000
DSS == Data Type and Size
  \ %000 : 16K @ $C000 - $FFFF
    %001 : 32K @ $8000 - $FFFF 
    %010 : 48K @ $4000 - $FFFF
    %011 : reserved
    %100 : reserved
    %101 : 4K @ $1800 - $27FF
    %110 : 16K @ $4000 - $7FFF
    %111 : reserved

Implementation Notes

• All reserved bits must be set to 0.
• The BEAD executable must be the same size as specified in the DSS field.
• DSS types that don't have memory covering the 6502 reset vector will begin execution from the BEAD header. For executables with DSS types that do cover the reset vector, it's strongly encouraged that code execution beginning at the header location works correctly, as some BEAD loader implementations may not begin execution at the reset vector address.
• BEAD loaders won't relocate any absolute references, so executable code should be assembled specifically for the target location.

Extended BEAD Header

An optional extended BEAD header allows for a name or description to also be embedded in the executable.

$BE,$AD,[F1],$18,$90,[SS],"Description",0

The first three bytes are the familiar minimal BEAD header. The following bytes $18,$90 identify that a description string follows, with the [SS] byte specifying the total number of bytes in the string. (including the zero terminator.)

The description text itself is ASCII encoded, and may contain any non-control ASCII character, though BEAD loaders may implement the display, or non-display, of any description text. For this reason it's recommended to stick to basic alphanumeric text.

It should be noted that the $18,$90 bytes are the 6502 CLC and BCC opcodes, so the [SS] value can easily be generated in assembly code, as with the following example.

 .BYTE $BE,$AD,%00000010
 CLC
 BCC DescriptionEnd
 .BYTE "My Description",0
DescriptionEnd:

Chained BEAD Support

The Atari 7800 SaveKey doesn't have a native filesystem. If BEAD executables are sequentially stored on the SaveKey (ie. "chained") loaders may optionaly support the user selecting to run a particular BEAD in the chain.

Chained BEAD support may also be applied to other storage devices without a filesystem.

Defines

To assist with BEAD header creation, you may wish to use the following assembly definitions.

BDHSC   = %01000000
BDYM    = %00100000
BDPOKEY = %00010000
BDROF   = %00001000
BD16K   = %00000000
BD32K   = %00000001
BD48K   = %00000010
BD1800  = %00000101
BD4000  = %00000110

These will allow you to generate BEAD headers with improved readability, as in the following example.

 .byte $BE,$AD,(BDHSC|BDPOKEY|BD1800)