NAME

sbpro − Sound Blaster Pro audio device

SYNOPSIS

/dev/sbpro /dev/sbproctl

DESCRIPTION

The sbpro device plays and records one or two channels of sound using the Creative Labs Sound Blaster Pro audio card.  Digital audio data is sampled at rates from 4000 to 44,100 samples per second with 8-bit precision.  By default, the data is converted to use u−law encoding, for compatibility with SPARC systems. 

The sbpro driver is implemented as a STREAMS device.  In order to record audio input, applications open(2) the /dev/sbpro device and read data from it using the read(2) system call.  (Note that for compatibility with SPARC systems, /dev/sbpro will typically be linked to /dev/audio).  Similarly, sound data is queued to the audio output port by using the write(2) system call. 

Opening the Sound Blaster Pro Device

The sbpro device is treated as an exclusive resource: only one process may typically open the device at a time.  However, two processes may simultaneously access the device if one opens it read-only and the other opens it write-only. 

When a process cannot open /dev/sbpro because the requested access mode is busy:

• If the O_NDELAY flag is set in the open() flags argument, then open() returns −1 immediately, with errno set to EBUSY. 

• If O_NDELAY is not set, then open() hangs until the device is available or a signal is delivered to the process, in which case open() returns −1 with errno set to EINTR. 

Since the sbpro device grants exclusive read or write access to a single process at a time, long-lived audio applications may choose to close the device when they enter an idle state, reopening it when required.  The play.waiting and record.waiting flags in the audio information structure (see below) provide an indication that another process has requested access to the device.  This information is advisory only; background audio output processes, for example, may choose to relinquish the sbpro device whenever another process requests write access. 

Recording Audio Data

The read() system call copies data from the system buffers to the application.  Ordinarily, read() blocks until the user buffer is filled.  The FIONREAD ioctl may be used to determine the amount of data that may be read without blocking.  The device may alternatively be set to a non-blocking mode, in which case read() completes immediately, but may return fewer bytes than requested.  Refer to the read(2) manual page for a complete description of this behavior. 

When the sbpro device is opened with read access, the device driver immediately starts buffering audio input data.  Since this consumes system resources, processes that do not record audio data should open the device write-only (O_WRONLY). 

The transfer of input data to STREAMS buffers may be paused (or resumed) by using the AUDIO_SETINFO ioctl to set (or clear) the record.pause flag in the audio information structure (see below).  All unread input data in the STREAMS queue may be discarded by using the I_FLUSH STREAMS ioctl (see streamio(7)). 

Input data accumulates in STREAMS buffers at a rate equivalent to the sampling rate times the number of channels (the default is 8000 bytes per second for 8kHz monophonic samples).  If the application that consumes the data cannot keep up with this data rate, the STREAMS queue may become full.  When this occurs, the record.error flag is set in the audio information structure and input sampling ceases until there is room in the input queue for additional data.  In such cases, the input data stream contains a discontinuity.  For this reason, audio recording applications should open the sbpro device when they are prepared to begin reading data, rather than at the start of extensive initialization. 

Playing Audio Data

The write() system call copies data from an applications buffer to the STREAMS output queue.  Ordinarily, write() blocks until the entire user buffer is transferred.  The device may alternatively be set to a non-blocking mode, in which case write() completes immediately, but may have transferred fewer bytes than requested (see write(2)). 

Although write() returns when the data is successfully queued, the actual completion of audio output may take considerably longer.  The AUDIO_DRAIN ioctl may be issued to allow an application to block until all of the queued output data has been played.  Alternatively, a process may request asynchronous notification of output completion by writing a zero-length buffer (end-of-file record) to the output stream.  When such a buffer has been processed, the play.eof flag in the audio information structure (see below) is ­incremented. 

The final close() of the file descriptor hangs until audio output has drained.  If a signal interrupts the close(), or if the process exits without closing the device, any remaining data queued for audio output is flushed and the device is closed immediately. 

The conversion of output data may be paused (or resumed) by using the AUDIO_SETINFO ioctl to set (or clear) the play.pause flag in the audio information structure.  Queued output data may be discarded by using the I_FLUSH STREAMS ioctl. 

Output data is played from the STREAMS buffers at the specified sampling rate.  If the output queue becomes empty, the play.error flag is set in the audio information structure and output ceases until additional data is written. 

Asynchronous I/O

The I_SETSIG STREAMS ioctl may be used to enable asynchronous notification, via the SIGPOLL signal, of input and output ready conditions.  This, in conjunction with non-blocking read() and write() requests, is normally sufficient for applications to maintain an audio stream in the background.  Alternatively, asynchronous reads and writes may be initiated using the aioread(3) functions. 

Audio Data Encoding

The data samples processed by the sbpro device are encoded in 8 bits.  The high-order bit is a sign bit; 1 represents positive data and 0 represents negative data.  The low-order 7 bits represent signal magnitude and are inverted (1’s complement).  The magnitude is encoded according to a u-law transfer function; such an encoding provides an improved signal-to-noise ratio at low amplitude levels.  In order to achieve the best results, the audio recording gain should be set so that typical amplitude levels lie within approximately three-fourths of the full dynamic range. 

