NAME

dspwrap − wrap a DSP macro in a host C function
 

SYNOPSIS

dspwrap [ -{ug,ap} ] [ -no{Doc,Link,C} ] [ -o <path> ] [ -xonly ] [ -local <path> ] [ -macroDir <path> ] [ -dsploadwrapDir <path> ] [ -trace <n> ] <filename(s)>
 

DESCRIPTION

The dspwrap program processes unit-generator (UG) or array processing (AP) macro source code, producing C or Objective C source files from DSP56000 assembly language. 
 
Example array processing macros may be found in the directory /usr/lib/dsp/apsrc, and example unit generator macros are in the directory /usr/lib/dsp/ugsrc. 
 
For AP macros, dspwrap creates a host C function which, when called by a C program running on the host processor, will load the preassembled DSP code, install DSP macro arguments from the arguments passed in C, and initiate execution on the DSP. dspwrap is so named because it in effect "wraps" DSP assembly language inside a C function.  Thus, dspwrap is used to take a new AP macro and add it to the library of array-processing C functions. 
 
As an example of AP macro processing, the command line
 
    dspwrap -ap apfunc.asm
 
will write a C function "DSPapfunc(<args>)" into the file "DSPapfunc.c", where the <args> are determined by the DSPWRAP ARGUMENT INFO field of the "man page" in the source file apfunc.asm.  Also written is the file "apfunc.dsp" which contains a binary encoding of "apfunc.lnk", the preassembled, relocatable, array processing module.
 
dspwrap provides no translation of C function arguments.  That is, the user must specify DSP addresses as 16-bit integers, right-justified within type int, and DSP data values must be specified as 24-bit fixed-point values right-justified within type int (sign extension not required). 
 
For UG macros, dspwrap creates a set of Objective C classes which allow the unit generator to be used in the context of the Music Kit.  A separate "leaf class" is generated for each memory-space combination.  For example, if a unit generator has two inputs and one output, 2^3 = 8 leaf classes are generated, corresponding to the DSP memory-space combinations, "xxx", "xxy", "xyx", "xyy", "yxx", "yxy", "yyx", and "yyy".  These leaf classes are what you allocate from the Music Kit Orchestra object.  If you want only the x memory-space configuration, include the -xonly option. 
 
In addition, dspwrap generates a "master" class, from which the leaf classes inherit.  The master class may be edited to provide methods to set the unit generator memory arguments in more convenient units.  For example, in an oscillator unit generator, one might provide a method to set the oscillator frequency in Hertz to avoid having to specify the frequency indirectly as a table increment.  Unit generators typically call for the most immediately useable format, and the master class is where you translate from high-level to low-level units. 
 
Objective C header files are also written for all of the classes generated.
 
For special UG macros having no memory-space variations, only the master class is generated.
 
As an example of UG macro processing, the command line
 
    dspwrap -ug add.asm
 
will write the following files, assuming add has 2 patch-point arguments:
 
    AddUG.m  /∗ this is the master class ∗/
    AddUG.h
    addUGInclude.m /∗ this file is included by AddUG.m ∗/
    AddUGxx.m /∗ These are the leaf classes ∗/
    AddUGxx.h
    AddUGxy.m
    AddUGxy.h
    AddUGyx.m
    AddUGyx.h
    AddUGyy.m
    AddUGyy.h
 
The -noC, -noDoc, and -noLink options inhibit the generation of the C source file, generated documentation files, and the relocatable object module, respectively.  Typically, -noLink is used to obtain documentation only, and -noDoc is used to skip document generation. -noC inhibits generation and output of the C source file(s). -noLink implies -noC.
 

OPERATION

dspwrap performs the following steps:

1.A DSP main assembly-language program is generated which invokes the macro. 

2.Macro arguments are filled in according to the DSPWRAP C SYNTAX spec. 

3.The DSP main program and macro are assembled, producing an object module. 

4.C Code is generated for binding C arguments to macro memory arguments. 

5.C Code is generated for downloading the program and data to the DSP. 

6.The C source file is written to disk. 
 

OPTIONS

Each option can be abbreviated to the shortest disambiguating extent. 
 

−ugIndicate that macro file is type "unit generator". 

−apIndicate that macro file is type "array processor". 

−no{Doc,Link,C}
Suppress generation of documentation output, DSP linker output, or C source file.

−o
Set output path for documentation files to <path>. 

−xonly
Generate output for x DSP memory space arguments only. This option is the default for "array processor" macro types.

−local
Use local directory for includes.  Overrides installed DSP system include source directory.

−macroDir
Add specified directory to start of search path for macros. Default path includes current directory and installed DSP system macro source directory.

−dsploadwrapDir
Use specified directory as location of program dsploadwrap.

−trace
Sets the trace variable. To get all possible tracing, use -1.
 

SEE ALSO

dsploadwrap − called by dspwrap to process assembled .lnk, .dsp and .lod files. 
 

DIAGNOSTICS

If an assembly error occurs when assembling the main program created by dspwrap, the assembler listing file (.lst) will be left in the current directory.  After a successful assembly, the listing file is deleted.  The main program created by dspwrap is not deleted, so a listing can also be generated by manually assembling that. 
 

NeXT, Inc.  —  6 Jun 1989