NAME

snddriver_get_device_parms, snddriver_set_device_parms, snddriver_get_volume, snddriver_set_volume, snddriver_set_dsp_owner_port, snddriver_set_sndin_owner_port, snddriver_set_sndout_owner_port, snddriver_get_dsp_cmd_port, snddriver_dspcmd_req_msg, snddriver_dspcmd_req_err, snddriver_dspcmd_req_condition, snddriver_dsp_set_flags, snddriver_dsp_host_cmd, snddriver_dsp_boot, snddriver_dsp_write, snddriver_dsp_read, snddriver_stream_setup, snddriver_dsp_protocol, snddriver_stream_start_reading, snddriver_stream_start_writing, snddriver_stream_control, snddriver_stream_nsamples, snddriver_reply_handler, − DSP/Sound driver interface

SYNOPSIS

#include <sound/sounddriver.h>
#include <nextdev/snd_msgs.h>
 kern_return_t snddriver_set_dsp_owner_port (
port_tdevice_port,
port_towner_port,
port_t∗negotiation_port)
 kern_return_t snddriver_set_sndin_owner_port (
port_tdevice_port,
port_towner_port,
port_t∗negotiation_port)
 kern_return_t snddriver_set_sndout_owner_port (
port_tdevice_port,
port_towner_port,
port_t∗negotiation_port)
 kern_return_t snddriver_set_device_parms (
port_tdevice_port,
boolean_tspeaker,
boolean_tlowpass,
boolean_tzerofill)
 kern_return_t snddriver_get_device_parms (
port_tdevice_port,
boolean_t∗speaker,
boolean_t∗lowpass,
boolean_t∗zerofill)
 kern_return_t snddriver_set_volume (
port_tdevice_port,
intleft_chan,
intright_chan)
 kern_return_t snddriver_get_volume (
port_tdevice_port,
int∗left_chan,
int∗right_chan);
 kern_return_t snddriver_get_dsp_cmd_port (
port_tdevice_port,
port_towner_port,
port_t∗cmd_port);
 kern_return_t snddriver_dspcmd_req_msg (
port_tcmd_port,
port_treply_port);
 kern_return_t snddriver_dspcmd_req_err (
port_tcmd_port,
port_treply_port);
 kern_return_t snddriver_dspcmd_req_condition (
port_tcmd_port,
u_intmask,
u_intflags,
intpriority,
port_treply_port)
 kern_return_t snddriver_dsp_set_flags (
port_tcmd_port,
u_intmask,
u_intflags,
intpriority)
 kern_return_t snddriver_dsp_host_cmd (
port_tcmd_port,
u_inthost_command,
intpriority)
 kern_return_t snddriver_dsp_boot (
port_tcmd_port,
int∗bootImage,
intbootImageSize,
intpriority)
 kern_return_t snddriver_dsp_write (
port_tcmd_port,
void∗data,
intcount,
intdata_size,
intpriority)
 kern_return_t snddriver_dsp_read (
port_tcmd_port,
void∗data,
int∗count,
intdata_size,
intpriority)
  kern_return_t snddriver_stream_setup (
port_tdev_port,
port_towner_port,
intconfig,
intbuf_size,
intsample_size,
intlow_water,
inthigh_water,
int∗protocol,
port_t∗stream_port)
 kern_return_t snddriver_dsp_protocol (
port_tdevice_port,
port_towner_port,
intprotocol)
 kern_return_t snddriver_stream_start_reading (
port_tstream_port,
char∗filename,
intdata_size,
inttag,
boolean_tstarted_msg,
boolean_tcompleted_msg,
boolean_taborted_msg,
boolean_tpaused_msg,
boolean_tresumed_msg,
boolean_toverflow_msg,
port_treply_port)
 kern_return_t snddriver_stream_start_writing (
port_tstream_port,
void∗data,
intdata_size,
inttag,
boolean_tpreempt,
boolean_tdeallocate,
boolean_tstarted_msg,
boolean_tcompleted_msg,
boolean_taborted_msg,
boolean_tpaused_msg,
boolean_tresumed_msg,
boolean_toverflow_msg,
port_treply_port)
 kern_return_t snddriver_stream_control (
port_tstream_port,
inttag,
intsnd_control)
 kern_return_t snddriver_stream_nsamples (
port_tstream_port,
int∗nsamples)
 kern_return_t snddriver_reply_handler(
msg_header_t∗msg,
snddriver_handlers_t ∗handlers)

DESCRIPTION

The Sound/DSP driver implements an interface to the 44Khz DACs (Digital Analog Converters), 8Khz CODEC ADC (Analog Digital Converter), and DSP (Motorola 56001 Digital Signal Processor).  The routines implemented by the driver are sufficient for playing and recording sound files, as well as playing and recording DSP generated sounds.  The DSP can also be used for array processing and other functions suited to it’s special purpose nature. 

