PAX stands for Propeller Auto-config eXecutable
The "header" of a PAX file uses the same format as a FAT32 directory, with the following differences/special rules:
- Instead of a cluster number, the file pointer field holds the offset of that file from the beginning of the PAX, in 512 byte units. All files are stored unfragmented in the PAX (the PAX itself may be fragmented though).
- The first entry must be named
___P2PAX.V01and have attributes 0x09 (Volume Label+ReadOnly) - All files must have attributes 0x01 (ReadOnly)
- Subdirectories may not use the name of any special files (see later).
- Irrelevant fields (offsets 0x0C, 0x0D, 0x12) must be zero
- Filenames must match this regex:
/^[A-Z0-9\-_]{1,8}(\.[A-Z0-9]{1,3})?$/. That is to say, only uppercase letters, numbers, underscores and minuses are allowed. - Empty entries (0xE5) are not allowed.
- The directory ends with an all-zero entry.
Files may be stored at any 512 byte offset within the PAX. They must be padded with zeroes to the next multiple of 512 bytes. They are just files. You know how those work.
Some file names are reserved for special functions:
| File name | function |
|---|---|
MANIFEST.INI |
See Manifest section. |
_BOOT_P2.BIX |
P2 main executable |
_BOOT_P1.BIN |
Reserved |
anything starting with ICON |
Reserved |
HELP.TXT |
Help file |
These files should be placed as early in the directory as possible, ideally in this order.
Each PAX must contain a MANIFEST.INI file. This file contains one attribute/value pair per line, matching this regex:
/^ (_?) ([A-Za-z0-9]{1,14}) \x20* = \x20* (.*) \x20* $/x
That is to say, these are all valid lines:
Attrib0123=Value
_Attrib0123=Value
Attrib0123=Välüeß
Attrib0123= Value
Attrib0123 = Value
Attrib0123 =Value
Attrib0123=
And these are all not:
ÄÜÖttrib0123=Value
Attrib0123=Value
Attrib
_
Additionally, a line should not be longer than 256 bytes.
An attribute that starts with an underscore may be ignored when loading, but one without should raise an error if the loader doesn't recognize it or can't parse the assigned value.
These are the currently defined attributes:
| Attribute | Possible values | Meaning |
|---|---|---|
CPU |
P2 |
Target CPU (currently only P2), Should be the first line. |
ARGV |
TODO | Argument passing convention. Again, TODO. |
ForHWID |
VentilatorOS-style Hardware ID (8 character uppercase hex) | Refuse to load unless Hardware ID matches |
LinearPAX |
SD |
Refuse to load if PAX is fragmented (ignored if not loading from SD card) |
VidPtchAddr |
RAM address (5 character uppercase hex) | See Video config section |
VidModes |
See Video config section | See Video config section |
CIO1PtchAddr |
RAM address (5 character uppercase hex) | See Common IO section |
_Title |
UTF-8 String | Application Name |
_Vendor |
UTF-8 String | Application Vendor |
_Version |
ASCII String | Application Version |
Here are some examples of valid manifests:
CPU = P2CPU = P2
_Title = Simple Application
_Vendor = Joe Schmoe
_Version = beta 0.1
CIO1PtchAddr = 7A000
LinearPAX = SD
VidPtchAddr = 7A020CPU = P2
_Title = Hardware Application
ForHWID = DEADBEEFCPU = P2
_Title = Fixed-resolution Application
_Vendor = Zivikiller 2000
_Version = 2.1
CIO1PtchAddr = 7A000
VidPtchAddr = 7A020
VidModes = 640x480,1024x768,_NATIVECPU = P2
_Title = Retro Nonsense
_Vendor = IRQsome Software
CIO1PtchAddr = 01234
VidPtchAddr = 0AAAA
VidModes = 512x240/4x7@60This is in UTF-8, with linebreaks encoded as 0x10 (LineFeed)
If the CIO1PtchAddr attribute is set, the following 32-byte structure is patched into the given address:
byte SD_DO,SD_CLK,SD_DI,SD_SELECT ' SD card SPI mode pins. All 255 if no SD card
byte SD_DAT1,SD_DAT2,SD_WP,_reserved1 ' Extra SD pins, 255 if not available
long FATWorkDirClust ' FAT Cluster(!) number of the current working directory, $FFFF_FFFF if not available
long ThisPAXSector ' SD Sector number of the PAX file, $FFFF_FFFF if not applicable
long AUDIO_DACMODE ' default DAC mode. Must be DAC_
byte AUDIO_LEFT,AUDIO_RIGHT,_reserved2,_reserved3 ' Audio DAC pins. may be pinfields. 255 if not available. For mono audio, AUDIO_LEFT is the same as AUDIO_RIGHT
byte USB0_BASE,USB1_BASE,USB2_BASE,USB3_BASE ' USB ports. P2 EVAL - like layout is assumed. USB0 should be the preferred port for a keyboard.
long _reserved4If the VidPtchAddr attribute is set, the following structure is patched into the given address:
byte VIDEO_TYPE,VIDEO_SUBTYPE,VIDEO_BASEPIN,VIDEO_VSYNC
' Video pins:
' VIDEO_TYPE is the video type enum value:
' #0, RGBHV, RGBS, RGB_SOG, CVBS, SVIDEO, SVIDEO_CVBS, DVI
' VIDEO_SUBTYPE further specifies video type:
' when RGB_SOG: 0 for RGB with Sync-On-Green, 1 for YPbPr
' when CVBS/SVIDEO: 0 for NTSC, 1 for PAL
' VIDEO_VSYNC is the VSYNC pin in case of RGBHV or the reversed pins flag in case of DVI
long VIDEO_CAPS ' Video capability flags, see below
byte VSYNC_MAX,HSYNC_MAX ' Maximum V/H sync frequencies in Hz/KHz. Set to zero if not known / only standard modes supported.
byte VASPECT_H,VASPECT_V ' Display's preferred aspect ratio. Always valid.
word VNATIVE_W,VNATIVE_H ' Display's native or preferred resolution. Always valid.
byte PRECALC_VMODES[N*VMODE_SIZE] ' N precalculated video modes requested in the manifest. N=0 if VidModes is not set. See precalculated modes section for details.VIDEO_CAPS is a bitfield encoded as follows
| Bit | Name | Meaning |
|---|---|---|
| 0 | VC_NEED_BORDER | The display has a fixed native resolution and needs borders to be added to match it |
| 1 | VC_NEED_PILLARS | The display can not have its aspect ratio adjusted, so borders must be added in case the aspect ratio is mismatched |
| 2 | VC_PREF_LOWEST | When scaling fixed-resolution content, the display prefers lower resolutions |
| 3 | VC_CAN_PAL60 | The display supports PAL60 and NTSC50 decoding (CVBS/SVIDEO only) |
| 4 | VC_CAN_240P | The display supports 240p 60Hz |
| 5 | VC_CAN_288P50 | The display supports 288p 50Hz |
| 6 | VC_CAN_480I | The display supports 480i 60Hz |
| 7 | VC_CAN_576I50 | The display supports 576i 50Hz |
| 8 | VC_CAN_400P70 | The display supports 400p 70Hz |
| 9 | VC_CAN_480P | The display supports 480p 60Hz |
| 10 | VC_CAN_540P | The display supports 540p 60Hz |
| 11 | VC_CAN_576P50 | The display supports 576p 50Hz |
| 12 | VC_CAN_600P | The display supports 600p 60Hz |
| 13 | VC_CAN_720P | The display supports 720p 60Hz |
| 14 | VC_CAN_720P50 | The display supports 720p 50Hz |
| 15 | VC_CAN_720P24 | The display supports 720p 24Hz |
| 16 | VC_CAN_768P | The display supports 768p 60Hz |
| 17 | VC_CAN_800P | The display supports 800p 60Hz |
| 18 | VC_CAN_900P | The display supports 900p 60Hz |
| 19 | VC_CAN_960P | The display supports 960p 60Hz |
| 20 | VC_CAN_1024P | The display supports 1024p 60Hz |
| 21 | VC_CAN_1050P | The display supports 1050p 60Hz |
| 22 | VC_CAN_1080I | The display supports 1080i 60Hz |
| 23 | VC_CAN_1080P | The display supports 1080p 60Hz |
| 24 | VC_CAN_1080P50 | The display supports 1080p 50Hz |
| 25 | VC_CAN_1080P24 | The display supports 1080p 24Hz |
| 26 | VC_CAN_1152P50 | The display supports 1152p 50Hz |
| 27 | VC_CAN_1200P | The display supports 1200p 60Hz |
| 28 | VC_CAN_1440P | The display supports 1440p 60Hz |
| 29 | VC_CAN_1440P24 | The display supports 1440p 24Hz |
| 30 | VC_CAN_2160P | The display supports 2160p 60Hz |
| 31 | VC_CAN_2160P24 | The display supports 2160p 24Hz |
The manifest can request a number of video modes to be calculated by the loader. This is useful for simply displaying a fixed resolution without having to worry too much about interlacing or linedoubling.
The VidModes attribute is a comma-seperated list where each entry is either
NATIVE, the native resolution of the displayNAHALF, half the native resolution of the displaySAFE, a safe resolution- A resolution specification of the form
WxH - A resolution + pixel aspect specification of the form
WxH/wxh - A resolution + pixel aspect + refresh rate specification of the form
WxH/wxh@R
Additionally, each entry may be prefixed by an underscore if the mode is optional (failed calculation / not supported by display will result in zeroed mode) or by an exclamation point to additionally ignore display compatibility.
This is the structure patched into memory, per mode:
byte VMODE_VSCALE ' Vertical scaling factor. 0 if mode failed to be calculated, 1 if normal, 2 for linedoubling, 255 if interlaced mode
byte VMODE_HSCALE ' Horizontal scaling factor. 1 or 2.
word VMODE_PASPECT ' Pixel aspect ratio, as 4.12 fixed point
word VMODE_TOPBORDER
word VMODE_BOTTBORDER
word VMODE_SIDEBORDER
byte VMODE_TIMING[28] ' Video timing as per p2videodrv.spin2