sys/dev/audio_if.h

   1 /*      $NetBSD: audio_if.h,v 1.65 2008/03/04 18:23:44 cube Exp $       */
   2
   3 /*
   4  * Copyright (c) 1994 Havard Eidnes.
   5  * All rights reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions
   9  * are met:
  10  * 1. Redistributions of source code must retain the above copyright
  11  *    notice, this list of conditions and the following disclaimer.
  12  * 2. Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  * 3. All advertising materials mentioning features or use of this software
  16  *    must display the following acknowledgement:
  17  *      This product includes software developed by the Computer Systems
  18  *      Engineering Group at Lawrence Berkeley Laboratory.
  19  * 4. Neither the name of the University nor of the Laboratory may be used
  20  *    to endorse or promote products derived from this software without
  21  *    specific prior written permission.
  22  *
  23  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  24  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26  * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  27  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33  * SUCH DAMAGE.
  34  *
  35  */
  36
  37 #ifndef _SYS_DEV_AUDIO_IF_H_
  38 #define _SYS_DEV_AUDIO_IF_H_
  39 #include <sys/types.h>
  40 #include <sys/audioio.h>
  41
  42 /* check we have an audio(4) configured into kernel */
  43 #if defined(_KERNEL_OPT)
  44 #include "audio.h"
  45
  46 #if (NAUDIO == 0) && (NMIDI == 0) && (NMIDIBUS == 0)
  47 #error "No 'audio* at audiobus?' or 'midi* at midibus?' or similar configured"
  48 #endif
  49
  50 #endif /* _KERNEL_OPT */
  51
  52 /*
  53  * Interfaces for hardware drivers and MI audio.
  54  */
  55
  56 struct audio_softc;
  57
  58 /**
  59  * audio stream format
  60  */
  61 typedef struct audio_params {
  62         u_int   sample_rate;    /* sample rate */
  63         u_int   encoding;       /* e.g. mu-law, linear, etc */
  64         u_int   precision;      /* bits/subframe */
  65         u_int   validbits;      /* valid bits in a subframe */
  66         u_int   channels;       /* mono(1), stereo(2) */
  67 } audio_params_t;
  68
  69 /* The default audio mode: 8 kHz mono mu-law */
  70 extern const struct audio_params audio_default;
  71
  72 /**
  73  * audio stream buffer
  74  */
  75 typedef struct audio_stream {
  76         size_t bufsize;         /* allocated memory */
  77         uint8_t *start;         /* start of buffer area */
  78         uint8_t *end;           /* end of valid buffer area */
  79         uint8_t *inp;           /* address to be written next */
  80         const uint8_t *outp;    /* address to be read next */
  81         int used;               /* valid data size in this stream */
  82         audio_params_t param;   /* represents this stream */
  83         bool loop;
  84 } audio_stream_t;
  85
  86 static __inline int
  87 audio_stream_get_space(const audio_stream_t *s)
  88 {
  89         if (s)
  90                 return (s->end - s->start) - s->used;
  91         return 0;
  92 }
  93
  94 static __inline int
  95 audio_stream_get_used(const audio_stream_t *s)
  96 {
  97         return s ? s->used : 0;
  98 }
  99
 100 static __inline uint8_t *
 101 audio_stream_add_inp(audio_stream_t *s, uint8_t *v, int diff)
 102 {
 103         s->used += diff;
 104         v += diff;
 105         if (v >= s->end)
 106                 v -= s->end - s->start;
 107         return v;
 108 }
 109
 110 static __inline const uint8_t *
 111 audio_stream_add_outp(audio_stream_t *s, const uint8_t *v, int diff)
 112 {
 113         s->used -= diff;
 114         v += diff;
 115         if (v >= s->end)
 116                 v -= s->end - s->start;
 117         return v;
 118 }
 119
 120 /**
 121  * an interface to fill a audio stream buffer
 122  */
 123 typedef struct stream_fetcher {
 124         int (*fetch_to)(struct stream_fetcher *, audio_stream_t *, int);
 125 } stream_fetcher_t;
 126
 127 /**
 128  * audio stream filter.
 129  * This must be an extension of stream_fetcher_t.
 130  */
 131 typedef struct stream_filter {
 132 /* public: */
 133         stream_fetcher_t base;
 134         void (*dtor)(struct stream_filter *);
 135         void (*set_fetcher)(struct stream_filter *, stream_fetcher_t *);
 136         void (*set_inputbuffer)(struct stream_filter *, audio_stream_t *);
 137 /* private: */
 138         stream_fetcher_t *prev;
 139         audio_stream_t *src;
 140 } stream_filter_t;
 141
 142 /**
 143  * factory method for stream_filter_t
 144  */
 145 typedef stream_filter_t *stream_filter_factory_t(struct audio_softc *,
 146         const audio_params_t *, const audio_params_t *);
 147
 148 /**
 149  * filter pipeline request
 150  *
 151  * filters[0] is the first filter for playing or the last filter for recording.
 152  * The audio_params_t instance for the hardware is filters[0].param.
 153  */
 154 #ifndef AUDIO_MAX_FILTERS
 155 # define AUDIO_MAX_FILTERS      8
 156 #endif
 157 typedef struct stream_filter_list {
 158         void (*append)(struct stream_filter_list *, stream_filter_factory_t,
 159                        const audio_params_t *);
 160         void (*prepend)(struct stream_filter_list *, stream_filter_factory_t,
 161                         const audio_params_t *);
 162         void (*set)(struct stream_filter_list *, int, stream_filter_factory_t,
 163                     const audio_params_t *);
 164         int req_size;
 165         struct stream_filter_req {
 166                 stream_filter_factory_t *factory;
 167                 audio_params_t param; /* from-param for recording,
 168                                          to-param for playing */
 169         } filters[AUDIO_MAX_FILTERS];
 170 } stream_filter_list_t;
 171
 172 struct malloc_type;
 173 struct audio_hw_if {
 174         int     (*open)(void *, int);   /* open hardware */
 175         void    (*close)(void *);       /* close hardware */
 176         int     (*drain)(void *);       /* Optional: drain buffers */
 177
 178         /* Encoding. */
 179         /* XXX should we have separate in/out? */
 180         int     (*query_encoding)(void *, audio_encoding_t *);
 181
 182         /* Set the audio encoding parameters (record and play).
 183          * Return 0 on success, or an error code if the
 184          * requested parameters are impossible.
 185          * The values in the params struct may be changed (e.g. rounding
 186          * to the nearest sample rate.)
 187          */
 188         int     (*set_params)(void *, int, int, audio_params_t *,
 189                     audio_params_t *, stream_filter_list_t *,
 190                     stream_filter_list_t *);
 191
 192         /* Hardware may have some say in the blocksize to choose */
 193         int     (*round_blocksize)(void *, int, int, const audio_params_t *);
 194
 195         /*
 196          * Changing settings may require taking device out of "data mode",
 197          * which can be quite expensive.  Also, audiosetinfo() may
 198          * change several settings in quick succession.  To avoid
 199          * having to take the device in/out of "data mode", we provide
 200          * this function which indicates completion of settings
 201          * adjustment.
 202          */
 203         int     (*commit_settings)(void *);
 204
 205         /* Start input/output routines. These usually control DMA. */
 206         int     (*init_output)(void *, void *, int);
 207         int     (*init_input)(void *, void *, int);
 208         int     (*start_output)(void *, void *, int,
 209                                     void (*)(void *), void *);
 210         int     (*start_input)(void *, void *, int,
 211                                    void (*)(void *), void *);
 212         int     (*halt_output)(void *);
 213         int     (*halt_input)(void *);
 214
 215         int     (*speaker_ctl)(void *, int);
 216 #define SPKR_ON         1
 217 #define SPKR_OFF        0
 218
 219         int     (*getdev)(void *, struct audio_device *);
 220         int     (*setfd)(void *, int);
 221
 222         /* Mixer (in/out ports) */
 223         int     (*set_port)(void *, mixer_ctrl_t *);
 224         int     (*get_port)(void *, mixer_ctrl_t *);
 225
 226         int     (*query_devinfo)(void *, mixer_devinfo_t *);
 227
 228         /* Allocate/free memory for the ring buffer. Usually malloc/free. */
 229         void    *(*allocm)(void *, int, size_t, struct malloc_type *, int);
 230         void    (*freem)(void *, void *, struct malloc_type *);
 231         size_t  (*round_buffersize)(void *, int, size_t);
 232         paddr_t (*mappage)(void *, void *, off_t, int);
 233
 234         int     (*get_props)(void *); /* device properties */
 235
 236         int     (*trigger_output)(void *, void *, void *, int,
 237                     void (*)(void *), void *, const audio_params_t *);
 238         int     (*trigger_input)(void *, void *, void *, int,
 239                     void (*)(void *), void *, const audio_params_t *);
 240         int     (*dev_ioctl)(void *, u_long, void *, int, struct lwp *);
 241         int     (*powerstate)(void *, int);
 242 #define AUDIOPOWER_ON   1
 243 #define AUDIOPOWER_OFF  0
 244 };
 245
 246 struct audio_attach_args {
 247         int     type;
 248         const void *hwif;       /* either audio_hw_if * or midi_hw_if * */
 249         void    *hdl;
 250 };
 251 #define AUDIODEV_TYPE_AUDIO     0
 252 #define AUDIODEV_TYPE_MIDI      1
 253 #define AUDIODEV_TYPE_OPL       2
 254 #define AUDIODEV_TYPE_MPU       3
 255 #define AUDIODEV_TYPE_AUX       4
 256
 257 /* Attach the MI driver(s) to the MD driver. */
 258 device_t audio_attach_mi(const struct audio_hw_if *, void *, device_t);
 259 int     audioprint(void *, const char *);
 260
 261 /* Device identity flags */
 262 #define SOUND_DEVICE            0
 263 #define AUDIO_DEVICE            0x80
 264 #define AUDIOCTL_DEVICE         0xc0
 265 #define MIXER_DEVICE            0x10
 266
 267 #define AUDIOUNIT(x)            (minor(x)&0x0f)
 268 #define AUDIODEV(x)             (minor(x)&0xf0)
 269
 270 #define ISDEVSOUND(x)           (AUDIODEV((x)) == SOUND_DEVICE)
 271 #define ISDEVAUDIO(x)           (AUDIODEV((x)) == AUDIO_DEVICE)
 272 #define ISDEVAUDIOCTL(x)        (AUDIODEV((x)) == AUDIOCTL_DEVICE)
 273 #define ISDEVMIXER(x)           (AUDIODEV((x)) == MIXER_DEVICE)
 274
 275 /*
 276  * USB Audio specification defines 12 channels:
 277  *      L R C LFE Ls Rs Lc Rc S Sl Sr T
 278  */
 279 #define AUDIO_MAX_CHANNELS      12
 280
 281 #endif /* _SYS_DEV_AUDIO_IF_H_ */
 282