1.\" $NetBSD: ym.4,v 1.20 2020/08/23 13:35:46 ryoon 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 23, 2020 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 44The 45.Nm 46driver provides support for 47Yamaha YMF711 (OPL3-SA2) and YMF715x (OPL3-SA3) sound devices. 48.Pp 49The OPL3-SAx device has 50WSS compatible full-duplex 16bit CODEC, 51OPL3 FM synthesizer, and 52MPU401 compatible MIDI I/O port interface. 53Additionally, OPL3-SA3 has built-in 54.Sq 3D Enhanced 55equalizer. 56.Pp 57The joystick interface is handled by the 58.Xr joy 4 59driver. 60.Sh MIXER DEVICE 61The mixer device of 62.Nm 63driver can be accessed by 64.Xr mixerctl 1 65command. 66The layout is shown below. 67.Bd -literal 68 dac ------------------------<----- ----------------- 69midi(OPL3/ZV)->-+----------------------------+->|inputs.midi | 70cd ->------+-*--------------------------+->|inputs.cd | 71line ->----*-+-+--------------------------+->|inputs.line | 72speaker ->----+-+-+--------------------------+->|inputs.speaker | 73mic ->--*-+-+-+--------------------------+->|inputs.mic | 74 v v v v monitor.monitor | | | 75 --------------- ------- | ------- | | | 76 |record.record|->| A/D |---->| D/A |-*->|inputs.dac |analog 77 | | |conv.|-- ->|conv.| | |output 78 --------------- ------- | | ------- | outputs.master|--> 79 wave v | wave | equalization.*| 80 recording playback ----------------- 81.Ed 82.Pp 83Note that the 84.Sq Dv inputs.dac 85is twice as sensitive as other 86.Sq Dv inputs 87volume variables. 88.Pp 89The hardware volume changes the 90.Sq Dv outputs.master 91value. 92.Pp 93If an external input source is unmuted by setting corresponding 94.Sq Dv inputs.*.mute 95variable to 96.Sq Dv off , 97the device is never put in global power down or power save mode. 98This is because if the device is in global power down or power save mode, 99the output is automatically muted. 100.Pp 101All the external input sources (CD playback, line input, speaker, and MIC) 102are muted by default. 103.Pp 104The 105.Sq Dv equalization.* 106variables does not exists on OPL3-SA2. 107The 108.Sq equalization.treble 109and 110.Sq equalization.bass 111are enhancement only, and any values below the center position (128) 112don't take any effect. 113.Sh POWER MANAGEMENT 114The 115.Nm 116driver is capable of power management on the OPL3-SAx devices. 117The following modes can be selected by setting 118.Sq Dv power.save 119variable of 120.Xr mixerctl 1 121to 122.Sq Dv powerdown , 123.Sq Dv powersave , 124and 125.Sq Dv nosave 126respectively. 127.Pp 128.Bl -tag -width indent -compact 129.It Global power-down mode 130When a subpart of the device is unused, the part is power-down after 131a timeout period (specified by 132.Sq Dv power.save.timeout 133variable of 134.Xr mixerctl 1 135in seconds). 136When all the subparts of the device are unused, 137and all the external input sources are muted, 138the driver puts the device in 139.Sq Global Power Down 140mode. 141.Pp 142On 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 145but the click noise on power up/down the device is rather loud. 146.Bf Em 147This mode should not be used with headphones or hi\-fi audio systems, 148or your ears or the systems may be damaged. 149.Ef 150.It Power save mode 151When a subpart of the device is unused, the part is powered-down after 152a timeout period (specified by 153.Sq Dv power.save.timeout 154variable of 155.Xr mixerctl 1 156in seconds). 157When all the subparts of the device are unused, 158and all the external input sources are muted, 159the driver put the device in 160.Sq Power Save 161mode. 162.Pp 163In power save mode, the power consumption is reduced (5mA typ.). 164The click noise on power up/down of the device is very small, 165but this operation requires muting/unmuting the device, which make some noise. 166In order to reduce the noise, setting the master volume at the small value 167is effective. 168.It "No power-save mode" 169Once the device is powered-up, it remains on after the use of the device. 170Once a subpart of the device is powered-up, it shall not be power-down. 171This mode minimizes click noises on power switching, 172but maximizes power consumption (30-100mA). 173.Pp 174On 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 i386/pnpbios 4 186.Sh HISTORY 187The 188.Nm 189device driver appeared in 190.Nx 1.4 . 191.Sh BUGS 192Although the parameters of the device are saved and restored on 193.Xr apm 4 194suspend/resume, the DMA state is not restored. 195That is, if the system suspends during playback, 196this is not continued after suspend/resume cycle. 197.Pp 198The joystick port is not under power management. 199If a 200.Xr joy 4 201device is configured, 202the device will never be put in global power down or power save mode. 203.Pp 204The external devices, such as Zoomed Video port, OPL4-ML/2, modem, and CD-ROM 205are not supported. 206