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 27extern "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 * <h6>Vendor Tokens</h6> 258 * A vendor token list is defined as a new section. Each token element is 259 * a pair of string ID and integer value. And both the ID and value are 260 * vendor-specific. 261 * 262 * <pre> 263 * SectionVendorTokens."id of the vendor tokens" { 264 * comment "optional comments" 265 * VENDOR_TOKEN_ID1 "1" 266 * VENDOR_TOKEN_ID2 "2" 267 * VENDOR_TOKEN_ID3 "3" 268 * ... 269 * } 270 * </pre> 271 * 272 * <h6>Vendor Tuples</h6> 273 * Vendor tuples are defined as a new section. It contains a reference to 274 * a vendor token list and several tuple arrays. 275 * All arrays share a vendor token list, defined by the tokens keyword. 276 * Each tuple array is for a specific type, defined by the string following 277 * the tuples keyword. Supported types are: string, uuid, bool, byte, 278 * short and word. 279 * 280 * <pre> 281 * SectionVendorTuples."id of the vendor tuples" { 282 * tokens "id of the vendor tokens" 283 * 284 * tuples."string" { 285 * VENDOR_TOKEN_ID1 "character string" 286 * ... 287 * } 288 * 289 * tuples."uuid" { # 16 characters separated by commas 290 * VENDOR_TOKEN_ID2 "0x01,0x02,...,0x0f" 291 * ... 292 * } 293 * 294 * tuples."bool" { 295 * VENDOR_TOKEN_ID3 "true/false" 296 * ... 297 * } 298 * 299 * tuples."byte" { 300 * VENDOR_TOKEN_ID4 "0x11" 301 * VENDOR_TOKEN_ID5 "0x22" 302 * ... 303 * } 304 * 305 * tuples."short" { 306 * VENDOR_TOKEN_ID6 "0x1122" 307 * VENDOR_TOKEN_ID7 "0x3344" 308 * ... 309 * } 310 * 311 * tuples."word" { 312 * VENDOR_TOKEN_ID8 "0x11223344" 313 * VENDOR_TOKEN_ID9 "0x55667788" 314 * ... 315 * } 316 * } 317 * </pre> 318 * To define multiple vendor tuples of same type, please append some 319 * characters after the type string ("string", "uuid", "bool", "byte", "short" 320 * or "word"), to avoid ID duplication in the SectionVendorTuples.<br> 321 * The parser will check the first few characters in ID to get the tuple type. 322 * Here is an example: 323 * <pre> 324 * SectionVendorTuples."id of the vendor tuples" { 325 * ... 326 * tuples."word.module0" { 327 * VENDOR_TOKEN_PARAM_ID1 "0x00112233" 328 * VENDOR_TOKEN_PARAM_ID2 "0x44556677" 329 * ... 330 * } 331 * 332 * tuples."word.module2" { 333 * VENDOR_TOKEN_PARAM_ID1 "0x11223344" 334 * VENDOR_TOKEN_PARAM_ID2 "0x55667788" 335 * ... 336 * } 337 * ... 338 * } 339 * 340 * </pre> 341 * 342 * <h5>Mixer Controls</h5> 343 * A mixer control is defined as a new section that can include channel mapping, 344 * TLV data, callback operations and private data. The mixer section also 345 * includes a few other config options that are shown here :- 346 * 347 * <pre> 348 * SectionControlMixer."mixer name" { 349 * comment "optional comments" 350 * 351 * index "1" # Index number 352 * 353 * channel."name" { # Channel maps 354 * .... 355 * } 356 * 357 * ops."ctl" { # Ops callback functions 358 * .... 359 * } 360 * 361 * max "32" # Max control value 362 * invert "0" # Whether control values are inverted 363 * 364 * tlv "tld_data" # optional TLV data 365 * 366 * data "pdata for mixer1" # optional private data 367 * } 368 * </pre> 369 * 370 * The section name is used to define the mixer name. The index number can be 371 * used to identify topology objects groups(index "0" is common, fit for all 372 * user cases).This allows driver operations on objects with index number N and 373 * can be used to add/remove pipelines of objects whilst other objects are 374 * unaffected. 375 * 376 * <h5>Byte Controls</h5> 377 * A byte control is defined as a new section that can include channel mapping, 378 * TLV data, callback operations and private data. The bytes section also 379 * includes a few other config options that are shown here :- 380 * 381 * <pre> 382 * SectionControlBytes."name" { 383 * comment "optional comments" 384 * 385 * index "1" # Index number 386 * 387 * channel."name" { # Channel maps 388 * .... 389 * } 390 * 391 * ops."ctl" { # Ops callback functions 392 * .... 393 * } 394 * 395 * base "0" # Register base 396 * num_regs "16" # Number of registers 397 * mask "0xff" # Mask 398 * max "255" # Maximum value 399 * 400 * tlv "tld_data" # optional TLV data 401 * 402 * data "pdata for mixer1" # optional private data 403 * } 404 * </pre> 405 * 406 * <h5>Enumerated Controls</h5> 407 * A enumerated control is defined as a new section (like mixer and byte) that 408 * can include channel mapping, callback operations, private data and 409 * text strings to represent the enumerated control options.<br> 410 * 411 * The text strings for the enumerated controls are defined in a separate 412 * section as follows :- 413 * 414 * <pre> 415 * SectionText."name" { 416 * 417 * Values [ 418 * "value1" 419 * "value2" 420 * "value3" 421 * ] 422 * } 423 * </pre> 424 * 425 * All the enumerated text values are listed in the values list.<br> 426 * The enumerated control is similar to the other controls and defined as 427 * follows :- 428 * 429 * <pre> 430 * SectionControlMixer."name" { 431 * comment "optional comments" 432 * 433 * index "1" # Index number 434 * 435 * texts "EQU1" # Enumerated text items 436 * 437 * channel."name" { # Channel maps 438 * .... 439 * } 440 * 441 * ops."ctl" { # Ops callback functions 442 * .... 443 * } 444 * 445 * data "pdata for mixer1" # optional private data 446 * } 447 * </pre> 448 * 449 * <h4>DAPM Graph</h4> 450 * DAPM graphs can easily be defined using the topology file. The format is 451 * very similar to the DAPM graph kernel format. :- 452 * 453 * <pre> 454 * SectionGraph."dsp" { 455 * index "1" # Index number 456 * 457 * lines [ 458 * "sink1, control, source1" 459 * "sink2, , source2" 460 * ] 461 * } 462 * </pre> 463 * 464 * The lines in the graph are defined as a variable size list of sinks, 465 * controls and sources. The control name is optional as some graph lines have 466 * no associated controls. The section name can be used to differentiate the 467 * graph with other graphs, it's not used by the kernel atm. 468 * 469 * <h4>DAPM Widgets</h4> 470 * DAPM widgets are similar to controls in that they can include many other 471 * objects. Widgets can contain private data, mixer controls and enum controls. 472 * 473 * The following widget types are supported and match the driver types :- 474 * 475 * * input 476 * * output 477 * * mux 478 * * mixer 479 * * pga 480 * * out_drv 481 * * adc 482 * * dac 483 * * switch 484 * * pre 485 * * post 486 * * aif_in 487 * * aif_out 488 * * dai_in 489 * * dai_out 490 * * dai_link 491 * 492 * Widgets are defined as follows :- 493 * 494 * <pre> 495 * SectionWidget."name" { 496 * 497 * index "1" # Index number 498 * 499 * type "aif_in" # Widget type - detailed above 500 * stream_name "name" # Stream name 501 * 502 * no_pm "true" # No PM control bit. 503 * reg "20" # PM bit register offset 504 * shift "0" # PM bit register shift 505 * invert "1" # PM bit is inverted 506 * subseq "8" # subsequence number 507 * 508 * event_type "1" # DAPM widget event type 509 * event_flags "1" # DAPM widget event flags 510 * 511 * mixer "name" # Optional Mixer Control 512 * enum "name" # Optional Enum Control 513 * 514 * data "name" # optional private data 515 * } 516 * </pre> 517 * 518 * The section name is the widget name. The mixer and enum fields are mutually 519 * exclusive and used to include controls into the widget. The index and data 520 * fields are the same for widgets as they are for controls whilst the other 521 * fields map on very closely to the driver widget fields. 522 * 523 * <h5>Widget Private Data</h5> 524 * Widget can have private data. For the format of the private data, please 525 * refer to section Control Private Data. 526 * 527 * <h4>PCM Capabilities</h4> 528 * Topology can also define the PCM capabilities of front end or physical DAIs. 529 * Capabilities can be defined with the following section :- 530 * 531 * <pre> 532 * SectionPCMCapabilities."name" { 533 * 534 * formats "S24_LE,S16_LE" # Supported formats 535 * rates "48000" # Supported rates 536 * rate_min "48000" # Max supported sample rate 537 * rate_max "48000" # Min supported sample rate 538 * channels_min "2" # Min number of channels 539 * channels_max "2" # max number of channels 540 * } 541 * </pre> 542 * The supported formats use the same naming convention as the driver macros. 543 * The PCM capabilities name can be referred to and included by PCM and 544 * physical DAI sections. 545 * 546 * <h4>PCM Configurations</h4> 547 * PCM runtime configurations can be defined for playback and capture stream 548 * directions with the following section :- 549 * 550 * <pre> 551 * SectionPCMConfig."name" { 552 * 553 * config."playback" { # playback config 554 * format "S16_LE" # playback format 555 * rate "48000" # playback sample rate 556 * channels "2" # playback channels 557 * tdm_slot "0xf" # playback TDM slot 558 * } 559 * 560 * config."capture" { # capture config 561 * format "S16_LE" # capture format 562 * rate "48000" # capture sample rate 563 * channels "2" # capture channels 564 * tdm_slot "0xf" # capture TDM slot 565 * } 566 * } 567 * </pre> 568 * 569 * The supported formats use the same naming convention as the driver macros. 570 * The PCM configuration name can be referred to and included by PCM and 571 * physical link sections. 572 * 573 * <h4>PCM (Front-end DAI & DAI link) </h4> 574 * PCM sections define the supported capabilities and configurations for 575 * supported playback and capture streams, names and flags for front end 576 * DAI & DAI links. Topology kernel driver will use a PCM object to create 577 * a pair of FE DAI & DAI links. 578 * 579 * <pre> 580 * SectionPCM."name" { 581 * 582 * index "1" # Index number 583 * 584 * id "0" # used for binding to the PCM 585 * 586 * dai."name of front-end DAI" { 587 * id "0" # used for binding to the front-end DAI 588 * } 589 * 590 * pcm."playback" { 591 * capabilities "capabilities1" # capabilities for playback 592 * 593 * configs [ # supported configs for playback 594 * "config1" 595 * "config2" 596 * ] 597 * } 598 * 599 * pcm."capture" { 600 * capabilities "capabilities2" # capabilities for capture 601 * 602 * configs [ # supported configs for capture 603 * "config1" 604 * "config2" 605 * "config3" 606 * ] 607 * } 608 * 609 * # Optional boolean flags 610 * symmetric_rates "true" 611 * symmetric_channels "true" 612 * symmetric_sample_bits "false" 613 * 614 * data "name" # optional private data 615 * } 616 * </pre> 617 * 618 * <h4>Physical DAI Link Configurations</h4> 619 * The runtime configurations of a physical DAI link can be defined by 620 * SectionLink. <br> Backend DAI links belong to physical links, and can 621 * be configured by either SectionLink or SectionBE, with same syntax. 622 * But SectionBE is deprecated atm since the internal processing is 623 * actually same. 624 * 625 * <pre> 626 * SectionLink."name" { 627 * 628 * index "1" # Index number 629 * 630 * id "0" # used for binding to the link 631 * 632 * stream_name "name" # used for binding to the link 633 * 634 * hw_configs [ # runtime supported HW configurations, optional 635 * "config1" 636 * "config2" 637 * ... 638 * ] 639 * 640 * default_hw_conf_id "1" # default HW config ID for init 641 * 642 * # Optional boolean flags 643 * symmetric_rates "true" 644 * symmetric_channels "false" 645 * symmetric_sample_bits "true" 646 * 647 * data "name" # optional private data 648 * } 649 * </pre> 650 * 651 * A physical link can refer to multiple runtime supported hardware 652 * configurations, which is defined by SectionHWConfig. 653 * 654 * <pre> 655 * SectionHWConfig."name" { 656 * 657 * id "1" # used for binding to the config 658 * format "I2S" # physical audio format. 659 * bclk "codec_provider" # Codec provides the bit clock 660 * fsync "codec_consumer" # Codec follows the fsync 661 * } 662 * </pre> 663 * 664 * <h4>Physical DAI</h4> 665 * A physical DAI (e.g. backend DAI for DPCM) is defined as a new section 666 * that can include a unique ID, playback and capture stream capabilities, 667 * optional flags, and private data. <br> 668 * Its PCM stream capablities are same as those for PCM objects, 669 * please refer to section 'PCM Capabilities'. 670 * 671 * <pre> 672 * SectionDAI."name" { 673 * 674 * index "1" # Index number 675 * 676 * id "0" # used for binding to the Backend DAI 677 * 678 * pcm."playback" { 679 * capabilities "capabilities1" # capabilities for playback 680 * } 681 * 682 * pcm."capture" { 683 * capabilities "capabilities2" # capabilities for capture 684 * } 685 * 686 * symmetric_rates "true" # optional flags 687 * symmetric_channels "true" 688 * symmetric_sample_bits "false" 689 * 690 * data "name" # optional private data 691 * } 692 * </pre> 693 * 694 * <h4>Manifest Private Data</h4> 695 * Manfiest may have private data. Users need to define a manifest section 696 * and add the references to 1 or multiple data sections. Please refer to 697 * section 'How to define an element with private data'. <br> 698 * And the text conf file can have at most 1 manifest section. <br><br> 699 * 700 * Manifest section is defined as follows :- 701 * 702 * <pre> 703 * SectionManifest"name" { 704 * 705 * data "name" # optional private data 706 * } 707 * </pre> 708 * 709 * <h4>Include other files</h4> 710 * Users may include other files in a text conf file via alsaconf syntax 711 * <path/to/configuration-file>. This allows users to define common info 712 * in separate files (e.g. vendor tokens, tuples) and share them for 713 * different platforms, thus save the total size of config files. <br> 714 * Users can also specifiy additional configuraiton directories relative 715 * to "/usr/share/alsa/" to search the included files, via alsaconf syntax 716 * <searchfdir:/relative-path/to/usr/share/alsa>. <br><br> 717 * 718 * For example, file A and file B are two text conf files for platform X, 719 * they will be installed to /usr/share/alsa/topology/platformx. If we 720 * need file A to include file B, in file A we can add: <br> 721 * 722 * <searchdir:topology/platformx> <br> 723 * <name-of-file-B> <br><br> 724 * 725 * ALSA conf will search and open an included file in the following order 726 * of priority: 727 * 1. directly open the file by its name; 728 * 2. search for the file name in "/usr/share/alsa"; 729 * 3. search for the file name in user specified subdirectories under 730 * "/usr/share/alsa". 731 * 732 * The order of the included files need not to be same as their 733 * dependencies, since the topology library will load them all before 734 * parsing their dependencies. <br> 735 * 736 * The configuration directories defined by a file will only be used to search 737 * the files included by this file. 738 */ 739 740/** Maximum number of channels supported in one control */ 741#define SND_TPLG_MAX_CHAN 8 742 743/** Topology context */ 744typedef struct snd_tplg snd_tplg_t; 745 746/** Topology object types */ 747enum snd_tplg_type { 748 SND_TPLG_TYPE_TLV = 0, /*!< TLV Data */ 749 SND_TPLG_TYPE_MIXER, /*!< Mixer control*/ 750 SND_TPLG_TYPE_ENUM, /*!< Enumerated control */ 751 SND_TPLG_TYPE_TEXT, /*!< Text data */ 752 SND_TPLG_TYPE_DATA, /*!< Private data */ 753 SND_TPLG_TYPE_BYTES, /*!< Byte control */ 754 SND_TPLG_TYPE_STREAM_CONFIG, /*!< PCM Stream configuration */ 755 SND_TPLG_TYPE_STREAM_CAPS, /*!< PCM Stream capabilities */ 756 SND_TPLG_TYPE_PCM, /*!< PCM stream device */ 757 SND_TPLG_TYPE_DAPM_WIDGET, /*!< DAPM widget */ 758 SND_TPLG_TYPE_DAPM_GRAPH, /*!< DAPM graph elements */ 759 SND_TPLG_TYPE_BE, /*!< BE DAI link */ 760 SND_TPLG_TYPE_CC, /*!< Hostless codec <-> codec link */ 761 SND_TPLG_TYPE_MANIFEST, /*!< Topology manifest */ 762 SND_TPLG_TYPE_TOKEN, /*!< Vendor tokens */ 763 SND_TPLG_TYPE_TUPLE, /*!< Vendor tuples */ 764 SND_TPLG_TYPE_LINK, /*!< Physical DAI link */ 765 SND_TPLG_TYPE_HW_CONFIG, /*!< Link HW config */ 766 SND_TPLG_TYPE_DAI, /*!< Physical DAI */ 767}; 768 769/** Fit for all user cases */ 770#define SND_TPLG_INDEX_ALL 0 771 772/** Flags for the snd_tplg_create */ 773#define SND_TPLG_CREATE_VERBOSE (1<<0) /*!< Verbose output */ 774#define SND_TPLG_CREATE_DAPM_NOSORT (1<<1) /*!< Do not sort DAPM objects by index */ 775 776/** 777 * \brief Return the version of the topology library. 778 * \return A static string with the version number. 779 */ 780const char *snd_tplg_version(void); 781 782/** 783 * \brief Create a new topology parser instance. 784 * \return New topology parser instance 785 */ 786snd_tplg_t *snd_tplg_new(void); 787 788/** 789 * \brief Create a new topology parser instance. 790 * \return New topology parser instance 791 */ 792snd_tplg_t *snd_tplg_create(int flags); 793 794/** 795 * \brief Free a topology parser instance. 796 * \param tplg Topology parser instance 797 */ 798void snd_tplg_free(snd_tplg_t *tplg); 799 800/** 801 * \brief Load topology from the text buffer. 802 * \param tplg Topology instance. 803 * \param buf Text buffer. 804 * \param size Text buffer size in bytes. 805 * \return Zero on success, otherwise a negative error code 806 */ 807int snd_tplg_load(snd_tplg_t *tplg, const char *buf, size_t size); 808 809/** 810 * \brief Parse and build topology text file into binary file. 811 * \param tplg Topology instance. 812 * \param infile Topology text input file to be parsed 813 * \param outfile Binary topology output file. 814 * \return Zero on success, otherwise a negative error code 815 */ 816int snd_tplg_build_file(snd_tplg_t *tplg, const char *infile, 817 const char *outfile); 818 819/** 820 * \brief Enable verbose reporting of binary file output 821 * \param tplg Topology Instance 822 * \param verbose Enable verbose output level if non zero 823 */ 824void snd_tplg_verbose(snd_tplg_t *tplg, int verbose); 825 826/** \struct snd_tplg_tlv_template 827 * \brief Template type for all TLV objects. 828 */ 829struct snd_tplg_tlv_template { 830 int type; /*!< TLV type SNDRV_CTL_TLVT_ */ 831}; 832 833/** \struct snd_tplg_tlv_dbscale_template 834 * \brief Template type for TLV Scale objects. 835 */ 836struct snd_tplg_tlv_dbscale_template { 837 struct snd_tplg_tlv_template hdr; /*!< TLV type header */ 838 int min; /*!< dB minimum value in 0.1dB */ 839 int step; /*!< dB step size in 0.1dB */ 840 int mute; /*!< is min dB value mute ? */ 841}; 842 843/** \struct snd_tplg_channel_elem 844 * \brief Template type for single channel mapping. 845 */ 846struct snd_tplg_channel_elem { 847 int size; /*!< size in bytes of this structure */ 848 int reg; /*!< channel control register */ 849 int shift; /*!< channel shift for control bits */ 850 int id; /*!< ID maps to Left, Right, LFE etc */ 851}; 852 853/** \struct snd_tplg_channel_map_template 854 * \brief Template type for channel mapping. 855 */ 856struct snd_tplg_channel_map_template { 857 int num_channels; /*!< number of channel mappings */ 858 struct snd_tplg_channel_elem channel[SND_TPLG_MAX_CHAN]; /*!< mapping */ 859}; 860 861/** \struct snd_tplg_pdata_template 862 * \brief Template type for private data objects. 863 */ 864struct snd_tplg_pdata_template { 865 unsigned int length; /*!< data length */ 866 const void *data; /*!< data */ 867}; 868 869/** \struct snd_tplg_io_ops_template 870 * \brief Template type for object operations mapping. 871 */ 872struct snd_tplg_io_ops_template { 873 int get; /*!< get callback ID */ 874 int put; /*!< put callback ID */ 875 int info; /*!< info callback ID */ 876}; 877 878/** \struct snd_tplg_ctl_template 879 * \brief Template type for control objects. 880 */ 881struct snd_tplg_ctl_template { 882 int type; /*!< Control type */ 883 const char *name; /*!< Control name */ 884 int access; /*!< Control access */ 885 struct snd_tplg_io_ops_template ops; /*!< operations */ 886 union { 887 struct snd_tplg_tlv_template *tlv; /*!< non NULL means we have TLV data */ 888 struct snd_tplg_tlv_dbscale_template *tlv_scale; /*!< scale TLV data */ 889 }; 890}; 891 892/** \struct snd_tplg_mixer_template 893 * \brief Template type for mixer control objects. 894 */ 895struct snd_tplg_mixer_template { 896 struct snd_tplg_ctl_template hdr; /*!< control type header */ 897 struct snd_tplg_channel_map_template *map; /*!< channel map */ 898 int min; /*!< min value for mixer */ 899 int max; /*!< max value for mixer */ 900 int platform_max; /*!< max value for platform control */ 901 int invert; /*!< whether controls bits are inverted */ 902 struct snd_soc_tplg_private *priv; /*!< control private data */ 903}; 904 905/** \struct snd_tplg_enum_template 906 * \brief Template type for enumerated control objects. 907 */ 908struct snd_tplg_enum_template { 909 struct snd_tplg_ctl_template hdr; /*!< control type header */ 910 struct snd_tplg_channel_map_template *map; /*!< channel map */ 911 int items; /*!< number of enumerated items in control */ 912 int mask; /*!< register mask size */ 913 const char **texts; /*!< control text items */ 914 const int **values; /*!< control value items */ 915 struct snd_soc_tplg_private *priv; /*!< control private data */ 916}; 917 918/** \struct snd_tplg_bytes_template 919 * \brief Template type for TLV Scale objects. 920 */ 921struct snd_tplg_bytes_template { 922 struct snd_tplg_ctl_template hdr; /*!< control type header */ 923 int max; /*!< max byte control value */ 924 int mask; /*!< byte control mask */ 925 int base; /*!< base register */ 926 int num_regs; /*!< number of registers */ 927 struct snd_tplg_io_ops_template ext_ops; /*!< ops mapping */ 928 struct snd_soc_tplg_private *priv; /*!< control private data */ 929}; 930 931/** \struct snd_tplg_graph_elem 932 * \brief Template type for single DAPM graph element. 933 */ 934struct snd_tplg_graph_elem { 935 const char *src; /*!< source widget name */ 936 const char *ctl; /*!< control name or NULL if no control */ 937 const char *sink; /*!< sink widget name */ 938}; 939 940/** \struct snd_tplg_graph_template 941 * \brief Template type for array of DAPM graph elements. 942 */ 943struct snd_tplg_graph_template { 944 int count; /*!< Number of graph elements */ 945 struct snd_tplg_graph_elem elem[0]; /*!< graph elements */ 946}; 947 948/** \struct snd_tplg_widget_template 949 * \brief Template type for DAPM widget objects. 950 */ 951struct snd_tplg_widget_template { 952 int id; /*!< SND_SOC_DAPM_CTL */ 953 const char *name; /*!< widget name */ 954 const char *sname; /*!< stream name (certain widgets only) */ 955 int reg; /*!< negative reg = no direct dapm */ 956 int shift; /*!< bits to shift */ 957 int mask; /*!< non-shifted mask */ 958 int subseq; /*!< sort within widget type */ 959 unsigned int invert; /*!< invert the power bit */ 960 unsigned int ignore_suspend; /*!< kept enabled over suspend */ 961 unsigned short event_flags; /*!< PM event sequence flags */ 962 unsigned short event_type; /*!< PM event sequence type */ 963 struct snd_soc_tplg_private *priv; /*!< widget private data */ 964 int num_ctls; /*!< Number of controls used by widget */ 965 struct snd_tplg_ctl_template *ctl[0]; /*!< array of widget controls */ 966}; 967 968/** \struct snd_tplg_stream_template 969 * \brief Stream configurations. 970 */ 971struct snd_tplg_stream_template { 972 const char *name; /*!< name of the stream config */ 973 int format; /*!< SNDRV_PCM_FMTBIT_* */ 974 int rate; /*!< SNDRV_PCM_RATE_* */ 975 int period_bytes; /*!< size of period in bytes */ 976 int buffer_bytes; /*!< size of buffer in bytes. */ 977 int channels; /*!< number of channels */ 978}; 979 980/** \struct snd_tplg_stream_caps_template 981 * \brief Stream Capabilities. 982 */ 983struct snd_tplg_stream_caps_template { 984 const char *name; /*!< name of the stream caps */ 985 uint64_t formats; /*!< supported formats SNDRV_PCM_FMTBIT_* */ 986 unsigned int rates; /*!< supported rates SNDRV_PCM_RATE_* */ 987 unsigned int rate_min; /*!< min rate */ 988 unsigned int rate_max; /*!< max rate */ 989 unsigned int channels_min; /*!< min channels */ 990 unsigned int channels_max; /*!< max channels */ 991 unsigned int periods_min; /*!< min number of periods */ 992 unsigned int periods_max; /*!< max number of periods */ 993 unsigned int period_size_min; /*!< min period size bytes */ 994 unsigned int period_size_max; /*!< max period size bytes */ 995 unsigned int buffer_size_min; /*!< min buffer size bytes */ 996 unsigned int buffer_size_max; /*!< max buffer size bytes */ 997 unsigned int sig_bits; /*!< number of bits of content */ 998}; 999 1000/** \struct snd_tplg_pcm_template 1001 * \brief Template type for PCM (FE DAI & DAI links). 1002 */ 1003struct snd_tplg_pcm_template { 1004 const char *pcm_name; /*!< PCM stream name */ 1005 const char *dai_name; /*!< DAI name */ 1006 unsigned int pcm_id; /*!< unique ID - used to match */ 1007 unsigned int dai_id; /*!< unique ID - used to match */ 1008 unsigned int playback; /*!< supports playback mode */ 1009 unsigned int capture; /*!< supports capture mode */ 1010 unsigned int compress; /*!< 1 = compressed; 0 = PCM */ 1011 struct snd_tplg_stream_caps_template *caps[2]; /*!< playback & capture for DAI */ 1012 unsigned int flag_mask; /*!< bitmask of flags to configure */ 1013 unsigned int flags; /*!< flag value SND_SOC_TPLG_LNK_FLGBIT_* */ 1014 struct snd_soc_tplg_private *priv; /*!< private data */ 1015 int num_streams; /*!< number of supported configs */ 1016 struct snd_tplg_stream_template stream[0]; /*!< supported configs */ 1017}; 1018 1019 /** \struct snd_tplg_hw_config_template 1020 * \brief Template type to describe a physical link runtime supported 1021 * hardware config, i.e. hardware audio formats. 1022 */ 1023struct snd_tplg_hw_config_template { 1024 int id; /*!< unique ID - - used to match */ 1025 unsigned int fmt; /*!< SND_SOC_DAI_FORMAT_ format value */ 1026 unsigned char clock_gated; /*!< SND_SOC_TPLG_DAI_CLK_GATE_ value */ 1027 unsigned char invert_bclk; /*!< 1 for inverted BCLK, 0 for normal */ 1028 unsigned char invert_fsync; /*!< 1 for inverted frame clock, 0 for normal */ 1029 unsigned char bclk_provider; /*!< SND_SOC_TPLG_BCLK_ value */ 1030 unsigned char fsync_provider; /*!< SND_SOC_TPLG_FSYNC_ value */ 1031 unsigned char mclk_direction; /*!< SND_SOC_TPLG_MCLK_ value */ 1032 unsigned short reserved; /*!< for 32bit alignment */ 1033 unsigned int mclk_rate; /*!< MCLK or SYSCLK freqency in Hz */ 1034 unsigned int bclk_rate; /*!< BCLK freqency in Hz */ 1035 unsigned int fsync_rate; /*!< frame clock in Hz */ 1036 unsigned int tdm_slots; /*!< number of TDM slots in use */ 1037 unsigned int tdm_slot_width; /*!< width in bits for each slot */ 1038 unsigned int tx_slots; /*!< bit mask for active Tx slots */ 1039 unsigned int rx_slots; /*!< bit mask for active Rx slots */ 1040 unsigned int tx_channels; /*!< number of Tx channels */ 1041 unsigned int *tx_chanmap; /*!< array of slot number */ 1042 unsigned int rx_channels; /*!< number of Rx channels */ 1043 unsigned int *rx_chanmap; /*!< array of slot number */ 1044}; 1045 1046/** \struct snd_tplg_dai_template 1047 * \brief Template type for physical DAI. 1048 * It can be used to configure backend DAIs for DPCM. 1049 */ 1050struct snd_tplg_dai_template { 1051 const char *dai_name; /*!< DAI name */ 1052 unsigned int dai_id; /*!< unique ID - used to match */ 1053 unsigned int playback; /*!< supports playback mode */ 1054 unsigned int capture; /*!< supports capture mode */ 1055 struct snd_tplg_stream_caps_template *caps[2]; /*!< playback & capture for DAI */ 1056 unsigned int flag_mask; /*!< bitmask of flags to configure */ 1057 unsigned int flags; /*!< SND_SOC_TPLG_DAI_FLGBIT_* */ 1058 struct snd_soc_tplg_private *priv; /*!< private data */ 1059 1060}; 1061 1062/** \struct snd_tplg_link_template 1063 * \brief Template type for physical DAI Links. 1064 */ 1065struct snd_tplg_link_template { 1066 const char *name; /*!< link name, used to match */ 1067 int id; /*!< unique ID - used to match with existing physical links */ 1068 const char *stream_name; /*!< link stream name, used to match */ 1069 1070 int num_streams; /*!< number of configs */ 1071 struct snd_tplg_stream_template *stream; /*!< supported configs */ 1072 1073 struct snd_tplg_hw_config_template *hw_config; /*!< supported HW configs */ 1074 int num_hw_configs; /*!< number of hw configs */ 1075 int default_hw_config_id; /*!< default hw config ID for init */ 1076 1077 unsigned int flag_mask; /*!< bitmask of flags to configure */ 1078 unsigned int flags; /*!< SND_SOC_TPLG_LNK_FLGBIT_* flag value */ 1079 struct snd_soc_tplg_private *priv; /*!< private data */ 1080}; 1081 1082/** \struct snd_tplg_obj_template_t 1083 * \brief Generic Template Object 1084 */ 1085typedef struct snd_tplg_obj_template { 1086 enum snd_tplg_type type; /*!< template object type */ 1087 int index; /*!< group index for object */ 1088 int version; /*!< optional vendor specific version details */ 1089 int vendor_type; /*!< optional vendor specific type info */ 1090 union { 1091 struct snd_tplg_widget_template *widget; /*!< DAPM widget */ 1092 struct snd_tplg_mixer_template *mixer; /*!< Mixer control */ 1093 struct snd_tplg_bytes_template *bytes_ctl; /*!< Bytes control */ 1094 struct snd_tplg_enum_template *enum_ctl; /*!< Enum control */ 1095 struct snd_tplg_graph_template *graph; /*!< Graph elements */ 1096 struct snd_tplg_pcm_template *pcm; /*!< PCM elements */ 1097 struct snd_tplg_link_template *link; /*!< physical DAI Links */ 1098 struct snd_tplg_dai_template *dai; /*!< Physical DAI */ 1099 }; 1100} snd_tplg_obj_template_t; 1101 1102/** 1103 * \brief Register topology template object. 1104 * \param tplg Topology instance. 1105 * \param t Template object. 1106 * \return Zero on success, otherwise a negative error code 1107 */ 1108int snd_tplg_add_object(snd_tplg_t *tplg, snd_tplg_obj_template_t *t); 1109 1110/** 1111 * \brief Build all registered topology data into binary file. 1112 * \param tplg Topology instance. 1113 * \param outfile Binary topology output file. 1114 * \return Zero on success, otherwise a negative error code 1115 */ 1116int snd_tplg_build(snd_tplg_t *tplg, const char *outfile); 1117 1118/** 1119 * \brief Build all registered topology data into memory. 1120 * \param tplg Topology instance. 1121 * \param bin Binary topology output buffer (malloc). 1122 * \param size Binary topology output buffer size in bytes. 1123 * \return Zero on success, otherwise a negative error code 1124 */ 1125int snd_tplg_build_bin(snd_tplg_t *tplg, void **bin, size_t *size); 1126 1127/** 1128 * \brief Attach private data to topology manifest. 1129 * \param tplg Topology instance. 1130 * \param data Private data. 1131 * \param len Length of data in bytes. 1132 * \return Zero on success, otherwise a negative error code 1133 */ 1134int snd_tplg_set_manifest_data(snd_tplg_t *tplg, const void *data, int len); 1135 1136/** 1137 * \brief Set an optional vendor specific version number. 1138 * \param tplg Topology instance. 1139 * \param version Vendor specific version number. 1140 * \return Zero on success, otherwise a negative error code 1141 */ 1142int snd_tplg_set_version(snd_tplg_t *tplg, unsigned int version); 1143 1144/* 1145 * Flags for the snd_tplg_save() 1146 */ 1147#define SND_TPLG_SAVE_SORT (1<<0) /*!< sort identifiers */ 1148#define SND_TPLG_SAVE_GROUPS (1<<1) /*!< create the structure by group index */ 1149#define SND_TPLG_SAVE_NOCHECK (1<<16) /*!< unchecked output for debugging */ 1150 1151/** 1152 * \brief Save the topology to the text configuration string. 1153 * \param tplg Topology instance. 1154 * \param dst A pointer to string with result (malloc). 1155 * \param flags save mode 1156 * \return Zero on success, otherwise a negative error code 1157 * 1158 * Valid flags are 1159 * - SND_TPLG_SAVE_SORT 1160 * - SND_TPLG_SAVE_GROUPS 1161 * - SND_TPLG_SAVE_NOCHECK 1162 */ 1163int snd_tplg_save(snd_tplg_t *tplg, char **dst, int flags); 1164 1165/** 1166 * \brief Decode the binary topology contents. 1167 * \param tplg Topology instance. 1168 * \param bin Binary topology input buffer. 1169 * \param size Binary topology input buffer size. 1170 * \param dflags - not used, must be set to 0. 1171 * \return Zero on success, otherwise a negative error code 1172 */ 1173int snd_tplg_decode(snd_tplg_t *tplg, void *bin, size_t size, int dflags); 1174 1175/** \} */ 1176 1177#ifdef __cplusplus 1178} 1179#endif 1180 1181#endif /* __ALSA_TOPOLOGY_H */ 1182