Snddriver_set_dsp_owner_port establishes ownership of the DSP.  The device_port parameter is obtained by looking up the port named sound from the netname server (see the documentation for netname in The NeXT System Reference Manual).  The owner_port parameter is a port to be registered as the owner of this device.  When the registered owner_port is deallocated the device is released.  The negotiation_port parameter is registered with the driver to be returned when ownership is requested for and the DSP is already owned.  Thus, if the call fails, a port will be returned in negotiation_port that can be used to gain further access to the driver. 

Snddriver_set_sndin_owner_port establishes ownership of the 8Khz CODEC used for sound input through a microphone jack on the back of the monitor.  The treatment of owner_port and negotiation_port is the same as in snddriver_set_dsp_owner_port. 

Snddriver_set_sndout_owner_port establishes ownership of the 44Khz DACs used for sound output.  The treatment of owner_port and negotiation_port is the same as in snddriver_set_dsp_owner_port. 

Snddriver_set_device_parms sets parameters maintained by the sound hardware specific to playing back sounds.  The device_port parameter references the sound device.  The speaker parameter either turns on or off the external speaker in the back of the monitor based on it’s boolean value.  The lowpass parameter, if true, enables the lowpass filter played through either the speaker or the headphone jacks in the back of the monitor.  Has no effect for sound going through the line−out jacks.  The zerofill parameter has meaning only when playing 22Khz sounds.  If set, every other sample played through the DAC is zero, otherwise samples are repeated. 

Snddriver_get_device_parms returns the value of those parameters set using snddriver_set_device_parms or the default information if nothing’s been set. 

Snddriver_set_volume sets the volume of the left and right channels for sound output either through the speaker or the headphone jacks.  Sounds played through the line-out jacks are not affected.  Legal values for left_chan and right_chan are 0 (quietest setting) through VOLUME_MAX  (loudest setting, see <nextdev/snd_snd.h>). 

Snddriver_get_volume gets the current volume settings. 

Snddriver_get_dsp_cmd_port returns a port used for enqueuing commands for the DSP.  Device_port is the sound device port, owner_port is the port registered as owning the DSP.  The DSP command port is returned in cmd_port.

Snddriver_dspcmd_req_msg causes data received from the DSP by the driver to be returned.  The cmd_port parameter is the DSP command port.  When data has been received it will be forwarded to the user in a message sent to the port specified in the reply_port parameter (see snddriver_reply_handler). 

If the HOST MESSAGE protocol is enabled snddriver_dspcmd_req_err returns data received from the DSP identified as error messages separately from data received as messages (and thus returned by snddriver_dspcmd_req_msg), see snddriver_dsp_protocol).  Cmd_port and reply_port are treated the same as in snddriver_dspcmd_req_msg. 

Snddriver_dspcmd_req_condition enqueues a condition block event onto the DSP command port.  The contents of the four DSP host interface registers (Interrupt Control, Command Vector, Interrupt Status, and Interrupt Vector) are anded with the mask parameter and the result is comapred with the flags parameter.  If the comparison is successful the condition is complete and other enqueued events can be further processed.  The priority parameter is used to enqueue the event relative to other events in the DSP command queue.   Its values can be SNDDRIVER_LOW_PRIORITY, SNDDRIVER_MED_PRIORITY, or SNDDRIVER_HIGH_PRIORITY. If the reply_port is set to a value other than PORT_NULL the value of the DSP host interface registers will be returned in a message to the specified port. 

Snddriver_dsp_set_flags enqueues an event to modify the state of either HF0 or HF1 in the DSP Interrupt Control Register.  The DSP host interface registers are first anded with the value of the mask parameter, then ored with the value of the flags paramter. 

Snddriver_dsp_host_cmd enqueues an event to generate a host command.  The value of the host_command parameter is loaded into the DSP Command Vector Register and the HC bit is to cause the host command to be sent.  This event will not be executed until the HC bit is clear.  If in HOST_MESSAGE protocol is set HF2 must also be clear before the host command will be sent (see snddriver_dsp_protocol). 

Snddriver_dsp_boot performs a hard boot of the DSP utilizing the DSP’s on−chip ROM bootstrapping program. The specified instructions (starting at location zero) are downloaded into on-chip program memory, after which execution at location zero commences. External DSP memory and on−chip data memory is not affected by this operation. 

Snddriver_dsp_write writes the specified buffer to the DSP data registers.  Valid values for data_size are 1, 2, and 4. For a data_size of 4, the low−order bits of the 32-bit values are written to the DSP’s 24-bit register. 

Snddriver_dsp_read reads data from the DSP’s data registers into the specified buffer. The count argument is modified on return to indicate the actual number of words transferred. The data_size argument has the same meaning and restrictions as in snddriver_dsp_write. 

Snddriver_stream_setup provides a way to obtain a stream_port with given characteristics.  Dev_port is the sound device port, owner_port is the port registered  as owning the DSP.  Config is a constant identifying the data path of the steam. Its value may be one of the following:

