MusicKit  0.0.0
dsp_structs.h
00001 #ifndef __MK_dsp_structs_H___
00002 #define __MK_dsp_structs_H___
00003 /* DSP DATA STRUCTURES
00004  * Copyright 1988-1992, NeXT Inc.  All rights reserved.
00005  * Author: Julius O. Smith III
00006  */
00007 
00008 /*
00009  * These structs provide an in-memory version of a .lod or .lnk file as
00010  * produced by the Motorola DSP56000/1 assembler.  Either type may also appear
00011  * in a .dsp file (fast binary format).
00012  *
00013  * General support is provided for absolute assembly, and specialized support
00014  * exists for relative assembly (as needed by the Music Kit and array
00015  * processing frameworks).  In the relative case, only three "sections" are
00016  * supported: the "global", "system", and "user" sections.  In the case of
00017  * absolute assembly (using the -a assembler option) everything appears 
00018  * in the "global" section (since sections are not used in absolute assembly).
00019  *
00020  * For an example of how to manage relocatable DSP modules, see the programming
00021  * example in /NextDeveloper/Examples/ArrayProcessing/myAP/.
00022  */
00023 
00024 #ifndef _DSPSTRUCTS_
00025 #define _DSPSTRUCTS_
00026 
00027 #import <stdio.h>
00028 
00029 #include "MKDSPDefines.h"
00030 #import "dsp_types.h"
00031 
00032 typedef enum _DSPSectionType {DSP_Global=0,DSP_System,DSP_User,
00033         DSP_NSectionTypes} DSPSectionType;
00034 
00035 /* strings from DSPGlobals.c */
00036 MKDSP_API const char * const DSPSectionNames[]; /* "GLOBAL", "SYSTEM", "USER" */
00037 // Now a function LMS
00038 //extern const char * const DSPMemoryNames[];  /* Memory spaces (N,X,Y,L,P) */
00039 MKDSP_API const char *DSPMemoryNames(int memSpaceNo);  /* Memory spaces (N,X,Y,L,P) */
00040 MKDSP_API const char * const DSPLCNames[];      /* Location counters (N,XL,X,XH,...) */
00041 MKDSP_API int   DSPLCtoMS[];    /* DSP memory code given LC number */
00042 
00043 /* enum for DSP memory spaces */
00044 typedef enum _DSPMemorySpace {DSP_MS_N=0, 
00045                               DSP_MS_X,
00046                               DSP_MS_Y,
00047                               DSP_MS_L,
00048                               DSP_MS_P,
00049                             DSP_MS_Num} DSPMemorySpace;
00050 
00051 /* 
00052  * The exact layout of this enum is depended upon by _DSPGetMemStr 
00053  * and _DSPDataRecordMerge (DSPStructMisc.c) 
00054  */
00055 typedef enum _DSPLocationCounter {DSP_LC_N=0, 
00056                               DSP_LC_X, DSP_LC_XL, DSP_LC_XH, 
00057                               DSP_LC_Y, DSP_LC_YL, DSP_LC_YH, 
00058                               DSP_LC_L, DSP_LC_LL, DSP_LC_LH, 
00059                               DSP_LC_P, DSP_LC_PL, DSP_LC_PH, 
00060                             DSP_LC_Num} DSPLocationCounter;
00061 
00062 /* NOTE: DSP_LC_P,DSP_LC_PL,DSP_LC_PH MUST BE CONTIGUOUS */
00063 
00064 #define DSP_LC_NUM (int)DSP_LC_Num /* no. DSP mem space types (incl. none) */
00065 #define DSP_N_SECTIONS (int)DSP_NSectionTypes
00066 
00067 #define DSP_LC_NUM_P 3          /* no. DSP PROGRAM memory spaces */
00068 #define DSP_LC_P_BASE DSP_LC_P  /* First DSP_LC_P memory space. */
00069 
00070 /* 
00071  * DSPDataRecord
00072  *
00073  * The DSPDataRecord structure contains the result of reading a _DATA or
00074  * _BLOCKDATA record in the .lnk/.lod file.  If the owning section is type
00075  * absolute, there may be a linked list of data blocks, each specifying
00076  * its own loadAddress parameter. For relative sections, there will be only
00077  * one data block per memory space (next==NULL), and the loadAddress field
00078  * is not used. (The load address is specified for each memory space in the
00079  * DSPSection struct instead of the data block.)  
00080  * 
00081  * For a _DATA record,  repeatCount is 1 wordCount gives the number of words
00082  * in data[]. For long DSP data (type l:), words are stored interleaved: 
00083  * Hi1,Lo1, Hi2,Lo2, etc., and wordCount equals the number of 24-bit words
00084  * which is then the number of long words times 2.
00085  *
00086  * For a _BLOCKDATA record, wordCount is 1 and repeatCount tells how many
00087  * times the single word (or two words for l memory) in data is to be 
00088  * repeated in a memory constant fill.
00089  */
00090 
00091 typedef struct _DSPDataRecord { /* _BLOCKDATA or _DATA spec from lnk file */
00092     struct _DSPSection *section; /* Orig owning section when read from file */
00093     DSPLocationCounter locationCounter; /* mem segment for this data */
00094     DSPAddress loadAddress;     /* from _{BLOCK}DATA record. 0 for relative. */
00095     int repeatCount;            /* _BLOCKDATA repeatCount */
00096     int wordCount;              /* length of *data array in ints */
00097     int *data;                  /*  _DATA array or _BLOCKDATA constant(s) */
00098     struct _DSPDataRecord *next; /* For linked list (absolute sections only) */
00099     struct _DSPDataRecord *prev; /* Relative sections always have NULL here  */
00100 } DSPDataRecord;
00101 
00102 union DSPSymVal {
00103     int i;
00104     float f;
00105 };
00106 
00107 typedef struct _DSPSymbol {
00108     DSPLocationCounter locationCounter; /* one of DSPLCNames above */
00109     char *name;
00110     char *type;             /* (L|G)(A|R)(I|F). E.g., "LRI","GAI","I" */
00111     union DSPSymVal value;  /* int or float. (Must be last field in struct) */
00112 } DSPSymbol;
00113 
00114 
00115 /*
00116  * A "fixup" is the resolution of a relocatable symbol reference.
00117  * The idea is to provide a way to quickly relocate a DSP section.
00118  * To relocate a section, each fixup is performed by adding the symbol's
00119  * section load address to the relAddress of the relocatable symbol
00120  * (relAddress == relative address in its section). The "fixed up"
00121  * address is then installed where it is used, refOffset from
00122  * the beginning of the memory space owning the fixup.
00123  */
00124 
00125 typedef struct _DSPFixup {      /* used for fast relocation */
00126     DSPLocationCounter locationCounter; /* space of relocatable symbol */
00127     char *name;                 /* name of relocatable symbol (pass 1) */
00128     int decrement;              /* 1 means relAddress = symbol's val - 1 */
00129     int refOffset;              /* offset of ref in P, PL, or PH segment */
00130     DSPAddress relAddress;      /* symbol's address before relocation */
00131 } DSPFixup;
00132 
00133 typedef struct _DSPSection {    /* DSP section state from .lnk file. */
00134 /* _SECTION record fields */
00135     char *name;                 /* GLOBAL, SYSTEM, or USER */
00136     char *type;                 /* R (relative) or A (absolute) */
00137     int number;                 /* 0=global, 1=system, 2=user */
00138     DSPDataRecord *data[DSP_LC_NUM]; /* Sorted absolute data blocks */
00139     DSPDataRecord *dataEnd[DSP_LC_NUM]; /* point to end of data blocks */
00140     int symAlloc[DSP_LC_NUM];      /* no. of symbols allocated in each space */
00141     int symCount[DSP_LC_NUM];      /* number of symbols loaded in each space */
00142     struct _DSPSymbol *(symbols[DSP_LC_NUM]); /* symbol list per mem section */
00143     int fixupAlloc[DSP_LC_NUM_P]; /* number of fixups allocated per p space */
00144     int fixupCount[DSP_LC_NUM_P]; /* number of fixups in each p space */
00145     DSPFixup *fixups[DSP_LC_NUM_P]; /* fix-up array for each p space */
00146     DSPAddress loadAddress[DSP_LC_NUM]; /* Relocation offset 
00147                                            (unused for absolute) */
00148     int xrefAlloc;              /* number of xrefs allocated per p space */
00149     int xrefCount;              /* number of xrefs in each p space */
00150     char **xrefs;               /* xref array = external symbol references */
00151 } DSPSection;
00152 
00153 typedef struct _DSPLoadSpec {   /* All DSP state as loaded from .lnk file. */
00154 
00155 /* _START record fields */
00156     char *module;               /* module thru errorCount are set by _START */
00157     char *type;                 /* "A" => absolute assembly, "R" => relative */
00158     int version;
00159     int revision;
00160     int errorCount;
00161     DSPAddress startAddress;    /* set by _END directive of object file */
00162     char *comments;             /* _COMMENT lines from object file */
00163     char *description;          /* text settable by user program */
00164 /* _SECTION records possible for MK and AP DSP programs */
00165     DSPSection *globalSection;  /* Also used by (sectionless) .lod files */
00166     DSPSection *systemSection;
00167     DSPSection *userSection;
00168 /*  array of section pointers indexed by section number */
00169     DSPSection *indexToSection[DSP_N_SECTIONS];
00170 } DSPLoadSpec;
00171 
00172 typedef enum _DSPSCITXReg {DSP_STXA=0,DSP_STXL=1,DSP_STXM=2,DSP_STXH=3
00173 } DSPSCITXReg;
00174 
00175 #define DSP_STX DSP_STXL    
00176 
00177 #endif  /* _DSPSTRUCTS_ */
00178 
00179 #endif