1/*
2 * Copyright (c) 1998-2010 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * The contents of this file constitute Original Code as defined in and
7 * are subject to the Apple Public Source License Version 1.1 (the
8 * "License").  You may not use this file except in compliance with the
9 * License.  Please obtain a copy of the License at
10 * http://www.apple.com/publicsource and read it before using this file.
11 *
12 * This Original Code and all software distributed under the License are
13 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
14 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
15 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
17 * License for the specific language governing rights and limitations
18 * under the License.
19 *
20 * @APPLE_LICENSE_HEADER_END@
21 */
22
23#ifndef _IOKIT_IOAUDIOSTREAM_H
24#define _IOKIT_IOAUDIOSTREAM_H
25
26#include <IOKit/IOService.h>
27#ifndef IOAUDIOFAMILY_SELF_BUILD
28#include <IOKit/audio/IOAudioEngine.h>
29#include <IOKit/audio/IOAudioTypes.h>
30#else
31#include "IOAudioEngine.h"
32#include "IOAudioTypes.h"
33#endif
34
35class OSSymbol;
36class OSArray;
37class OSDictionary;
38class OSSet;
39
40class IOCommandGate;
41class IOAudioControl;
42
43struct IOAudioClientBuffer;
44struct IOAudioStreamFormatDesc;
45
46/*!
47 * @class IOAudioStream
48 * @abstract This class wraps a single sample buffer in an audio driver.
49 * @discussion An IOAudioStream represents one hardware sample buffer as well as the direction
50 *  of that buffer, the mix buffer that multiple clients mix into as well as a list of
51 *  all of the formats to which this buffer can be set.
52 *
53 *  When an IOAudioEngine is created during init time in the driver, an IOAudioStream must be
54 *  created for each sample buffer in the device.  Typically, the sample buffer will be interleaved
55 *  (or single channel), as a non-interleaved buffer should be divided into multiple single-channel
56 *  buffers (and multiple IOAudioStreams).
57 *
58 *  Additionally, when an IOAudioStream is created it must have all of the possible formats (and
59 *  allowed sample rates for each format) set and must have the currently set format specified
60 *  (addAvailableFormat() and setFormat()).
61 */
62
63class IOAudioStream : public IOService
64{
65    OSDeclareDefaultStructors(IOAudioStream)
66
67    friend class IOAudioEngine;
68    friend class IOAudioEngineUserClient;
69
70public:
71
72    typedef IOReturn (*AudioIOFunction)(const void *mixBuf, void *sampleBuf, UInt32 firstSampleFrame, UInt32 numSampleFrames, const IOAudioStreamFormat *streamFormat, IOAudioStream *audioStream);
73
74    static const OSSymbol	*gDirectionKey;
75    static const OSSymbol	*gNumChannelsKey;
76    static const OSSymbol	*gSampleFormatKey;
77    static const OSSymbol	*gNumericRepresentationKey;
78    static const OSSymbol	*gBitDepthKey;
79    static const OSSymbol	*gBitWidthKey;
80    static const OSSymbol	*gAlignmentKey;
81    static const OSSymbol	*gByteOrderKey;
82    static const OSSymbol	*gIsMixableKey;
83    static const OSSymbol	*gDriverTagKey;
84    static const OSSymbol	*gMinimumSampleRateKey;
85    static const OSSymbol	*gMaximumSampleRateKey;
86
87    static void initKeys();
88
89    static OSDictionary *createDictionaryFromFormat(const IOAudioStreamFormat *streamFormat, const IOAudioStreamFormatExtension *formatExtension, OSDictionary *formatDict = 0);
90    static IOAudioStreamFormat *createFormatFromDictionary(const OSDictionary *formatDict, IOAudioStreamFormat *streamFormat = 0, IOAudioStreamFormatExtension *formatExtension = 0);
91
92    IOAudioEngine 				*audioEngine;
93    IOWorkLoop					*workLoop;
94    IOCommandGate				*commandGate;
95    IORecursiveLock				*streamIOLock;
96
97    UInt32						numClients;
98
99    IOAudioStreamDirection		direction;
100
101    IOAudioStreamFormat			format;
102    IOAudioStreamFormatDesc		*availableFormats;
103    OSArray						*availableFormatDictionaries;
104    UInt32						numAvailableFormats;
105
106    UInt32						startingChannelID;
107    UInt32						maxNumChannels;
108
109    void						*sampleBuffer;
110    UInt32						sampleBufferSize;
111
112    void						*mixBuffer;
113    UInt32						mixBufferSize;
114    bool						streamAllocatedMixBuffer;
115
116    AudioIOFunction				*audioIOFunctions;
117    UInt32						numIOFunctions;
118
119    bool						streamAvailable;
120
121    OSSet						*defaultAudioControls;
122
123    IOAudioEnginePosition		startingPosition;
124    IOAudioEnginePosition		clippedPosition;
125
126    IOAudioClientBuffer			*clientBufferListStart;
127    IOAudioClientBuffer			*clientBufferListEnd;
128
129    IOAudioClientBuffer			*userClientList;
130
131protected:
132
133    struct ExpansionData {
134		IOAudioStreamFormatExtension	streamFormatExtension;
135		UInt32							mSampleFramesReadByEngine;
136		IOReturn						mClipOutputStatus;
137	};
138
139    ExpansionData *reserved;
140
141public:
142// New code added here:
143	// OSMetaClassDeclareReservedUsed(IOAudioStream, 0);
144    virtual const IOAudioStreamFormatExtension *getFormatExtension();
145	// OSMetaClassDeclareReservedUsed(IOAudioStream, 1);
146    virtual IOReturn setFormat(const IOAudioStreamFormat *streamFormat, const IOAudioStreamFormatExtension *formatExtension, bool callDriver = true);
147	// OSMetaClassDeclareReservedUsed(IOAudioStream, 2);
148    virtual IOReturn setFormat(const IOAudioStreamFormat *streamFormat, const IOAudioStreamFormatExtension *formatExtension, OSDictionary *formatDict, bool callDriver = true);
149	// OSMetaClassDeclareReservedUsed(IOAudioStream, 3);
150    virtual void addAvailableFormat(const IOAudioStreamFormat *streamFormat, const IOAudioStreamFormatExtension *formatExtension, const IOAudioSampleRate *minRate, const IOAudioSampleRate *maxRate, const AudioIOFunction *ioFunctionList = NULL, UInt32 numFunctions = 0);
151	// OSMetaClassDeclareReservedUsed(IOAudioStream, 4);
152    virtual void addAvailableFormat(const IOAudioStreamFormat *streamFormat, const IOAudioStreamFormatExtension *formatExtension, const IOAudioSampleRate *minRate, const IOAudioSampleRate *maxRate, AudioIOFunction ioFunction);
153	// OSMetaClassDeclareReservedUsed(IOAudioStream, 5);
154    virtual bool validateFormat(IOAudioStreamFormat *streamFormat, IOAudioStreamFormatExtension *formatExtension, IOAudioStreamFormatDesc *formatDesc);
155	// OSMetaClassDeclareReservedUsed(IOAudioStream, 6);
156	virtual void setTerminalType(const UInt32 terminalType);
157	// OSMetaClassDeclareReservedUsed(IOAudioStream, 7);
158	virtual IOReturn mixOutputSamples(const void *sourceBuf, void *mixBuf, UInt32 firstSampleFrame, UInt32 numSampleFrames, const IOAudioStreamFormat *streamFormat, IOAudioStream *audioStream);
159	// OSMetaClassDeclareReservedUsed(IOAudioStream, 8);
160	virtual void setSampleLatency(UInt32 numSamples);
161	// OSMetaClassDeclareReservedUsed(IOAudioStream, 9);
162	virtual bool validateFormat(IOAudioStreamFormat *streamFormat, IOAudioStreamFormatExtension *formatExtension, IOAudioStreamFormatDesc *formatDesc, const IOAudioSampleRate *sampleRate);
163	// OSMetaClassDeclareReservedUsed(IOAudioStream, 10);
164	virtual UInt32 getNumSampleFramesRead();
165	// OSMetaClassDeclareReservedUsed(IOAudioStream, 11);
166	virtual void setDefaultNumSampleFramesRead(UInt32);
167
168private:
169    OSMetaClassDeclareReservedUsed(IOAudioStream, 0);
170    OSMetaClassDeclareReservedUsed(IOAudioStream, 1);
171    OSMetaClassDeclareReservedUsed(IOAudioStream, 2);
172    OSMetaClassDeclareReservedUsed(IOAudioStream, 3);
173    OSMetaClassDeclareReservedUsed(IOAudioStream, 4);
174    OSMetaClassDeclareReservedUsed(IOAudioStream, 5);
175    OSMetaClassDeclareReservedUsed(IOAudioStream, 6);
176    OSMetaClassDeclareReservedUsed(IOAudioStream, 7);
177    OSMetaClassDeclareReservedUsed(IOAudioStream, 8);
178    OSMetaClassDeclareReservedUsed(IOAudioStream, 9);
179    OSMetaClassDeclareReservedUsed(IOAudioStream, 10);
180    OSMetaClassDeclareReservedUsed(IOAudioStream, 11);
181
182    OSMetaClassDeclareReservedUnused(IOAudioStream, 12);
183    OSMetaClassDeclareReservedUnused(IOAudioStream, 13);
184    OSMetaClassDeclareReservedUnused(IOAudioStream, 14);
185    OSMetaClassDeclareReservedUnused(IOAudioStream, 15);
186    OSMetaClassDeclareReservedUnused(IOAudioStream, 16);
187    OSMetaClassDeclareReservedUnused(IOAudioStream, 17);
188    OSMetaClassDeclareReservedUnused(IOAudioStream, 18);
189    OSMetaClassDeclareReservedUnused(IOAudioStream, 19);
190    OSMetaClassDeclareReservedUnused(IOAudioStream, 20);
191    OSMetaClassDeclareReservedUnused(IOAudioStream, 21);
192    OSMetaClassDeclareReservedUnused(IOAudioStream, 22);
193    OSMetaClassDeclareReservedUnused(IOAudioStream, 23);
194    OSMetaClassDeclareReservedUnused(IOAudioStream, 24);
195    OSMetaClassDeclareReservedUnused(IOAudioStream, 25);
196    OSMetaClassDeclareReservedUnused(IOAudioStream, 26);
197    OSMetaClassDeclareReservedUnused(IOAudioStream, 27);
198    OSMetaClassDeclareReservedUnused(IOAudioStream, 28);
199    OSMetaClassDeclareReservedUnused(IOAudioStream, 29);
200    OSMetaClassDeclareReservedUnused(IOAudioStream, 30);
201    OSMetaClassDeclareReservedUnused(IOAudioStream, 31);
202    OSMetaClassDeclareReservedUnused(IOAudioStream, 32);
203    OSMetaClassDeclareReservedUnused(IOAudioStream, 33);
204    OSMetaClassDeclareReservedUnused(IOAudioStream, 34);
205    OSMetaClassDeclareReservedUnused(IOAudioStream, 35);
206    OSMetaClassDeclareReservedUnused(IOAudioStream, 36);
207    OSMetaClassDeclareReservedUnused(IOAudioStream, 37);
208    OSMetaClassDeclareReservedUnused(IOAudioStream, 38);
209    OSMetaClassDeclareReservedUnused(IOAudioStream, 39);
210    OSMetaClassDeclareReservedUnused(IOAudioStream, 40);
211    OSMetaClassDeclareReservedUnused(IOAudioStream, 41);
212    OSMetaClassDeclareReservedUnused(IOAudioStream, 42);
213    OSMetaClassDeclareReservedUnused(IOAudioStream, 43);
214    OSMetaClassDeclareReservedUnused(IOAudioStream, 44);
215    OSMetaClassDeclareReservedUnused(IOAudioStream, 45);
216    OSMetaClassDeclareReservedUnused(IOAudioStream, 46);
217    OSMetaClassDeclareReservedUnused(IOAudioStream, 47);
218
219public:
220    virtual bool initWithAudioEngine(IOAudioEngine *engine, IOAudioStreamDirection dir, UInt32 startChannelID, const char *streamDescription = NULL, OSDictionary *properties = 0);
221    virtual void free();
222
223    virtual void stop(IOService *provider);
224
225    virtual IOWorkLoop *getWorkLoop() const;
226
227    virtual IOReturn setProperties(OSObject *properties);
228
229    virtual IOAudioStreamDirection getDirection();
230
231    virtual void setSampleBuffer(void *buffer, UInt32 size);
232    virtual void *getSampleBuffer();
233    virtual UInt32 getSampleBufferSize();
234
235    virtual void setMixBuffer(void *buffer, UInt32 size);
236    virtual void *getMixBuffer();
237    virtual UInt32 getMixBufferSize();
238
239    virtual void numSampleFramesPerBufferChanged();
240
241    virtual void clearSampleBuffer();
242
243    virtual void setIOFunction(AudioIOFunction ioFunction);
244    virtual void setIOFunctionList(const AudioIOFunction *ioFunctionList, UInt32 numFunctions);
245
246    virtual const IOAudioStreamFormat *getFormat();
247    static IOReturn setFormatAction(OSObject *owner, void *arg1, void *arg2, void *arg3, void *arg4);
248	static IOReturn _setFormatAction(OSObject *target, void *arg0, void *arg1, void *arg2, void *arg3);	// <rdar://8568040,8691669>
249    virtual IOReturn setFormat(const IOAudioStreamFormat *streamFormat, bool callDriver = true);
250    virtual IOReturn setFormat(OSDictionary *formatDict);
251    virtual IOReturn setFormat(const IOAudioStreamFormat *streamFormat, OSDictionary *formatDict, bool callDriver = true);
252    virtual IOReturn hardwareFormatChanged(const IOAudioStreamFormat *streamFormat);
253    virtual void addAvailableFormat(const IOAudioStreamFormat *streamFormat, const IOAudioSampleRate *minRate, const IOAudioSampleRate *maxRate, const AudioIOFunction *ioFunctionList = NULL, UInt32 numFunctions = 0);
254    virtual void addAvailableFormat(const IOAudioStreamFormat *streamFormat, const IOAudioSampleRate *minRate, const IOAudioSampleRate *maxRate, AudioIOFunction ioFunction);
255    virtual void clearAvailableFormats();
256    virtual bool validateFormat(IOAudioStreamFormat *streamFormat, IOAudioStreamFormatDesc *formatDesc);
257
258    virtual UInt32 getStartingChannelID();
259    virtual UInt32 getMaxNumChannels();
260
261    virtual void setStreamAvailable(bool available);
262    virtual bool getStreamAvailable();
263
264    virtual IOReturn addDefaultAudioControl(IOAudioControl *defaultAudioControl);
265    virtual void removeDefaultAudioControls();
266
267protected:
268    virtual void lockStreamForIO();
269    virtual void unlockStreamForIO();
270
271    virtual void updateNumClients();
272    virtual IOReturn addClient(IOAudioClientBuffer *clientBuffer);
273    virtual void removeClient(IOAudioClientBuffer *clientBuffer);
274    virtual UInt32 getNumClients();
275
276    virtual IOReturn processOutputSamples(IOAudioClientBuffer *clientBuffer, UInt32 firstSampleFrame, UInt32 loopCount, bool samplesAvailable);
277    virtual IOReturn readInputSamples(IOAudioClientBuffer *clientBuffer, UInt32 firstSampleFrame);
278
279    virtual void resetClipInfo();
280    virtual void clipIfNecessary();
281    virtual void clipOutputSamples(UInt32 startingSampleFrame, UInt32 numSampleFrames);
282
283    virtual void setStartingChannelNumber(UInt32 channelNumber);
284
285private:
286    virtual void setDirection(IOAudioStreamDirection dir);
287
288};
289
290#endif /* _IOKIT_IOAUDIOSTREAM_H */
291