Audio Control Pseudo-Device

It is sometimes convenient to have an application, such as a volume control panel, modify certain characteristics of the sbpro device while it is being used by an unrelated process.  The /dev/sbproctl minor device is provided for this purpose.  (Note that for compatibility with SPARC systems, /dev/sbproctl will typically be linked to /dev/audioctl).  Any number of processes may open /dev/sbproctl simultaneously.  However, read() and write() system calls are ignored by /dev/sbproctl.  The AUDIO_GETINFO and AUDIO_SETINFO ioctl commands may be issued to /dev/sbproctl in order to determine the status or alter the behavior of /dev/sbpro. 

Audio Status Change Notification

Applications that open the audio control pseudo-device may request asynchronous notification of changes in the state of the sbpro device by setting the S_MSG flag in an I_SETSIG STREAMS ioctl.  Such processes receive a SIGPOLL signal when any of the following events occur:

• An AUDIO_SETINFO ioctl has altered the device state. 

• An input overflow or output underflow has occurred. 

• An end-of-file record (zero-length buffer) has been processed on output. 

• An open() or close() of /dev/sbpro has altered the device state. 

Audio Information Structure

The state of the sbpro device may be polled or modified using the AUDIO_GETINFO and AUDIO_SETINFO ioctl commands.  These commands operate on the audio_info structure, defined in <sys/audioio.h> as follows:

/∗ Data encoding values, used below in the encoding field ∗/
#define AUDIO_ENCODING_ULAW(1)/∗ u-law encoding ∗/
#define AUDIO_ENCODING_ALAW(2)/∗ A-law encoding ∗/
#define AUDIO_ENCODING_LINEAR(3)/∗ linear (8-bit signed data) encoding ∗/
 /∗ These ranges apply to record, play, and monitor gain values ∗/
#define AUDIO_MIN_GAIN(0)/∗ minimum gain value ∗/
#define AUDIO_MAX_GAIN(255)/∗ maximum gain value ∗/
 /∗ Audio I/O channel status, used below in the audio_info structure ∗/
struct audio_prinfo {
/∗ The following values describe the audio data encoding ∗/
unsignedsample_rate;/∗ samples per second ∗/
unsignedchannels;/∗ number of interleaved
channels ∗/
unsignedprecision;/∗ number of bits per sample ∗/
unsignedencoding;/∗ data encoding method ∗/
 /∗ The following values control audio device configuration ∗/
unsignedgain;/∗ gain level ∗/
unsignedport;/∗ selected I/O port ∗/
 /∗ The following values describe the current device state ∗/
unsignedsamples;/∗ number of samples converted ∗/
unsignedeof;/∗ End Of File counter (play only) ∗/
unsigned charpause;/∗ non-zero if paused, zero to resume ∗/
unsigned charerror;/∗ non-zero if overflow/underflow ∗/
unsigned charwaiting;/∗ non-zero if a process wants access ∗/
 /∗ The following values are read-only device state flags ∗/
unsigned charopen;/∗ non-zero if open access granted ∗/
unsigned charactive;/∗ non-zero if I/O active ∗/
};
 /∗ This structure is used in AUDIO_GETINFO and AUDIO_SETINFO ioctl commands ∗/
typedef struct audio_info {
struct audio_prinforecord;/∗ input status information ∗/
struct audio_prinfoplay;/∗ output status information ∗/
unsignedmonitor_gain;/∗ input to output mix ∗/
}  audio_info_t;
  #defineMAX_AUDIO_DEV_LEN(16)
/∗ Parameter for the AUDIO_GETDEV ioctl ∗/
typedef struct audio_device {
charname[MAX_AUDIO_DEV_LEN];
charversion[MAX_AUDIO_DEV_LEN];
charconfig[MAX_AUDIO_DEV_LEN];
} audio_device_t;

The play.gain and record.gain fields specify the output and input volume levels.  A value of AUDIO_MAX_GAIN indicates maximum gain.  The device also allows input data to be monitored by mixing audio input onto the output channel.  The monitor_gain field controls the level of this feedback path. 

The Sound Blaster hardware does not support multiple output devices, so the play.port field is provided for compatibility purposes only.  On SPARC systems, it controls the output path for the audio device, and may be set to either AUDIO_SPEAKER or AUDIO_HEADPHONE to direct output to the built-in speaker or the headphone jack, respectively.  The record.port field allows selecting which audio source is used for recording, and may be set to one of AUDIO_MICROPHONE , AUDIO_LINE_IN , or AUDIO_CD to select input from the microphone jack, line-level input jack, or internal CD input, ­respectively. 

The play.pause and record.pause flags may be used to pause and resume the transfer of data between the sbpro device and the STREAMS buffers.  The play.error and record.error flags indicate that data underflow or overflow has occurred.  The play.active and record.active flags indicate that data transfer is currently active in the corresponding direction. 

