Return to IOAudioController.h CVS log

Up to [Apple XNU] / XNU / iokit / IOKit / audio

Annotation of XNU/iokit/IOKit/audio/IOAudioController.h, revision 1.1

1.1     ! root        1: /*
        !             2:  * Copyright (c) 1998-2000 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: /*!
        !            24:  * @header AudioController
        !            25:  * For controlling audio hardware, known as "codecs" to CPU S/W or "sound chips" or cards in the vernacular
        !            26:  * Including but not limited to streaming of data in and out, as well as control parameters and topology
        !            27:  */
        !            28: 
        !            29: #ifndef _IOAUDIOCONTOLLER_H
        !            30: #define _IOAUDIOCONTOLLER_H
        !            31: 
        !            32: #include <IOKit/IORegistryEntry.h>
        !            33: #include <IOKit/IOService.h>
        !            34: #include <IOKit/IOUserClient.h>
        !            35: #include <IOKit/audio/IOAudioParts.h>
        !            36: 
        !            37: /*!
        !            38:  * @class IOAudioController
        !            39:  * @abstract Base class for abstracting streaming, control, and topology of audio hardware
        !            40:  * @discussion Pressent a shared memory ring buffer for the DMA engine and provides auto erase capability
        !            41:  */
        !            42: class IOAudioController : public IOAudio
        !            43: {      
        !            44:     OSDeclareDefaultStructors(IOAudioController)
        !            45: 
        !            46: public:
        !            47:     /*!
        !            48:      * @function getMap
        !            49:      * @abstract Get access to sample buffer and status for a stream
        !            50:      * @param index
        !            51:      * @param map
        !            52:      * @result void
        !            53:      */
        !            54:     virtual void getMap(AudioStreamIndex index, IOAudioStreamMap * map);
        !            55: 
        !            56:     /*!
        !            57:      * @function releaseMap
        !            58:      * @abstract Call when done with stream
        !            59:      * @param index
        !            60:      * @result void
        !            61:      */
        !            62:     virtual void releaseMap(AudioStreamIndex index);
        !            63:     
        !            64:     /*!
        !            65:      * @function setFlow
        !            66:      * @abstract Control stream flow
        !            67:      * @param index
        !            68:      * @param flowing
        !            69:      * @result void
        !            70:      */
        !            71:      virtual void setFlow(AudioStreamIndex index, bool flowing);
        !            72: 
        !            73:     /*
        !            74:      * @function flushStream
        !            75:      * @abstract Set the ending stream position gauranteed to be played after all clients have disconnected
        !            76:      * @param endingPosition Ending position for the audio stream - gauranteed to be played
        !            77:      * @result void
        !            78:      */
        !            79:     virtual void flushStream(AudioStreamIndex index, IOAudioStreamPosition *endingPosition);
        !            80: 
        !            81: 
        !            82:     /*!
        !            83:      * @function SetControl
        !            84:      * @abstract Set a control to a value
        !            85:      * @discussion Called by IOAudioControls, on the workloop thread.
        !            86:      * @param id
        !            87:      * @param val
        !            88:      * @result IOReturn
        !            89:      */
        !            90:     virtual IOReturn SetControl(UInt16 id, int val) = 0;
        !            91: 
        !            92:     /*!
        !            93:      * @function getWorkLoop
        !            94:      * @result IOWorkLoop
        !            95:      */
        !            96:     virtual IOWorkLoop *getWorkLoop() const;
        !            97: 
        !            98:     /*!
        !            99:      * @function setMasterVolumeLeft
        !           100:      * @param newMasterVolumeLeft
        !           101:      * @result void
        !           102:      */
        !           103:     virtual void setMasterVolumeLeft(UInt16 newMasterVolumeLeft);
        !           104: 
        !           105:     /*!
        !           106:      * @function setMasterVolumeRight
        !           107:      * @param newMasterVolumeRight
        !           108:      * @result void
        !           109:      */
        !           110:     virtual void setMasterVolumeRight(UInt16 newMasterVolumeRight);
        !           111: 
        !           112:     /*!
        !           113:      * @function setMasterMute
        !           114:      * @param newMasterMute
        !           115:      * @result void
        !           116:      */
        !           117:     virtual void setMasterMute(bool newMasterMute);
        !           118: 
        !           119: protected:
        !           120:     /*!
        !           121:      * @function free
        !           122:      * @result void
        !           123:      */
        !           124:     virtual void free();
        !           125: 
        !           126:     /*!
        !           127:      * @function createAudioStream
        !           128:      * @abstract Create an audio stream.
        !           129:      * @discussion Streams represent hardware input/output connectors such as headphone jacks,
        !           130:      *  speakers, CD analog input etc. or I/O channels that the CPU can directly access such as
        !           131:      *  simple D->A and A->D converters and more complex codecs.
        !           132:      *  IOAudioController::createAudioStream can handle simple stream types
        !           133:      *  (implemented by IOAudioStream and IOAudioMappedStream).
        !           134:      *  Fancy things like streams with 3D positioning will probably need a new IOAudioStream subclass.
        !           135:      * @param index
        !           136:      * @result IOAudioStream A pointer if successful, NULL otherwise 
        !           137:      */
        !           138:     virtual IOAudioStream *createAudioStream(AudioStreamIndex index);
        !           139: 
        !           140:     /*!
        !           141:      * @function getStreamProperties
        !           142:      * @abstract Get properties of a (possibly not yet created) stream.
        !           143:      * @discussion Properties are:
        !           144:      *  Input or Output
        !           145:      *  Directly Accessable by CPU
        !           146:      *  Data type (16 bit samples, AC3 compressed etc)
        !           147:      *  Sample size
        !           148:      *  Channels (Mono/Stereo/5 channel/3D etc.
        !           149:      *
        !           150:      *  Must be provided by the driver.
        !           151:      * @param index
        !           152:      * @result OSDictionary
        !           153:      */
        !           154:     virtual OSDictionary * getStreamProperties(AudioStreamIndex index) = 0;
        !           155: 
        !           156:     /*!
        !           157:      * @function probeStreams
        !           158:      * @abstract How many cpu accessable streams does the device have?
        !           159:      * @result int number of streams
        !           160:      */
        !           161:     virtual int probeStreams() = 0;
        !           162: 
        !           163:     /*!
        !           164:      * @function CreateAudioTopology
        !           165:      * @abstract Create all the AudioControls and AudioComponents for the device
        !           166:      * @discussion This method is caled after creating the streams
        !           167:      * @param queue
        !           168:      * @result void
        !           169:      */
        !           170:     virtual void CreateAudioTopology(IOCommandQueue *queue) = 0;
        !           171: 
        !           172:     /*!
        !           173:      * @function buildComponentAndAttach
        !           174:      * @param parent
        !           175:      * @param child
        !           176:      * @param serialProps
        !           177:      * @param queue
        !           178:      * @result IOAudioComponentImpl
        !           179:      */
        !           180:     virtual IOAudioComponentImpl * buildComponentAndAttach(
        !           181:                IORegistryEntry *parent, IORegistryEntry *child, 
        !           182:                const char *serialProps, IOCommandQueue *queue);
        !           183: 
        !           184:     /*!
        !           185:      * @function AttachComponents
        !           186:      * @param parent
        !           187:      * @param child
        !           188:      * @result void
        !           189:      */
        !           190:     virtual void AttachComponents(IORegistryEntry *parent,
        !           191:                        IORegistryEntry *child);
        !           192: 
        !           193:     /*!
        !           194:      * @function createWorkLoop
        !           195:      * @abstract Get the workloop object for the hardware.
        !           196:      * @discussion The default implementation creates a new workloop.
        !           197:      *  Drivers may want to override this
        !           198:      *  eg. USBAudio will probably want to use an existing USB workloop.
        !           199:      * @result IOWorkLoop
        !           200:      */
        !           201:     virtual IOWorkLoop * createWorkLoop();
        !           202: 
        !           203:     /*!
        !           204:      * @function startWorkLoop
        !           205:      * @abstract Called from the device's start() method after hardware is initialized
        !           206:      * @result void
        !           207:      */
        !           208:     virtual void startWorkLoop();
        !           209: 
        !           210:     /*!
        !           211:      * @function getSharedStatus
        !           212:      * @param index
        !           213:      * @result IOAudioStreamStatus
        !           214:      */
        !           215:     virtual IOAudioStreamStatus * getSharedStatus(AudioStreamIndex index) = 0;
        !           216: 
        !           217:     /*!
        !           218:      * @function getSampleBuffer
        !           219:      * @param index
        !           220:      * @result void *
        !           221:      */
        !           222:     virtual void * getSampleBuffer(AudioStreamIndex index) = 0;
        !           223: 
        !           224:     /*!
        !           225:      * @function allocateMixBuffer
        !           226:      * @abstract Allocates the mix buffer for the given stream.
        !           227:      * @discussion Only called by execCommand()
        !           228:      * @param index
        !           229:      * @result void *
        !           230:      */
        !           231: 
        !           232:     virtual void *allocateMixBuffer(AudioStreamIndex index);
        !           233: 
        !           234:     /*!
        !           235:      * @function getMixBuffer
        !           236:      * @param index
        !           237:      * @result void *
        !           238:      */
        !           239: 
        !           240:     virtual void *getMixBuffer(AudioStreamIndex index);
        !           241: 
        !           242:     /*!
        !           243:      * @function startStream
        !           244:      * @abstract Start a stream
        !           245:      * @param index Stream index
        !           246:      * @result IOAudioStreamStatus
        !           247:      */
        !           248:     virtual IOAudioStreamStatus * startStream(AudioStreamIndex index) = 0;
        !           249: 
        !           250:     /*!
        !           251:      * @function startStream
        !           252:      * @abstract Stop a stream
        !           253:      * @param index Stream index
        !           254:      * @result void
        !           255:      */
        !           256:     virtual void stopStream(AudioStreamIndex index) = 0;
        !           257: 
        !           258:     /*!
        !           259:      * @function pauseStream
        !           260:      * @abstract Control stream flow
        !           261:      * @param index Audio stream
        !           262:      * @result void
        !           263:      */
        !           264:     virtual void pauseStream(AudioStreamIndex index) = 0;
        !           265: 
        !           266:     /*!
        !           267:      * @function resumeStream
        !           268:      * @abstract Control stream flow
        !           269:      * @param index Audio stream
        !           270:      * @result void
        !           271:      */
        !           272:     virtual void resumeStream(AudioStreamIndex index) = 0;
        !           273: 
        !           274:     /*!
        !           275:      * @function DoClockTick
        !           276:      * @param IOTimerEventSource
        !           277:      * @result void
        !           278:      */
        !           279:     virtual void DoClockTick(IOTimerEventSource *);
        !           280: 
        !           281:     /*!
        !           282:      * @function calculateTickInterval
        !           283:      * @param tickInterval
        !           284:      * @result void
        !           285:      */
        !           286:     virtual void calculateTickInterval(AbsoluteTime *tickInterval);
        !           287: 
        !           288:     /*!
        !           289:      * @function execCommand
        !           290:      * @param cmd
        !           291:      * @param field2
        !           292:      * @param field3
        !           293:      * @result void
        !           294:      */
        !           295:     virtual void execCommand(IOAudioCmd cmd, void *field2, void *field3);
        !           296: 
        !           297:     /*!
        !           298:      * @function GetStream
        !           299:      * @param index Audio stream index
        !           300:      * @result IOAudioStream
        !           301:      */
        !           302:     IOAudioStream * GetStream(AudioStreamIndex index) const;
        !           303: 
        !           304:     /*!
        !           305:      * @function init
        !           306:      * @param properties
        !           307:      * @result bool
        !           308:      */
        !           309:     virtual bool init(OSDictionary *properties);
        !           310: 
        !           311:     /*!
        !           312:      * @function start
        !           313:      * @param provider
        !           314:      * @result bool
        !           315:      */
        !           316:     virtual bool start( IOService * provider );
        !           317: 
        !           318: public:
        !           319:     static const IORegistryPlane * gIOAudioPlane;
        !           320: 
        !           321:     // Common IOSymbols, precooked and ready to use.
        !           322:     static const OSSymbol * gValSym;
        !           323:     static const OSSymbol * gInputsSym;
        !           324:     static const OSSymbol * gControlsSym;
        !           325:     static const OSSymbol * gJackSym;
        !           326:     static const OSSymbol * gSpeakerSym;
        !           327:     static const OSSymbol * gHeadphonesSym;
        !           328:     static const OSSymbol * gLineOutSym;
        !           329:     static const OSSymbol * gTypeSym;
        !           330:     static const OSSymbol * gMuteSym;
        !           331:     static const OSSymbol * gIdSym;
        !           332:     static const OSSymbol * gMasterSym;
        !           333: 
        !           334: protected:
        !           335:     OSArray *fStreams;
        !           336: 
        !           337:     IOService *fDevice;
        !           338: 
        !           339:     IOTimerEventSource *       fTimer;
        !           340:     IOCommandQueue *           fQueue;
        !           341:     IOWorkLoop *               fWorkLoop;
        !           342:     AbsoluteTime               fTickPeriod;
        !           343:     AbsoluteTime               fNextTick;
        !           344:     bool                       fTimerInUse;
        !           345:     AbsoluteTime               fMaxPollInterval;
        !           346:     OSSet *                    fMasterVolumeComponents;
        !           347:     UInt32                     fNumStreamsInUse;
        !           348: 
        !           349:     static void execAndSignal(OSObject * obj, void *field0, void *field1, void *field2, void *field3);
        !           350:     static void clockTick(OSObject *, IOTimerEventSource *sender);
        !           351: 
        !           352:     void setMasterComponentsProperties(OSDictionary *properties);
        !           353: };
        !           354: 
        !           355: inline IOAudioStream * 
        !           356: IOAudioController::GetStream(AudioStreamIndex index) const
        !           357: {
        !           358:     return (IOAudioStream *)fStreams->getObject(index);
        !           359: }
        !           360: 
        !           361: #endif /* _IOAUDIOCONTOLLER_H */

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.