[mirror_ubuntu-artful-kernel.git] / Documentation / sound / alsa / CMIPCI.txt

              Brief Notes on C-Media 8738/8338 Driver
              =======================================

                   Takashi Iwai <tiwai@suse.de>


Front/Rear Multi-channel Playback
---------------------------------

CM8x38 chip can use ADC as the second DAC so that two different stereo
channels can be used for front/rear playbacks.  Since there are two
DACs, both streams are handled independently unlike the 4/6ch multi-
channel playbacks in the section below.

As default, ALSA driver assigns the first PCM device (i.e. hw:0,0 for
card#0) for front and 4/6ch playbacks, while the second PCM device
(hw:0,1) is assigned to the second DAC for rear playback.

There are slight difference between two DACs.

- The first DAC supports U8 and S16LE formats, while the second DAC
  supports only S16LE.
- The seconde DAC supports only two channel stereo.

Please note that the CM8x38 DAC doesn't support continuous playback
rate but only fixed rates: 5512, 8000, 11025, 16000, 22050, 32000,
44100 and 48000 Hz.

The rear output can be heard only when "Four Channel Mode" switch is
disabled.  Otherwise no signal will be routed to the rear speakers.
As default it's turned on.

*** WARNING ***
When "Four Channel Mode" switch is off, the output from rear speakers
will be FULL VOLUME regardless of Master and PCM volumes.
This might damage your audio equipment.  Please disconnect speakers
before your turn off this switch.
*** WARNING ***

[ Well.. I once got the output with correct volume (i.e. same with the
  front one) and was so excited.  It was even with "Four Channel" bit
  on and "double DAC" mode.  Actually I could hear separate 4 channels
  from front and rear speakers!  But.. after reboot, all was gone.
  It's a very pity that I didn't save the register dump at that
  time..  Maybe there is an unknown register to achieve this... ]

If your card has an extra output jack for the rear output, the rear
playback should be routed there as default.  If not, there is a
control switch in the driver "Line-In As Rear", which you can change
via alsamixer or somewhat else.  When this switch is on, line-in jack
is used as rear output.

There are two more controls regarding to the rear output.
The "Exchange DAC" switch is used to exchange front and rear playback
routes, i.e. the 2nd DAC is output from front output.


4/6 Multi-Channel Playback
--------------------------

The recent CM8738 chips support for the 4/6 multi-channel playback
function.  This is useful especially for AC3 decoding.

When the multi-channel is supported, the driver name has a suffix
"-MC" such like "CMI8738-MC6".  You can check this name from
/proc/asound/cards.

When the 4/6-ch output is enabled, the second DAC accepts up to 6 (or
4) channels.  While the dual DAC supports two different rates or
formats, the 4/6-ch playback supports only the same condition for all
channels.  Since the multi-channel playback mode uses both DACs, you
cannot operate with full-duplex.

The 4.0 and 5.1 modes are defined as the pcm "surround40" and "surround51"
in alsa-lib.  For example, you can play a WAV file with 6 channels like

	% aplay -Dsurround51 sixchannels.wav

For programmin the 4/6 channel playback, you need to specify the PCM
channels as you like and set the format S16LE.  For example, for playback
with 4 channels,

	snd_pcm_hw_params_set_access(pcm, hw, SND_PCM_ACCESS_RW_INTERLEAVED);
	    // or mmap if you like
	snd_pcm_hw_params_set_format(pcm, hw, SND_PCM_FORMAT_S16_LE);
	snd_pcm_hw_params_set_channels(pcm, hw, 4);

and use the interleaved 4 channel data.

There are some control switchs affecting to the speaker connections:

"Line-In As Rear"	- As mentioned above, the line-in jack is used
	for the rear (3th and 4th channels) output.
"Line-In As Bass"	- The line-in jack is used for the bass (5th
	and 6th channels) output.
"Mic As Center/LFE"	- The mic jack is used for the bass output.
	If this switch is on, you cannot use a microphone as a capture
	source, of course.


Digital I/O
-----------

The CM8x38 provides the excellent SPDIF capability with very chip
price (yes, that's the reason I bought the card :)

The SPDIF playback and capture are done via the third PCM device
(hw:0,2).  Usually this is assigned to the PCM device "spdif".
The available rates are 44100 and 48000 Hz.
For playback with aplay, you can run like below:

	% aplay -Dhw:0,2 foo.wav

or

	% aplay -Dspdif foo.wav

24bit format is also supported experimentally.

The playback and capture over SPDIF use normal DAC and ADC,
respectively, so you cannot playback both analog and digital streams
simultaneously.

To enable SPDIF output, you need to turn on "IEC958 Output Switch"
control via mixer or alsactl.  Then you'll see the red light on from
the card so you know that's working obviously :)
The SPDIF input is always enabled, so you can hear SPDIF input data
from line-out with "IEC958 In Monitor" switch at any time (see
below).

You can play via SPDIF even with the first device (hw:0,0),
but SPDIF is enabled only when the proper format (S16LE), sample rate
(441100 or 48000) and channels (2) are used.  Otherwise it's turned
off.  (Also don't forget to turn on "IEC958 Output Switch", too.)


Additionally there are relevant control switches:

"IEC958 Mix Analog" - Mix analog PCM playback and FM-OPL/3 streams and
	output through SPDIF.  This switch appears only on old chip
	models (CM8738 033 and 037).
	Note: without this control you can output PCM to SPDIF.
	This is "mixing" of streams, so e.g. it's not for AC3 output
	(see the next section).

"IEC958 In Select"  - Select SPDIF input, the internal CD-in (false)
	and the external input (true).

"IEC958 Loop"       - SPDIF input data is loop back into SPDIF
	output (aka bypass)

"IEC958 Copyright"  - Set the copyright bit.

"IEC958 5V"         - Select 0.5V (coax) or 5V (optical) interface.
	On some cards this doesn't work and you need to change the
	configuration with hardware dip-switch.

"IEC958 In Monitor" - SPDIF input is routed to DAC.

"IEC958 In Phase Inverse" - Set SPDIF input format as inverse.
	[FIXME: this doesn't work on all chips..]

"IEC958 In Valid"   - Set input validity flag detection.

Note: When "PCM Playback Switch" is on, you'll hear the digital output
stream through analog line-out.


The AC3 (RAW DIGITAL) OUTPUT
----------------------------

The driver supports raw digital (typically AC3) i/o over SPDIF.  This
can be toggled via IEC958 playback control, but usually you need to
access it via alsa-lib.  See alsa-lib documents for more details.

On the raw digital mode, the "PCM Playback Switch" is automatically
turned off so that non-audio data is heard from the analog line-out.
Similarly the following switches are off: "IEC958 Mix Analog" and
"IEC958 Loop".  The switches are resumed after closing the SPDIF PCM
device automatically to the previous state.

On the model 033, AC3 is implemented by the software conversion in
the alsa-lib.  If you need to bypass the software conversion of IEC958
subframes, pass the "soft_ac3=0" module option.  This doesn't matter
on the newer models.


ANALOG MIXER INTERFACE
----------------------

The mixer interface on CM8x38 is similar to SB16.
There are Master, PCM, Synth, CD, Line, Mic and PC Speaker playback
volumes.  Synth, CD, Line and Mic have playback and capture switches,
too, as well as SB16.

In addition to the standard SB mixer, CM8x38 provides more functions.
- PCM playback switch
- PCM capture switch (to capture the data sent to DAC)
- Mic Boost switch
- Mic capture volume
- Aux playback volume/switch and capture switch
- 3D control switch


MIDI CONTROLLER
---------------

The MPU401-UART interface is enabled as default only for the first
(CMIPCI) card.  You need to set module option "midi_port" properly
for the 2nd (CMIPCI) card.

There is _no_ hardware wavetable function on this chip (except for
OPL3 synth below).
What's said as MIDI synth on Windows is a software synthesizer
emulation.  On Linux use TiMidity or other softsynth program for
playing MIDI music.


FM OPL/3 Synth
--------------

The FM OPL/3 is also enabled as default only for the first card.
Set "fm_port" module option for more cards.

The output quality of FM OPL/3 is, however, very weird.
I don't know why..


Joystick and Modem
------------------

The joystick and modem should be available by enabling the control
switch "Joystick" and "Modem" respectively.  But I myself have never
tested them yet.


Debugging Information
---------------------

The registers are shown in /proc/asound/cardX/cmipci.  If you have any
problem (especially unexpected behavior of mixer), please attach the
output of this proc file together with the bug report.
Commit	Line	Data
1da177e4 LT	1	Brief Notes on C-Media 8738/8338 Driver
	2	=======================================
	3
	4	Takashi Iwai <tiwai@suse.de>
	5
	6
	7	Front/Rear Multi-channel Playback
	8	---------------------------------
	9
	10	CM8x38 chip can use ADC as the second DAC so that two different stereo
	11	channels can be used for front/rear playbacks. Since there are two
	12	DACs, both streams are handled independently unlike the 4/6ch multi-
	13	channel playbacks in the section below.
	14
	15	As default, ALSA driver assigns the first PCM device (i.e. hw:0,0 for
	16	card#0) for front and 4/6ch playbacks, while the second PCM device
	17	(hw:0,1) is assigned to the second DAC for rear playback.
	18
	19	There are slight difference between two DACs.
	20
	21	- The first DAC supports U8 and S16LE formats, while the second DAC
	22	supports only S16LE.
	23	- The seconde DAC supports only two channel stereo.
	24
	25	Please note that the CM8x38 DAC doesn't support continuous playback
	26	rate but only fixed rates: 5512, 8000, 11025, 16000, 22050, 32000,
	27	44100 and 48000 Hz.
	28
	29	The rear output can be heard only when "Four Channel Mode" switch is
	30	disabled. Otherwise no signal will be routed to the rear speakers.
	31	As default it's turned on.
	32
	33	* WARNING *
	34	When "Four Channel Mode" switch is off, the output from rear speakers
	35	will be FULL VOLUME regardless of Master and PCM volumes.
	36	This might damage your audio equipment. Please disconnect speakers
	37	before your turn off this switch.
	38	* WARNING *
	39
	40	[ Well.. I once got the output with correct volume (i.e. same with the
	41	front one) and was so excited. It was even with "Four Channel" bit
	42	on and "double DAC" mode. Actually I could hear separate 4 channels
	43	from front and rear speakers! But.. after reboot, all was gone.
	44	It's a very pity that I didn't save the register dump at that
	45	time.. Maybe there is an unknown register to achieve this... ]
	46
	47	If your card has an extra output jack for the rear output, the rear
	48	playback should be routed there as default. If not, there is a
	49	control switch in the driver "Line-In As Rear", which you can change
	50	via alsamixer or somewhat else. When this switch is on, line-in jack
	51	is used as rear output.
	52
	53	There are two more controls regarding to the rear output.
	54	The "Exchange DAC" switch is used to exchange front and rear playback
	55	routes, i.e. the 2nd DAC is output from front output.
	56
	57
	58	4/6 Multi-Channel Playback
	59	--------------------------
	60
	61	The recent CM8738 chips support for the 4/6 multi-channel playback
	62	function. This is useful especially for AC3 decoding.
	63
	64	When the multi-channel is supported, the driver name has a suffix
65	"-MC" such like "CMI8738-MC6". You can check this name from
66	/proc/asound/cards.
67
68	When the 4/6-ch output is enabled, the second DAC accepts up to 6 (or
69	4) channels. While the dual DAC supports two different rates or
70	formats, the 4/6-ch playback supports only the same condition for all
71	channels. Since the multi-channel playback mode uses both DACs, you
72	cannot operate with full-duplex.
73
74	The 4.0 and 5.1 modes are defined as the pcm "surround40" and "surround51"
75	in alsa-lib. For example, you can play a WAV file with 6 channels like
76
77	% aplay -Dsurround51 sixchannels.wav
78
79	For programmin the 4/6 channel playback, you need to specify the PCM
80	channels as you like and set the format S16LE. For example, for playback
81	with 4 channels,
82
83	snd_pcm_hw_params_set_access(pcm, hw, SND_PCM_ACCESS_RW_INTERLEAVED);
84	// or mmap if you like
85	snd_pcm_hw_params_set_format(pcm, hw, SND_PCM_FORMAT_S16_LE);
86	snd_pcm_hw_params_set_channels(pcm, hw, 4);
87
88	and use the interleaved 4 channel data.
89
90	There are some control switchs affecting to the speaker connections:
91
92	"Line-In As Rear" - As mentioned above, the line-in jack is used
93	for the rear (3th and 4th channels) output.
94	"Line-In As Bass" - The line-in jack is used for the bass (5th
95	and 6th channels) output.
96	"Mic As Center/LFE" - The mic jack is used for the bass output.
97	If this switch is on, you cannot use a microphone as a capture
98	source, of course.
99
100
101	Digital I/O
102	-----------
103
104	The CM8x38 provides the excellent SPDIF capability with very chip
105	price (yes, that's the reason I bought the card :)
106
107	The SPDIF playback and capture are done via the third PCM device
108	(hw:0,2). Usually this is assigned to the PCM device "spdif".
109	The available rates are 44100 and 48000 Hz.
110	For playback with aplay, you can run like below:
111
112	% aplay -Dhw:0,2 foo.wav
113
114	or
115
116	% aplay -Dspdif foo.wav
117
118	24bit format is also supported experimentally.
119
120	The playback and capture over SPDIF use normal DAC and ADC,
121	respectively, so you cannot playback both analog and digital streams
122	simultaneously.
123
124	To enable SPDIF output, you need to turn on "IEC958 Output Switch"
125	control via mixer or alsactl. Then you'll see the red light on from
126	the card so you know that's working obviously :)
127	The SPDIF input is always enabled, so you can hear SPDIF input data
128	from line-out with "IEC958 In Monitor" switch at any time (see
129	below).
130
131	You can play via SPDIF even with the first device (hw:0,0),
132	but SPDIF is enabled only when the proper format (S16LE), sample rate
133	(441100 or 48000) and channels (2) are used. Otherwise it's turned
134	off. (Also don't forget to turn on "IEC958 Output Switch", too.)
135
136
137	Additionally there are relevant control switches:
138
139	"IEC958 Mix Analog" - Mix analog PCM playback and FM-OPL/3 streams and
140	output through SPDIF. This switch appears only on old chip
141	models (CM8738 033 and 037).
142	Note: without this control you can output PCM to SPDIF.
143	This is "mixing" of streams, so e.g. it's not for AC3 output
144	(see the next section).
145
146	"IEC958 In Select" - Select SPDIF input, the internal CD-in (false)
147	and the external input (true).
148
149	"IEC958 Loop" - SPDIF input data is loop back into SPDIF
150	output (aka bypass)
151
152	"IEC958 Copyright" - Set the copyright bit.
153
154	"IEC958 5V" - Select 0.5V (coax) or 5V (optical) interface.
155	On some cards this doesn't work and you need to change the
156	configuration with hardware dip-switch.
157
158	"IEC958 In Monitor" - SPDIF input is routed to DAC.
159
160	"IEC958 In Phase Inverse" - Set SPDIF input format as inverse.
161	[FIXME: this doesn't work on all chips..]
162
163	"IEC958 In Valid" - Set input validity flag detection.
164
165	Note: When "PCM Playback Switch" is on, you'll hear the digital output
166	stream through analog line-out.
167
168
169	The AC3 (RAW DIGITAL) OUTPUT
170	----------------------------
171
172	The driver supports raw digital (typically AC3) i/o over SPDIF. This
173	can be toggled via IEC958 playback control, but usually you need to
174	access it via alsa-lib. See alsa-lib documents for more details.
175
176	On the raw digital mode, the "PCM Playback Switch" is automatically
177	turned off so that non-audio data is heard from the analog line-out.
178	Similarly the following switches are off: "IEC958 Mix Analog" and
179	"IEC958 Loop". The switches are resumed after closing the SPDIF PCM
180	device automatically to the previous state.
181
182	On the model 033, AC3 is implemented by the software conversion in
183	the alsa-lib. If you need to bypass the software conversion of IEC958
184	subframes, pass the "soft_ac3=0" module option. This doesn't matter
185	on the newer models.
186
187
188	ANALOG MIXER INTERFACE
189	----------------------
190
191	The mixer interface on CM8x38 is similar to SB16.
192	There are Master, PCM, Synth, CD, Line, Mic and PC Speaker playback
193	volumes. Synth, CD, Line and Mic have playback and capture switches,
194	too, as well as SB16.
195
196	In addition to the standard SB mixer, CM8x38 provides more functions.
197	- PCM playback switch
198	- PCM capture switch (to capture the data sent to DAC)
199	- Mic Boost switch
200	- Mic capture volume
201	- Aux playback volume/switch and capture switch
202	- 3D control switch
203
204
205	MIDI CONTROLLER
206	---------------
207
208	The MPU401-UART interface is enabled as default only for the first
209	(CMIPCI) card. You need to set module option "midi_port" properly
210	for the 2nd (CMIPCI) card.
211
212	There is _no_ hardware wavetable function on this chip (except for
213	OPL3 synth below).
214	What's said as MIDI synth on Windows is a software synthesizer
215	emulation. On Linux use TiMidity or other softsynth program for
216	playing MIDI music.
217
218
219	FM OPL/3 Synth
220	--------------
221
222	The FM OPL/3 is also enabled as default only for the first card.
223	Set "fm_port" module option for more cards.
224
225	The output quality of FM OPL/3 is, however, very weird.
226	I don't know why..
227
228
229	Joystick and Modem
230	------------------
231
232	The joystick and modem should be available by enabling the control
233	switch "Joystick" and "Modem" respectively. But I myself have never
234	tested them yet.
235
236
237	Debugging Information
238	---------------------
239
240	The registers are shown in /proc/asound/cardX/cmipci. If you have any
241	problem (especially unexpected behavior of mixer), please attach the
242	output of this proc file together with the bug report.