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 "codec_provider" # Codec provides the bit clock 662 * fsync "codec_consumer" # Codec follows the 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_provider; /* SND_SOC_TPLG_BCLK_ value */ 1032 unsigned char fsync_provider; /* 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 */ 1177