UEF (file format)

Infobox file format
name = Unified Emulator Format
icon =



caption =
extension = .uef
mime = application/octet-stream
type code =
uniform type =
magic = UEF File!
owner = Thomas Harte
released = before 10 August 2000 [http://mdfs.net/Archive/BBCMicro/2000/08/10/130415.htm]
latest release version = 0.10 draft 28
latest release date = 10 January 2006
genre = Emulation, chunked file format
container for =
contained by =
extended from =
extended to =
standard =
url = http://electrem.acornelectron.co.uk/UEFSpecs.html

UEF (Unified Emulator Format) is a compressed, chunked file format for the storage of audio tapes, ROMs, floppy disks and machine state snapshots for the 8-bit range of computers manufactured by Acorn Computers Ltd. First implemented by Thomas Harte's ElectrEm emulator and related tools, it is now supported by major emulators of Acorn machines and carried by two online archives of Acorn software numbering thousands of titles.

UEF attempts to concisely reproduce media borne signals rather than simply the data represented by them, the intention being an accurate archive of original media rather than merely a capability to reproduce files stored on them. A selection of metadata can be included, such as compatibility ratings, position markers, images of packaging and the text of instruction manuals.cite web
last = Harte
first = Thomas
title = UEF File Format Specs 0.10 (document draft 28)
date = 2006-01-10
url = http://electrem.acornelectron.co.uk/UEFSpecs.html
accessdate = 2008-08-08]

