[0m


SOUND(4)	    UNIX Programmer's Manual		 SOUND(4)



[1mNAME
     [0msound - audio output device

[1mDESCRIPTION
     [0mThe device /_d_e_v/_s_o_u_n_d gives access to the sound output
     hardware.	The hardware has a variable sampling rate and two
     separate audio output ports, allowing for stereo sound via
     an external socket, or monaural sound from the built-in
     loudspeaker.  The number of channels of sound sample data
     can be varied over 1, 2, 4 or 8 and each channel is indepen-
     dently positionable to one of 7 different stereo positions
     (full left through full right).  The hardware functionality
     is controllable by means of _i_o_c_t_l(2) commands on a open file
     descriptor for the device.

     [1mSound output

     [0mSound output is achieved using the _w_r_i_t_e(2) system call to
     send sound data samples as a stream of bytes to the device.
     For hardware-related reasons, all _w_r_i_t_e calls should specify
     a number of bytes which is a multiple of 16, otherwise the
     error EINVAL will be returned and no data output. In the
     present implementation of the system, the sound device
     driver uses a number of 4096-byte buffers to store the data
     to be output, and hence for maximum efficiency writes to the
     device should normally be of this size or an integer multi-
     ple of it (the block size returned by a _s_t_a_t(2) or _f_s_t_a_t(2)
     call for the device is 4096).

     The device may be operated in blocking or non-blocking mode:
     in blocking mode (the default), any attempt to write data
     will wait until all user data has been transferred to the
     driver's buffers.	In non-blocking mode, only as much data
     as can be accepted at the time will be transferred and the
     return value from the _w_r_i_t_e call will indicate how much data
     was moved.  If there is no room at all in the buffers, the
     error EWOULDBLOCK (or EAGAIN, they have the same value) will
     be returned.  Non-blocking mode is selected either by using
     the O_NONBLOCK flag to the initial call of _o_p_e_n(2), or by
     setting this flag on the file descriptor using the _f_c_n_t_l(2)
     call once the device has been opened.

     [1mSample Format

     [0mIndividual sound samples are presented to the device as 8-
     bit quantities in a signed, pseudo-logarithmic format shown
     below (bit 0 is the least significant bit, bit 7 the most
     significant):

	  bits 7..5 - chord number
	  bits 4..1 - position on chord
	  bit	  0 - sign (0: positive, 1: negative)



Printed 3/12/91     Revision 1.2 of 10/08/90			1






SOUND(4)	    UNIX Programmer's Manual		 SOUND(4)



     where a chord is a linear segment in which each successive
     position has a value a fixed step up from the previous one,
     and the step size in one chord is twice that in the previous
     chord.  The input value 0 produces 0 on output; the step in
     chord 0 is 1, in chord 7 it is 128.  Thus the range of input
     values 0..127 (viewing bits 7..1 of the sample as a single
     7-bit binary number) will produce output values (as audio
     signal amplitudes) in the range 0..3952.


     [1mSound system structure

     [0mThe output sample rate (i.e. the rate at which individual
     byte samples are converted to analogue audio output values)
     is controllable in terms of the interval between samples,
     expressed in microseconds, where the available range is from
     6 microseconds to 255 microseconds.  For a simple single-
     channel configuration, this is the equivalent of a sample
     frequency range from 166.7 kHz down to 3.921 kHz.

     In order to provide multi-channel operation, the hardware
     uses time-division multiplexing to break up the sequence of
     byte samples in the output stream into blocks of 8.  Each of
     the 8 samples in a block has associated with it a register
     (numbered from 0 to 7) to control the positioning of that
     sample within the stereo stage; the register takes one out
     of seven different values representing from far left to far
     right.  The data being fed to the hardware is viewable as
     representing 1, 2, 4 or 8 separate channels of sound, as
     follows.  For single channel use, all 8 stereo position
     registers are set to the same value, and the output byte
     stream sample rate is the same as the effective channel sam-
     ple rate.	For two channels, the data in the output stream
     comprises pairs of bytes, one for each channel; all odd num-
     bered stereo position registers are set to the desired posi-
     tion for the first channel, and all even numbered channel
     position registers are set to the desired position for the
     second channel (which might be the same as for the first
     channel). The output byte stream sample rate must then be
     set to twice the individual channel sample rate, e.g. for
     two channels of data, each sampled at 10kHz, the output sam-
     ple rate is 20kHz.  For four channels, stereo position
     registers 0 and 4 are set to the desired position for the
     first channel, registers 1 and 5 to that for the second
     channel, etc, and the output rate is 4 times the individual
     channel sample rate.  Similarly for 8 channels, each indivi-
     dual stereo position register controls its corresponding
     channel position, and the output sample rate is 8 times the
     individual channel sample rate.

     It is the responsibility of the program controlling the
     sound device to set up the 8 stereo position registers and



Printed 3/12/91     Revision 1.2 of 10/08/90			2






SOUND(4)	    UNIX Programmer's Manual		 SOUND(4)



     the output sample rate as required for the application.  The
     default setting of the device parameters is for single-
     channel mode, 20kHz output sample rate.

     [1mParameter control

     [0mThe parameters of the sound output system may be examined
     and modified by means of two _i_o_c_t_l commands, SNDIOCGETPARAMS
     and SNDIOCSETPARAMS, applied to a file descriptor for the
     sound device.  These commands, the structure they operate
     on, and various other useful macros are given in the header
     file <_d_e_v/_s_n_d_i_o_c_t_l._h>. The structure is defined as:

	  typedef struct snd_params
	  {
	      unsigned int period; /* output inter-sample time in usec */
	      unsigned char image_pos[SND_MAX_CHANS];
	  } SNDParams, *SNDParamsRef;

     A simplified example of use (no error checking, etc) is:

	  SNDParams sparams;
	  int fd, i;
	  fd = open ("/dev/sound", O_WRONLY);
	  ioctl (fd, SNDIOCGETPARAMS,  &sparams);
	  printf ("Original sample period: %d0, sparams.period);
	  /*
	   * Set up for two channel use, full-spread stereo, at
	   * 16.67 kHz sample rate.  This implies an output sample
	   * rate of 33.33kHz, i.e. a period of 30 microseconds.
	   */
	  sparams.period = 30;
	  /* Position alternate channels to full left, full right.
	  for (i = 0; i < SND_MAX_CHANS; ++i)
	      sparams.image_pos[i] =
	       ((i % 2) == 0) ? SND_LEFT_100 : SND_RIGHT_100;
	  /* Now set parameters into the device */
	  ioctl (fd, SNDIOCSETPARAMS, &sparams);
	  /* Then start sending output data... */


     [1mLoudspeaker control

     [0mIn addition to controlling the hardware parameters, two
     further ioctl commands to the sound device allow the built-
     in loudspeaker to be enabled or disabled, and its state
     examined:

	  int state;
	  ioctl (fd, SNDIOCGETSPKR, &state);

     writes into _s_t_a_t_e the value 1 if the speaker is enabled, and



Printed 3/12/91     Revision 1.2 of 10/08/90			3






SOUND(4)	    UNIX Programmer's Manual		 SOUND(4)



     0 if it is not.  Correspondingly,

	  int state;
	  ..
	  ioctl (fd, SNDIOCGETSPKR, &state);

     will turn the speaker off if _s_t_a_t_e has the value 0 and on
     otherwise.

[1mNOTES
     [0mSound data samples may be either computed dynamically or
     derived from existing data, but in either case the program
     must arrange to provide data to the device at a rate in
     accordance with the output sample rate in use.  If data is
     not supplied fast enough, audibly unpleasant effects can
     occur as the sample stream is interrupted by periods of
     silence.

[1mFILES
     [0m/dev/sound

[1mSEE ALSO
     [0m_c_o_n_s_o_l_e(4), _i_o_c_t_l(2)
     VIDC data sheet































Printed 3/12/91     Revision 1.2 of 10/08/90			4



[0m