Description of the 3DO Portfolio OS Audio Folio ".dsp" file format.

===== Structure =====

"dsp" files are IFF files (Interchange File Format) which store the DSP program and metadata.

IFF files are made up of "chunks." A chunk is made up of an id (4 chars), size (32bit signed int), and data (byte array). In C/C++ a chunk structure would look like this:

<code>
typedef char iff_id_t[4];

typedef struct iff_chunk_s iff_chunk_t;
struct iff_chunk_s
{
  iff_id_t id;
  int32_t  size;
  uint8_t  data[0];
};

</code>

Syntax definitions from the original IFF document:

<code>
Chunk    ::= ID #{ UBYTE* } [0]

Property    ::= Chunk

FORM    ::= "FORM" #{ FormType (LocalChunk | FORM | LIST | CAT)* }
FormType    ::= ID
LocalChunk    ::= Property | Chunk

CAT    ::= "CAT " #{ ContentsType (FORM | LIST | CAT)* }
ContentsType    ::= ID    -- a hint or an "abstract data type" ID

LIST    ::= "LIST" #{ ContentsType PROP* (FORM | LIST | CAT)* }
PROP    ::= "PROP" #{ FormType Property* }

In this extended regular expression notation, the token "#" represents
a ckSize LONG count of the following {braced} data bytes. Literal
items are shown in "quotes", [square bracketed items] are optional,
and "*" means 0 or more instances. A sometimes-needed pad byte is
shown as "[0]".

</code>

More information:

  * [[https://en.wikipedia.org/wiki/Interchange_File_Format|https://en.wikipedia.org/wiki/Interchange_File_Format]]
  * [[http://www.martinreddy.net/gfx/2d/IFF.txt|http://www.martinreddy.net/gfx/2d/IFF.txt]] ({{:documentation:file_formats:iff.txt|local copy}}  )

===== Chunks =====

Details in part taken from the [[https://ext.3dodev.com/3DO/Portfolio_2.5/OnLineDoc/DevDocs/ppgfldr/smmfldr/cdmfldr/08CDM003.html#XREF23322|SDK documentation]].

^ID^Description|
|FORM.3INS|3DO Instrument|
|FORM.3INS.NAME|The original filename|
|FORM.3INS.FORM|DSP file info|
|FORM.3INS.FORM.DSPP|DSP program|
|FORM.3INS.FORM.DSPP.DHDR|DSP program header \\  \\ 16 bytes. 4 32bit words. \\  \\ word[0] = \\ word[1] = \\ word[2] = \\ word[3] =|
|FORM.3INS.FORM.DSPP.[[https://ext.3dodev.com/3DO/Portfolio_2.5/OnLineDoc/DevDocs/ppgfldr/smmfldr/cdmfldr/08CDM003.html#XREF25510|DCOD]]|DSP code plus chunk \\  \\ The beginning of the DCOD chunk contains a table with entries for each subchunk, as follows: \\  \\ int32 dcod_Type; \\ int32 dcod_Offset; \\ int32 dcod_Size; \\  \\ There are three possible values for dcod_Type: \\  \\ DCOD_INIT_DSPP () = initialization code for DSP \\ DCOD_RUN_DSPP () = run time DSP code \\ DCOD_ARGS () = TagArgs with null terminator|
|FORM.3INS.FORM.DSPP.[[https://ext.3dodev.com/3DO/Portfolio_2.5/OnLineDoc/DevDocs/ppgfldr/smmfldr/cdmfldr/08CDM003.html#XREF19989|DRSC]]|A DRSC chunk consists of an array of resource requests, as follows: \\  \\ int32 drsc_Type \\ int32 drsc_Many \\ various drsc_Allocated /* Filled when allocated */ \\ int32 drsc_References /* Count for exported references */ \\  \\ The following types are supported are: \\  \\ DRSC_EN_MEM = EN Memory for DSPP programs \\ DRSC_EI_MEM = EI Input Memory for knobs \\ DRSC_I_MEM = I Memory \\ DRSC_EO_MEM = EO Output Memory for debugging \\ DRSC_RBASE4 = RBASE with 4 I regs \\ DRSC_RBASE8 = RBASE with 8 I regs \\ DRSC_INFIFO \\ DRSC_OUTFIFO \\ DRSC_TICKS = CPU cycles in DSPP|
|FORM.3INS.FORM.DSPP.[[https://ext.3dodev.com/3DO/Portfolio_2.5/OnLineDoc/DevDocs/ppgfldr/smmfldr/cdmfldr/08CDM003.html#XREF14022|DRLC]]|Relocation \\  \\ A DRLC chunk is an array of relocation commands consisting of the following: \\  \\ uchar drlc_Attribute /* of resource */ \\ uchar drlc_Flags \\ uchar drlc_Width /* of field to update */ \\ uchar drlc_Bit /* bit position of LSB of field*/ \\ int32 drlc_CodeIndex /* Index of subchunk in DCOD */ \\ int32 drlc_RsrcIndex /* Index of entry in Resource Chunk */ \\ int32 drlc_CodeOffset /* Offset within subchunk */ \\  \\ Some important fields are discussed in the following table \\  \\ DLRC chunk fields. \\  \\ DLRC_Attribute: Used to calculate the relocation value from the allocated value. An example would be the STATUS address for a FIFO as opposed to the normal FIFO address. \\  \\ DRLC_ADD: Adds allocated value to current contents of word pointed to by CodeOffset instead of simply setting contents. Generally used for relocating branchesby referencing EN Resource. When the EN instruction space isallocated, the new base address is added to the offset currently compiled for each branch. \\  \\ DRLC_LIST: The CodeOffset points to a singly linked list of fields to be set to the allocated value. This field should not be set if DRLC_ADD is set. \\  \\ DRLC_32: 32-bit data are relocated. Offsets are indexes into uint32 instead of ushort arrays.|
|FORM.3INS.FORM.DSPP.[[https://ext.3dodev.com/3DO/Portfolio_2.5/OnLineDoc/DevDocs/ppgfldr/smmfldr/cdmfldr/08CDM003.html#XREF21605|DNMS]]|Packed Resource Names \\  \\ A DNMS chunk is a packed array of Forth/Pascal style strings. Resources without names have a 0-byte placeholder.|
|FORM.3INS.FORM.DSPP.[[https://ext.3dodev.com/3DO/Portfolio_2.5/OnLineDoc/DevDocs/ppgfldr/smmfldr/cdmfldr/08CDM003.html#XREF10686|DKNB]]|The DKNB Chunk is an array of knob declarations used to control DSP programs, typically through the EI stack. Knobs may require single or double precision EI space or they may be virtual knobs that control ARM parameters and require no EI space. \\  \\ int32 dknb_Next /* offset in chunk of next knob */ \\ int32 dknb_Min \\ int32 dknb_Max \\ int32 dknb_Nominal \\ int32 dknb_NumResources \\ char dknb_Name[AF_MAX_NAME_SIZE] \\ arrayof \\ int32 dknr_RsrcIndex \\ int32 dknr_CalcType \\ int32 dknr_Data1 \\ int32 dknr_Data2 \\  \\ The CalcType (see the table below) determines how the knob parameters are converted. \\  \\ CALC_LINEAR = knob_value * Data1 + Data2 \\ CALC_INVERT = (Data1/knob_value) + Data2 \\ CALC_LINEAR_FP = knob_value * Data1 + Data2 /* fixed point */ \\ CALC_SIN = sin(knob_value * Data1) * Data2|