SB(4) — NEWS-OS Programmer’s Manual

NAME

sb, sbe − NEWS built-in/expansion audio interface

SYNOPSIS

device sb0 at hb0 priority 116
device sbe0 at hb0 priority 116

DESCRIPTION

It is possible to use the audio interface built into some NEWS workstations (NWA-033 or standard built-in audio interface) or an expansion audio interface board (NWB-260) with the device driver sb. Through the use any of these boards and this device driver, it is possible to record and playback straight PCM data (both 8-bit and 16-bit formats), ADPCM format audio data conforming to CD-I and CD-ROM XA specifications, as well as three types of logrithmically compressed PCM format audio data (8-bit) corresponding to the mu-law and A-law data formats.

Each format can handle either mono or stereo data and the sampling frequency may be chosen from among 8 KHz, 9.45 KHz, 18.9 KHz, and 37.8KHz.

Even though the major number of the one of the three interface boards is different due to the fact that it has differing hardware configurations, the software interface specifications of all the board at the device driver level are essentially the same. The correspondence between each respective special device name and its device number (major and minor numbers) is as follows.

File NameDevice No.Board
/dev/sb0 35,0        Built-in interface
/dev/sbe0 36,0        Expansion interface
/dev/sbec036,1        sbed daemon and data transfer (sbe0 only)

The data formats which can be handled by each respective board are as follows.

Sampling Frequency37.8KHz18.9KHz9.45KHz8KHz
Straight PCM 16bit % % % %
Straight PCM 8bit % % % %
ADPCM 8bit ∗ − − −
ADPCM 4bit ∗ ∗ ∗ −
mu-law/A-law 8bit % % % %
% : Record/Playback
∗ : Playback only
− : Not supported

Include Files

The following header files must be included in order to operate these devices.

#include <stdio.h>
#include <newsiodev/sound.h>

Opening Devices

Devices are exclusively opened by using the system call open(2). The error EBUSY is returned if the board is already open. In addition, non-blocking I/O mode can be specifed as shown below when opening the board.

int sbfd;
sbfd = open("/dev/sb0", O_RDWR|O_NDELAY); /∗ Non-Blocking I/O ∗/

Read/Write

The hardware begins recording with a call to the system call read(2). The system call returns the error EIO when the data cannot be transferred in time and spills over. In addition, the hardware will continue to operate even after the read ends (as long as it is not stopped forcefully with SBIOCABORT or SBIOCRESET) and will stop after FIFO becomes full. If this happens, be sure to initialize the board using SBIOCABORT because any reads attempted thereafter will result in an EIO error. The hardware will begin playback when the total amount of data written using the system call write(2) exceeds 32KB. The hardware can be tweeked to begin playback by using SBIOCFLUSH if the total amount of data is less than 32KB after the data is written. In non-blocking I/O mode, the number of bytes to actually be read/written in the region not blocked by the system call is returned.

int sbfd;/∗ file descriptor ∗/
char ∗data;/∗ pointer to the data buffer ∗/
int cnt;/∗ number of bytes to read/write ∗/
read(sbfd, data, cnt);/∗ record ∗/
write(sbfd, data, cnt);/∗ playback ∗/

Closing Devices

Devices are closed by close(2) after they have been used. close waits until all of the data in FIFO has been played back.

int sbfd;
close(sbfd);

IOCTL

SBIOCSETPARAM

SBIOCGETPARAM
These are used by the function ioctl in setting the device’s operational mode and getting its operational parameters.

/∗ sbparam ∗/
struct sbparam {
int sb_mode;     /∗ mode ∗/
int sb_format;   /∗ ADPCM file format ∗/
int sb_compress; /∗ LogPCM data compression function ∗/
int sb_rate;     /∗ sampling frequency ∗/
int sb_channel; /∗ No. of channels ∗/
int sb_bitwidth; /∗ bit width ∗/
int sb_emphasis; /∗ emphasis on/off ∗/
};
struct sbparam sbp;
ioctl(sbfd, SBIOCSETPARAM, &sbp);/∗ to set parameters ∗/
ioctl(sbfd, SBIOCGETPARAM, &sbp);/∗ to get parameters ∗/
/∗ mode ∗/
#define ADPCM 0/∗ ADPCM ∗/
#define STRPCM1/∗ Straight PCM ∗/
#define LOGPCM2/∗ Log-PCM (mu-law/A-law) ∗/
/∗ file format (ADPCM mode) ∗/
#define BSZ128 0/∗ Sony standard sound data format ∗/
#define BSZ23361/∗ user data for CD-ROM mode 2 ∗/
/∗ data compression function (LOGPCM mode) ∗/
#define MULAW0/∗ mu-law ∗/
#define ALAW 1/∗ A-law ∗/
/∗ sampling frequency ∗/
#define RATE8000 8000/∗ 8.00 kHz ∗/
#define RATE9450 9450/∗ 9.45 kHz ∗/
#define RATE1890018900/∗ 18.9 kHz ∗/
#define RATE3780037800/∗ 37.8 kHz ∗/
/∗ No. of channels ∗/
#define MONO 1/∗ MONAURAL ∗/
#define STEREO2/∗ STEREO ∗/
/∗ bit width ∗/
#define RES16B16/∗ 16 bits ∗/
#define RES8B 8/∗ 8 bits ∗/
#define RES4B 4/∗ 4 bits (ADPCM mode) ∗/
/∗ emphasis ∗/
#define EMPH_OFF0/∗ emphasis OFF ∗/
#define EMPH_ON 1/∗ emphasis ON ∗/

