IOCTLS
======

* HDA_IOCTL_PVERSION

  Returns the version protocol as 32bit int.
  (major << 16) | (minor << 8) | (tiny)

* HDA_IOCTL_GET_STATUS
  HDA_IOCTL_SET_STATUS

  Gets / sets the current running status, either
  HDA_STATUS_UNINITIALIZED or HDA_STATUS_RUNNING.
  When the configurater finishes the setup, it has to set the status
  to set to HDA_STATUS_RUNNING.  Then the driver will register the
  device files visible in return.

  The only way to return to the uninitialized status is to call RESET
  ioctl below.

* HDA_IOCTL_GET_CODEC_INFO
  HDA_IOCTL_SET_CODEC_INFO

  Gets / sets struct hda_codec_info record.  Most of fields are
  read-only and given from the driver initially.  The vendor_id,
  subsystem_id, revision_id fields specify the ids of codecs.
  The pci_* fields are PCI IDs.
  The codec_addr is the assigned codec address (zero-based).  The afg
  and mfg are AFG and MFG node IDs.  The num_nodes contains the total
  number of widget nodes, start_nid contains the ID of the first
  widget.
  The rest, name and spec fields, are for the user-space tools.  When
  the name field is changed, it's reflected to the mixer name of the
  driver automatically.  The spec field can be used freely by the
  user-space tools.

* HDA_IOCTL_VERB_WRITE

  Writes and reads a HDA verb.  It writes a verb in 32bit int
  (use HDA_VERB() macro to compose nid, verb and parameter) stored in
  struct hda_verb_ioctl.verb field.  The response from the codec is
  stored in res field in return.

* HDA_IOCTL_GET_WCAP

  Gets the widget capability bits of the corresponding widget node.
  This is a fast operation referring a cache without issuing the real
  HD-audio verbs.  The NID of the widget should be placed in 24bit of
  struct hda_verb_ioctl.verb field (use HDA_VERB() macro as well), and
  the capability bits are stored in res field in return.

* HDA_IOCTL_CMD_EXEC

  Out-of-bound execution of the given TLV-command.

* HDA_IOCTL_ADD_MIXER

  Adds a mixer element with the corresponding type and value.
  The parameter must begin with struct hda_mixer_head, which contains
  iface, device, subdevice, name and index fields to specify the mixer
  element ID (equivalent with struct snd_ctl_elem_id), and type field
  to specify the type of this mixer element (HDA_MIXER_TYPE_*).  The
  numid field should be zero at call, and the non-zero value is stored
  in return.

  The rest bytes depend on the mixer type.

  - HDA_MIXER_TYPE_VOLUME
  - HDA_MIXER_TYPE_SWITCH

    A mixer controlling volume(s) or switch(s) of a single amp
    widget.  As an argument, pass a 32bit int, composed from
    HDA_COMPOSE_AMP_VAL() macro. 
    HDA_CODEC_VOLUME*() and HDA_CODEC_MUTE*() macros are available to
    create a std_mxier instance easily (see below).

  - HDA_MIXER_TYPE_BIND_VOLUME
  - HDA_MIXER_TYPE_BIND_SWITCH

    A mixer controlling volumes/switch of multiple amp widgets.  Each
    widget has to have identical amp capability (the driver doesn't
    check, though).  As an argument, pass 32bit int array terminated
    by zero.  Each value corresponds to a composed value of
    HDA_COMPOSE_AMP_VAL() like above.

 - HDA_MIXER_TYPE_ENUM

   A generic enumeration mixer.  It can execute an arbitrary (TLV)
   command for each corresponding item.  Pass the TLV list that
   consists of pairs of label and command TLVs,
     LABEL CMD LABEL CMD ...
   where LABEL is a string-TLV element and CMD is a command-TLV
   element to execute when the previous label is selected.

 - HDA_MIXER_TYPE_BOOLEAN

   A generic boolean mixer.  It can execute an arbitrary (TLV) command
   for each, true or false case.  Pass the TLV list that consists of
   command pairs for false and true, respectively.

* HDA_IOCTL_ADD_PCM

  Adds a PCM with the given type.  Pass struct hda_usr_pcm_info as an
  argument.  The type of the PCM to create is specified in type field
  (HDA_PCM_TYPE_*).  The number of substreams is set to substreams
  field, usually 1.  The min/max number of channels are set to
  channels_min and channels_max fields.  The minimal number should be
  2.  When nid is non-zero, the default values of rates, maxbps and
  formats are parsed from the widget PCM capability.

  The assoc_nids contains the NIDs of audio in/out widgets associated
  to this stream.  When the stream is a multi-channel one, multiple
  NIDs have to be specified here.  The extra_nids are audio i/o
  widgets to be copied (e.g. for headphone or extra speaker).

  The name has to be non-empty.  It should contain the same string for
  both playback and capture streams with the same device number.  The
  device field specifies the device number that this PCM is assigned.

