share/man/man4/ym.4

   1 .\" $NetBSD: ym.4,v 1.17 2006/08/14 09:50:18 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Lennart Augustsson.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd August 14, 2006
  31 .Dt YM 4
  32 .Os
  33 .Sh NAME
  34 .Nm ym
  35 .Nd Yamaha OPL3-SA2 and OPL3-SA3 audio device driver
  36 .Sh SYNOPSIS
  37 .Cd "ym*    at acpi?"
  38 .Cd "ym*    at isapnp?"
  39 .Cd "ym*    at pnpbios? index ?"
  40 .Cd "audio* at audiobus?"
  41 .Cd "mpu*   at ym?"
  42 .Cd "opl*   at ym?"
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 driver provides support for
  47 Yamaha YMF711 (OPL3-SA2) and YMF715x (OPL3-SA3) sound devices.
  48 .Pp
  49 The OPL3-SAx device has
  50 WSS compatible full-duplex 16bit CODEC,
  51 OPL3 FM synthesizer, and
  52 MPU401 compatible MIDI I/O port interface.
  53 Additionally, OPL3-SA3 has built-in
  54 .Sq 3D Enhanced
  55 equalizer.
  56 .Pp
  57 The joystick interface is handled by the
  58 .Xr joy 4
  59 driver.
  60 .Sh MIXER DEVICE
  61 The mixer device of
  62 .Nm
  63 driver can be accessed by
  64 .Xr mixerctl 1
  65 command.
  66 The layout is shown below.
  67 .Bd -literal
  68             dac ------------------------\*[Lt]-----  -----------------
  69 midi(OPL3/ZV)-\*[Gt]-+----------------------------+-\*[Gt]|inputs.midi    |
  70 cd      -\*[Gt]------+-*--------------------------+-\*[Gt]|inputs.cd      |
  71 line    -\*[Gt]----*-+-+--------------------------+-\*[Gt]|inputs.line    |
  72 speaker -\*[Gt]----+-+-+--------------------------+-\*[Gt]|inputs.speaker |
  73 mic     -\*[Gt]--*-+-+-+--------------------------+-\*[Gt]|inputs.mic     |
  74             v v v v      monitor.monitor     |  |               |
  75         ---------------  -------  |  ------- |  |               |
  76         |record.record|-\*[Gt]| A/D |----\*[Gt]| D/A |-*-\*[Gt]|inputs.dac     |analog
  77         |             |  |conv.|-- -\*[Gt]|conv.|    |               |output
  78         ---------------  ------- | | -------    | outputs.master|--\*[Gt]
  79                            wave  v | wave       | equalization.*|
  80                          recording playback     -----------------
  81 .Ed
  82 .Pp
  83 Note that the
  84 .Sq Dv inputs.dac
  85 is twice as sensitive as other
  86 .Sq Dv inputs
  87 volume variables.
  88 .Pp
  89 The hardware volume changes the
  90 .Sq Dv outputs.master
  91 value.
  92 .Pp
  93 If an external input source is unmuted by setting corresponding
  94 .Sq Dv inputs.*.mute
  95 variable to
  96 .Sq Dv off ,
  97 the device is never put in global power down or power save mode.
  98 This is because if the device is in global power down or power save mode,
  99 the output is automatically muted.
 100 .Pp
 101 All the external input sources (CD playback, line input, speaker, and MIC)
 102 are muted by default.
 103 .Pp
 104 The
 105 .Sq Dv equalization.*
 106 variables does not exists on OPL3-SA2.
 107 The
 108 .Sq equalization.treble
 109 and
 110 .Sq equalization.bass
 111 are enhancement only, and any values below the center position (128)
 112 don't take any effect.
 113 .Sh POWER MANAGEMENT
 114 The
 115 .Nm
 116 driver is capable of power management on the OPL3-SAx devices.
 117 The following modes can be selected by setting
 118 .Sq Dv power.save
 119 variable of
 120 .Xr mixerctl 1
 121 to
 122 .Sq Dv powerdown ,
 123 .Sq Dv powersave ,
 124 and
 125 .Sq Dv nosave
 126 respectively.
 127 .Pp
 128 .Bl -tag -width indent -compact
 129 .It Global power-down mode
 130 When a subpart of the device is unused, the part is power-down after
 131 a timeout period (specified by
 132 .Sq Dv power.save.timeout
 133 variable of
 134 .Xr mixerctl 1
 135 in seconds).
 136 When all the subparts of the device are unused,
 137 and all the external input sources are muted,
 138 the driver puts the device in
 139 .Sq Global Power Down
 140 mode.
 141 .Pp
 142 On the global power down mode, the power consumption is minimized
 143 (10\(*mA (SA3) or 200\(*mA (SA2) typ.),
 144 .\" Note: \(*m is Greek mu
 145 but the click noise on power up/down the device is rather loud.
 146 .Bf Em
 147 This mode should not be used with headphones or hi\-fi audio systems,
 148 or your ears or the systems may be damaged.
 149 .Ef
 150 .It Power save mode
 151 When a subpart of the device is unused, the part is powered-down after
 152 a timeout period (specified by
 153 .Sq Dv power.save.timeout
 154 variable of
 155 .Xr mixerctl 1
 156 in seconds).
 157 When all the subparts of the device are unused,
 158 and all the external input sources are muted,
 159 the driver put the device in
 160 .Sq Power Save
 161 mode.
 162 .Pp
 163 In power save mode, the power consumption is reduced (5mA typ.).
 164 The click noise on power up/down of the device is very small,
 165 but this operation requires muting/unmuting the device, which make some noise.
 166 In order to reduce the noise, setting the master volume at the small value
 167 is effective.
 168 .It "No power-save mode"
 169 Once the device is powered-up, it remains on after the use of the device.
 170 Once a subpart of the device is powered-up, it shall not be power-down.
 171 This mode minimizes click noises on power switching,
 172 but maximizes power consumption (30-100mA).
 173 .Pp
 174 On suspending, the device is put into power-save state.
 175 .El
 176 .Sh SEE ALSO
 177 .Xr mixerctl 1 ,
 178 .Xr apm 4 ,
 179 .Xr audio 4 ,
 180 .Xr isapnp 4 ,
 181 .Xr joy 4 ,
 182 .Xr midi 4 ,
 183 .Xr mpu 4 ,
 184 .Xr opl 4 ,
 185 .Xr pnpbios 4
 186 .Sh HISTORY
 187 The
 188 .Nm
 189 device driver appeared in
 190 .Nx 1.4 .
 191 .Sh BUGS
 192 Although the parameters of the device are saved and restored on
 193 .Xr apm 4
 194 suspend/resume, the DMA state is not restored.
 195 That is, if the system suspends during playback,
 196 this is not continued after suspend/resume cycle.
 197 .Pp
 198 The joystick port is not under power management.
 199 If a
 200 .Xr joy 4
 201 device is configured,
 202 the device will never be put in global power down or power save mode.
 203 .Pp
 204 The external devices, such as Zoomed Video port, OPL4-ML/2, modem, and CD-ROM
 205 are not supported.