The structure sbparam is used to set/get device parameters.

sb_mode is used to determine the operational mode of the board. sb_format specifies the data format being used when in ADPCM mode. When BSZ128 is specified, any ADPCM data written is interpreted as being of the Sony standard sound data format and output as such. When BSZ2336 is specified, the data is interpreted as user data for CD-ROM mode 2, having a 2336 byte per block configuration. When BSZ128 or BSZ2336 (with sbe0) is specified, the sampling frequency, bit width, emphasis, and number of channels must also be set appropriately at the same time. sb_compress is the function for compressing sound data in LOGPCM mode. sb_rate specifies the sampling frequency being used. Any of four allowed values from RATE8000 to RATE37800 can be specified in ADPCM mode. only RATE37800 can be specified when using an 8-bit bit width. With a 4-bit bit width, however, it is possible to specify values from RATE9450 to RATE37800. sb_channel specifies the number of channels being used. sb_bitwidth specifies the number of quantized bits to be used for sampling. Be sure to make this specification in STRPCM or ADPCM mode. RES8B and RES16B can be specified for STRPCM and RES4B or RES8B can be specified for ADPCM. RES8B must be specified for LOGPCM data. sb_emphasis specifies the emphasis on/off status in ADPCM mode. Playback will be interrupted by SBIOCSETPARAM call. To make sure playback will not be interrupted, SBIOCWAIT should be called before starting playback.

SBIOCSETINLVL

SBIOCSETOUTLVL

SBIOCGETINLVL

SBIOCGETOUTLVL
The above are used by the ioctl function for setting and getting the audio signal’s input/output gain specifications. The corresponding parameters are specified in the structure sblevel.

struct sblevel {
int sb_left;/∗ left channel ∗/
int sb_right;/∗ right channel ∗/
};
struct sblevel sbinlevel;
int gain = -12; /∗ -12dB ∗/
sbinlevel.sb_left = sbinlevel.sb_right = gain << 16;
ioctl(sbfd, SBIOCSETINLVL, &sbinlevel);

The gain (in dB) for both the left and right channels is represented using a 31-bit, fixed point number. b31-b16 represents the integer part and b15-b1 represents the fractional part in two’s complement. Input/output through the sb0 or sbe0 mic/speaker box can be specified to have a gain from 0 dB to −32 dB in 0.5 dB increments. The line input for sbe0 can be specified from +7.5dB to −10dB in 2.5 dB increments. The line output for sbe0 is fixed at 0 dB. The least significant bit LSB (b0) represents muting. muting is on (gain −∞ dB) when this bit is 1. However, when the input selector is set to line in with sbe0 (See SBIOCSETINSW.), separate channels cannot be muted individually. The gain for both channels is set to −∞ dB when the muting bit for both channels is 1. Full scale digital data input of nearly 2 Vrms (root-mean-square value) can be obtained when the INPUT LEVEL of the mic/speaker box is set to 5 and the input gain is set to 0 dB. In addition, full scale digital data output of nearly 2 Vrms can be obtained when the volume of the mic/speaker box is set to 10 (maximum value) and the output gain is set to 0 dB.

The relationship between the specified value and the actual I/O gain used is as follows.

Value I/O Gain
0x00078000+7.5 dB
0x00050000+5.0 dB
0x00028000+2.5 dB
0x0 0 dB
0xffff8000−0.5 dB
0xffff0000−1.0 dB
0xfffe8000−1.5 dB
::
0xffe10000−31.0 dB
0xffe08000−31.5 dB
0xffe00000−32.0 dB
::
0x???????1−∞ dB

SBIOCMUTE
This is used to turn audio output on/off. The output gain setting remains unchanged.

int mflg = MUTE_ON;
ioctl(sbfd, SBIOCMUTE, &mflg);
#define MUTE_OFF0/∗ no muting ∗/
#define MUTE_ON 1/∗ muting ∗/