* HDA_IOCTL_ADD_INIT

  Adds a TLV command to execute for initialization.  This command is
  executed automatically also at PM resume.

* HDA_IOCTL_ADD_RESUME

  Adds an extra TLV command to execute for resume.

* HDA_IOCTL_ADD_UNSOL

  Adds an unsolicited event handler.  It passes struct hda_unsol_ioctl
  containing nid, tag and shift fields, followed by a TLV command to
  execute by the handler (typically a jack-presence event).  The nid
  field specifies the widget NID triggering unsolicited events.  The
  tag is the assigned tag number.  The shift is the bits to be shifted
  from the response verb, usually 26.  This might be different,
  depending on codec chips.  For example, it's 28 for ALC880.
  When an unsol event is registered, the driver issues
  AC_VERB_SET_UNSOLICITED_ENABLE verb automatically to the
  corresponding widget.

* HDA_IOCTL_RESET

  Resets the whole set up and returns to the uninitialized status.
  All init cmds, mixers and PCMs are released.


TLV
===

The commands to be executed by some ioctls are specified in a form of
TLV (type-length-value) record.  It begins with a 16bit integer
specifying the type of the record, then a 16bit integer specifying the
size of the record data (without this 4bytes header).  The rest is an
arbitrary data, varies depending on the type.  The length is always
aligned (round up) to 4.

The following TLV types are available:

 * HDA_CMD_TYPE_NOP

   A place holder.  Do nothing.

 * HDA_CMD_TYPE_CMDS

   Executes the child TLV entries sequentially.  It's a list of TLVs,
  i.e
     HDA_CMD_TYPE_CMDS length TLV1 TLV2 ...

 * HDA_CMD_TYPE_VERBS

   Writes the HD-audio verbs sequentially.  The last verb is
   synchronized and the response from the codec is read.  This value
   can be used by other commands like VERB_UPDATE, AMP_UPDATE.

 * HDA_CMD_TYPE_AMP_READ

   Reads a volume value from the amp widget.  It takes a child TLV
   representing an integer value, which corresponds to HDA_AMP_IDX()
   macro.  The return value is from 0 to 0xff, masked with the given
   value in the first argument.

 * HDA_CMD_TYPE_VERB_UPDATE

   Updates bits of the given HDA verb.  This contains two child TLV
   entries.  The first one specifies NID, verb and mask bits in 32bit
   integer, as composed via HDA_VERB() where param corresponds to the
   bit mask to change.  This is typically set via HDA_CMD_TYPE_INT
   command below.  The second one specifies the bit value to be
   updated.  This can be a value returned from HDA_CMD_TYPE_VERBS, for
   example.

 * HDA_CMD_TYPE_AMP_UPDATE

   Similar to VERB_UPDATE command but applied to an amp widget.
   The first value is an integer composed by HDA_AMP_IDX() macro.
   The second value is the value to write.

 * HDA_CMD_TYPE_CTL_NOTIFY

   Notifies an event to the given mixer element via control API.  It
   takes a TLV giving the mixer numid to notify.

 * HDA_CMD_TYPE_SET_CHANNELS

   Sets the number of channels for multi-channel playback.  It takes a
   child TLV indicating the number of channels, which should be an
   integer (e.g. 2, 4, 6).

 * HDA_CMD_TYPE_INT

   Returns the given integer value.

 * HDA_CMD_TYPE_LABEL

   Returns the given string.  Not executable.

 * HDA_CMD_TYPE_LIST

   Returns the list of TLVs.  Used for ENUM and BOOLEAN mixer types.
   Not executable.

 * HDA_CMD_TYPE_IF

   Takes two or three arguments.  The first argument is the condition.
   If this value is non-zero, the second argument is evaluated.
   If the condition is zero and the third argument exists, then the
   third argument is evaluated.

 * HDA_CMD_TYPE_AND
   HDA_CMD_TYPE_OR

   Bitwise AND (&) and OR (|) operations.  Returns the integer value.

 * HDA_CMD_TYPE_NOT

   Bitwise NOT (~) operation.

 * HDA_CMD_TYPE_PLUS
   HDA_CMD_TYPE_MINUS

   Arithmetic plus (+) and minus (-) operations.

 * HDA_CMD_TYPE_SHIFTL
   HDA_CMD_TYPE_SHIFTR

   Left bit-shift (<<) and right bit-shift (>>) operations.

 * HDA_CMD_TYPE_LAND
   HDA_CMD_TYPE_LOR

   Logical AND (&&) and OR (&&) operations.  This can take two or more
   arguments.

 * HDA_CMD_TYPE_LNOT

   Logical NOT (!) operation.

 * HDA_CMD_TYPE_GET_REG

   Returns the value of the user-defined variable with the given index
   Takes an argument (evaluated) as an index.
   The driver can hold up to HDA_MAX_USER_REGS (32) values that can be
   used arbitrarily.

 * HDA_CMD_TYPE_SET_REG

   Takes two arguments, the first for the index and the second for the
   value to set.
   