SNDDRIVER_STREAM_FROM_SNDIN
SNDDRIVER_STREAM_TO_SNDOUT_22
SNDDRIVER_STREAM_TO_SNDOUT_44
SNDDRIVER_STREAM_FROM_DSP
SNDDRIVER_STREAM_TO_DSP
SNDDRIVER_STREAM_SNDIN_TO_DSP
SNDDRIVER_STREAM_DSP_TO_SNDOUT_22
SNDDRIVER_STREAM_DSP_TO_SNDOUT_44
SNDDRIVER_STREAM_FROM_SNDIN_THROUGH_DSP
SNDDRIVER_STREAM_THROUGH_DSP_TO_SNDOUT_22
SNDDRIVER_STREAM_THROUGH_DSP_TO_SNDOUT_44

Buf_size is the size of the DMA transfers employed in stream transfers, and should be a multiple of 16. The supported sample_sizes are 1, 2, and 4 bytes.  The low_water and high_water values are used by the driver to optimize control flow on the stream. The protocol value passed by reference is modified to accomodate the new stream; initially, it should be set to zero, and after any number of calls to snddriver_stream_setup, it contains the value that needs to be passed to snddriver_dsp_protocol.  The stream port that corresponds to the specified configuration is returned in stream_port.

Snddriver_dsp_protocol sets protocol information used by the driver in interpreting DSP output and in sending data to the DSP.  Details of the protocols are layed out in the Sound Driver section of The NeXT Reference Manual. 

Snddriver_stream_start_reading causes a region to be enqueued on the specified stream for reading data.  The stream_port parameter represents a stream returned by snddriver_stream_setup.  The data_size parameter specifies the number of samples to be read into this region.  The tag parameter associates the specified value with the region for subsequent control by snddriver_stream_control.  The started_msg, completed_msg, aborted_msg, paused_msg, resumed_msg, and overflow_msg parameters indicate which asynchronous messages should be sent at critical points during the life of this region.  Such messages are sent to the port specified in the reply_port parameter. 

Snddriver_stream_start_writing causes a region to be enqueued on the specified stream for writing data.  The data parameter points to the data to be written.  The preempt parameter, if true, specifies that this region should preempt (abort) other regions enqueued on this stream.  Other parameters are treated as in snddriver_stream_start_reading. 

Snddriver_stream_control implements some control on the region with tag value tag on the specified stream.  The snd_control parameter represents one, or more, controls to be applied.  Values are made up from a conjunction of SNDDRIVER_AWAIT_STREAM, to cause partially full read streams to return all data read so far, SNDDRIVER_ABORT_STREAM, to cause the specified region to terminate early, SNDDRIVER_PAUSE_STREAM, to pause the current active region, and SNDDRIVER_RESUME_STREAM, to resume the active region.

Snddriver_stream_nsamples returns the number of samples read or written on the specified stream since the device’s ownership was established. 

Certain calls to the sound driver may result in messages being sent asynchronously back to the calling application (actually, to the port that was registered in the call resulting in the asynchronous event).  The routine snddriver_reply_handler takes the received message (resulting from a msg_receive; see the section on Mach programming in The NeXT System Reference Manual) and a pointer to a snddriver_handlers_t structure (see <sound/sounddriver.h>).  The structure referenced by the handlers parameter contains pointers to (user void ∗ argument that is passed as the first parameter to the user-supplied routine. If no routine is specified (value of the structure member is zero) the message is thrown away.  The snddriver_handlers_t structure is as follows:

 typedef void (∗sndreply_tagged_t) (
void∗arg,
inttag);
 typedef void (∗sndreply_recorded_data_t) (
void∗arg,
inttag,
 void∗data,
intsize);
 typedef void (∗sndreply_dsp_cond_true_t) (
void∗arg,
u_intmask,
 u_intflags,
u_intregs);
 typedef void (∗sndreply_dsp_msg_t) (
void∗arg,
int∗data,
intsize);
 typedef struct snddriver_handlers {
void∗arg;
inttimeout;
sndreply_tagged_tstarted;
sndreply_tagged_tcompleted;
sndreply_tagged_taborted;
sndreply_tagged_tpaused;
sndreply_tagged_tresumed;
sndreply_tagged_toverflow;
sndreply_recorded_data_trecorded_data;
sndreply_dsp_cond_true_tcondition_true;
sndreply_dsp_msg_tdsp_message;
sndreply_dsp_msg_tdsp_error;
} snddriver_handlers_t;
 

ERRORS

Each function returns KERN_SUCCESS unless there’s an error, in which case one of the following values is returned:

SND_BAD_PORT
The destination port used does not implement the requested routine.

SND_BAD_MSG
Unknown message ID.

SND_BAD_PARM
A parameter passed to this routine was invalid.

SND_NO_MEMORY
Can’t allocate kernel virtual memory (stream recording only).

SND_PORT_BUSY
The device is already owned, the current owner’s negotiation_port is returned. 

SND_NOT_OWNER
The port passed as the owner_port was not the same as the registered owner. 

SND_SEARCH
The requested resource couldn’t be found.

SND_NODATA
Mode is wrong for sending data commands on the DSP command port. 

SND_NOTALIGNED
Data passed into the device was not properly aligned.

SEE ALSO

The NeXT Reference Manual chapters Sound, Music, ArrayProcessing, and ProgrammingtheDSP.
 

NeXT, Inc.  —  13 July 1989