Date: Wed, 24 Apr 1996 00:12:16 -0700
From: jordan@pongo.West.Sun.COM (Jordan Brown)
Subject: Item #350: DSE:  "sound" device properties


P1275 Openboot Working Group Proposal -- Proposal #:350 Ver 2.0

Title:          "sound" properties describing device capabilities

Author:         Jordan Brown, SunSoft
		Vicki Abe, SunSoft

Date:           24 April 1996

Ed/Tech:        Technical

Synopsis:       Proposes properties to describe the capabilities of an audio
		device.

Doc & Version:  Device Support Extensions, v0.6

Problem:

Proposal 295 attempted to clarify the DSE-specified properties for "sound"
devices by having them describe the device's current settings.  The Committee
decided instead that the *capabilities* of the device, rather than its
current settings, should be described.

This proposal is a rewrite of 295 that attempts to do so.  It takes the
form of replacement text for the entire "sound" section.  It also includes
a few minor cleanups and removal of some text in "open" that was removed
by, I believe, proposal 296 but that the editor apparently missed.

Proposal:

6.  Sound Device

In order to use a sound device within the context of Open Firmware
(e.g., "boot beeps"), the following properties and methods shall be
implemented. To provide a common data format for universal support,
Open Firmware shall, by default, accept audio to write or return audio
from read that consists of 8-bit monophonic samples encoded as unsigned
linear values, centered at 128.

    Note 1: Some implementation of "sound" nodes may need to convert
    this data into a form acceptable to the audio hardware being
    supported.  It is not anticipated that this is an unreasonable
    requirement.

    Note 2: An implementation may choose to supply additional
    properties, methods and "open" arguments so as to support more
    advanced audio capabilities, so long as a default _open_ results in
    _read_ and _write_ using the standard format.

6.1 Definition of Terms

channel
	One "track" of audio data.  In stereophonic data, there are
	two channels - left and right.

sample
	The atomic unit of audio data.  A single digital sample from one
	channel.

sample frame
	A set of samples, one per channel.  (In the trivial case of
	a single channel, synonymous with "sample".)

precision
	The size (in bits) of a sample.

signed linear
	An audio encoding where the sample is represented by a signed
	number, with 0 as the centerpoint.

unsigned linear
	An audio encoding where the sample is represented by an unsigned
	number with 1/2 range, e.g. 128 or 32768, as the centerpoint.

6.2.  "sound" device standard properties

"device_type"                           			S

    Standard property; the value of this property shall be "sound".

The following properties document the _possible_ values to which the
device can be set.

"#input-channels"						S

    Standard property name to define the possible numbers of input channels
    supported.

    prop-encoded-array:
	Arbitrary number of integers, each encoded with encode-int.

"#output-channels"						S

    Standard property name to define the possible numbers of output
    channels supported.

    prop-encoded-array:
	Arbitrary number of integers, each encoded with encode-int.

"sample-precisions"						S

    Standard property name to define the possible sample precisions.

    prop-encoded-array:
	Arbitrary number of integers, each encoded with encode-int.

    Specifies the possible numbers of bits required to store one audio
    sample from one channel.

"sample-frame-sizes"						S

    Standard property name to define the possible sample frame sizes.

    prop-encoded-array:
	Arbitrary number of integers, each encoded with encode-int.

    Specifies the possible numbers of bits required to store one sample
    frame - one sample from each channel.

"input-frame-rates"						S

    Standard property name to define the possible sample frame rates for
    audio input.

    prop-encoded-array:
	Arbitrary number of integers, each encoded with encode-int.

    Specifies the possible input sampling rates, in sample frames per
    second.

"output-frame-rates"						S

    Standard property name to define the possible sample frame rates for
    audio output.

    prop-encoded-array:
	Arbitrary number of integers, each encoded with encode-int.

    Specifies the possible output sampling rates, in sample frames per
    second.

"input-encoding-types"						S

    Standard property name to define the possible input encoding types.

    prop-encoded-array:
	The concatenation, with encode+, of an arbitrary number of
	text strings, each encoded with encode-string.

    Specifies possible input encodings.  Valid values include
    "8bit ulaw", "8bit alaw", "8bit unsigned linear", "8bit signed linear",
    "16bit LE unsigned linear", "16bit BE unsigned linear",
    "16bit LE signed linear", "16bit BE unsigned linear",
    and "4bit ADPCM".

"output-encoding-types"						S

    Standard property name to define the possible output encoding types.

    prop-encoded-array:
	The concatenation, with encode+, of an arbitrary number of
	text strings, each encoded with encode-string.

    Specifies possible output encodings.  Valid values are as
    for "input-encoding-types".

6.3.  "sound" device standard methods

The following methods shall be implemented by a "sound" device.

open		( -- true | false )				M

    This Standard method prepares the "sound" device for subsequent
    reads and/or writes.

close		( -- )						M

    Standard Open Firmware behavior.

read		( addr size -- actual )				M

    Acquire sound data, storing the samples at addr.

write		( addr size -- actual )				M

    Output sound samples stored at addr.

[ P1275 Item #350 -- Received: Wed Apr 24 02:39:55 PDT 1996 ]