summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMisael Lopez Cruz2013-11-11 04:39:58 -0600
committerMisael Lopez Cruz2013-11-11 18:09:54 -0600
commit861c79838ff3b85ac4ab700d9e1728d458327429 (patch)
treedd54f270ad572a207bd15460a86ea30e8e0e97be
parent2c752c915aa52925cec575b26f8b221eb524c0ce (diff)
downloaddevice-ti-common-open-861c79838ff3b85ac4ab700d9e1728d458327429.tar.gz
device-ti-common-open-861c79838ff3b85ac4ab700d9e1728d458327429.tar.xz
device-ti-common-open-861c79838ff3b85ac4ab700d9e1728d458327429.zip
audio: utils: Add library documentation
Add more documentation to the tiaudioutils library, more specifically to the doxygen's main page and missing documentation in Log.h file. Doxygen 1.8 or later and Dot is required to properly build the documentation since it relies on Doxygen's Markdown. Change-Id: I395fed314aeaad8ded0233ab3a94771b7bb34888 Signed-off-by: Misael Lopez Cruz <misael.lopez@ti.com>
-rw-r--r--audio/utils/doc/Doxyfile91
-rw-r--r--audio/utils/doc/mainpage.dox36
-rw-r--r--audio/utils/doc/pcm.dox143
-rw-r--r--audio/utils/doc/stream.dox288
-rw-r--r--audio/utils/include/tiaudioutils/Log.h13
5 files changed, 531 insertions, 40 deletions
diff --git a/audio/utils/doc/Doxyfile b/audio/utils/doc/Doxyfile
index 78568d6..ae0a911 100644
--- a/audio/utils/doc/Doxyfile
+++ b/audio/utils/doc/Doxyfile
@@ -1,4 +1,4 @@
1# Doxyfile 1.7.6.1 1# Doxyfile 1.8.1.2
2 2
3# This file describes the settings to be used by the documentation system 3# This file describes the settings to be used by the documentation system
4# doxygen (www.doxygen.org) for a project. 4# doxygen (www.doxygen.org) for a project.
@@ -240,6 +240,15 @@ OPTIMIZE_OUTPUT_VHDL = NO
240 240
241EXTENSION_MAPPING = 241EXTENSION_MAPPING =
242 242
243# If MARKDOWN_SUPPORT is enabled (the default) then doxygen pre-processes all
244# comments according to the Markdown format, which allows for more readable
245# documentation. See http://daringfireball.net/projects/markdown/ for details.
246# The output of markdown processing is further processed by doxygen, so you
247# can mix doxygen, HTML, and XML commands with Markdown formatting.
248# Disable only in case of backward compatibilities issues.
249
250MARKDOWN_SUPPORT = YES
251
243# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want 252# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
244# to include (a tag file for) the STL sources as input, then you should 253# to include (a tag file for) the STL sources as input, then you should
245# set this tag to YES in order to let doxygen match functions declarations and 254# set this tag to YES in order to let doxygen match functions declarations and
@@ -353,6 +362,10 @@ EXTRACT_ALL = NO
353 362
354EXTRACT_PRIVATE = NO 363EXTRACT_PRIVATE = NO
355 364
365# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal scope will be included in the documentation.
366
367EXTRACT_PACKAGE = NO
368
356# If the EXTRACT_STATIC tag is set to YES all static members of a file 369# If the EXTRACT_STATIC tag is set to YES all static members of a file
357# will be included in the documentation. 370# will be included in the documentation.
358 371
@@ -540,12 +553,6 @@ MAX_INITIALIZER_LINES = 30
540 553
541SHOW_USED_FILES = YES 554SHOW_USED_FILES = YES
542 555
543# If the sources in your project are distributed over multiple directories
544# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy
545# in the documentation. The default is NO.
546
547SHOW_DIRECTORIES = NO
548
549# Set the SHOW_FILES tag to NO to disable the generation of the Files page. 556# Set the SHOW_FILES tag to NO to disable the generation of the Files page.
550# This will remove the Files entry from the Quick Index and from the 557# This will remove the Files entry from the Quick Index and from the
551# Folder Tree View (if specified). The default is YES. 558# Folder Tree View (if specified). The default is YES.
@@ -571,7 +578,7 @@ FILE_VERSION_FILTER =
571 578
572# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed 579# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed
573# by doxygen. The layout file controls the global structure of the generated 580# by doxygen. The layout file controls the global structure of the generated
574# output files in an output format independent way. The create the layout file 581# output files in an output format independent way. To create the layout file
575# that represents doxygen's defaults, run doxygen with the -l option. 582# that represents doxygen's defaults, run doxygen with the -l option.
576# You can optionally specify a file name after the option, if omitted 583# You can optionally specify a file name after the option, if omitted
577# DoxygenLayout.xml will be used as the name of the layout file. 584# DoxygenLayout.xml will be used as the name of the layout file.
@@ -784,7 +791,7 @@ INLINE_SOURCES = NO
784 791
785# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct 792# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
786# doxygen to hide any special comment blocks from generated source code 793# doxygen to hide any special comment blocks from generated source code
787# fragments. Normal C and C++ comments will always remain visible. 794# fragments. Normal C, C++ and Fortran comments will always remain visible.
788 795
789STRIP_CODE_COMMENTS = YES 796STRIP_CODE_COMMENTS = YES
790 797
@@ -934,20 +941,23 @@ HTML_COLORSTYLE_GAMMA = 80
934 941
935HTML_TIMESTAMP = YES 942HTML_TIMESTAMP = YES
936 943
937# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes,
938# files or namespaces will be aligned in HTML using tables. If set to
939# NO a bullet list will be used.
940
941HTML_ALIGN_MEMBERS = YES
942
943# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML 944# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML
944# documentation will contain sections that can be hidden and shown after the 945# documentation will contain sections that can be hidden and shown after the
945# page has loaded. For this to work a browser that supports 946# page has loaded.
946# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox
947# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari).
948 947
949HTML_DYNAMIC_SECTIONS = NO 948HTML_DYNAMIC_SECTIONS = NO
950 949
950# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of
951# entries shown in the various tree structured indices initially; the user
952# can expand and collapse entries dynamically later on. Doxygen will expand
953# the tree to such a level that at most the specified number of entries are
954# visible (unless a fully collapsed tree already exceeds this amount).
955# So setting the number of entries 1 will produce a full collapsed tree by
956# default. 0 is a special value representing an infinite number of entries
957# and will result in a full expanded tree by default.
958
959HTML_INDEX_NUM_ENTRIES = 100
960
951# If the GENERATE_DOCSET tag is set to YES, additional index files 961# If the GENERATE_DOCSET tag is set to YES, additional index files
952# will be generated that can be used as input for Apple's Xcode 3 962# will be generated that can be used as input for Apple's Xcode 3
953# integrated development environment, introduced with OSX 10.5 (Leopard). 963# integrated development environment, introduced with OSX 10.5 (Leopard).
@@ -1126,11 +1136,6 @@ GENERATE_TREEVIEW = NO
1126 1136
1127ENUM_VALUES_PER_LINE = 4 1137ENUM_VALUES_PER_LINE = 4
1128 1138
1129# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories,
1130# and Class Hierarchy pages using a tree view instead of an ordered list.
1131
1132USE_INLINE_TREES = NO
1133
1134# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be 1139# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
1135# used to set the initial width (in pixels) of the frame in which the tree 1140# used to set the initial width (in pixels) of the frame in which the tree
1136# is shown. 1141# is shown.
@@ -1162,7 +1167,7 @@ FORMULA_TRANSPARENT = YES
1162# (see http://www.mathjax.org) which uses client side Javascript for the 1167# (see http://www.mathjax.org) which uses client side Javascript for the
1163# rendering instead of using prerendered bitmaps. Use this if you do not 1168# rendering instead of using prerendered bitmaps. Use this if you do not
1164# have LaTeX installed or if you want to formulas look prettier in the HTML 1169# have LaTeX installed or if you want to formulas look prettier in the HTML
1165# output. When enabled you also need to install MathJax separately and 1170# output. When enabled you may also need to install MathJax separately and
1166# configure the path to it using the MATHJAX_RELPATH option. 1171# configure the path to it using the MATHJAX_RELPATH option.
1167 1172
1168USE_MATHJAX = NO 1173USE_MATHJAX = NO
@@ -1171,10 +1176,11 @@ USE_MATHJAX = NO
1171# HTML output directory using the MATHJAX_RELPATH option. The destination 1176# HTML output directory using the MATHJAX_RELPATH option. The destination
1172# directory should contain the MathJax.js script. For instance, if the mathjax 1177# directory should contain the MathJax.js script. For instance, if the mathjax
1173# directory is located at the same level as the HTML output directory, then 1178# directory is located at the same level as the HTML output directory, then
1174# MATHJAX_RELPATH should be ../mathjax. The default value points to the 1179# MATHJAX_RELPATH should be ../mathjax. The default value points to
1175# mathjax.org site, so you can quickly see the result without installing 1180# the MathJax Content Delivery Network so you can quickly see the result without
1176# MathJax, but it is strongly recommended to install a local copy of MathJax 1181# installing MathJax.
1177# before deployment. 1182# However, it is strongly recommended to install a local
1183# copy of MathJax from http://www.mathjax.org before deployment.
1178 1184
1179MATHJAX_RELPATH = http://www.mathjax.org/mathjax 1185MATHJAX_RELPATH = http://www.mathjax.org/mathjax
1180 1186
@@ -1524,22 +1530,18 @@ SKIP_FUNCTION_MACROS = YES
1524# Configuration::additions related to external references 1530# Configuration::additions related to external references
1525#--------------------------------------------------------------------------- 1531#---------------------------------------------------------------------------
1526 1532
1527# The TAGFILES option can be used to specify one or more tagfiles. 1533# The TAGFILES option can be used to specify one or more tagfiles. For each
1528# Optionally an initial location of the external documentation 1534# tag file the location of the external documentation should be added. The
1529# can be added for each tagfile. The format of a tag file without 1535# format of a tag file without this location is as follows:
1530# this location is as follows:
1531# 1536#
1532# TAGFILES = file1 file2 ... 1537# TAGFILES = file1 file2 ...
1533# Adding location for the tag files is done as follows: 1538# Adding location for the tag files is done as follows:
1534# 1539#
1535# TAGFILES = file1=loc1 "file2 = loc2" ... 1540# TAGFILES = file1=loc1 "file2 = loc2" ...
1536# where "loc1" and "loc2" can be relative or absolute paths or 1541# where "loc1" and "loc2" can be relative or absolute paths
1537# URLs. If a location is present for each tag, the installdox tool 1542# or URLs. Note that each tag file must have a unique name (where the name does
1538# does not have to be run to correct the links. 1543# NOT include the path). If a tag file is not located in the directory in which
1539# Note that each tag file must have a unique name 1544# doxygen is run, you must also specify the path to the tagfile here.
1540# (where the name does NOT include the path)
1541# If a tag file is not located in the directory in which doxygen
1542# is run, you must also specify the path to the tagfile here.
1543 1545
1544TAGFILES = 1546TAGFILES =
1545 1547
@@ -1652,6 +1654,15 @@ GROUP_GRAPHS = YES
1652 1654
1653UML_LOOK = NO 1655UML_LOOK = NO
1654 1656
1657# If the UML_LOOK tag is enabled, the fields and methods are shown inside
1658# the class node. If there are many fields or methods and many nodes the
1659# graph may become too big to be useful. The UML_LIMIT_NUM_FIELDS
1660# threshold limits the number of items for each type to make the size more
1661# managable. Set this to 0 for no limit. Note that the threshold may be
1662# exceeded by 50% before the limit is enforced.
1663
1664UML_LIMIT_NUM_FIELDS = 10
1665
1655# If set to YES, the inheritance and collaboration graphs will show the 1666# If set to YES, the inheritance and collaboration graphs will show the
1656# relations between templates and their instances. 1667# relations between templates and their instances.
1657 1668
@@ -1692,7 +1703,7 @@ CALLER_GRAPH = NO
1692 1703
1693GRAPHICAL_HIERARCHY = YES 1704GRAPHICAL_HIERARCHY = YES
1694 1705
1695# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES 1706# If the DIRECTORY_GRAPH and HAVE_DOT tags are set to YES
1696# then doxygen will show the dependencies a directory has on other directories 1707# then doxygen will show the dependencies a directory has on other directories
1697# in a graphical way. The dependency relations are determined by the #include 1708# in a graphical way. The dependency relations are determined by the #include
1698# relations between the files in the directories. 1709# relations between the files in the directories.
diff --git a/audio/utils/doc/mainpage.dox b/audio/utils/doc/mainpage.dox
new file mode 100644
index 0000000..77c83d7
--- /dev/null
+++ b/audio/utils/doc/mainpage.dox
@@ -0,0 +1,36 @@
1/**
2
3\mainpage
4
5# Introduction # {#Intro}
6
7The *tiaudioutils* library is meant to help implementing the Audio HAL modules
8required in Android, more specifically for Audio HALs used in the multizone
9audio context.
10
11The multizone audio solution is composed of three listening zones: *Cabin*,
12*Back-Seat 1* and *Back-Seat 2*. The listening zones can render different
13audio content simultaneously, which has new challenges that are not present in
14single output systems, like how the zone streams are rendered to the hardware,
15either using a single or multiple PCM ports:
16
17- Dedicated PCM ports for each listening zone. Each PCM port is mapped to the
18 Android audio output device for the listening zone.
19- Single PCM port that contains all listening zones. The PCM stream is produced
20 by merging the channels of each individual listening zone to preassigned slots.
21
22The audio capture case is slightly different since it's not divided in zones.
23However, similar requirements might exist, where the audio data for a given
24stream may be embedded into specific slots of an input audio stream.
25
26The *tiaudioutils* library implements both mechanisms described above for audio
27playback and capture, and provides a set of APIs for the Audio HAL to use which
28helps reducing the complexity and lines of code.
29
30The *tiaudioutils* library can be broadly divided into:
31
32\subpage pcmdoc
33
34\subpage streamdoc
35
36*/ \ No newline at end of file
diff --git a/audio/utils/doc/pcm.dox b/audio/utils/doc/pcm.dox
new file mode 100644
index 0000000..98cb6e0
--- /dev/null
+++ b/audio/utils/doc/pcm.dox
@@ -0,0 +1,143 @@
1/**
2
3\page pcmdoc PCM ports: the data interface
4
5[ThreadBase]: \ref tiaudioutils::ThreadBase "ThreadBase"
6[SlotMap]: \ref tiaudioutils::SlotMap "SlotMap"
7[BufferAdaptor]: \ref tiaudioutils::BufferAdaptor "BufferAdaptor"
8[BufferProvider]: \ref tiaudioutils::BufferProvider "BufferProvider"
9[Buffer]: \ref tiaudioutils::BufferProvider::Buffer "Buffer"
10[Resampler]: \ref tiaudioutils::Resampler "Resampler"
11[PcmParams]: \ref tiaudioutils::PcmParams "PcmParams"
12[PcmPort]: \ref tiaudioutils::PcmPort "PcmPort"
13[PcmInPort]: \ref tiaudioutils::PcmInPort "PcmInPort"
14[PcmOutPort]: \ref tiaudioutils::PcmOutPort "PcmOutPort"
15[NullInPort]: \ref tiaudioutils::NullInPort "NullInPort"
16[NullOutPort]: \ref tiaudioutils::NullOutPort "NullOutPort"
17[ALSAInPort]: \ref tiaudioutils::ALSAInPort "ALSAInPort"
18[ALSAOutPort]: \ref tiaudioutils::ALSAOutPort "ALSAOutPort"
19[ALSAControl]: \ref tiaudioutils::ALSAControl "ALSAControl"
20[ALSAMixer]: \ref tiaudioutils::ALSAMixer "ALSAMixer"
21[SimpleInStream]: \ref tiaudioutils::SimpleInStream "SimpleInStream"
22[SimpleOutStream]: \ref tiaudioutils::SimpleOutStream "SimpleOutStream"
23[SimpleReader]: \ref tiaudioutils::SimpleReader "SimpleReader"
24[ReaderProvider]: \ref tiaudioutils::SimpleReader::ReaderProvider "ReaderProvider"
25[SimpleWriter]: \ref tiaudioutils::SimpleWriter "SimpleWriter"
26[InStream]: \ref tiaudioutils::InStream "InStream"
27[AdaptedInStream]: \ref tiaudioutils::AdaptedInStream "AdaptedInStream"
28[BufferedInStream]: \ref tiaudioutils::BufferedInStream "BufferedInStream"
29[OutStream]: \ref tiaudioutils::OutStream "OutStream"
30[AdaptedOutStream]: \ref tiaudioutils::AdaptedOutStream "AdaptedOutStream"
31[BufferedOutStream]: \ref tiaudioutils::BufferedOutStream "BufferedOutStream"
32[PcmReader]: \ref tiaudioutils::PcmReader "PcmReader"
33[PcmWriter]: \ref tiaudioutils::PcmWriter "PcmWriter"
34[Merge]: \ref tiaudioutils::Merge "Merge"
35[UnMerge]: \ref tiaudioutils::UnMerge "UnMerge"
36[MonoPipe]: \ref tiaudioutils::MonoPipe "MonoPipe"
37[PipeReader]: \ref tiaudioutils::PipeReader "PipeReader"
38[PipeWriter]: \ref tiaudioutils::PipeWriter "PipeWriter"
39
40[ALSA]: http://www.alsa-project.org/main/index.php/Main_Page "ALSA"
41[tinyalsa]: https://github.com/tinyalsa/tinyalsa "tinyalsa"
42
43# Data and Mixer Interfaces # {#PcmAndMixer}
44
45## PCM interface ## {#PCMInterface}
46
47The PCM audio interface consists of the audio ports that are used to capture
48data from an audio input device or play back data to an output device. The
49[PcmPort], [PcmInPort] and [PcmOutPort] classes represent the abstraction of the
50PCM interface in the library.
51
52The PCM ports transfer data in buffers that contain multiple audio frames.
53An audio frame contains one or more samples that correspond to the channels
54in the stream. The terms *sample* and *channel* are used interchangeably
55throughout the library.
56
57The configuration of a PCM port is done with the [PcmParams] class through the
58following parameters:
59
60- Channels. The number of channels or samples in an audio frame.
61- Bits per sample. The number of bits in an audio sample. The format per se is
62 not specified (e.g. little-endian, big-endian) but is assumed to be aligned
63 between the reader or writer and the PCM port implementation.
64- Sampling rate. The number of audio frames in a second.
65- Buffer size. The number of frames in an audio buffer.
66
67The basic operations on the PCM ports include:
68[open](\ref tiaudioutils::PcmPort::open),
69[read](\ref tiaudioutils::PcmInPort::read) or
70[write](\ref tiaudioutils::PcmOutPort::write), and
71[close](\ref tiaudioutils::PcmPort::close).
72
73## Null PCM ## {#NullPCM}
74
75The null PCM classes ([NullInPort] and [NullOutPort]) are dummy PCM ports that
76produce silence (capture) or consume the data (playback) at the same pace that
77an actual hardware port does for a given configuration. They can be useful when
78hardware ports are not available but data needs to be produced/consumed to
79satisfy the requirements of upper layers.
80
81## ALSA PCM interface ## {#ALSAPcm}
82
83The [Advance Linux Sound Architecture][ALSA] (ALSA) provides audio functionality
84to the Linux operating system. Android uses [tinyalsa] to interface with ALSA in
85the Linux kernel.
86
87The ALSA PCM interface in this library uses tinyalsa to implement the interface
88described in the [PCM interface](#PCMInterface) section. It consists of the
89[ALSAInPort] and [ALSAOutPort] classes for capture and playback, respectively.
90
91The ALSA PCM interface implementation allows setting only the most significant
92parameters, like the number of channels, sampling rate, bits per sample, period
93size and period count. All of them are set in the [PcmParams] passed to the
94corresponding ALSA port when it's opened, except for the period count that is
95set during the ALSA port construction. Other parameters like the start and stop
96thresholds are not configurable, they are set to one frame for capture and one
97period for playback. These are typical values used in Android Audio HALs.
98
99The ALSA PCM classes support the same parameters that tinyalsa does, that is:
100
101- Formats: 8, 16, 24 and 32-bits little-endian, no compressed formats supported.
102- Channels: mono, stereo or multichannel.
103- Sampling rate: those supported by ALSA.
104
105## ALSA mixer interface ## {#ALSAMixer}
106
107The mixer interface of ALSA allows configuring the sound card settings like the
108audio routes and volumes. The [ALSAMixer] class represents the abstraction of
109the mixer interface and offers helpful mechanisms to set mixer controls.
110
111Two mechanisms are available to set the ALSA controls:
112
113- Named control(s). [ALSAControl] class is used to describe a single ALSA mixer
114 control consisting of a name and a target value. The target value can be
115 an integer for boolean, integer and byte control types, or a string for
116 enum controls. The [ALSAControl]s can then be set (to its target value) or
117 cleared (to 0 or "Off" depending the control type) through the
118 [set()](\ref tiaudioutils::ALSAMixer::set) methods.
119
120- Paths. This mechanism is built on top of Android's libaudioroute, an XML-based
121 solution. The XML file name is derived from the card name (e.g. dra7evm_paths.xml)
122 and contains:
123
124 - Card defaults section. Controls in this section are set when the [ALSAMixer]
125 object is created or by explicitly calling the
126 [initRoutes()](\ref tiaudioutils::ALSAMixer::initRoutes) method. It can be
127 useful for:
128 - Controls that are not going to change dynamically.
129 - Set the inactive state of controls that will change dynamically, e.g. when
130 calling [setPath()](\ref tiaudioutils::ALSAMixer::setPath) to reset a path.
131
132 - One or multiple path sections. The path sections are identified by a name
133 which can be used to set the path through the
134 [setPath()](\ref tiaudioutils::ALSAMixer::setPath) method. A helpful way to
135 simplify setting the mixer controls in the Audio HAL consists of naming the
136 XML path sections after the Android audio devices (e.g. AUDIO_DEVICE_OUT_SPEAKER)
137 and use [setPath()](\ref tiaudioutils::ALSAMixer::setPath) directly with the
138 device (or devices) to set the path for, without the need to translate audio
139 devices values to the path name strings.
140
141Go to the [next](\ref streamdoc) section or return to the [index](index.html).
142
143*/ \ No newline at end of file
diff --git a/audio/utils/doc/stream.dox b/audio/utils/doc/stream.dox
new file mode 100644
index 0000000..f5aa127
--- /dev/null
+++ b/audio/utils/doc/stream.dox
@@ -0,0 +1,288 @@
1/**
2
3\page streamdoc Streams: writing and reading audio data
4
5[ThreadBase]: \ref tiaudioutils::ThreadBase "ThreadBase"
6[SlotMap]: \ref tiaudioutils::SlotMap "SlotMap"
7[BufferAdaptor]: \ref tiaudioutils::BufferAdaptor "BufferAdaptor"
8[BufferProvider]: \ref tiaudioutils::BufferProvider "BufferProvider"
9[Buffer]: \ref tiaudioutils::BufferProvider::Buffer "Buffer"
10[Resampler]: \ref tiaudioutils::Resampler "Resampler"
11[PcmParams]: \ref tiaudioutils::PcmParams "PcmParams"
12[PcmPort]: \ref tiaudioutils::PcmPort "PcmPort"
13[PcmInPort]: \ref tiaudioutils::PcmInPort "PcmInPort"
14[PcmOutPort]: \ref tiaudioutils::PcmOutPort "PcmOutPort"
15[NullInPort]: \ref tiaudioutils::NullInPort "NullInPort"
16[NullOutPort]: \ref tiaudioutils::NullOutPort "NullOutPort"
17[ALSAInPort]: \ref tiaudioutils::ALSAInPort "ALSAInPort"
18[ALSAOutPort]: \ref tiaudioutils::ALSAOutPort "ALSAOutPort"
19[ALSAControl]: \ref tiaudioutils::ALSAControl "ALSAControl"
20[ALSAMixer]: \ref tiaudioutils::ALSAMixer "ALSAMixer"
21[SimpleInStream]: \ref tiaudioutils::SimpleInStream "SimpleInStream"
22[SimpleOutStream]: \ref tiaudioutils::SimpleOutStream "SimpleOutStream"
23[SimpleReader]: \ref tiaudioutils::SimpleReader "SimpleReader"
24[ReaderProvider]: \ref tiaudioutils::SimpleReader::ReaderProvider "ReaderProvider"
25[SimpleWriter]: \ref tiaudioutils::SimpleWriter "SimpleWriter"
26[InStream]: \ref tiaudioutils::InStream "InStream"
27[AdaptedInStream]: \ref tiaudioutils::AdaptedInStream "AdaptedInStream"
28[BufferedInStream]: \ref tiaudioutils::BufferedInStream "BufferedInStream"
29[OutStream]: \ref tiaudioutils::OutStream "OutStream"
30[AdaptedOutStream]: \ref tiaudioutils::AdaptedOutStream "AdaptedOutStream"
31[BufferedOutStream]: \ref tiaudioutils::BufferedOutStream "BufferedOutStream"
32[PcmReader]: \ref tiaudioutils::PcmReader "PcmReader"
33[PcmWriter]: \ref tiaudioutils::PcmWriter "PcmWriter"
34[Merge]: \ref tiaudioutils::Merge "Merge"
35[UnMerge]: \ref tiaudioutils::UnMerge "UnMerge"
36[MonoPipe]: \ref tiaudioutils::MonoPipe "MonoPipe"
37[PipeReader]: \ref tiaudioutils::PipeReader "PipeReader"
38[PipeWriter]: \ref tiaudioutils::PipeWriter "PipeWriter"
39
40[ALSA]: http://www.alsa-project.org/main/index.php/Main_Page "ALSA"
41[tinyalsa]: https://github.com/tinyalsa/tinyalsa "tinyalsa"
42
43# PCM stream readers and writers # {#PCMReaderAndWriter}
44
45Audio capture or playback is achieved using streams which are registered to PCM
46readers or writers. The life cycle of a PCM stream and its reader/writer is as
47follows:
48
491. Create a PCM reader/writer for a given PCM input/output port.
502. Create a PCM stream and register it to the reader/writer.
513. Start the stream.
524. Read/write data using the stream object, if applicable. Some stream types
53 don't require explicit read() or write() calls, instead buffers are acquired
54 using the [BufferProvider] interface.
555. Stop the stream.
566. Unregister the stream and destroy it if needed.
577. Destroy the PCM reader/writer if no more streams are registered and active.
58
59All the stream types supported by this library can transparently do sample rate
60conversion if the stream sampling rate differs from the PCM port's.
61
62The [buffer provider][BufferProvider] interface describes the mechanism used to
63[acquire](\ref tiaudioutils::BufferProvider::getNextBuffer) and
64[release](\ref tiaudioutils::BufferProvider::releaseBuffer) buffers.
65An [audio buffer][Buffer] is defined in terms of its size (in frames) and its
66location in memory. The life cycle of the audio buffer delivered by a provider
67is as follows:
68
691. The PCM reader/writer requests a new buffer through the
70 [getNextBuffer()](\ref tiaudioutils::BufferProvider::getNextBuffer) method.
71 The requestor must specify a valid buffer size by setting the buffer's frame
72 count field.
732. The provider gets the buffer request and determines whether the requested
74 size can be delivered or not, if not the buffer frame count is updated.
75 The provider also sets the pointer to the actual buffer in memory.
763. The PCM reader/writer uses the buffer and releases it through the
77 [releaseBuffer()](\ref tiaudioutils::BufferProvider::releaseBuffer) method.
784. The provider gets the buffer release call and reuses or frees the buffer.
79
80The buffer provider mechanism is used by the non-simple streams described in
81the [Merge Stream](#MStream) and [Un-Merge Stream](#UMStream) sections.
82
83
84## Simple stream ## {#SimpleStream}
85
86Simple stream classes can be used when the data going to or coming from the
87hardware doesn't need any additional processing, that is, when the audio stream
88is connected directly to a PCM port.
89
90\dot
91digraph SimpleDiag {
92 node [shape=box,fontsize=10,height=0.25];
93 AudioFrameCabin [label="Audio Frame"];
94 AudioFrameBS1 [label="Audio Frame"];
95 AudioFrameBS2 [label="Audio Frame"];
96 Cabin -> AudioFrameCabin -> PcmOutPort1;
97 BackSeat1 -> AudioFrameBS1 -> PcmOutPort2;
98 BackSeat2 -> AudioFrameBS2 -> PcmOutPort3;
99}
100\enddot
101
102### Capture ### {#SimpleStreamCapture}
103
104Audio capture is carried out by the [SimpleInStream] and the [SimpleReader].
105
106The simple PCM reader ([SimpleReader]) is in charge of receiving the audio data
107from the underlying [PCM port][PCMInPort] and passing it to a simple PCM stream.
108The PCM stream needs to be registered before use and unregistered if another
109stream will use the reader or if the reader is going to be destroyed.
110
111The simple PCM input stream ([SimpleInStream]) can be directly used in the Audio
112HAL to read data from the hardware through the stream's
113[read()](\ref tiaudioutils::SimpleInStream::read) method. The audio data is
114actually read from the PCM input port by the reader that the stream is registered
115to.
116
117### Playback ### {#SimpleStreamPlayback}
118
119Audio playback is carried out by the [SimpleOutStream] and the [SimpleWriter].
120
121The simple PCM writer ([SimpleWriter]) is in charge of taking data from a simple
122PCM stream and writing it to an underlying [PCM port][PCMOutPort]. The PCM stream
123needs to be registered before use and unregistered if another stream will use the
124writer or if the writer is going to be destroyed.
125
126The simple PCM output stream ([SimpleOutStream]) can be directly used in the
127Audio HAL to write data to the hardware through the stream's
128[write()](\ref tiaudioutils::SimpleOutStream::write) method. The audio data
129is actually written to the PCM output port by the writer that the stream is
130registered to.
131
132
133## Un-Merge Stream ## {#UMStream}
134
135The un-merge capable reader can be used when a single audio input port contains
136data for multiple input streams. The data for each stream comes into specific
137slots of the incoming hardware data stream.
138
139\dot
140digraph UnMergeDiag {
141 node [shape=box,fontsize=10,height=0.25];
142 AudioFrame [shape=record,label="{Audio\ Frame|{<f0>0|<f1>1|<f2>2|<f3>3|<f4>4|<f5>5}}"];
143 Stream1 [label="Stream 1"];
144 Stream2 [label="Stream 2"];
145 PcmInPort -> AudioFrame;
146 "AudioFrame":f0:s -> Stream1;
147 "AudioFrame":f1:s -> Stream1;
148 "AudioFrame":f2:s -> Stream2;
149 "AudioFrame":f2:s -> Stream2;
150}
151\enddot
152
153Audio capture is carried out by the [PcmReader] and an input stream: [InStream],
154[AdaptedInStream] or [BufferedInStream].
155
156### PCM reader ### {#PCMReader}
157
158The PCM reader ([PcmReader]) is in charge of receiving the audio data from the
159the underlying [PCM port][PcmInPort], extracting the corresponding channels from
160the incoming stream and copying them to the registered streams.
161
162The un-merge operation is performed by the [UnMerge] class which uses a
163source-to-destination [slot map][SlotMap] to determine the channels to be
164un-merged and the order and/or position. Slots that don't have any stream active
165at a given time are filled with zeros. The [UnMerge] class is flexible enough to
166allow channel duplication (one channel in the source to multiple channels in the
167destination) or rearranging the channels of the incoming stream (remix).
168
169The PCM reader uses the pull mechanism based on [buffer providers][BufferProvider]
170described in the [PCM stream readers and writers](#PCMReaderAndWriter) section to
171get the audio buffers from all its registered streams. These buffers are filled
172by the reader with new un-merged data and then released.
173
174### Input streams ### {#PcmInStream}
175
176The [InStream] is created with a buffer provider that is automatically called
177when the reader needs the next buffer to fill new data. This type of stream can
178be useful when the provider itself can deliver the audio buffers and later store
179them in their final destination (e.g. when audio data is stored in a file or
180in a circular buffer / pipe).
181
182The [AdaptedInStream] uses an [adaptor][BufferAdaptor] to connect a push-based
183stream with a PCM reader that requires pull-based streams. The adapted input
184stream provides a [read()](\ref tiaudioutils::AdaptedInStream::read) method
185that can be called directly from the Audio HAL, while also implements the
186[BufferProvider] interface that the reader needs. The adaptation is bufferless
187so it doesn't add extra latency.
188
189The [BufferedInStream] uses an internal buffer to adapt the read() calls from
190the Audio HAL and the [BufferProvider] interface that the reader needs. The
191consumer side (Audio HAL) reads data using the push mechanism (through the
192[read()](\ref tiaudioutils::BufferedInStream::read) method provided by the
193buffered input stream) while the producer side (PCM reader) writes the data to
194the buffer using the pull mechanism. The size of internal buffer is configurable,
195but it adds a delay to the audio path.
196
197
198## Merge Stream ## {#MStream}
199
200The merge capable writer can be used when a single audio output port carries
201data for multiple streams. For example, when the three listening zones are
202routed to specific slots of a single, multi-channel PCM output port, and the
203data from each zone must be merged before it's passed to the hardware for
204rendering.
205
206\dot
207digraph MergeDiag {
208 node [shape=box,fontsize=10,height=0.25];
209 AudioFrame [shape=record,label="{{<f0>0|<f1>1|<f2>2|<f3>3|<f4>4|<f5>5}|Audio\ Frame}"];
210 Cabin:s -> "AudioFrame":f0:n;
211 Cabin:se -> "AudioFrame":f1:n;
212 BackSeat1:sw -> "AudioFrame":f2:n;
213 BackSeat1:se -> "AudioFrame":f3:n;
214 BackSeat2:sw -> "AudioFrame":f4:n;
215 BackSeat2:s -> "AudioFrame":f5:n;
216 AudioFrame -> PcmOutPort;
217}
218\enddot
219
220Audio playback is carried out by the [PcmWriter] and an output stream:
221[OutStream], [AdaptedOutStream] or [BufferedOutStream].
222
223### PCM writer ### {#PCMWriter}
224
225The PCM writer ([PcmWriter]) is in charge of taking data from all registered
226streams, copying the audio samples from each stream into preassigned slots of the
227resulting stream and writing it to an underlying [PCM port][PcmOutPort].
228
229The merge operation is performed by the [Merge] class which uses a
230source-to-destination [slot map][SlotMap] to determine the channels to be merged
231and the order and/or position. Slots that don't have any stream active at a
232given time are filled with zeros. The [Merge] class is flexible enough to allow
233channel duplication (one channel in the source to multiple channels in the
234destination) or rearranging the channels of the incoming stream (remix) which
235could be useful for multi-channel streams where the audio track and the hardware
236sink don't have the same slot allocation.
237
238The PCM writer uses the pull mechanism based on [buffer providers][BufferProvider]
239described in the [PCM stream readers and writers](#PCMReaderAndWriter) section to
240get the audio buffers from all its registered streams.
241
242### Output streams ### {#PcmOutStream}
243
244The [OutStream] is created with a buffer provider that is automatically called
245when the writer needs more data. This type of stream can be useful when the
246provider itself can deliver the audio buffers filled with new data (e.g. when
247the audio data is stored in a file or in a circular buffer / pipe).
248
249The [AdaptedOutStream] uses an [adaptor][BufferAdaptor] to connect a push-based
250stream with a PCM writer that requires pull-based streams. The adapted output
251stream provides a [write()](\ref tiaudioutils::AdaptedOutStream::write) method
252that can be called directly from the Audio HAL, while also implements the
253[BufferProvider] interface that the writer needs. The adaptation is bufferless
254so it doesn't add extra latency.
255
256The [BufferedOutStream] uses an internal buffer to adapt the write() calls from
257the Audio HAL and the [BufferProvider] interface that the writer needs. The
258producer side (Audio HAL) writes data using the push mechanism (through the
259[write()](\ref tiaudioutils::BufferedOutStream::write) method provided by the
260buffered output stream) while the consumer side (PCM writer) reads the data from
261the buffer using the pull mechanism. The size of internal buffer is configurable,
262but it adds a delay to the audio path.
263
264## Circular Buffer: the Mono Pipe ## {#MonoPipe}
265
266The [mono pipe][MonoPipe] is a circular buffer where there is a single producer
267and a single consumer. Currently, the pipe's implementation in this library
268relies on the Android's NBAIO (Non-Blocking Audio I/O) implementation.
269
270A [pipe reader][PipeReader] and a [pipe writer][PipeWriter] are buffer providers
271aimed to facilitate the interaction of PCM readers and writers with the mono pipe.
272
273\dot
274digraph PipeDiag {
275 node [shape=box,fontsize=10,height=0.25];
276 MonoPipe [shape=record,label="{MonoPipe |{<f0>|<f1>|<f2>|<f3>|<f4>}}"];
277 "MonoPipe":f0:w -> PipeWriter [dir=back];
278 "MonoPipe":f4:e -> PipeReader;
279 PipeWriter -> PcmReader [label=" InStream",fontsize=10,dir=back];
280 PipeReader -> PcmWriter [label=" OutStream",fontsize=10];
281 PcmReader -> PcmInPort [dir=back];
282 PcmWriter -> PcmOutPort;
283}
284\enddot
285
286Go to the [previous](\ref pcmdoc) section or return to the [index](index.html).
287
288*/ \ No newline at end of file
diff --git a/audio/utils/include/tiaudioutils/Log.h b/audio/utils/include/tiaudioutils/Log.h
index dfc5d79..27bd711 100644
--- a/audio/utils/include/tiaudioutils/Log.h
+++ b/audio/utils/include/tiaudioutils/Log.h
@@ -14,11 +14,24 @@
14 * limitations under the License. 14 * limitations under the License.
15 */ 15 */
16 16
17/**
18 * \file Log.h
19 * \brief Definitions used for logging in Android
20 *
21 * Contains the definition of the library's tag name and the very verbose
22 * log level macro. Defining the log level (LOG_NDEBUG) here will affect all
23 * modules in the library.
24 */
25
17#ifndef _TIAUDIOUTILS_LOG_H_ 26#ifndef _TIAUDIOUTILS_LOG_H_
18#define _TIAUDIOUTILS_LOG_H_ 27#define _TIAUDIOUTILS_LOG_H_
19 28
20/* As usual, LOG_NDEBUG and VERY_VERBOSE_LOGGING must be defined before */ 29/* As usual, LOG_NDEBUG and VERY_VERBOSE_LOGGING must be defined before */
30
31/** The tag name of the tiaudioutils library in Android */
21#define LOG_TAG "tiaudioutils" 32#define LOG_TAG "tiaudioutils"
33
34/** Definition of the very-verbose logging macro */
22#ifdef VERY_VERBOSE_LOGGING 35#ifdef VERY_VERBOSE_LOGGING
23#define ALOGVV ALOGV 36#define ALOGVV ALOGV
24#else 37#else