Defines | |
| #define | MK_TRACEORCHALLOC 1 |
| Trace Constants. | |
Functions | |
| unsigned | MKSetTrace (int traceCode) |
| Turns on specified trace bit. | |
| unsigned | MKClearTrace (int traceCode) |
| Turns off specified trace bit. | |
| BOOL | MKIsTraced (int traceCode) |
| Returns whether specified trace bit is on. | |
| #define MK_TRACEORCHALLOC 1 |
Trace Constants.
To enable a set of messages, you pass a trace code to the MKSetTrace() function. You can enable more than one set with a single function call by bitwise-or'ing the codes. Clearing a trace is done similarly, by passing codes to MKClearTrace(). The MKIsTraced() function returns YES or NO as the argument code is or isn't currently traced. These functions should only be used while you're debugging and fine-tuning your application.
| unsigned MKClearTrace | ( | int | traceCode | ) |
Turns off specified trace bit.
To aid in debugging, the MusicKit is peppered with activity-tracing messages that print to stderr if but asked.
To enable a set of messages, you pass a trace code to the MKSetTrace() function. You can enable more than one set with a single function call by bitwise-or'ing the codes. Clearing a trace is done similarly, by passing codes to MKClearTrace(). The MKIsTraced() function returns YES or NO as the argument code is or isn't currently traced. These functions should only be used while you're debugging and fine-tuning your application.
| traceCode | is an int. |
| BOOL MKIsTraced | ( | int | traceCode | ) |
Returns whether specified trace bit is on.
To aid in debugging, the MusicKit is peppered with activity-tracing messages that print to stderr if but asked.
To enable a set of messages, you pass a trace code to the MKSetTrace() function. You can enable more than one set with a single function call by bitwise-or'ing the codes. Clearing a trace is done similarly, by passing codes to MKClearTrace(). The MKIsTraced() function returns YES or NO as the argument code is or isn't currently traced. These functions should only be used while you're debugging and fine-tuning your application.
| traceCode | is an int. |
| unsigned MKSetTrace | ( | int | traceCode | ) |
Turns on specified trace bit.
To aid in debugging, the MusicKit is peppered with activity-tracing messages that print to stderr if but asked. The trace messages are divided into eight categories, represented by the following codes:
| Code | Value | Meaning |
| MK_TRACEORCHALLOC | 1 | DSP resource allocation |
| MK_TRACEPARS | 2 | Application-defined parameters |
| MK_TRACEDSP | 4 | DSP manipulation |
| MK_TRACEMIDI | 8 | MIDI manipulation |
| MK_TRACEPREEMPT | 16 | MKSynthPatch preemption |
| MK_TRACESYNTHINS | 32 | MKSynthInstrument mechanations |
| MK_TRACESYNTHPATCH | 64 | MKSynthPatch library messages |
| MK_TRACEUNITGENERATOR | 128 | MKUnitGenerator library messages |
| MK_TRACECONDUCTOR | 256 | Conductor time setting messages |
| MK_TRACEDSPARRAYS | 512 | DSP array-setting messages |
To enable a set of messages, you pass a trace code to the MKSetTrace() function. You can enable more than one set with a single function call by bitwise-or'ing the codes. Clearing a trace is done similarly, by passing codes to MKClearTrace(). The MKIsTraced() function returns YES or NO as the argument code is or isn't currently traced. These functions should only be used while you're debugging and fine-tuning your application.
You should note that the codes given above are #define'd as their corresponding values and so can be used only when you call one of these functions within an application - they can't be used in a symbolic debugger such as gdb. For this reason, the integer values themselves are also given; you must use the integer values to enable and disable a set of trace messages from within a debugger.
The debug flags are listed below with some of the possible messages you may see when using them. MKNote that not all possible messages are included.
MK_TRACEORCHALLOC The Orchestra allocation messages inform you of DSP resource allocation. The most important of these have to do with MKSynthPatch, MKUnitGenerator, and Synth Data allocation. When a MKSynthPatch is allocated, one of the following messages is printed:
"allocSynthPatch returns <i>MKSynthPatchClass_SynthPatchId</i>" "allocSynthPatch building <i>MKSynthPatchClass_SynthPatchId</i>..." "allocSynthPatch can't allocate <i>MKSynthPatchClass</i>" The first of these signifies that an appropriate MKSynthPatch object was found. The second means that a new object was created. The third denotes an inability to construct the requested object because of insufficient DSP resources. As a MKSynthPatch's MKUnitGenerators are connected, the following message is printed:
"allocSynthPatch connectsContents of <i>MKSynthPatchClass_SynthPatchId</i>"
When a MKSynthPatch is deallocated and when it's freed, respectively, the following are printed:
"Returning <i>MKSynthPatchClass_SynthPatchId</i> to avail pool." "Freeing <i>MKSynthPatchClass_SynthPatchId</i>" A MKUnitGenerator can be allocated without reference to other MKUnitGenerators, or it can be positioned before, after, or between other objects. Examples:
"allocUnitGenerator looking for a <i>UGClass</i>." "allocUnitGenerator looking for a <i>UGClass</i> before <i>UGClass_UGid</i>" "allocUnitGenerator looking for a <i>UGClass</i> after <i>UGClass_UGid</i>" "allocUnitGenerator looking for a <i>UGClass</i> after <i>UGClass_UGid</i> and before <i>UGClass_UGid</i>" If a new MKUnitGenerator is built, the addresses (relocation or “Reloc”) and sizes (resources or “Reso”) of the allocated DSP resources are given:
"Reloc: pLoop address, xArg address, yArg address, lArg address, xData address, yData address, pSubr address" "Reso: pLoop size, xArg size, yArg size, lArg size, xData size, yData size, pSubr size, time orchestraLoopDuration" As the MKUnitGenerator search (or allocation) succeeds or fails, one of the following is printed:
"allocUnitGenerator returns <i>UGClass_UGid</i>" "Allocation failure: Can't allocate before specified ug." "Allocation failure. DSP error." "Allocation failure. Not enough computeTime." "Allocation failure. Not enough <i>memorySegment</i> memory." Allocating a MKSynthData generates the first and then either the second or third of these messages:
"allocSynthData: looking in segment <i>memorySegment</i> for size <i>size</i>." "allocSynthData returns <i>memorySegment</i> address of length <i>size</i>." "Allocation failure: No more offchip data memory." When you install shared data, the following is printed:
"Installing shared data <i>keyObjectName</i> in segment <i>memorySegment</i>."
During allocation of MKUnitGenerators and MKSynthDatas, existing resources might be compacted. Compaction can cause free MKUnitGenerators and unreferenced shared data to be garbage collected, and active MKUnitGenerators to be relocated:
"Compacting stack." "Copying arguments." "Copying p memory." "Garbage collecting freed unit generator UGClass_UGid" "Moving <i>UGClass_UGid</i>." "NewReloc: pLoop <i>address</i>, xArg <i>address</i>, yArg <i>address</i>, lArg <i>address</i>." "Garbage collecting unreferenced shared data." "No unreferenced shared data found." MK_TRACEDSP
The DSP-trace messages give you details of how the DSP is being used. For example, when a MKUnitGenerator is allocated, the following message is printed among the search-build-return messages given above:
"Loading <i>UGClass_UGid</i> as UG <i>ugNum</i>."
Unit Generators are given integer numbers for debugging purposes. These numbers simply count up. Numbers are not recycled. Thus, an example of an actual "Loading..." message would be:
"Loading Out1aUGx_0x43100 as UG3."
The most important of the DSP-trace messages reflect the setting of a MKUnitGenerator's memory arguments. A memory argument takes either an address value or a data value. When you set an address-valued argument, the following is printed:
"Setting <i>argName</i> of <i>UGugNum_Class</i> to <i>memSegment memNum</i> (0x<i>address</i>)."
argName is the argument name in the source DSP (.asm) file.
A data-valued arguments is either a 24-bit or 48-bit word; separate functions (and cover methods) are defined for setting the two sizes of arguments. The following messages are printed as the “correct” function is used to set an argument's value:
"Setting <i>argName</i> of <i>UGugNum_Class</i> to datum <i>value</i>." "Setting <i>argName</i> of <i>UGugNum_Class</i> to long: <i>hi wd value</i> and <i>low wd value</i>." A 24-bit argument that's set with the long-setting function and vice versa produce these messages, respectively:
"Setting (L-just, 0-filled) <i>argName</i> of <i>UGugNum_Class</i> to datum <i>value</i>." "Setting <i>argName</i> of <i>UGugNum_Class</i> to: <i>value</i>" If an argument is declared as optimizable, the following is printed when the optimization obtains:
"Optimizing away poke of <i>argName</i> of <i>UGugNum_Class</i>."
MKSynthData allocation doesn't actually involve the DSP; the address of the memory that will be allocated on the DSP is computed, but the state of the DSP itself doesn't change until data is loaded into the MKSynthData:
"Loading array into <i>memorySegment</i> <i>memNum</i> [<i>lowAddr-highAddr</i>]." "Loading constant value into <i>memorySegement</i> <i>memNum</i> [<i>lowAddr-highAddr</i>]." Here memNum is an integer assigned for debugging purposes. memorySegment if one of xData, yData, xPatch or yPatch. When an array is loaded, the loaded values are printed if MK_DSPTRACEARRAYS has been enabled. Example:
"Loading array into <i>xPatch</i> <i>4</i> [<i>0x412-0x418</i>]."
Clearing a SynthData's memory produces the following:
"Clearing <i>memorySegment</i> <i>memNum</i> [<i>lowAddr-highAddr</i>]."
DSP manipulations that are performed as an atomic unit are bracketed by the messages:
"<<< Begin orchestra atomic unit " "end orchestra atomic unit.>>> " MK_TRACESYNTHINS
The MKSynthInstrument messages are printed when a MKSynthInstrument object receives MKNotes, and as it finds or creates MKSynthPatches to realize these MKNotes.
If a received MKNote's note tag is active or inactive, or if its note type is mute, the following are printed, respectively:
"MKSynthInstrument receives note for active notetag stream <i>noteTag</i> at time <i>time</i>." "MKSynthInstrument receives note for new notetag stream <i>noteTag</i> at time <i>time</i>." "MKSynthInstrument receives mute MKNote at time <i>time</i>." MKSynthPatch allocation is noted only if the MKSynthInstrument is in auto-allocation mode:
"MKSynthInstrument creates patch <i>synthPatchId</i> at time <i>time</i> for tag <i>noteTag</i>."
However, MKSynthPatch reuse and preemption produce the following messages, respectively, regardless of the MKSynthInstrument's allocation mode:
"MKSynthInstrument uses patch <i>synthPatchId</i> at time <i>time</i> for tag <i>noteTag</i>." "MKSynthInstrument preempts patch <i>synthPatchId</i> at time <i>time</i> for tag <i>noteTag</i>." If a MKSynthPatch of the correct MKPatchTemplate isn't found and can't be allocated, an alternative is used; barring that, the MKSynthInstrument omits the MKNote:
"No patch of requested template was available. Using alternative template." "MKSynthInstrument omits note at time <i>time</i> for tag <i>noteTag</i>." MK_TRACEPREEMPT
These are a subset of the MKSynthInstrument messages that deal with MKSynthPatch preemption and MKNote omission:
"MKSynthInstrument preempts patch <i>synthPatchId</i> at time <i>time</i> for tag noteTag." "MKSynthInstrument omits note at time time for tag noteTag. MK_TRACEMIDI
The following are printed as ill-formed MKNote objects are converted to MIDI messages:
"MKNoteOn missing a noteTag at time <i>time</i>" "MKNoteOff missing a note tag at time <i>time</i>" "MKNoteOff for noteTag which is already off at time <i>time</i>" "PolyKeyPressure with invalid noteTag or missing keyNum: time <i>time</i>;" MK_TRACESYNTHPATCH
This referes to MKSynthPatch Library messages. When debugging MKSynthPatches, you may also want to turn on TRACEUNITGENERATOR.
MK_TRACEUNITGENERATOR
This refers to MKUnitGenerator library messages. f the sine ROM, which resides in Y memory, is requested by a MKUnitGenerator's X-space memory argument, the following appears:
"X-space oscgaf cannot use sine ROM at time <i>time</i>."
If insufficient DSP memory is available to load a WaveTable of the requested length, the following is printed:
"Insufficient wavetable memory at time <i>time</i>. Using smaller table length <i>newLength</i>."
MK_TRACEPARS By tracing MK_TRACEPARS, you're informed when an application-defined parameter is created:
"Adding new parameter <i>parameterName</i>"
MK_TRACECONDUCTOR
By tracing MK_TRACECONDUCTOR, a message giving the time in seconds is printed whenever time advances:
"t 4.1"
| traceCode | is an int. |
1.5.6