1{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf280 2{\fonttbl\f0\fswiss\fcharset0 Helvetica;} 3{\colortbl;\red255\green255\blue255;} 4\pard\tx1440\tx2880\tx4320\tx5760\tx7200\ql\qnatural 5 6\f0\fs24 \cf0 \ 7\pard\tx1440\tx2880\tx4320\tx5760\tx7200\ql\qnatural 8 9\b \cf0 IOAudioFamily 1.1 10\b0 \ 11\ 12 13\b \ 14\pard\tx360\tx2880\tx4320\tx5760\tx7200\ql\qnatural 15\cf0 I. Contents 16\b0 \ 17\ 18\pard\tx540\tx2880\tx4320\tx5760\tx7200\li540\fi-180\ql\qnatural 19\cf0 - /System/Library/Extensions/IOAudioFamily.kext\ 20- /System/Library/Frameworks/\ 21\pard\tx540\tx2880\tx4320\tx5760\tx7200\li720\ql\qnatural 22\cf0 Kernel.framework/Headers/IOKit/audio/\ 23\pard\tx540\tx2880\tx4320\tx5760\tx7200\li1080\ql\qnatural 24\cf0 IOAudioControl.h\ 25IOAudioControlUserClient.h\ 26IOAudioDebug.h\ 27IOAudioDefines.h\ 28IOAudioDevice.h\ 29IOAudioEngine.h\ 30IOAudioEngineUserClient.h\ 31IOAudioPort.h\ 32IOAudioSelectorControl.h\ 33IOAudioStream.h\ 34IOAudioToggleControl.h\ 35IOAudioTypes.h\ 36\pard\tx540\tx2880\tx4320\tx5760\tx7200\li720\ql\qnatural 37\cf0 IOKit.framework/Headers/audio/\ 38\pard\tx540\tx2880\tx4320\tx5760\tx7200\li1080\ql\qnatural 39\cf0 IOAudioDefines.h\ 40IOAudioTypes.h\ 41\ 42\pard\tx540\tx2880\tx4320\tx5760\tx7200\li540\fi-180\ql\qnatural 43\cf0 - /Developer/Examples/IOKit/audio/\ 44\pard\tx540\tx2880\tx4320\tx5760\tx7200\li720\ql\qnatural 45\cf0 PhantomAudioDriver/\ 46\pard\tx540\tx2880\tx4320\tx5760\tx7200\li1080\ql\qnatural 47\cf0 English.lproj\ 48PhantomAudioClip.cpp\ 49PhantomAudioDevice.cpp\ 50PhantomAudioDevice.h\ 51PhantomAudioEngine.cpp\ 52PhantomAudioEngine.h\ 53PhantomAudioDriver.pbproj\ 54\pard\tx1440\tx2880\tx4320\tx5760\tx7200\ql\qnatural 55 56\i \cf0 \ 57\ 58\pard\tx360\tx2880\tx4320\tx5760\tx7200\ql\qnatural 59 60\i0\b \cf0 II. Changes\ 61\ 62 IOAudioFamily-1.1d27 to IOAudioFamily-1.1fc3\ 63 64\b0 \ 65\pard\tx540\tx2880\tx4320\tx5760\tx7200\li540\fi-180\ql\qnatural 66\cf0 - Added clock source selector control subtype: kIOAudioSelectorControlSubTypeClockSource to identify clock source selector controls.\ 67- Fixed a bug in IOAudioEngine::takeTimeStamp() that caused it to ignore the timestamp argument if present.\ 68- Fixed a bug in IOAudioEngineUserClient::stopClientAction() that caused it to always return kIOReturnBadArgument\ 69- Fixed a bug in IOAudioEngine::updateChannelNumbers() which caused input and passthru controls on the last channel to get a -1 channel number instead of the correct one. This caused the HAL to ignore those controls.\ 70- Fixed some minor locking issues\ 71- Added a watchdog timer which will fire if a client takes too long to perform output. This prevents glitching in other apps playing audio if one app is misbehaving. \ 72\pard\tx360\tx2880\tx4320\tx5760\tx7200\ql\qnatural 73 74\b \cf0 \ 75 IOAudioFamily-1.1d19 to IOAudioFamily-1.1d27\ 76 77\b0 \ 78\pard\tx540\tx2880\tx4320\tx5760\tx7200\li540\fi-180\ql\qnatural 79\cf0 - Removed IOAudioManager class\ 80- Changes to the mix/clip API and semantics\ 81\pard\tx720\tx2880\tx4320\tx5760\tx7200\li720\fi-180\ql\qnatural 82\cf0 - Previously, the function IOAudioEngine::mixAndClip() was called each time samples were sent from any client. Each output sample was clipped once for each client and the order the the buffer of samples was called was not deterministic. It would frequently jump forward and backwards making it difficult to properly implement some types of DSP operations in the clipping function.\ 83- This has been changed so that the clip function is only called once all of the samples have been received from all clients. This insures that the clip function is called with a continuous stream of sample data. The one caveat is that if a new client starts up, the clip position will move backwards to the position at which that new client wants to start outputting samples. In that case, those first samples will be clipped a second time. When this occurs, a new function IOAudioEngine::resetClipFunction() is called to indication that the clip location is moving backwards.\ 84- The mix and clip functionality has been broken out into separate functions and the names of all of the mix, clip and input conversion functions have been changed:\ 85\pard\tx900\tx2880\tx4320\tx5760\tx7200\li900\fi-180\ql\qnatural 86\cf0 - IOAudioEngine::mixAndClip() has been removed\ 87- New function IOAudioEngine::mixOutputSamples() called to mix in new samples\ 88- IOAudioEngine::clipToOutputStream() renamed to clipOutputSamples()\ 89- IOAudioEngine::convertFromInputStream() renamed to convertInputSamples()\ 90\pard\tx720\tx2880\tx4320\tx5760\tx7200\li720\fi-180\ql\qnatural 91\cf0 - The IOAudioStream class has been extended to allow a custom clip or input conversion function or list of functions to be specified on a per-stream basis (new type IOAudioStream::AudioIOFunction).\ 92- Each allowable format in each IOAudioStream can have a custom clip/input function or list of functions specified that will get set automatically when the format is selected.\ 93\pard\tx540\tx2880\tx4320\tx5760\tx7200\li540\fi-180\ql\qnatural 94\cf0 - Changed format changing semantics to automatically pause and resume the engine around the call to IOAudioEngine::performFormatChange(). \ 95- While paused, all aspects of the engine can now be changed (controls added or removed, numSampleFramesPerBuffer attribute, etc...)\ 96- Added IOAudioEngine::removeDefaultAudioControl()\ 97- Other IOAudioEngine changes:\ 98\pard\tx720\tx2880\tx4320\tx5760\tx7200\li720\fi-180\ql\qnatural 99\cf0 - Changed type of audioEngines var from OSSet to OSArray\ 100- Removed masterControls variable (not needed anymore)\ 101- Removed addMasterControl(), setMasterVolumeLeft(), setMasterVolumeRight() and setMasterMute()\ 102- Renamed deactivateAudioEngines() to deactivateAllAudioEngines()\ 103- Removed unsupported deactivateAudioEngine()\ 104- Renamed clearTimerEvents() to removeAllTimerEvents()\ 105- Renamed deactivateAudioPorts() to detachAllAudioPorts()\ 106- Renamed removeDefaultAudioControls() to removeAllDefaultAudioControls()\ 107\pard\tx540\tx2880\tx4320\tx5760\tx7200\li540\fi-180\ql\qnatural 108\cf0 - Removed master, setMaster() and isMaster() from IOAudioLevelControl and IOAudioToggleControl.\ 109- Added IOAudioEngine::hardwareSampleRateChanged() to be called when the hardware changes and the new sample rate is needed to be reflected to the rest of the system.\ 110- Added IOAudioStream::hardwareFormatChanged() to indicate that the format has changed.\ 111- Added support for a global unique ID to be assigned to each IOAudioEngine to allow each engine to be identified across reboots and detach/re-attach operations. \ 112\pard\tx720\tx2880\tx4320\tx5760\tx7200\li720\fi-180\ql\qnatural 113\cf0 - New IOAudioEngine functions: getGlobalUniqueID() and getLocalUniqueID()\ 114- getGlobalUniqueID() by default generates a unique ID string by concatenating the class name, the location of audioDevice->getProvider() (which ls the location within the provider's bus) and the result of getLocalUniqueID().\ 115- getLocalUniqueID() needs to generate a scoped ID that is local to the device. The default implementation returns an index based on the order that the IOAudioEngine was added to the IOAudioDevice. If that isn't sufficient to guarantee uniqueness for the engine, this should be overridden to provide a better ID. A case where this is necessary is the USB audio driver. Since a single driver/class may drive different pieces of hardware that could be plugged into the same port (and hence return the same location), it needs to provide another piece of information that is unique to each device.\ 116\pard\tx540\tx2880\tx4320\tx5760\tx7200\li540\fi-180\ql\qnatural 117\cf0 - Added IOAudioEngine::setDescription() to allow a custom description to be set on each IOAudioEngine.\ 118- Added IOAudioControl::setCoreAudioPropertyID() to allow an IOAudioControl to represent a custom CoreAudio property.\ 119\pard\tx720\tx2880\tx4320\tx5760\tx7200\li720\fi-180\ql\qnatural 120\cf0 - The HAL will pass thru CoreFoundation objects passed to AudioDeviceSetProperty(). They can be CFNumber, CFString, CFData, etc... and will be turned into OSObjects in the kernel: OSNumber, OSString, OSData, etc...\ 121- A new usage has been added to allow the HAL to recognize the controls which represent custom properties (kIOAudioControlUsageCoreAudioProperty).\ 122\pard\tx540\tx2880\tx4320\tx5760\tx7200\li540\fi-180\ql\qnatural 123\cf0 - Added IOAudioEngine::stopEngineAtPosition() as a convenience location where the family calls when it needs to stop the engine at a certain location (called when the last client has disconnected and the engine should stop at a point after it has played the specified samples). By default the function makes sure the timer is running and checks the current sample frame vs. the stop position and calls stopAudioEngine() if it is passed the stop position. This new function makes it easy for a driver to override that behavior if there is a different or better mechanism it wants to use to decide when to stop.\ 124\pard\tx720\tx2880\tx4320\tx5760\tx7200\li720\fi-180\ql\qnatural 125\cf0 \ 126\ 127\pard\tx360\tx2880\tx4320\tx5760\tx7200\ql\qnatural 128 129\b \cf0 III. Future Plans 130\b0 \ 131\ 132\pard\tx540\tx2880\tx4320\tx5760\tx7200\li540\fi-180\ql\qnatural 133\cf0 - All planned API changes are complete for IOAudioFamily-1.1fc3, however final API review and any final functionality additions may necessitate small API changes before IOAudioFamily-1.1 final.\ 134- Headerdoc for all classes will be completed 135\i \ 136\pard\tx1440\tx2880\tx4320\tx5760\tx7200\ql\qnatural 137 138\i0 \cf0 \ 139\ 140\pard\tx360\tx2880\tx4320\tx5760\tx7200\ql\qnatural 141 142\b \cf0 IV. Getting Started 143\b0 \ 144\ 145\pard\tx540\tx2880\tx4320\tx5760\tx7200\li540\fi-180\ql\qnatural 146\cf0 - Read the headerdoc class descriptions of IOAudioDevice, IOAudioEngine, IOAudioControl and IOAudioStream\ 147- Look over the examples and templates. The PhantomAudioDriver is fully functional.\ 148- Follow IOAudioFamily development in Darwin. The source repository is named IOAudioFamily and is live. The source for this specific version can be found by checking out tag IOAudioFamily-1-1d18.\ 149- Here is a list of what is needed for a fully functional driver:\ 150\pard\tx720\tx2880\tx4320\tx5760\tx7200\li720\fi-180\ql\qnatural 151\cf0 - Implement an IOAudioDevice subclass\ 152\pard\tx900\tx2880\tx4320\tx5760\tx7200\li900\fi-180\ql\qnatural 153\cf0 - Override initHardware()\ 154\pard\tx1080\tx2880\tx4320\tx5760\tx7200\li1080\fi-180\ql\qnatural 155\cf0 - Call setDeviceName(), setDeviceShortName(), setManufacturerName() at init time - typically in initHardware()\ 156- In initHardware() - create an instance of the driver's IOAudioEngine subclass for each I/O engine on the device and call activateAudioEngine() when each is ready to begin vending audio services to the system.\ 157- May create various IOAudioControls to control volume, mute, input selection, etc...\ 158\pard\tx1260\tx2880\tx4320\tx5760\tx7200\li1260\fi-180\ql\qnatural 159\cf0 - Call addDefaultAudioControl() on the appropriate audio engine for each control created\ 160- Implement a ValueChangeHandler for each control created. The handler gets called when the control's value needs to change. The hardware should be updated to the new value in the handler.\ 161\pard\tx1080\tx2880\tx4320\tx5760\tx7200\li1080\fi-180\ql\qnatural 162\cf0 - Perform any necessary hardware initialization\ 163\pard\tx720\tx2880\tx4320\tx5760\tx7200\li720\fi-180\ql\qnatural 164\cf0 - Implement an IOAudioEngine subclass\ 165\pard\tx900\tx2880\tx4320\tx5760\tx7200\li900\fi-180\ql\qnatural 166\cf0 - Override initHardware() (this gets called during the IOAudioDevice::activateAudioEngine() call)\ 167\pard\tx1080\tx2880\tx4320\tx5760\tx7200\li1080\fi-180\ql\qnatural 168\cf0 - Determine current sample rate and set it using setSampleRate()\ 169- Call setNumSampleFramesPerBuffer() to indicate the number of sample frames in each buffer serviced by this audio-I/O engine\ 170- Call setDescription()\ 171- Call setOutputSampleLatency()/setInputSampleLatency() to indicate how much latency exists on the input and output streams.\ 172- Call setSampleOffset() to make sure that the CoreAudio.framework stays at least the specified number of samples away from the I/O head.\ 173- Create an IOAudioStream instance for each sample buffer serviced by the audio engine\ 174\pard\tx1260\tx2880\tx4320\tx5760\tx7200\li1260\fi-180\ql\qnatural 175\cf0 - For each IOAudioStream, call addAvailableFormat() for each format to which the stream can be set. As part of the addAvailableFormat() call, the allowed sample rates for that format must be specified.\ 176- Once all formats have been added to an IOAudioStream, call setFormat() to indicate what the hardware is currently set to. Note that performFormatChange() will be called as a result of the setFormat() call. This will be fixed in the future.\ 177- Call setSampleBuffer() to pass the actual hardware sample buffer to the stream. If the sample buffer resides in main memory, it should be allocated here.\ 178\pard\tx1080\tx2880\tx4320\tx5760\tx7200\li1080\fi-180\ql\qnatural 179\cf0 - Perform any necessary hardware initialization\ 180\pard\tx900\tx2880\tx4320\tx5760\tx7200\li900\fi-180\ql\qnatural 181\cf0 - Override free() to free any resources allocated by this audio engine (like the sample buffer)\ 182- Implement performAudioEngineStart() and performAudioEngineStop() to start and stop the I/O process\ 183\pard\tx1080\tx2880\tx4320\tx5760\tx7200\li1080\fi-180\ql\qnatural 184\cf0 - In performAudioEngineStart(), call takeTimeStamp(false) to set the timestamp when the audio engine is started without incrementing the buffer loop count.\ 185\pard\tx900\tx2880\tx4320\tx5760\tx7200\li900\fi-180\ql\qnatural 186\cf0 - Implement getCurrentSampleFrame() to provide a sample counter\ 187\pard\tx1080\tx2880\tx4320\tx5760\tx7200\li1080\fi-180\ql\qnatural 188\cf0 - This value doesn't need to be exact, but should never be larger than the current sample counter.\ 189- This value is used for the erase head process and it will erase up to, but not including the sample frame returned by this function.\ 190- If the value is too large, sound data that hasn't been played will be erased.\ 191\pard\tx900\tx2880\tx4320\tx5760\tx7200\li900\fi-180\ql\qnatural 192\cf0 - Implement performFormatChange() if multiple formats or sample rates are allowed\ 193\pard\tx1080\tx2880\tx4320\tx5760\tx7200\li1080\fi-180\ql\qnatural 194\cf0 - It is possible that either the new format or sample rate pointer will be NULL in this function. That indicates that only the sample rate or format has changed.\ 195\pard\tx900\tx2880\tx4320\tx5760\tx7200\li900\fi-180\ql\qnatural 196\cf0 - Implement a mechanism to allow a new timestamp to be taken every time the audio engine loops to the beginning of the sample buffer.\ 197\pard\tx1080\tx2880\tx4320\tx5760\tx7200\li1080\fi-180\ql\qnatural 198\cf0 - Typically, hardware will throw an interrupt when this situation occurs. \ 199- In that interrupt routine, a simple call to takeTimeStamp() is all that's needed. That will get the current time and set it as the loop timestamp. It will also increment the loop count so that the CoreAudio.framework can keep track of where the audio engine is.\ 200\pard\tx900\tx2880\tx4320\tx5760\tx7200\li900\fi-180\ql\qnatural 201\cf0 - Implement clipOutputSamples() if an output IOAudioStream is present\ 202- Implement convertInputSamples() if an input IOAudioStream is present\ 203\pard\tx1080\tx2880\tx4320\tx5760\tx7200\li1080\fi-180\ql\qnatural 204\cf0 - Because these functions will be executing floating point code, they can't be included in the same source file as the other functions. By default, floating point emulation is enabled in the compiler which prevents floating point instructions from being generated. \ 205- To get around this, a separate library is created to contain the floating point code and is compiled and linked into the resulting kernel module. Take a look at the example code for an example of how to do this. Or better yet, use one of the sample drivers as a starting point and all of the work is done for you.\ 206\pard\tx900\tx2880\tx4320\tx5760\tx7200\li900\fi-180\ql\qnatural 207\cf0 \ 208\pard\tx1440\tx2880\tx4320\tx5760\tx7200\ql\qnatural 209 210\i \cf0 Copyright 2001-2010, Apple Computer, Inc. 211\i0 \ 212}