View source for IOAudio2Transformer

'''IOAudio2Transformer''' is a kernel-extension for encoding/decoding audio.

It's interacted with exclusively by CoreAudio, so it can't be used directly if CoreAudio is in the picture.

The service has two child services - both of class '''IOAudio2TransformerStream'''. 
One is input and the other is output.


== Service Properties ==

IOAudio2Transformer:
{| class="wikitable"
|-
! Name !! R/W !! Contents
|-
| input format || W || Format dictionary
|-
| output format || W || Format dictionary
|}

IOAudio2TransformerStream:
{| class="wikitable"
|-
! Name !! R/W !! Contents
|-
| is input || R || 1 if input stream, 0 if output stream.
|}

Format dictionary argument:

(For more info, see ioreg of IOAudio2Device)
{| class="wikitable"
|-
! Key !! Description
|-
| format ID || Same as in AudioStreamBasicDescription
|-
| frames per packet ||
|-
| bytes per frame ||
|-
| bytes per packet ||
|-
| channels per frame ||
|-
| bits per channel ||
|-
| format flags || Same as in AudioStreamBasicDescription
|-
| sample rate
|}

== Methods ==
IOAudio2Transformer:
{| class="wikitable"
|-
! Selector !! Action !! Input !! Output
|-
| 0 || startSetup || - || -
|-
| 1 || endSetup || - || -
|-
| 2 || resetSetup || - || -
|-
| 3 || flush || - || -
|-
| 4 || stop || - || -
|}

IOAudio2TransformerStream:
{| class="wikitable"
|-
! Selector !! Action !! Input !! Output
|-
| 0 || start || - || -
|-
| 1 || end || - || -
|}

== Traps ==

IOAudio2TransformerStream:
{| class="wikitable"
|-
! Selector !! Description || Args
|-
| 0 || Signals there's data in the input queue || -
|}

== Mapped Memory ==
The following memory can be mapped via IOConnectMapMemory into each of the IOAudio2TransformerStream-s:

{| class="wikitable"
|-
! Type !! Description !! Format
|-
| 0x10000000 || output queue || struct IOAudio2TransformerQueue
|-
| 0x20000000 || input queue || struct IOAudio2TransformerQueue
|-
| 0x30000000 + bufferId || data buffer || raw data
|-
| 0x40000000 + bufferId || control buffer || struct IOAudio2TransformerControlBuffer
|}

where 

<source lang="C">
struct IOAudio2TransformerQueue {
  uint32_t count;
  uint32_t reader; // index to 'nodes'
  uint32_t writer; // index to 'nodes'
  uint32_t ???[2];

  struct Node {
    uint32_t bufferId;
    uint32_t dataSize; // 0 for queues that store "free" buffers
    uint32_t ???[2];

  } nodes[count];
};

struct IOAudio2TransformerControlBuffer {
  uint64_t numPackets;
  struct AudioStreamPacketDescriptions packetDescriptions[numPackets]; // officially documented struct
};
</source>

== Operation ==
The IOAudio2Transformer's startSetup method is called, then the "input format" and "output format" service properties are set.

Once endSetup is called and the streams are started:
* The queues of both streams are cleared.
* The output queue of the input stream is filled with entry for each buffer (representing a free buffer)
* The input queue of the output stream is filled with entry for each buffer (representing a free buffer)

Now, user-land simultaneously:
* Dequeues any free buffers from the output queue of the input stream, fills them with input data, and enqueues them to the input queue of the input stream.
* Dequeues any buffers from the output queue of the output stream, reads the output data from them, and enqueues them to the input queue of the output stream.

While the driver:
* Dequeues a buffer from the input queue of the input stream, this contains the input data.
* Dequeues a free buffer from the input queue of the output stream.
* Transformers the input data to output data according to the input/output formats. The output data is placed in the free buffer dequeued above.
* Enqueues the previously-free buffer in the output queue of the output stream.

Notes:
* For each buffer, its data can be accessed/modified by mapping its data buffer and reading/writing to it.
* For each buffer, its packet descriptions can be accessed/modified by mapping its control buffer and reading/writing to it.

{{occlass|library=IOKit.framework|navbox=1}}