include/topology.h

   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., 59 Temple Place, Suite 330, Boston, MA  02111-1307 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 /**
 775  * \brief Create a new topology parser instance.
 776  * \return New topology parser instance
 777  */
 778 snd_tplg_t *snd_tplg_new(void);
 779
 780 /**
 781  * \brief Free a topology parser instance.
 782  * \param tplg Topology parser instance
 783  */
 784 void snd_tplg_free(snd_tplg_t *tplg);
 785
 786 /**
 787  * \brief Parse and build topology text file into binary file.
 788  * \param tplg Topology instance.
 789  * \param infile Topology text input file to be parsed
 790  * \param outfile Binary topology output file.
 791  * \return Zero on success, otherwise a negative error code
 792  */
 793 int snd_tplg_build_file(snd_tplg_t *tplg, const char *infile,
 794         const char *outfile);
 795
 796 /**
 797  * \brief Enable verbose reporting of binary file output
 798  * \param tplg Topology Instance
 799  * \param verbose Enable verbose output level if non zero
 800  */
 801 void snd_tplg_verbose(snd_tplg_t *tplg, int verbose);
 802
 803 /** \struct snd_tplg_tlv_template
 804  * \brief Template type for all TLV objects.
 805  */
 806 struct snd_tplg_tlv_template {
 807         int type;        /*!< TLV type SNDRV_CTL_TLVT_ */
 808 };
 809
 810 /** \struct snd_tplg_tlv_dbscale_template
 811  * \brief Template type for TLV Scale objects.
 812  */
 813 struct snd_tplg_tlv_dbscale_template {
 814         struct snd_tplg_tlv_template hdr;       /*!< TLV type header */
 815         int min;                        /*!< dB minimum value in 0.1dB */
 816         int step;                       /*!< dB step size in 0.1dB */
 817         int mute;                       /*!< is min dB value mute ? */
 818 };
 819
 820 /** \struct snd_tplg_channel_template
 821  * \brief Template type for single channel mapping.
 822  */
 823 struct snd_tplg_channel_elem {
 824         int size;       /*!< size in bytes of this structure */
 825         int reg;        /*!< channel control register */
 826         int shift;      /*!< channel shift for control bits */
 827         int id;         /*!< ID maps to Left, Right, LFE etc */
 828 };
 829
 830 /** \struct snd_tplg_channel_map_template
 831  * \brief Template type for channel mapping.
 832  */
 833 struct snd_tplg_channel_map_template {
 834         int num_channels;       /*!< number of channel mappings */
 835         struct snd_tplg_channel_elem channel[SND_TPLG_MAX_CHAN];        /*!< mapping */
 836 };
 837
 838 /** \struct snd_tplg_pdata_template
 839  * \brief Template type for private data objects.
 840  */
 841 struct snd_tplg_pdata_template {
 842         unsigned int length;    /*!< data length */
 843         const void *data;       /*!< data */
 844 };
 845
 846 /** \struct snd_tplg_io_ops_template
 847  * \brief Template type for object operations mapping.
 848  */
 849 struct snd_tplg_io_ops_template {
 850         int get;        /*!< get callback ID */
 851         int put;        /*!< put callback ID */
 852         int info;       /*!< info callback ID */
 853 };
 854
 855 /** \struct snd_tplg_ctl_template
 856  * \brief Template type for control objects.
 857  */
 858 struct snd_tplg_ctl_template {
 859         int type;               /*!< Control type */
 860         const char *name;       /*!< Control name */
 861         int access;             /*!< Control access */
 862         struct snd_tplg_io_ops_template ops;    /*!< operations */
 863         struct snd_tplg_tlv_template *tlv; /*!< non NULL means we have TLV data */
 864 };
 865
 866 /** \struct snd_tplg_mixer_template
 867  * \brief Template type for mixer control objects.
 868  */
 869 struct snd_tplg_mixer_template {
 870         struct snd_tplg_ctl_template hdr;       /*!< control type header */
 871         struct snd_tplg_channel_map_template *map;      /*!< channel map */
 872         int min;        /*!< min value for mixer */
 873         int max;        /*!< max value for mixer */
 874         int platform_max;       /*!< max value for platform control */
 875         int invert;     /*!< whether controls bits are inverted */
 876         struct snd_soc_tplg_private *priv;      /*!< control private data */
 877 };
 878
 879 /** \struct snd_tplg_enum_template
 880  * \brief Template type for enumerated control objects.
 881  */
 882 struct snd_tplg_enum_template {
 883         struct snd_tplg_ctl_template hdr;       /*!< control type header */
 884         struct snd_tplg_channel_map_template *map;      /*!< channel map */
 885         int items;      /*!< number of enumerated items in control */
 886         int mask;       /*!< register mask size */
 887         const char **texts;     /*!< control text items */
 888         const int **values;     /*!< control value items */
 889         struct snd_soc_tplg_private *priv;      /*!< control private data */
 890 };
 891
 892 /** \struct snd_tplg_bytes_template
 893  * \brief Template type for TLV Scale objects.
 894  */
 895 struct snd_tplg_bytes_template {
 896         struct snd_tplg_ctl_template hdr;       /*!< control type header */
 897         int max;                /*!< max byte control value */
 898         int mask;               /*!< byte control mask */
 899         int base;               /*!< base register */
 900         int num_regs;           /*!< number of registers */
 901         struct snd_tplg_io_ops_template ext_ops;        /*!< ops mapping */
 902         struct snd_soc_tplg_private *priv;      /*!< control private data */
 903 };
 904
 905 /** \struct snd_tplg_graph_elem
 906  * \brief Template type for single DAPM graph element.
 907  */
 908 struct snd_tplg_graph_elem {
 909         const char *src;        /*!< source widget name */
 910         const char *ctl;        /*!< control name or NULL if no control */
 911         const char *sink;       /*!< sink widget name */
 912 };
 913
 914 /** \struct snd_tplg_graph_template
 915  * \brief Template type for array of DAPM graph elements.
 916  */
 917 struct snd_tplg_graph_template {
 918         int count;              /*!< Number of graph elements */
 919         struct snd_tplg_graph_elem elem[0];     /*!< graph elements */
 920 };
 921
 922 /** \struct snd_tplg_widget_template
 923  * \brief Template type for DAPM widget objects.
 924  */
 925 struct snd_tplg_widget_template {
 926         int id;                 /*!< SND_SOC_DAPM_CTL */
 927         const char *name;       /*!< widget name */
 928         const char *sname;      /*!< stream name (certain widgets only) */
 929         int reg;                /*!< negative reg = no direct dapm */
 930         int shift;              /*!< bits to shift */
 931         int mask;               /*!< non-shifted mask */
 932         int subseq;             /*!< sort within widget type */
 933         unsigned int invert;            /*!< invert the power bit */
 934         unsigned int ignore_suspend;    /*!< kept enabled over suspend */
 935         unsigned short event_flags;     /*!< PM event sequence flags */
 936         unsigned short event_type;      /*!< PM event sequence type */
 937         struct snd_soc_tplg_private *priv;      /*!< widget private data */
 938         int num_ctls;                   /*!< Number of controls used by widget */
 939         struct snd_tplg_ctl_template *ctl[0];   /*!< array of widget controls */
 940 };
 941
 942 /** \struct snd_tplg_stream_template
 943  * \brief Stream configurations.
 944  */
 945 struct snd_tplg_stream_template {
 946         const char *name;       /*!< name of the stream config */
 947         int format;             /*!< SNDRV_PCM_FMTBIT_* */
 948         int rate;               /*!< SNDRV_PCM_RATE_* */
 949         int period_bytes;       /*!< size of period in bytes */
 950         int buffer_bytes;       /*!< size of buffer in bytes. */
 951         int channels;           /*!< number of channels */
 952 };
 953
 954 /** \struct snd_tplg_stream_caps_template
 955  * \brief Stream Capabilities.
 956  */
 957 struct snd_tplg_stream_caps_template {
 958         const char *name;       /*!< name of the stream caps */
 959         uint64_t formats;       /*!< supported formats SNDRV_PCM_FMTBIT_* */
 960         unsigned int rates;     /*!< supported rates SNDRV_PCM_RATE_* */
 961         unsigned int rate_min;  /*!< min rate */
 962         unsigned int rate_max;  /*!< max rate */
 963         unsigned int channels_min;      /*!< min channels */
 964         unsigned int channels_max;      /*!< max channels */
 965         unsigned int periods_min;       /*!< min number of periods */
 966         unsigned int periods_max;       /*!< max number of periods */
 967         unsigned int period_size_min;   /*!< min period size bytes */
 968         unsigned int period_size_max;   /*!< max period size bytes */
 969         unsigned int buffer_size_min;   /*!< min buffer size bytes */
 970         unsigned int buffer_size_max;   /*!< max buffer size bytes */
 971         unsigned int sig_bits;          /*!< number of bits of content */
 972 };
 973
 974 /** \struct snd_tplg_pcm_template
 975  * \brief Template type for PCM (FE DAI & DAI links).
 976  */
 977 struct snd_tplg_pcm_template {
 978         const char *pcm_name;   /*!< PCM stream name */
 979         const char *dai_name;   /*!< DAI name */
 980         unsigned int pcm_id;    /*!< unique ID - used to match */
 981         unsigned int dai_id;    /*!< unique ID - used to match */
 982         unsigned int playback;  /*!< supports playback mode */
 983         unsigned int capture;   /*!< supports capture mode */
 984         unsigned int compress;  /*!< 1 = compressed; 0 = PCM */
 985         struct snd_tplg_stream_caps_template *caps[2]; /*!< playback & capture for DAI */
 986         unsigned int flag_mask; /*!< bitmask of flags to configure */
 987         unsigned int flags;     /*!< flag value SND_SOC_TPLG_LNK_FLGBIT_* */
 988         struct snd_soc_tplg_private *priv;      /*!< private data */
 989         int num_streams;        /*!< number of supported configs */
 990         struct snd_tplg_stream_template stream[0]; /*!< supported configs */
 991 };
 992
 993  /** \struct snd_tplg_hw_config_template
 994  * \brief Template type to describe a physical link runtime supported
 995  * hardware config, i.e. hardware audio formats.
 996  */
 997 struct snd_tplg_hw_config_template {
 998         int id;                         /* unique ID - - used to match */
 999         unsigned int fmt;               /* SND_SOC_DAI_FORMAT_ format value */
1000         unsigned char clock_gated;      /* 1 if clock can be gated to save power */
1001         unsigned char  invert_bclk;     /* 1 for inverted BCLK, 0 for normal */
1002         unsigned char  invert_fsync;    /* 1 for inverted frame clock, 0 for normal */
1003         unsigned char  bclk_master;     /* 1 for master of BCLK, 0 for slave */
1004         unsigned char  fsync_master;    /* 1 for master of FSYNC, 0 for slave */
1005         unsigned char  mclk_direction;  /* 0 for input, 1 for output */
1006         unsigned short reserved;        /* for 32bit alignment */
1007         unsigned int mclk_rate;         /* MCLK or SYSCLK freqency in Hz */
1008         unsigned int bclk_rate;         /* BCLK freqency in Hz */
1009         unsigned int fsync_rate;        /* frame clock in Hz */
1010         unsigned int tdm_slots;         /* number of TDM slots in use */
1011         unsigned int tdm_slot_width;    /* width in bits for each slot */
1012         unsigned int tx_slots;          /* bit mask for active Tx slots */
1013         unsigned int rx_slots;          /* bit mask for active Rx slots */
1014         unsigned int tx_channels;       /* number of Tx channels */
1015         unsigned int *tx_chanmap;       /* array of slot number */
1016         unsigned int rx_channels;       /* number of Rx channels */
1017         unsigned int *rx_chanmap;       /* array of slot number */
1018 };
1019
1020 /** \struct snd_tplg_dai_template
1021  * \brief Template type for physical DAI.
1022  * It can be used to configure backend DAIs for DPCM.
1023  */
1024 struct snd_tplg_dai_template {
1025         const char *dai_name;   /*!< DAI name */
1026         unsigned int dai_id;    /*!< unique ID - used to match */
1027         unsigned int playback;  /*!< supports playback mode */
1028         unsigned int capture;   /*!< supports capture mode */
1029         struct snd_tplg_stream_caps_template *caps[2]; /*!< playback & capture for DAI */
1030         unsigned int flag_mask; /*!< bitmask of flags to configure */
1031         unsigned int flags;     /*!< SND_SOC_TPLG_DAI_FLGBIT_* */
1032         struct snd_soc_tplg_private *priv;      /*!< private data */
1033
1034 };
1035
1036 /** \struct snd_tplg_link_template
1037  * \brief Template type for physical DAI Links.
1038  */
1039 struct snd_tplg_link_template {
1040         const char *name;       /*!< link name, used to match */
1041         int id; /*!< unique ID - used to match with existing physical links */
1042         const char *stream_name;        /*!< link stream name, used to match */
1043
1044         int num_streams;        /*!< number of configs */
1045         struct snd_tplg_stream_template *stream;       /*!< supported configs */
1046
1047         struct snd_tplg_hw_config_template *hw_config; /*!< supported HW configs */
1048         int num_hw_configs;             /* number of hw configs */
1049         int default_hw_config_id;       /* default hw config ID for init */
1050
1051         unsigned int flag_mask;         /* bitmask of flags to configure */
1052         unsigned int flags;             /* SND_SOC_TPLG_LNK_FLGBIT_* flag value */
1053         struct snd_soc_tplg_private *priv; /*!< private data */
1054 };
1055
1056 /** \struct snd_tplg_obj_template
1057  * \brief Generic Template Object
1058  */
1059 typedef struct snd_tplg_obj_template {
1060         enum snd_tplg_type type;        /*!< template object type */
1061         int index;              /*!< group index for object */
1062         int version;            /*!< optional vendor specific version details */
1063         int vendor_type;        /*!< optional vendor specific type info */
1064         union {
1065                 struct snd_tplg_widget_template *widget;        /*!< DAPM widget */
1066                 struct snd_tplg_mixer_template *mixer;          /*!< Mixer control */
1067                 struct snd_tplg_bytes_template *bytes_ctl;      /*!< Bytes control */
1068                 struct snd_tplg_enum_template *enum_ctl;        /*!< Enum control */
1069                 struct snd_tplg_graph_template *graph;          /*!< Graph elements */
1070                 struct snd_tplg_pcm_template *pcm;              /*!< PCM elements */
1071                 struct snd_tplg_link_template *link;            /*!< physical DAI Links */
1072                 struct snd_tplg_dai_template *dai;              /*!< Physical DAI */
1073         };
1074 } snd_tplg_obj_template_t;
1075
1076 /**
1077  * \brief Register topology template object.
1078  * \param tplg Topology instance.
1079  * \param t Template object.
1080  * \return Zero on success, otherwise a negative error code
1081  */
1082 int snd_tplg_add_object(snd_tplg_t *tplg, snd_tplg_obj_template_t *t);
1083
1084 /**
1085  * \brief Build all registered topology data into binary file.
1086  * \param tplg Topology instance.
1087  * \param outfile Binary topology output file.
1088  * \return Zero on success, otherwise a negative error code
1089  */
1090 int snd_tplg_build(snd_tplg_t *tplg, const char *outfile);
1091
1092 /**
1093  * \brief Attach private data to topology manifest.
1094  * \param tplg Topology instance.
1095  * \param data Private data.
1096  * \param len Length of data in bytes.
1097  * \return Zero on success, otherwise a negative error code
1098  */
1099 int snd_tplg_set_manifest_data(snd_tplg_t *tplg, const void *data, int len);
1100
1101 /**
1102  * \brief Set an optional vendor specific version number.
1103  * \param tplg Topology instance.
1104  * \param version Vendor specific version number.
1105  * \return Zero on success, otherwise a negative error code
1106  */
1107 int snd_tplg_set_version(snd_tplg_t *tplg, unsigned int version);
1108
1109 /* \} */
1110
1111 #ifdef __cplusplus
1112 }
1113 #endif
1114
1115 #endif /* __ALSA_TOPOLOGY_H */