Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/alsa/topology.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 69:33d812a61356
1 /*
2 *
3 * This library is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU Lesser General Public License as
5 * published by the Free Software Foundation; either version 2.1 of
6 * the License, or (at your option) any later version.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU Lesser General Public License for more details.
12 *
13 * You should have received a copy of the GNU Lesser General Public
14 * License along with this library; if not, write to the Free Software
15 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16 *
17 * Copyright (C) 2015 Intel Corporation
18 *
19 */
20
21 #ifndef __ALSA_TOPOLOGY_H
22 #define __ALSA_TOPOLOGY_H
23
24 #include <stdint.h>
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30 /**
31 * \defgroup topology Topology Interface
32 * \{
33 */
34
35 /*! \page topology ALSA Topology Interface
36 *
37 * The topology interface allows developers to define DSP topologies in a text
38 * file format and to convert the text topology to a binary topology
39 * representation that can be understood by the kernel. The topology core
40 * currently recognises the following object types :-
41 *
42 * * Controls (mixer, enumerated and byte) including TLV data.
43 * * PCMs (Front End DAI & DAI link)
44 * * DAPM widgets
45 * * DAPM graph elements.
46 * * Physical DAI & DAI links
47 * * Private data for each object type.
48 * * Manifest (containing count of each object type)
49 *
50 * <h3>Topology File Format</h3>
51 *
52 * The topology text format uses the standard ALSA configuration file format to
53 * describe each topology object type. This allows topology objects to include
54 * other topology objects as part of their definition. i.e. a TLV data object
55 * can be shared amongst many control objects that use the same TLV data.
56 *
57 *
58 * <h4>Controls</h4>
59 * Topology audio controls can belong to three different types :-
60 * * Mixer control
61 * * Enumerated control
62 * * Byte control
63 *
64 * Each control type can contain TLV data, private data, operations and also
65 * belong to widget objects.<br>
66 *
67 * <h5>Control Operations</h5>
68 * Driver Kcontrol callback info(), get() and put() operations are mapped with
69 * the CTL ops section in topology configuration files. The ctl ops section can
70 * assign operations using the standard names (listed below) for the standard
71 * kcontrol types or use ID numbers (>256) to map to bespoke driver controls.<br>
72 *
73 * <pre>
74 *
75 * ops."ctl" {
76 * info "volsw"
77 * get "257"
78 * put "257"
79 * }
80 *
81 * </pre>
82 *
83 * This mapping shows info() using the standard "volsw" info callback whilst
84 * the get() and put() are mapped to bespoke driver callbacks. <br>
85 *
86 * The Standard operations names for control get(), put() and info calls
87 * are :-
88 * * volsw
89 * * volsw_sx
90 * * volsw_xr_sx
91 * * enum
92 * * bytes
93 * * enum_value
94 * * range
95 * * strobe
96 *
97 * <h5>Control Access</h5>
98 * Controls access can be specified using the "access" section. If no "access"
99 * section is defined then default RW access flags are set for normal and TLV
100 * controls.
101 *
102 * <pre>
103 * access [
104 * read
105 * write
106 * tlv_command
107 * ]
108 * </pre>
109 *
110 * The standard access flags are as follows :-
111 * * read
112 * * write
113 * * read_write
114 * * volatile
115 * * timestamp
116 * * tlv_read
117 * * tlv_write
118 * * tlv_read_write
119 * * tlv_command
120 * * inactive
121 * * lock
122 * * owner
123 * * tlv_callback
124 * * user
125 *
126 * <h5>Control TLV Data</h5>
127 * Controls can also use TLV data to represent dB information. This can be done
128 * by defining a TLV section and using the TLV section within the control.
129 * The TLV data for DBScale types are defined as follows :-
130 *
131 * <pre>
132 * scale {
133 * min "-9000"
134 * step "300"
135 * mute "1"
136 * }
137 * </pre>
138 *
139 * Where the meanings and values for min, step and mute are exactly the same
140 * as defined in driver code.
141 *
142 * <h5>Control Channel Mapping</h5>
143 * Controls can also specify which channels they are mapped with. This is useful
144 * for userspace as it allows applications to determine the correct control
145 * channel for Left and Right etc. Channel maps are defined as follows :-
146 *
147 * <pre>
148 * channel."name" {
149 * reg "0"
150 * shift "0"
151 * }
152 * </pre>
153 *
154 * The channel map reg is the register offset for the control, shift is the
155 * bit shift within the register for the channel and the section name is the
156 * channel name and can be one of the following :-
157 *
158 * <pre>
159 * * mono # mono stream
160 * * fl # front left
161 * * fr # front right
162 * * rl # rear left
163 * * rr # rear right
164 * * fc # front center
165 * * lfe # LFE
166 * * sl # side left
167 * * sr # side right
168 * * rc # rear center
169 * * flc # front left center
170 * * frc # front right center
171 * * rlc # rear left center
172 * * rrc # rear right center
173 * * flw # front left wide
174 * * frw # front right wide
175 * * flh # front left high
176 * * fch # front center high
177 * * frh # front right high
178 * * tc # top center
179 * * tfl # top front left
180 * * tfr # top front right
181 * * tfc # top front center
182 * * trl # top rear left
183 * * trr # top rear right
184 * * trc # top rear center
185 * * tflc # top front left center
186 * * tfrc # top front right center
187 * * tsl # top side left
188 * * tsr # top side right
189 * * llfe # left LFE
190 * * rlfe # right LFE
191 * * bc # bottom center
192 * * blc # bottom left center
193 * * brc # bottom right center
194 * </pre>
195 *
196 * <h5>Control Private Data</h5>
197 * Controls can also have private data. This can be done by defining a private
198 * data section and including the section within the control. The private data
199 * section is defined as follows :-
200 *
201 * <pre>
202 * SectionData."pdata for EQU1" {
203 * file "/path/to/file"
204 * bytes "0x12,0x34,0x56,0x78"
205 * shorts "0x1122,0x3344,0x5566,0x7788"
206 * words "0xaabbccdd,0x11223344,0x66aa77bb,0xefef1234"
207 * tuples "section id of the vendor tuples"
208 * };
209 * </pre>
210 * The file, bytes, shorts, words and tuples keywords are all mutually
211 * exclusive as the private data should only be taken from one source.
212 * The private data can either be read from a separate file or defined in
213 * the topology file using the bytes, shorts, words or tuples keywords.
214 * The keyword tuples is to define vendor specific tuples. Please refer to
215 * section Vendor Tokens and Vendor tuples.
216 *
217 * It's easy to use a vendor tuples object to define a C structure instance.
218 * And a data section can include multiple vendor tuples objects:
219 *
220 * <pre>
221 * SectionData."data element name" {
222 * index "1" #Index number
223 * tuples [
224 * "id of the 1st vendor tuples section"
225 * "id of the 2nd vendor tuples section"
226 * ...
227 * ]
228 * };
229 * </pre>
230 *
231 * <h5>How to define an element with private data</h5>
232 * An element can refer to a single data section or multiple data
233 * sections.
234 *
235 * <h6>To refer to a single data section:</h6>
236 * <pre>
237 * Sectionxxx."element name" {
238 * ...
239 * data "name of data section" # optional private data
240 * }
241 * </pre>
242 *
243 * <h6>To refer to multiple data sections:</h6>
244 * <pre>
245 * Sectionxxx."element name" {
246 * ...
247 * data [ # optional private data
248 * "name of 1st data section"
249 * "name of 2nd data section"
250 * ...
251 * ]
252 * }
253 * </pre>
254 * And data of these sections will be merged in the same order as they are
255 * in the list, as the element's private data for kernel.
256 *
257 * </pre>
258 *
259 * <h6>Vendor Tokens</h6>
260 * A vendor token list is defined as a new section. Each token element is
261 * a pair of string ID and integer value. And both the ID and value are
262 * vendor-specific.
263 *
264 * <pre>
265 * SectionVendorTokens."id of the vendor tokens" {
266 * comment "optional comments"
267 * VENDOR_TOKEN_ID1 "1"
268 * VENDOR_TOKEN_ID2 "2"
269 * VENDOR_TOKEN_ID3 "3"
270 * ...
271 * }
272 * </pre>
273 *
274 * <h6>Vendor Tuples</h6>
275 * Vendor tuples are defined as a new section. It contains a reference to
276 * a vendor token list and several tuple arrays.
277 * All arrays share a vendor token list, defined by the tokens keyword.
278 * Each tuple array is for a specific type, defined by the string following
279 * the tuples keyword. Supported types are: string, uuid, bool, byte,
280 * short and word.
281 *
282 * <pre>
283 * SectionVendorTuples."id of the vendor tuples" {
284 * tokens "id of the vendor tokens"
285 *
286 * tuples."string" {
287 * VENDOR_TOKEN_ID1 "character string"
288 * ...
289 * }
290 *
291 * tuples."uuid" { # 16 characters separated by commas
292 * VENDOR_TOKEN_ID2 "0x01,0x02,...,0x0f"
293 * ...
294 * }
295 *
296 * tuples."bool" {
297 * VENDOR_TOKEN_ID3 "true/false"
298 * ...
299 * }
300 *
301 * tuples."byte" {
302 * VENDOR_TOKEN_ID4 "0x11"
303 * VENDOR_TOKEN_ID5 "0x22"
304 * ...
305 * }
306 *
307 * tuples."short" {
308 * VENDOR_TOKEN_ID6 "0x1122"
309 * VENDOR_TOKEN_ID7 "0x3344"
310 * ...
311 * }
312 *
313 * tuples."word" {
314 * VENDOR_TOKEN_ID8 "0x11223344"
315 * VENDOR_TOKEN_ID9 "0x55667788"
316 * ...
317 * }
318 * }
319 * </pre>
320 * To define multiple vendor tuples of same type, please append some
321 * characters after the type string ("string", "uuid", "bool", "byte", "short"
322 * or "word"), to avoid ID duplication in the SectionVendorTuples.<br>
323 * The parser will check the first few characters in ID to get the tuple type.
324 * Here is an example:
325 * <pre>
326 * SectionVendorTuples."id of the vendor tuples" {
327 * ...
328 * tuples."word.module0" {
329 * VENDOR_TOKEN_PARAM_ID1 "0x00112233"
330 * VENDOR_TOKEN_PARAM_ID2 "0x44556677"
331 * ...
332 * }
333 *
334 * tuples."word.module2" {
335 * VENDOR_TOKEN_PARAM_ID1 "0x11223344"
336 * VENDOR_TOKEN_PARAM_ID2 "0x55667788"
337 * ...
338 * }
339 * ...
340 * }
341 *
342 * </pre>
343 *
344 * <h5>Mixer Controls</h5>
345 * A mixer control is defined as a new section that can include channel mapping,
346 * TLV data, callback operations and private data. The mixer section also
347 * includes a few other config options that are shown here :-
348 *
349 * <pre>
350 * SectionControlMixer."mixer name" {
351 * comment "optional comments"
352 *
353 * index "1" # Index number
354 *
355 * channel."name" { # Channel maps
356 * ....
357 * }
358 *
359 * ops."ctl" { # Ops callback functions
360 * ....
361 * }
362 *
363 * max "32" # Max control value
364 * invert "0" # Whether control values are inverted
365 *
366 * tlv "tld_data" # optional TLV data
367 *
368 * data "pdata for mixer1" # optional private data
369 * }
370 * </pre>
371 *
372 * The section name is used to define the mixer name. The index number can be
373 * used to identify topology objects groups(index "0" is common, fit for all
374 * user cases).This allows driver operations on objects with index number N and
375 * can be used to add/remove pipelines of objects whilst other objects are
376 * unaffected.
377 *
378 * <h5>Byte Controls</h5>
379 * A byte control is defined as a new section that can include channel mapping,
380 * TLV data, callback operations and private data. The bytes section also
381 * includes a few other config options that are shown here :-
382 *
383 * <pre>
384 * SectionControlBytes."name" {
385 * comment "optional comments"
386 *
387 * index "1" # Index number
388 *
389 * channel."name" { # Channel maps
390 * ....
391 * }
392 *
393 * ops."ctl" { # Ops callback functions
394 * ....
395 * }
396 *
397 * base "0" # Register base
398 * num_regs "16" # Number of registers
399 * mask "0xff" # Mask
400 * max "255" # Maximum value
401 *
402 * tlv "tld_data" # optional TLV data
403 *
404 * data "pdata for mixer1" # optional private data
405 * }
406 * </pre>
407 *
408 * <h5>Enumerated Controls</h5>
409 * A enumerated control is defined as a new section (like mixer and byte) that
410 * can include channel mapping, callback operations, private data and
411 * text strings to represent the enumerated control options.<br>
412 *
413 * The text strings for the enumerated controls are defined in a separate
414 * section as follows :-
415 *
416 * <pre>
417 * SectionText."name" {
418 *
419 * Values [
420 * "value1"
421 * "value2"
422 "value3"
423 * ]
424 * }
425 * </pre>
426 *
427 * All the enumerated text values are listed in the values list.<br>
428 * The enumerated control is similar to the other controls and defined as
429 * follows :-
430 *
431 * <pre>
432 * SectionControlMixer."name" {
433 * comment "optional comments"
434 *
435 * index "1" # Index number
436 *
437 * texts "EQU1" # Enumerated text items
438 *
439 * channel."name" { # Channel maps
440 * ....
441 * }
442 *
443 * ops."ctl" { # Ops callback functions
444 * ....
445 * }
446 *
447 * data "pdata for mixer1" # optional private data
448 * }
449 * </pre>
450 *
451 * <h4>DAPM Graph</h4>
452 * DAPM graphs can easily be defined using the topology file. The format is
453 * very similar to the DAPM graph kernel format. :-
454 *
455 * <pre>
456 * SectionGraph."dsp" {
457 * index "1" # Index number
458 *
459 * lines [
460 * "sink1, control, source1"
461 * "sink2, , source2"
462 * ]
463 * }
464 * </pre>
465 *
466 * The lines in the graph are defined as a variable size list of sinks,
467 * controls and sources. The control name is optional as some graph lines have
468 * no associated controls. The section name can be used to differentiate the
469 * graph with other graphs, it's not used by the kernel atm.
470 *
471 * <h4>DAPM Widgets</h4>
472 * DAPM widgets are similar to controls in that they can include many other
473 * objects. Widgets can contain private data, mixer controls and enum controls.
474 *
475 * The following widget types are supported and match the driver types :-
476 *
477 * * input
478 * * output
479 * * mux
480 * * mixer
481 * * pga
482 * * out_drv
483 * * adc
484 * * dac
485 * * switch
486 * * pre
487 * * post
488 * * aif_in
489 * * aif_out
490 * * dai_in
491 * * dai_out
492 * * dai_link
493 *
494 * Widgets are defined as follows :-
495 *
496 * <pre>
497 * SectionWidget."name" {
498 *
499 * index "1" # Index number
500 *
501 * type "aif_in" # Widget type - detailed above
502 * stream_name "name" # Stream name
503 *
504 * no_pm "true" # No PM control bit.
505 * reg "20" # PM bit register offset
506 * shift "0" # PM bit register shift
507 * invert "1 # PM bit is inverted
508 * subseq "8" # subsequence number
509 *
510 * event_type "1" # DAPM widget event type
511 * event_flags "1" # DAPM widget event flags
512 *
513 * mixer "name" # Optional Mixer Control
514 * enum "name" # Optional Enum Control
515 *
516 * data "name" # optional private data
517 * }
518 * </pre>
519 *
520 * The section name is the widget name. The mixer and enum fields are mutually
521 * exclusive and used to include controls into the widget. The index and data
522 * fields are the same for widgets as they are for controls whilst the other
523 * fields map on very closely to the driver widget fields.
524 *
525 * <h5>Widget Private Data</h5>
526 * Widget can have private data. For the format of the private data, please
527 * refer to section Control Private Data.
528 *
529 * <h4>PCM Capabilities</h4>
530 * Topology can also define the PCM capabilities of front end or physical DAIs.
531 * Capabilities can be defined with the following section :-
532 *
533 * <pre>
534 * SectionPCMCapabilities."name" {
535 *
536 * formats "S24_LE,S16_LE" # Supported formats
537 * rates "48000" # Supported rates
538 * rate_min "48000" # Max supported sample rate
539 * rate_max "48000" # Min supported sample rate
540 * channels_min "2" # Min number of channels
541 * channels_max "2" # max number of channels
542 * }
543 * </pre>
544 * The supported formats use the same naming convention as the driver macros.
545 * The PCM capabilities name can be referred to and included by PCM and
546 * physical DAI sections.
547 *
548 * <h4>PCM Configurations</h4>
549 * PCM runtime configurations can be defined for playback and capture stream
550 * directions with the following section :-
551 *
552 * <pre>
553 * SectionPCMConfig."name" {
554 *
555 * config."playback" { # playback config
556 * format "S16_LE" # playback format
557 * rate "48000" # playback sample rate
558 * channels "2" # playback channels
559 * tdm_slot "0xf" # playback TDM slot
560 * }
561 *
562 * config."capture" { # capture config
563 * format "S16_LE" # capture format
564 * rate "48000" # capture sample rate
565 * channels "2" # capture channels
566 * tdm_slot "0xf" # capture TDM slot
567 * }
568 * }
569 * </pre>
570 *
571 * The supported formats use the same naming convention as the driver macros.
572 * The PCM configuration name can be referred to and included by PCM and
573 * physical link sections.
574 *
575 * <h4>PCM (Front-end DAI & DAI link) </h4>
576 * PCM sections define the supported capabilities and configurations for
577 * supported playback and capture streams, names and flags for front end
578 * DAI & DAI links. Topology kernel driver will use a PCM object to create
579 * a pair of FE DAI & DAI links.
580 *
581 * <pre>
582 * SectionPCM."name" {
583 *
584 * index "1" # Index number
585 *
586 * id "0" # used for binding to the PCM
587 *
588 * dai."name of front-end DAI" {
589 * id "0" # used for binding to the front-end DAI
590 * }
591 *
592 * pcm."playback" {
593 * capabilities "capabilities1" # capabilities for playback
594 *
595 * configs [ # supported configs for playback
596 * "config1"
597 * "config2"
598 * ]
599 * }
600 *
601 * pcm."capture" {
602 * capabilities "capabilities2" # capabilities for capture
603 *
604 * configs [ # supported configs for capture
605 * "config1"
606 * "config2"
607 * "config3"
608 * ]
609 * }
610 *
611 * # Optional boolean flags
612 * symmetric_rates "true"
613 * symmetric_channels "true"
614 * symmetric_sample_bits "false"
615 *
616 * data "name" # optional private data
617 * }
618 * </pre>
619 *
620 * <h4>Physical DAI Link Configurations</h4>
621 * The runtime configurations of a physical DAI link can be defined by
622 * SectionLink. <br> Backend DAI links belong to physical links, and can
623 * be configured by either SectionLink or SectionBE, with same syntax.
624 * But SectionBE is deprecated atm since the internal processing is
625 * actually same.
626 *
627 * <pre>
628 * SectionLink."name" {
629 *
630 * index "1" # Index number
631 *
632 * id "0" # used for binding to the link
633 *
634 * stream_name "name" # used for binding to the link
635 *
636 * hw_configs [ # runtime supported HW configurations, optional
637 * "config1"
638 * "config2"
639 * ...
640 * ]
641 *
642 * default_hw_conf_id "1" #default HW config ID for init
643 *
644 * # Optional boolean flags
645 * symmetric_rates "true"
646 * symmetric_channels "false"
647 * symmetric_sample_bits "true"
648 *
649 * data "name" # optional private data
650 * }
651 * </pre>
652 *
653 * A physical link can refer to multiple runtime supported hardware
654 * configurations, which is defined by SectionHWConfig.
655 *
656 * <pre>
657 * SectionHWConfig."name" {
658 *
659 * id "1" # used for binding to the config
660 * format "I2S" # physical audio format.
661 * bclk "master" # Platform is master of bit clock
662 * fsync "slave" # Platform is slave of fsync
663 * }
664 * </pre>
665 *
666 * <h4>Physical DAI</h4>
667 * A physical DAI (e.g. backend DAI for DPCM) is defined as a new section
668 * that can include a unique ID, playback and capture stream capabilities,
669 * optional flags, and private data. <br>
670 * Its PCM stream capablities are same as those for PCM objects,
671 * please refer to section 'PCM Capabilities'.
672 *
673 * <pre>
674 * SectionDAI."name" {
675 *
676 * index "1" # Index number
677 *
678 * id "0" # used for binding to the Backend DAI
679 *
680 * pcm."playback" {
681 * capabilities "capabilities1" # capabilities for playback
682 * }
683 *
684 * pcm."capture" {
685 * capabilities "capabilities2" # capabilities for capture
686 * }
687 *
688 * symmetric_rates "true" # optional flags
689 * symmetric_channels "true"
690 * symmetric_sample_bits "false"
691 *
692 * data "name" # optional private data
693 * }
694 * </pre>
695 *
696 * <h4>Manifest Private Data</h4>
697 * Manfiest may have private data. Users need to define a manifest section
698 * and add the references to 1 or multiple data sections. Please refer to
699 * section 'How to define an element with private data'. <br>
700 * And the text conf file can have at most 1 manifest section. <br><br>
701 *
702 * Manifest section is defined as follows :-
703 *
704 * <pre>
705 * SectionManifest"name" {
706 *
707 * data "name" # optional private data
708 * }
709 * </pre>
710 *
711 * <h4>Include other files</h4>
712 * Users may include other files in a text conf file via alsaconf syntax
713 * <path/to/configuration-file>. This allows users to define common info
714 * in separate files (e.g. vendor tokens, tuples) and share them for
715 * different platforms, thus save the total size of config files. <br>
716 * Users can also specifiy additional configuraiton directories relative
717 * to "/usr/share/alsa/" to search the included files, via alsaconf syntax
718 * <searchfdir:/relative-path/to/usr/share/alsa>. <br><br>
719 *
720 * For example, file A and file B are two text conf files for platform X,
721 * they will be installed to /usr/share/alsa/topology/platformx. If we
722 * need file A to include file B, in file A we can add: <br>
723 *
724 * <searchdir:topology/platformx> <br>
725 * <name-of-file-B> <br><br>
726 *
727 * ALSA conf will search and open an included file in the following order
728 * of priority:
729 * 1. directly open the file by its name;
730 * 2. search for the file name in "/usr/share/alsa";
731 * 3. search for the file name in user specified subdirectories under
732 * "/usr/share/alsa".
733 *
734 * The order of the included files need not to be same as their
735 * dependencies, since the topology library will load them all before
736 * parsing their dependencies. <br>
737 *
738 * The configuration directories defined by a file will only be used to search
739 * the files included by this file.
740 */
741
742 /** Maximum number of channels supported in one control */
743 #define SND_TPLG_MAX_CHAN 8
744
745 /** Topology context */
746 typedef struct snd_tplg snd_tplg_t;
747
748 /** Topology object types */
749 enum snd_tplg_type {
750 SND_TPLG_TYPE_TLV = 0, /*!< TLV Data */
751 SND_TPLG_TYPE_MIXER, /*!< Mixer control*/
752 SND_TPLG_TYPE_ENUM, /*!< Enumerated control */
753 SND_TPLG_TYPE_TEXT, /*!< Text data */
754 SND_TPLG_TYPE_DATA, /*!< Private data */
755 SND_TPLG_TYPE_BYTES, /*!< Byte control */
756 SND_TPLG_TYPE_STREAM_CONFIG, /*!< PCM Stream configuration */
757 SND_TPLG_TYPE_STREAM_CAPS, /*!< PCM Stream capabilities */
758 SND_TPLG_TYPE_PCM, /*!< PCM stream device */
759 SND_TPLG_TYPE_DAPM_WIDGET, /*!< DAPM widget */
760 SND_TPLG_TYPE_DAPM_GRAPH, /*!< DAPM graph elements */
761 SND_TPLG_TYPE_BE, /*!< BE DAI link */
762 SND_TPLG_TYPE_CC, /*!< Hostless codec <-> codec link */
763 SND_TPLG_TYPE_MANIFEST, /*!< Topology manifest */
764 SND_TPLG_TYPE_TOKEN, /*!< Vendor tokens */
765 SND_TPLG_TYPE_TUPLE, /*!< Vendor tuples */
766 SND_TPLG_TYPE_LINK, /*!< Physical DAI link */
767 SND_TPLG_TYPE_HW_CONFIG, /*!< Link HW config */
768 SND_TPLG_TYPE_DAI, /*!< Physical DAI */
769 };
770
771 /** Fit for all user cases */
772 #define SND_TPLG_INDEX_ALL 0
773
774 /** Flags for the snd_tplg_create */
775 #define SND_TPLG_CREATE_VERBOSE (1<<0) /*!< Verbose output */
776 #define SND_TPLG_CREATE_DAPM_NOSORT (1<<1) /*!< Do not sort DAPM objects by index */
777
778 /**
779 * \brief Return the version of the topology library.
780 * \return A static string with the version number.
781 */
782 const char *snd_tplg_version(void);
783
784 /**
785 * \brief Create a new topology parser instance.
786 * \return New topology parser instance
787 */
788 snd_tplg_t *snd_tplg_new(void);
789
790 /**
791 * \brief Create a new topology parser instance.
792 * \return New topology parser instance
793 */
794 snd_tplg_t *snd_tplg_create(int flags);
795
796 /**
797 * \brief Free a topology parser instance.
798 * \param tplg Topology parser instance
799 */
800 void snd_tplg_free(snd_tplg_t *tplg);
801
802 /**
803 * \brief Load topology from the text buffer.
804 * \param tplg Topology instance.
805 * \param buf Text buffer.
806 * \param size Text buffer size in bytes.
807 * \return Zero on success, otherwise a negative error code
808 */
809 int snd_tplg_load(snd_tplg_t *tplg, const char *buf, size_t size);
810
811 /**
812 * \brief Parse and build topology text file into binary file.
813 * \param tplg Topology instance.
814 * \param infile Topology text input file to be parsed
815 * \param outfile Binary topology output file.
816 * \return Zero on success, otherwise a negative error code
817 */
818 int snd_tplg_build_file(snd_tplg_t *tplg, const char *infile,
819 const char *outfile);
820
821 /**
822 * \brief Enable verbose reporting of binary file output
823 * \param tplg Topology Instance
824 * \param verbose Enable verbose output level if non zero
825 */
826 void snd_tplg_verbose(snd_tplg_t *tplg, int verbose);
827
828 /** \struct snd_tplg_tlv_template
829 * \brief Template type for all TLV objects.
830 */
831 struct snd_tplg_tlv_template {
832 int type; /*!< TLV type SNDRV_CTL_TLVT_ */
833 };
834
835 /** \struct snd_tplg_tlv_dbscale_template
836 * \brief Template type for TLV Scale objects.
837 */
838 struct snd_tplg_tlv_dbscale_template {
839 struct snd_tplg_tlv_template hdr; /*!< TLV type header */
840 int min; /*!< dB minimum value in 0.1dB */
841 int step; /*!< dB step size in 0.1dB */
842 int mute; /*!< is min dB value mute ? */
843 };
844
845 /** \struct snd_tplg_channel_template
846 * \brief Template type for single channel mapping.
847 */
848 struct snd_tplg_channel_elem {
849 int size; /*!< size in bytes of this structure */
850 int reg; /*!< channel control register */
851 int shift; /*!< channel shift for control bits */
852 int id; /*!< ID maps to Left, Right, LFE etc */
853 };
854
855 /** \struct snd_tplg_channel_map_template
856 * \brief Template type for channel mapping.
857 */
858 struct snd_tplg_channel_map_template {
859 int num_channels; /*!< number of channel mappings */
860 struct snd_tplg_channel_elem channel[SND_TPLG_MAX_CHAN]; /*!< mapping */
861 };
862
863 /** \struct snd_tplg_pdata_template
864 * \brief Template type for private data objects.
865 */
866 struct snd_tplg_pdata_template {
867 unsigned int length; /*!< data length */
868 const void *data; /*!< data */
869 };
870
871 /** \struct snd_tplg_io_ops_template
872 * \brief Template type for object operations mapping.
873 */
874 struct snd_tplg_io_ops_template {
875 int get; /*!< get callback ID */
876 int put; /*!< put callback ID */
877 int info; /*!< info callback ID */
878 };
879
880 /** \struct snd_tplg_ctl_template
881 * \brief Template type for control objects.
882 */
883 struct snd_tplg_ctl_template {
884 int type; /*!< Control type */
885 const char *name; /*!< Control name */
886 int access; /*!< Control access */
887 struct snd_tplg_io_ops_template ops; /*!< operations */
888 union {
889 struct snd_tplg_tlv_template *tlv; /*!< non NULL means we have TLV data */
890 struct snd_tplg_tlv_dbscale_template *tlv_scale; /*!< scale TLV data */
891 };
892 };
893
894 /** \struct snd_tplg_mixer_template
895 * \brief Template type for mixer control objects.
896 */
897 struct snd_tplg_mixer_template {
898 struct snd_tplg_ctl_template hdr; /*!< control type header */
899 struct snd_tplg_channel_map_template *map; /*!< channel map */
900 int min; /*!< min value for mixer */
901 int max; /*!< max value for mixer */
902 int platform_max; /*!< max value for platform control */
903 int invert; /*!< whether controls bits are inverted */
904 struct snd_soc_tplg_private *priv; /*!< control private data */
905 };
906
907 /** \struct snd_tplg_enum_template
908 * \brief Template type for enumerated control objects.
909 */
910 struct snd_tplg_enum_template {
911 struct snd_tplg_ctl_template hdr; /*!< control type header */
912 struct snd_tplg_channel_map_template *map; /*!< channel map */
913 int items; /*!< number of enumerated items in control */
914 int mask; /*!< register mask size */
915 const char **texts; /*!< control text items */
916 const int **values; /*!< control value items */
917 struct snd_soc_tplg_private *priv; /*!< control private data */
918 };
919
920 /** \struct snd_tplg_bytes_template
921 * \brief Template type for TLV Scale objects.
922 */
923 struct snd_tplg_bytes_template {
924 struct snd_tplg_ctl_template hdr; /*!< control type header */
925 int max; /*!< max byte control value */
926 int mask; /*!< byte control mask */
927 int base; /*!< base register */
928 int num_regs; /*!< number of registers */
929 struct snd_tplg_io_ops_template ext_ops; /*!< ops mapping */
930 struct snd_soc_tplg_private *priv; /*!< control private data */
931 };
932
933 /** \struct snd_tplg_graph_elem
934 * \brief Template type for single DAPM graph element.
935 */
936 struct snd_tplg_graph_elem {
937 const char *src; /*!< source widget name */
938 const char *ctl; /*!< control name or NULL if no control */
939 const char *sink; /*!< sink widget name */
940 };
941
942 /** \struct snd_tplg_graph_template
943 * \brief Template type for array of DAPM graph elements.
944 */
945 struct snd_tplg_graph_template {
946 int count; /*!< Number of graph elements */
947 struct snd_tplg_graph_elem elem[0]; /*!< graph elements */
948 };
949
950 /** \struct snd_tplg_widget_template
951 * \brief Template type for DAPM widget objects.
952 */
953 struct snd_tplg_widget_template {
954 int id; /*!< SND_SOC_DAPM_CTL */
955 const char *name; /*!< widget name */
956 const char *sname; /*!< stream name (certain widgets only) */
957 int reg; /*!< negative reg = no direct dapm */
958 int shift; /*!< bits to shift */
959 int mask; /*!< non-shifted mask */
960 int subseq; /*!< sort within widget type */
961 unsigned int invert; /*!< invert the power bit */
962 unsigned int ignore_suspend; /*!< kept enabled over suspend */
963 unsigned short event_flags; /*!< PM event sequence flags */
964 unsigned short event_type; /*!< PM event sequence type */
965 struct snd_soc_tplg_private *priv; /*!< widget private data */
966 int num_ctls; /*!< Number of controls used by widget */
967 struct snd_tplg_ctl_template *ctl[0]; /*!< array of widget controls */
968 };
969
970 /** \struct snd_tplg_stream_template
971 * \brief Stream configurations.
972 */
973 struct snd_tplg_stream_template {
974 const char *name; /*!< name of the stream config */
975 int format; /*!< SNDRV_PCM_FMTBIT_* */
976 int rate; /*!< SNDRV_PCM_RATE_* */
977 int period_bytes; /*!< size of period in bytes */
978 int buffer_bytes; /*!< size of buffer in bytes. */
979 int channels; /*!< number of channels */
980 };
981
982 /** \struct snd_tplg_stream_caps_template
983 * \brief Stream Capabilities.
984 */
985 struct snd_tplg_stream_caps_template {
986 const char *name; /*!< name of the stream caps */
987 uint64_t formats; /*!< supported formats SNDRV_PCM_FMTBIT_* */
988 unsigned int rates; /*!< supported rates SNDRV_PCM_RATE_* */
989 unsigned int rate_min; /*!< min rate */
990 unsigned int rate_max; /*!< max rate */
991 unsigned int channels_min; /*!< min channels */
992 unsigned int channels_max; /*!< max channels */
993 unsigned int periods_min; /*!< min number of periods */
994 unsigned int periods_max; /*!< max number of periods */
995 unsigned int period_size_min; /*!< min period size bytes */
996 unsigned int period_size_max; /*!< max period size bytes */
997 unsigned int buffer_size_min; /*!< min buffer size bytes */
998 unsigned int buffer_size_max; /*!< max buffer size bytes */
999 unsigned int sig_bits; /*!< number of bits of content */
1000 };
1001
1002 /** \struct snd_tplg_pcm_template
1003 * \brief Template type for PCM (FE DAI & DAI links).
1004 */
1005 struct snd_tplg_pcm_template {
1006 const char *pcm_name; /*!< PCM stream name */
1007 const char *dai_name; /*!< DAI name */
1008 unsigned int pcm_id; /*!< unique ID - used to match */
1009 unsigned int dai_id; /*!< unique ID - used to match */
1010 unsigned int playback; /*!< supports playback mode */
1011 unsigned int capture; /*!< supports capture mode */
1012 unsigned int compress; /*!< 1 = compressed; 0 = PCM */
1013 struct snd_tplg_stream_caps_template *caps[2]; /*!< playback & capture for DAI */
1014 unsigned int flag_mask; /*!< bitmask of flags to configure */
1015 unsigned int flags; /*!< flag value SND_SOC_TPLG_LNK_FLGBIT_* */
1016 struct snd_soc_tplg_private *priv; /*!< private data */
1017 int num_streams; /*!< number of supported configs */
1018 struct snd_tplg_stream_template stream[0]; /*!< supported configs */
1019 };
1020
1021 /** \struct snd_tplg_hw_config_template
1022 * \brief Template type to describe a physical link runtime supported
1023 * hardware config, i.e. hardware audio formats.
1024 */
1025 struct snd_tplg_hw_config_template {
1026 int id; /* unique ID - - used to match */
1027 unsigned int fmt; /* SND_SOC_DAI_FORMAT_ format value */
1028 unsigned char clock_gated; /* SND_SOC_TPLG_DAI_CLK_GATE_ value */
1029 unsigned char invert_bclk; /* 1 for inverted BCLK, 0 for normal */
1030 unsigned char invert_fsync; /* 1 for inverted frame clock, 0 for normal */
1031 unsigned char bclk_master; /* SND_SOC_TPLG_BCLK_ value */
1032 unsigned char fsync_master; /* SND_SOC_TPLG_FSYNC_ value */
1033 unsigned char mclk_direction; /* SND_SOC_TPLG_MCLK_ value */
1034 unsigned short reserved; /* for 32bit alignment */
1035 unsigned int mclk_rate; /* MCLK or SYSCLK freqency in Hz */
1036 unsigned int bclk_rate; /* BCLK freqency in Hz */
1037 unsigned int fsync_rate; /* frame clock in Hz */
1038 unsigned int tdm_slots; /* number of TDM slots in use */
1039 unsigned int tdm_slot_width; /* width in bits for each slot */
1040 unsigned int tx_slots; /* bit mask for active Tx slots */
1041 unsigned int rx_slots; /* bit mask for active Rx slots */
1042 unsigned int tx_channels; /* number of Tx channels */
1043 unsigned int *tx_chanmap; /* array of slot number */
1044 unsigned int rx_channels; /* number of Rx channels */
1045 unsigned int *rx_chanmap; /* array of slot number */
1046 };
1047
1048 /** \struct snd_tplg_dai_template
1049 * \brief Template type for physical DAI.
1050 * It can be used to configure backend DAIs for DPCM.
1051 */
1052 struct snd_tplg_dai_template {
1053 const char *dai_name; /*!< DAI name */
1054 unsigned int dai_id; /*!< unique ID - used to match */
1055 unsigned int playback; /*!< supports playback mode */
1056 unsigned int capture; /*!< supports capture mode */
1057 struct snd_tplg_stream_caps_template *caps[2]; /*!< playback & capture for DAI */
1058 unsigned int flag_mask; /*!< bitmask of flags to configure */
1059 unsigned int flags; /*!< SND_SOC_TPLG_DAI_FLGBIT_* */
1060 struct snd_soc_tplg_private *priv; /*!< private data */
1061
1062 };
1063
1064 /** \struct snd_tplg_link_template
1065 * \brief Template type for physical DAI Links.
1066 */
1067 struct snd_tplg_link_template {
1068 const char *name; /*!< link name, used to match */
1069 int id; /*!< unique ID - used to match with existing physical links */
1070 const char *stream_name; /*!< link stream name, used to match */
1071
1072 int num_streams; /*!< number of configs */
1073 struct snd_tplg_stream_template *stream; /*!< supported configs */
1074
1075 struct snd_tplg_hw_config_template *hw_config; /*!< supported HW configs */
1076 int num_hw_configs; /* number of hw configs */
1077 int default_hw_config_id; /* default hw config ID for init */
1078
1079 unsigned int flag_mask; /* bitmask of flags to configure */
1080 unsigned int flags; /* SND_SOC_TPLG_LNK_FLGBIT_* flag value */
1081 struct snd_soc_tplg_private *priv; /*!< private data */
1082 };
1083
1084 /** \struct snd_tplg_obj_template
1085 * \brief Generic Template Object
1086 */
1087 typedef struct snd_tplg_obj_template {
1088 enum snd_tplg_type type; /*!< template object type */
1089 int index; /*!< group index for object */
1090 int version; /*!< optional vendor specific version details */
1091 int vendor_type; /*!< optional vendor specific type info */
1092 union {
1093 struct snd_tplg_widget_template *widget; /*!< DAPM widget */
1094 struct snd_tplg_mixer_template *mixer; /*!< Mixer control */
1095 struct snd_tplg_bytes_template *bytes_ctl; /*!< Bytes control */
1096 struct snd_tplg_enum_template *enum_ctl; /*!< Enum control */
1097 struct snd_tplg_graph_template *graph; /*!< Graph elements */
1098 struct snd_tplg_pcm_template *pcm; /*!< PCM elements */
1099 struct snd_tplg_link_template *link; /*!< physical DAI Links */
1100 struct snd_tplg_dai_template *dai; /*!< Physical DAI */
1101 };
1102 } snd_tplg_obj_template_t;
1103
1104 /**
1105 * \brief Register topology template object.
1106 * \param tplg Topology instance.
1107 * \param t Template object.
1108 * \return Zero on success, otherwise a negative error code
1109 */
1110 int snd_tplg_add_object(snd_tplg_t *tplg, snd_tplg_obj_template_t *t);
1111
1112 /**
1113 * \brief Build all registered topology data into binary file.
1114 * \param tplg Topology instance.
1115 * \param outfile Binary topology output file.
1116 * \return Zero on success, otherwise a negative error code
1117 */
1118 int snd_tplg_build(snd_tplg_t *tplg, const char *outfile);
1119
1120 /**
1121 * \brief Build all registered topology data into memory.
1122 * \param tplg Topology instance.
1123 * \param bin Binary topology output buffer (malloc).
1124 * \param size Binary topology output buffer size in bytes.
1125 * \return Zero on success, otherwise a negative error code
1126 */
1127 int snd_tplg_build_bin(snd_tplg_t *tplg, void **bin, size_t *size);
1128
1129 /**
1130 * \brief Attach private data to topology manifest.
1131 * \param tplg Topology instance.
1132 * \param data Private data.
1133 * \param len Length of data in bytes.
1134 * \return Zero on success, otherwise a negative error code
1135 */
1136 int snd_tplg_set_manifest_data(snd_tplg_t *tplg, const void *data, int len);
1137
1138 /**
1139 * \brief Set an optional vendor specific version number.
1140 * \param tplg Topology instance.
1141 * \param version Vendor specific version number.
1142 * \return Zero on success, otherwise a negative error code
1143 */
1144 int snd_tplg_set_version(snd_tplg_t *tplg, unsigned int version);
1145
1146 /*
1147 * Flags for the snd_tplg_save()
1148 */
1149 #define SND_TPLG_SAVE_SORT (1<<0) /*!< sort identifiers */
1150 #define SND_TPLG_SAVE_GROUPS (1<<1) /*!< create the structure by group index */
1151 #define SND_TPLG_SAVE_NOCHECK (1<<16) /*!< unchecked output for debugging */
1152
1153 /**
1154 * \brief Save the topology to the text configuration string.
1155 * \param tplg Topology instance.
1156 * \param dst A pointer to string with result (malloc).
1157 * \return Zero on success, otherwise a negative error code
1158 */
1159 int snd_tplg_save(snd_tplg_t *tplg, char **dst, int flags);
1160
1161 /**
1162 * \brief Decode the binary topology contents.
1163 * \param tplg Topology instance.
1164 * \param bin Binary topology input buffer.
1165 * \param size Binary topology input buffer size.
1166 * \return Zero on success, otherwise a negative error code
1167 */
1168 int snd_tplg_decode(snd_tplg_t *tplg, void *bin, size_t size, int dflags);
1169
1170 /* \} */
1171
1172 #ifdef __cplusplus
1173 }
1174 #endif
1175
1176 #endif /* __ALSA_TOPOLOGY_H */