The Acorn machines implement the Kansas City standard (KCS) for tape data encoding and as a result the file format is suitable for creating backups of original media for several non-Acorn machines. As of version 0.10 the file format carries BASICODE signals as well. TZX [http://www.worldofspectrum.org/TZXformat.html] is a chunked format with similar scope for the ZX Spectrum series.

History

Before UEF, software archives on the Web such as [http://www.nvg.org/bbc/ The BBC Lives!] adopted a convention of hosting ZIP archives of the raw files on a tape, each raw file accompanied by a plain-text INF file carrying the load and execution addresses from the file header. The INF convention, described and implemented by Wouter Scholten in [http://wouter.bbcmicro.net/8bit/bbc/bbc-pc-software.html "bbcim"] (1995), extends the output format of the *INFO command (Acorn DFS, ADFS) to cover CRCs and the order of files on tape. While it works adequately for user files, it does not preserve the baud rate, precise timing information or non-standard data streams used in copy protected titles.

tructure

A UEF file consists of a fixed length "header" that identifies itself, followed by a linked list of "chunks" containing the data of interest. The header comprises the magic string UEF File!, a terminating null character, and a two-byte version number of the UEF specification in use. A reading application needs to pay attention to the version number, as the unit of measurement in some chunks differs according to the specification version, and one chunk has been redefined.

Each chunk consists of a two-byte "ID" which determines its meaning, the "length" of the body in four bytes, and the "body" itself. An application can readily skip the bodies of chunks it does not need to process. After the last chunk the file simply ends. Currently, UEF chunks do not nest.

The whole UEF file, including the header, may optionally be compressed in gzip format; by examining the start of the file for a gzip or UEF header, a decompression routine can be invoked as appropriate.

Content

The Unified Emulator Format models software on cassette as a contiguous sequence of segments, which may be carrier tones, modulated asynchronous signals, "security cycles" (modulated synchronous signals, said to be an "identification feature") or "gaps" where no recognised signal is present. Tape UEF chunks are concatenated in the order they appear, to build up the representation of a whole recording. When generated from a real source tape, each tape chunk corresponds directly to a waveform on the tape, such that the source can be accurately reconstructed (with any non-encodable signals replaced by gaps of equal length.) Standard Acorn streams are encoded so that their bytes reappear in the UEF chunk body.

There are some "modal variables" affecting the interpretation of these chunks: the baud rate, 1200 baud for Acorn signals or 300 baud for KCS; the exact carrier frequency, which determines the playing time of the reconstructed tape; and the phase of the signal. The latter two may change within a published recording, and their absolute values depend on the tape player, amplifier and sound card used to digitise the signal.

A UEF file can contain markers to separate the tapes of a multiple-tape distribution, and the sides of each tape; positions of interest within each side can also be marked.

Disks are stored as raw sector dumps of each surface, plus their geometry and a byte identifying the file system. Previous versions of the specification had provisions to encode disks at the byte stream level, or the magnetic domain level.

Sideways ROMs are likewise stored as raw data, plus an indication of their purpose and a ROM slot recommendation.

State snapshot UEF files include standardised chunks to store the major portions of an Acorn Electron or BBC Micro's state: main memory, the CPU and floppy disk controller registers, and so on. A range of chunk IDs is reserved for private use by emulators, and they use these private chunks for state variables not accommodated in the standard chunks.

Multiplexed data is an extension for emulators, used by ElectrEm but with no published specification:

Bit multiplexing supplies the emulator with additional information so that old programs may be run to produce a greater quality of output.

This feature is really only for emulation use of UEF files and ignoring bit multiplexing will have no effect on the accuracy of your tool to original hardware.

—Thomas Harte, UEF File Format Specs 0.10 (document draft 28)

One salient application mentioned by Harte is to superimpose "new graphics on old games",cite web
url= http://mdfs.net/Archive/BBCMicro/2003/08/01/004758.htm
title= Re: BBC double density disc images
accessdate= 2008-05-25
last= Harte
first= Thomas
date= 2003-08-01
work= BBC Micro Mailing List Archive] and a single example, a 256-color enhanced "Daredevil Dennis", is available from [http://www.stairwaytohell.com/ StairwayToHell.com] to run in ElectrEm.

Multiplexed data chunks are intended to follow ordinary data chunks in any of the above classes, supplementing the data. Their contents are not meant to be "presented to" Acorn computers, real or emulated, but otherwise their meaning has not been specified.

Content information includes a "file origin" chunk, which identifies the application that generated the UEF file. There are defined formats for scanned images of cassette inlays; the text of any accompanying instruction booklet can be included; the UEF file can recommend a "short title", minimum machine specification and keyboard mapping for the enclosed software; and where a game does not use the whole screen, the coordinates of the "visible area" can be given. A minority of UEF files available online contain anything in this class but an origin chunk.

A UEF file can contain multiple classes of data at once; it is not possible to know which classes it contains without scanning the whole file. In its file selection box ElectrEm displays an icon according to the first data class chunk it finds.

Applications

MakeUEF

[http://www.acornpreservation.org/makeuef/index.html MakeUEF] is a Windows application written by Thomas Harte and expanded by Fraser Ross to convert audio samples into UEF files. Two grades are offered. An 'amateur' version reads WAV files or a live signal played to the sound card, and transcribes only standard data blocks with accuracycite web
last = Ross
first = Fraser
coauthors = Harte, Thomas
title = MakeUEF 2.1 distribution
publisher = Acornpreservation.org
date = 2007-01-18
url = http://www.acornpreservation.org/makeuef/MakeUEF-v2.1.zip
format = ZIP archive containing PDF
accessdate = 2008-02-24] . The 'professional' grade accepts only CSW files, which represent waves preprocessed into rectangular pulse trains, but it encodes all audio information supported by the UEF specification.

In its manual MakeUEF claims to have been the sole creator of UEF files that were available on the Web before November 2004, the month of its version 1.0 release. Although the file format was more capable, only "program data" was retained by MakeUEF prior to version 1.0. From November 2004 the fidelity of MakeUEF improved and the file spec was further refined, and an extension of .hq.uef ("high quality") was adopted to reflect this. The [http://www.acornpreservation.org/ AcornPreservation.org] archive only carries the .hq.uef variety as well as the CSW source files. Its sister site [http://www.stairwaytohell.com/ StairwayToHell.com] accepts 'amateur' UEF translations and files produced by pre-1.0 MakeUEF. As of 2008 the latter site hosts 1,494 transcriptions of BBC Micro cassette titles and at least 800 of Electron titles.

Others

* Several emulators of Acorn machines support UEF natively, to read and write tape data (at original speed or faster) and store state snapshots. Examples include ElectrEm, BeebEm and B-Em.

* [http://electrem.acornelectron.co.uk/Tools.html FreeUEF] by Thomas Harte and the [http://uefreader.sourceforge.net/ UEFReader] plugin to the jlGui media player, convert a UEF file to a wave suitable for recording on tape or playing back to a physical computer.

* The [http://homepages.tesco.net/~rainstorm/#prog.uefwalk UEFwalk] script validates and extracts data from UEF files.

* The [http://homepages.tesco.net/~rainstorm/#prog.xvuef XVUEF] patch extends the Xv image editor to support the little-used inlay scan chunks of the UEF.

References