SBIOCFLUSH
The data in the buffer is flushed. ioctl is called to begin playback when the amount of data to be written is less than 32KB. ioctl must be called after all data has been written (in ADPCM mode). The buffer is automatically flushed when the device being used is closed.

ioctl(sbfd, SBIOCFLUSH, 0);

SBIOCWAIT
It is possible to wait for all data left in the buffer to finish being played back by calling ioctl after writing all of the specified sound data.

ioctl(sbfd, SBIOCWAIT, 0);

SBIOCSTART

SBIOCSTOP
Here, ioctl can be used to stop (SBIOCSTOP) / start (SBIOCSTART) the playback/record of data remaining in the buffer. Stop mode is released (even in stop mode) when a read is executed and the results of a write remaining in FIFO are greater than 32KB.

ioctl(sbfd, SBIOCSTART, 0);

SBIOCABORT
Stops playback/record and initializes the board and the buffer. Parameters already set are maintained.

ioctl(sbfd, SBIOCABORT, 0);

SBIOCRESET
This is used to reset the board and the device driver. After reset, settings are made to be LOGPCM mode, compressed mu-law, at a sampling frequency of RATE8000, mono, with a bit width of RES8B, and emphasis OFF. All buffers are then cleared. The gain for both input/output are set to 0 dB.

ioctl(sbfd, SBIOCRESET, 0);

SBIOCBUFRESID
The number of bytes of data remaining in the buffer are gotten. The value obtained using ioctl has an error of up to 1KB when using sb0 and up to 4KB when using sbe0.

int resid;
ioctl(sbfd, SBIOCBUFRESID, &resid);

SBIOCBUFSIZE
The total capacity of the butter in bytes is gotten. the total capacity of the buffer when using sb0 differs in LOGPCM mode from that in other modes.

int bsize;
ioctl(sbfd, SBIOCBUFSIZE, &bsize);

SBIOCEMPHASIS(sbe0)
This is used to select emphasis on/off in ADPCM mode when using sbe0.

int emphasis = EMPH_OFF;
ioctl(sbfd, SBIOCEMPHASIS, &emphasis);
#define EMPH_OFF0x0/∗ Emphasis OFF ∗/
#define EMPH_ON 0x1/∗ Emphasis ON ∗/

SBIOCSETINSW(sbe0)

SBIOCGETINSW(sbe0)
This is the audio input selector for sbe0. It is possible to select LINE IN (RCA pin jack) or the mic/speaker box. It is possible to set selector switch and get its status. The initial values are set in accordance with the input select switch on the board when the device is opened.

int insel = MIC_SP_BOX;
ioctl(sbfd, SBIOCINSEL, &insel);
#define RCALINE 0x0/∗ RCA pin ∗/
#define MIC_SP_BOX0x1/∗ MIC/SP BOX ∗/

SBIOCSETMONSW(NWS-1200/3200 Series)

SBIOCGETMONSW(NWS-1200/3200 Series)
Monitor switching at recording time will be controlled by software in NWS-1200/3200 Series models. Monitor switch can be set (SBIOCSETMONSW) or get (SBIOCGETMONSW) by using ioctl. Once monitor switch is set to ON, the mode will not be changed even when the device is closed using the system call, close(), until the switch will be turned OFF. Writing to the device with the system call, write() or SBIOCRESET call resets the monitor switch to OFF.

int monit = MONITOR_ON;
ioctl(sbfd, SBIOCSETMONSW, &monit);
ioctl(sbfd, SBIOCGETMONSW, &monit);
#define MONITOR_OFF0
#define MONITOR_ON1

ERRORS

The system calls return −1 when errors occur and the value of the error code itself is returned as follows.

[ENXIO] - undefined special device name specified for opening.
- data read attempted in ADPCM mode.
- sbed (daemon) not running (when using sbe0).

[EBUSY] - device already open.

[EINVAL] - ioctl request, argument not defined.
- decode not possible due to error in the ADPCM data written.

[EINTR] - system call interrupted by another signal.

[EFAULT] - outside specified address area allocated to the read/write buffer.

[EIO] - FIFO overflow during the read.

BUGS

Although it is possible to use sb0 and sbe0 simultaneously, it is not possible to more than one of the same type of board at once.

The relative amount of data (per unit time) for transfer is directly proportional to the settings for the number of channels, the number of quantized bits, and the sampling frequency. If the amount of data for transfer is large per unit time, data input may spill over into other areas of memory depending on the system load and the conditions of the file system being used. Also, data output may be delayed.

FILES

/dev/sb0 Built-in audio interface device file
/dev/sbe0 Expansion audio interface device file
/dev/sbec0Expansion audio interface device file (for use by Daemon)

Museum

Related Articles