On Wed, 21 Oct 2015 08:53:27 +0200, han.lu@xxxxxxxxx wrote: > > From: "Lu, Han" <han.lu@xxxxxxxxx> > > Add more information about BAT utility, including design intent, > principles, use mode, hardware connection, options, example and > return value. > > Signed-off-by: Lu, Han <han.lu@xxxxxxxxx> Applied, thanks. Takashi > > diff --git a/bat/Makefile.am b/bat/Makefile.am > index 0849d0d..3a76d7f 100644 > --- a/bat/Makefile.am > +++ b/bat/Makefile.am > @@ -1,4 +1,7 @@ > bin_PROGRAMS = bat > +man_MANS = bat.1 > + > +EXTRA_DIST = bat.1 > > bat_SOURCES = \ > bat.c \ > diff --git a/bat/bat.1 b/bat/bat.1 > new file mode 100644 > index 0000000..e00fc27 > --- /dev/null > +++ b/bat/bat.1 > @@ -0,0 +1,158 @@ > +.TH BAT 1 "20th October 2015" > +.SH NAME > +bat \- command\-line sound tester for ALSA sound card driver > + > +.SH SYNOPSIS > +\fBbat\fP [\fIflags\fP] > + > +.SH DESCRIPTION > +\fBBAT(Basic Audio Tester)\fP is a simple command\-line utility intended > +to help automate audio driver and sound server testing with little human > +interaction. BAT can be used to test audio quality, stress test features > +and test audio before and after PM state changes. > + > +BAT's design is relatively simple. BAT plays an audio stream and captures > +the same stream in either a digital or analog loop back. It then compares > +the captured stream using a FFT to the original to determine if the test > +case passes or fails. > + > +BAT can either run wholly on the target machine being tested (standalone > +mode) or can run as a client/server mode where by bat client runs on the > +target and runs as a server on a separate tester machine. The client/server > +mode still requires some manual interaction for synchronization, but this > +is actively being developed for future releases. > + > +The hardware testing configuration may require the use of an analog cable > +connecting target to tester machines or a cable to create an analog > +loopback if no loopback mode is not available on the sound hardware that > +is being tested. > +An analog loopback cable can be used to connect the "line in" to "line out" > +jacks to create a loopback. If only headphone and mic jacks (or combo jack) > +are available then the following simple circuit can be used to create an > +analog loopback :- > + > +https://source.android.com/devices/audio/loopback.html > + > +.SH OPTIONS > +.TP > +\fI\-h, \-\-help\fP > +Help: show syntax. > +.TP > +\fI\-D\fP > +Select sound card to be tested by name. > +.TP > +\fI\-P\fP > +Select the playback PCM device. > +.TP > +\fI\-C\fP > +Select the capture PCM device. > +.TP > +\fI\-f\fP > +Sample format > +.br > +Recognized sample formats are: U8 S16_LE S24_3LE S32_LE > +.br > +Some of these may not be available on selected hardware > +.br > +The available format shortcuts are: > +.nf > +\-f cd (16 bit little endian, 44100, stereo) [\-f S16_LE \-c2 \-r44100] > +\-f dat (16 bit little endian, 48000, stereo) [\-f S16_LE \-c2 \-r48000] > +.fi > +If no format is given S16_LE is used. > +.TP > +\fI\-c\fP > +The number of channels. The default is one channel. > +Valid values at the moment are 1 or 2. > +.TP > +\fI\-r\fP > +Sampling rate in Hertz. The default rate is 44100 Hertz. > +Valid values depends on hardware support. > +.TP > +\fI\-n\fP > +Duration of generated signal. > +The value could be either of the two forms: > +.br > +1. Decimal integer, means number of frames; > +.br > +2. Floating point with suffix 's', means number of seconds. > +.br > +The default is 2 seconds. > +.TP > +\fI\-k\fP > +Sigma k value for analysis. > +.br > +The analysis function reads data from WAV file, run FFT against the data > +to get magnitude of frequency vectors, and then calculates the average > +value and standard deviation of frequency vectors. After that, we define > +a threshold: > +.br > +threshold = k * standard_deviation + mean_value > +.br > +Frequencies with amplitude larger than threshold will be recognized as a > +peak, and the frequency with largest peak value will be recognized as a > +detected frequency. > +.br > +BAT then compares the detected frequency to target frequency, to decide > +if the detecting passes or fails. > +.br > +The default value is 3.0. > +.TP > +\fI\-F\fP > +Target frequency for signal generation and analysis, in Hertz. > +The default is 997.0 Hertz. > +Valid range is (DC_THRESHOLD, 40% * Sampling rate). > +.TP > +\fI\-p\fP > +Total number of periods to play or capture. > +.TP > +\fI\-\-log=#\fP > +Write stderr and stdout output to this log file. > +.TP > +\fI\-\-file=#\fP > +Input WAV file for playback. > +.TP > +\fI\-\-saveplay=#\fP > +Target WAV file to save capture test content. > +.TP > +\fI\-\-local\fP > +Internal loopback mode. > +Playback, capture and analysis internal to BAT only. This is intended for > +developers to test new BAT features as no audio is routed outside of BAT. > + > +.SH EXAMPLES > + > +.TP > +\fBbat \-P plughw:0,0 \-C plughw:0,0 \-c 2 \-f S32_LE \-F 250\fR > +Generate and play a sine wave of 250 Hertz with 2 channel and S32_LE format, > +and then capture and analyze. > + > +.TP > +\fBbat \-P plughw:0,0 \-C plughw:0,0 \-\-file 500Hz.wav\fR > +Play the RIFF WAV file "500Hz.wav" which contains 500 Hertz waveform LPCM > +data, and then capture and analyze. > + > +.SH RETURN VALUE > +.br > +On success, returns 0. > +.br > +If no peak be detected, returns -1001; > +.br > +If only DC be detected, returns -1002; > +.br > +If peak frequency does not match with the target frequency, returns -1003. > + > +.SH SEE ALSO > +\fB > +aplay(1) > +\fP > + > +.SH BUGS > +Currently only support RIFF WAV format with PCM data. Please report any bugs to > +the alsa-devel mailing list. > + > +.SH AUTHOR > +\fBbat\fP is by Liam Girdwood <liam.r.girdwood@xxxxxxxxxxxxxxx>, Bernard Gautier > +<bernard.gautier@xxxxxxxxx> and Han Lu <han.lu@xxxxxxxxx>. > +This document is by Liam Girdwood <liam.r.girdwood@xxxxxxxxxxxxxxx> and Han Lu > +<han.lu@xxxxxxxxx>. > -- > 1.9.1 > _______________________________________________ Alsa-devel mailing list Alsa-devel@xxxxxxxxxxxxxxxx http://mailman.alsa-project.org/mailman/listinfo/alsa-devel
