Skip to content

Site map) Home > Getting Started > Running Durango Software > On actual hardware

Running Durango Software on actual Hardware

Like any other computer, Durango·X needs the code to be in some form of primary memory in order to be able to execute it. This can be any form of non-volatile Read-Only Memory (ROM) (usually EPROM/EEPROM/Flash) or, if some downloading means is available, into volatile Random Access Memory (RAM), much like a modern computer does.

ROM cartridges

This is the originally intended way to execute code in Durango·X. Since there's no ROM at all in the Durango·X main board, a suitable cartridge with appropriate code must be fitted into the cartridge slot.

In order to store suitable code in a cartridge, you'll need: - A non-volatile, programmable memory chip (EPROM, EEPROM, Flash) - A suitable programming device. A popular choice is the MiniPro TL866, but many others exist.

For this application, you may use any kind of Durango cartridge; the base mini-cartridge is very adequate.

Tip

At boot time, the 65C02 looks for a RESET vector located at addresses $FFFC-$FFFD and jumps to the address stored there (little-endian), executing the code. The cartridge slot in Durango·X is mapped to the upper 32 KiB of memory ($8000-$FFFF, minus the I/O area at $DF80-$DFFF), thus the ROM inside must have its contents aligned to the upper addresses, if needed, so this RESET vector is available.

ROM images on SD card

A ROM image is the actual binary contents of a ROM chip stored in a file on some secondary memory (mass storage) device, intended to be transferred to some RAM and be executed there; but Durango·X's RAM is mapped to $0000-$7FFF, whereas the ROM code is expected to fill the top of the addressing range.

The solution to this is the use of shadow RAM, which sits on the same address range of ROM and can be swapped with it -- starts in a write-only status to be loaded from a suitable bootloader in ROM, which then gets switched off and puts the shadow RAM in a read-only status, actually replacing the bootloader ROM and continuing the downloaded code execution.

This shadow RAM is present in the Development cartridge, but for a clean swap between the ROM and RAM execution, a proper footer must be present on the ROM image which, besides the aforementioned RESET vector, consists of:

  • The DmOS signature from address $FFD6.
  • A JMP ($FFFC) instruction from address $FFE1 (bytes $6C, $FC, $FF)

Note

The bootloader ROM code does swap to shadow RAM thru an instruction just before $FFE1, thus expects the RAM to be loaded with a suitable jump instruction -- JMP ($FFFC) goes to the specified RESET vector, actually bootstrapping the downloaded image as if it were in physical ROM.

In addition to that, bootstrap and image managing utilities expect a standard header on any ROM image for proper identification and metadata access.

A .dux file extension is recommended for ROM images in the host file system (but not mandatory).

Tip

Bootloaders expect to find a Durango volume (written raw in the card or, since multiBoot v2.0, as a durango.av file in the root directory of a FAT32 filesystem) containing at least one ROM image (or other executable). Note that a single ROM image may act as a whole volume.

The aforementioned Development cartridge provides all that is needed to get ROM images up and running:

  • 32 KiB of Shadow RAM.
  • A suitable (albeit a bit slow at ~3.4 KiB/s) SD card interface.

Pocket executables on SD card

Unlike a ROM image, a Pocket executable is a file containing code intended to be run on regular RAM (typically within $0800-$5FFF to stay clear of system variables and video memory). Thus, no shadow RAM or footer is needed; but the proper header becomes essential as it provides the load and execution addresses for the bootloader to be able to run the executable.

From the hardware side, any cartridge is suitable for the bootloader to run these Pocket executables; but, in any case, some way to access the SD card is needed, like the FastSPI interface or the SD+RTC sidecar, both performing at ~19 KiB/s. The slower Development cartridge is suitable as well.

Note

The handheld Durango Pocket computer (still in early development) lacks any cartridge slot, relying on Pocket executables downloaded from SD into regular RAM, hence the format's name -- albeit they aren't directly compatible.

Pocket executables from Raspberry Pi

Since the Pocket format has no special hardware requirements, the very same files can be transferred to the Durango·X computer from a Raspberry Pi or almost any other device with suitable GPIO pins, since all Durangos are equipped with a nanoLink input port which acts as an almost zero-hardware receiving interface, based on the use of both interrupt lines thru a simple three-wire connection (ground, clock & data) at a nominal speed around 15 kbps (~1.1 KiB/s after adding overhead).

Once again, any cartridge is suitable for the bootloader.

Warning

The concept of using the nanoLink port for receiving from a Raspberry Pi was first implemented on the nanoBoot protocol, but as of version 2.1.3 of the multiBoot bootstrapper, this option is NOT yet supported.