The play.open and record.open flags indicate that the device is currently open with the corresponding access permission.  The play.waiting and record.waiting flags provide an indication that a process may be waiting to access the device.  These flags are set automatically when a process blocks on open(), though they may also be set using the AUDIO_SETINFO ioctl command.  They are cleared only when a process relinquishes access by closing the device. 

The play.samples and record.samples fields are initialized, at open(), to zero and increment each time a data sample is copied to or from the associated STREAMS queue.  Applications that keep track of the number of samples read or written may use these fields to determine exactly how many samples remain in the STREAMS buffers.  The play.eof field increments whenever a zero-length output buffer is synchronously processed.  Applications may use this field to detect the completion of particular segments of audio output. 

The sample_rate, channels, precision, and encoding fields report the audio data format in use by the device.  Unlike the SPARC systems, these values may be modified and the sbpro driver will use valid values.  The sample_rate field can be set to any value between 4000 and 44100.  channels can be set to 1 for monophonic and 2 for stereophonic samples, and encoding may be set to AUDIO_ENCODING_ULAW or AUDIO_ENCODING_LINEAR , for SPARC-compatible u−law encoding or PC-compatible linear 8-bit signed data, ­respectively. 

Filio and STREAMS IOCTLS

All of the streamio(7) ioctl commands may be issued for the /dev/sbpro device.  Because the /dev/sbproctl device has its own STREAMS queues, most of these commands neither modify nor report the state of /dev/sbpro if issued for the /dev/sbproctl device.  The I_SETSIG ioctl may be issued for /dev/sbproctl to enable the notification of audio status changes, as described above. 

Audio IOCTLS

The sbpro device additionally supports the following ioctl commands:

AUDIO_DRAIN
The argument is ignored. This command suspends the calling process until the output STREAMS queue is empty, or until a signal is delivered to the calling process.  It may only be issued for the /dev/sbpro device.  An implicit AUDIO_DRAIN is performed on the final close() of /dev/sbpro. 

AUDIO_GETINFO
The argument is a pointer to an audio_info structure.  This command may be issued for either /dev/sbpro or /dev/sbproctl.  The current state of the /dev/sbpro device is returned in the structure. 

AUDIO_SETINFO
The argument is a pointer to an audio_info structure.  This command may be issued for either /dev/sbpro or /dev/sbproctl.  This command configures the sbpro device according to the structure supplied and overwrites the structure with the new state of the device.  Note: The play.samples, record.samples, play.error, record.error, and play.eof fields are modified to reflect the state of the device when the AUDIO_SETINFO was issued.  This allows programs to atomically modify these fields while retrieving the previous value. 

Certain fields in the information structure, such as the pause flags, are treated as read-only when /dev/sbpro is not open with the corresponding access permission.  Other fields, such as the gain levels and encoding information, may have a restricted set of acceptable values.  Applications that attempt to modify such fields should check the returned values to be sure that the corresponding change took effect. 

Once set, the following values persist through subsequent open() and close() calls of the device: play.gain, record.gain, monitor_gain, play.port, and record.port. All other state is reset when the corresponding I/O stream of /dev/sbpro is closed. 

The audio_info structure may be initialized through the use of the AUDIO_INITINFO macro.  This macro sets all fields in the structure to values that are ignored by the AUDIO_SETINFO command.  For instance, the following code switches the input port from the microphone port to the line-level input jack without modifying any other audio parameters:

audio_info_tinfo;
 AUDIO_INITINFO(&info);
info.record.port = AUDIO_LINE_IN;
err = ioctl(audio_fd, AUDIO_SETINFO, &info);

This technique is preferred over using a sequence of AUDIO_GETINFO followed by AUDIO_SETINFO. 

AUDIO_GETDEV
The argument is a pointer to an audio_device structure.  This command may be issued for either /dev/sbpro or /dev/sbproctl.  The returned value in the name field will be a string that will identify the current hardware device, the value in version will be a string indicating the current version of the hardware, and config will be a device-specific string identifying the properties of the audio stream associated with that file descriptor.  The sbpro driver will return "SUNW,sbpro" in the name field of the audio_device structure. The version field will contain the version number of the device driver, and the config field will be set to "config" . 

Unsupported Device Features

The Sound Blaster Pro card also supports FM synthesis and MIDI device control, although neither is supported in this version of the driver. 

FILES

/dev/sbpro

/dev/sbproctl

/dev/audio linked to /dev/sbpro

/dev/audioctl linked to /dev/sbproctl

/usr/demo/SOUND

SEE ALSO

ioctl(2), read(2), write(2), aioread(3), streamio(7)

Creative Labs, Inc.  Sound Blaster Pro User Reference Manual

BUGS

Due to a feature of the STREAMS implementation, programs that are terminated or exit without closing the audio device may hang for a short period while audio output drains.  In general, programs that produce audio output should catch the SIGINT signal and flush the output stream before exiting. 

The current driver implementation does not support the A-law encoding mode.  Future implementations may permit the AUDIO_SETINFO ioctl to modify the play.encoding and record.encoding fields of the device information structure to enable this mode. 
 
 

SunOS 5.1  —  Last change: 31 May 1993