pmic_audio.h

Microsoft WinCE 6.0 BSP FINAL release source code for use with the i.MX27ADS TO2 WCE600_FINAL_MX27_S

                                     gain <b>(MC13783-only)</b>.      */
    BAL_GAIN_0DB                /*!< Select 0dB channel balance gain. */
} PMIC_AUDIO_OUTPUT_BALANCE_GAIN;

/*!
 * @enum PMIC_AUDIO_MONO_ADDER_MODE
 * @brief Select the output mono adder operating mode.
 *
 * This enumeration is used to select the operating mode for the mono adder
 * in the audio output section.
 */
typedef enum
{
    MONO_ADDER_OFF,             /*!< Disable mono adder (keep separate
                                     left and right channels).           */
    MONO_ADD_LEFT_RIGHT,        /*!< Add left and right channels.        */
    MONO_ADD_OPPOSITE_PHASE,    /*!< Add left and right channels but
                                     with outputs in opposite phase
                                     <b>(MC13783-only)</b>.              */
    STEREO_OPPOSITE_PHASE       /*!< Keep separate left and right
                                     channels but invert phase of
                                     left channel <b>(MC13783-only)</b>. */
} PMIC_AUDIO_MONO_ADDER_MODE;

/*!
 * @enum PMIC_AUDIO_MONO_ADDER_OUTPUT_GAIN
 * @brief Select the mono adder output amplifier gain level.
 *
 * This enumeration is used to select the output amplifier gain level for
 * the mono adder.
 */
typedef enum
{
    MONOADD_GAIN_MINUS_6DB,     /*!< Select -6dB mono adder output gain
                                     <b>(SC55112)</b>.          */
    MONOADD_GAIN_MINUS_3DB,     /*!< Select -3dB mono adder output gain
                                     <b>(SC55112)</b>.          */
    MONOADD_GAIN_0DB            /*!< Select 0dB mono adder output gain. */
} PMIC_AUDIO_MONO_ADDER_OUTPUT_GAIN;

/*@}*/
 
/***************************************************************************
 *                       PMIC-SPECIFIC DEFINITIONS                         *
 ***************************************************************************/

/*!
 * @name Definition of PMIC-specific Capabilities
 * Constants that are used to define PMIC-specific capabilities.
 */
/*@{*/

/*!
 * Define the minimum Stereo DAC sampling rate (Hz).
 */
extern const unsigned MIN_STDAC_SAMPLING_RATE_HZ;
/*!
 * Define the maximum Stereo DAC sampling rate (Hz).
 */
extern const unsigned MAX_STDAC_SAMPLING_RATE_HZ;

/*@}*/
 
/***************************************************************************
 *                          PMIC API DEFINITIONS                           *
 ***************************************************************************/

/*!
 * @name General Setup and Configuration APIs
 * Functions for general setup and configuration of the PMIC Audio
 * hardware.
 */
/*@{*/

/*!
 * @brief Request exclusive access to the PMIC Audio hardware.
 *
 * Attempt to open and gain exclusive access to a key PMIC audio hardware
 * component (e.g., the Stereo DAC or the Voice CODEC). Depending upon the
 * type of audio operation that is desired and the nature of the audio data
 * stream, the Stereo DAC and/or the Voice CODEC will be a required hardware
 * component and needs to be acquired by calling this function.
 *
 * If the open request is successful, then a numeric handle is returned
 * and this handle must be used in all subsequent function calls to complete
 * the configuration of either the Stereo DAC or the Voice CODEC and along
 * with any other associated audio hardware components that will be needed.
 *
 * The same handle must also be used in the close call when use of the PMIC
 * audio hardware is no longer required.
 *
 * The open request will fail if the requested audio hardware component has
 * already been acquired by a previous open call but not yet closed.
 *
 * @param[out]  handle          Device handle to be used for subsequent PMIC
 *                              Connectivity API calls.
 * @param[in]   device          The required PMIC audio hardware component.
 *
 * @retval      PMIC_SUCCESS         If the open request was successful
 * @retval      PMIC_PARAMETER_ERROR If the handle argument is NULL.
 * @retval      PMIC_ERROR           If the audio hardware component is
 *                                   unavailable.
 */
PMIC_STATUS PmicAudioOpen(
    PMIC_AUDIO_HANDLE *const handle,
    const PMIC_AUDIO_SOURCE  device);

/*!
 * @brief Terminate further access to the PMIC audio hardware.
 *
 * Terminate further access to the PMIC audio hardware that was previously
 * acquired by calling pmic_audio_open(). This now allows another thread to
 * successfully call pmic_audio_open() to gain access.
 *
 * @param[in]   handle          Device handle from pmic_audio_open() call.
 *
 * @retval      PMIC_SUCCESS         If the close request was successful.
 * @retval      PMIC_PARAMETER_ERROR If the handle is invalid.
 */
PMIC_STATUS PmicAudioClose(
    const PMIC_AUDIO_HANDLE handle);

/*!
 * @brief Configure the data bus protocol to be used.
 *
 * Provide the parameters needed to properly configure the audio data bus
 * protocol so that data can be read/written to either the Stereo DAC or
 * the Voice CODEC.
 *
 * @param[in]   handle          Device handle from pmic_audio_open() call.
 * @param[in]   busID           Select data bus to be used.
 * @param[in]   protocol        Select the data bus protocol.
 * @param[in]   masterSlave     Select the data bus timing mode.
 * @param[in]   numSlots        Define the number of timeslots (only if in
 *                              master mode).
 *
 * @retval      PMIC_SUCCESS         If the protocol was successful configured.
 * @retval      PMIC_PARAMETER_ERROR If the handle or the protocol parameters
 *                                   are invalid.
 */
PMIC_STATUS PmicAudioSetProtocol(
    const PMIC_AUDIO_HANDLE       handle,
    const PMIC_AUDIO_DATA_BUS     busID,
    const PMIC_AUDIO_BUS_PROTOCOL protocol,
    const PMIC_AUDIO_BUS_MODE     masterSlave,
    const PMIC_AUDIO_NUMSLOTS     numSlots);

/*!
 * @brief Retrieve the current data bus protocol configuration.
 *
 * Retrieve the parameters that define the current audio data bus protocol.
 *
 * @param[in]   handle          Device handle from pmic_audio_open() call.
 * @param[out]  busID           The data bus being used.
 * @param[out]  protocol        The data bus protocol being used.
 * @param[out]  masterSlave     The data bus timing mode being used.
 * @param[out]  numSlots        The number of timeslots being used (if in
 *                              master mode).
 *
 * @retval      PMIC_SUCCESS         If the protocol was successful retrieved.
 * @retval      PMIC_PARAMETER_ERROR If the handle is invalid.
 */
PMIC_STATUS PmicAudioGetProtocol(
    const PMIC_AUDIO_HANDLE        handle,
    PMIC_AUDIO_DATA_BUS     *const busID,
    PMIC_AUDIO_BUS_PROTOCOL *const protocol,
    PMIC_AUDIO_BUS_MODE     *const masterSlave,
    PMIC_AUDIO_NUMSLOTS     *const numSlots);

/*!
 * @brief Enable the Stereo DAC or the Voice CODEC.
 *
 * Explicitly enable the Stereo DAC or the Voice CODEC to begin audio
 * playback or recording as required. This should only be done after
 * successfully configuring all of the associated audio components (e.g.,
 * microphones, amplifiers, etc.). 
 *
 * @param[in]   handle          Device handle from pmic_audio_open() call.
 *
 * @retval      PMIC_SUCCESS         If the device was successful enabled.
 * @retval      PMIC_PARAMETER_ERROR If the handle is invalid.
 * @retval      PMIC_ERROR           If the device could not be enabled.
 */
PMIC_STATUS PmicAudioEnable(
    const PMIC_AUDIO_HANDLE handle);

/*!
 * @brief Disable the Stereo DAC or the Voice CODEC.
 *
 * Explicitly disable the Stereo DAC or the Voice CODEC to end audio
 * playback or recording as required.
 *
 * @param[in]   handle          Device handle from pmic_audio_open() call.
 *
 * @retval      PMIC_SUCCESS         If the device was successful disabled.
 * @retval      PMIC_PARAMETER_ERROR If the handle is invalid.
 * @retval      PMIC_ERROR           If the device could not be disabled.
 */
PMIC_STATUS PmicAudioDisable(
    const PMIC_AUDIO_HANDLE handle);

/*!
 * @brief Reset the selected audio hardware control registers to their
 *        power on state.
 *
 * This resets all of the audio hardware control registers currently
 * associated with the device handle back to their power on states. For
 * example, if the handle is associated with the Stereo DAC and a
 * specific output port and output amplifiers, then this function will
 * reset all of those components to their power on state.
 *
 * @param[in]   handle          Device handle from pmic_audio_open() call.
 *
 * @retval      PMIC_SUCCESS         If the reset operation was successful.
 * @retval      PMIC_PARAMETER_ERROR If the handle is invalid.
 * @retval      PMIC_ERROR           If the reset was unsuccessful.
 */
PMIC_STATUS PmicAudioReset(
    const PMIC_AUDIO_HANDLE handle);

/*!
 * @brief Reset all audio hardware control registers to their power on state.
 *
 * This resets all of the audio hardware control registers back to their
 * power on states. Use this function with care since it also invalidates
 * (i.e., automatically closes) all currently opened device handles.
 *
 * @retval      PMIC_SUCCESS         If the reset operation was successful.
 * @retval      PMIC_ERROR           If the reset was unsuccessful.
 */
PMIC_STATUS PmicAudioResetAll(void);

/*!
 * @brief Set the Audio callback function.
 *
 * Register a callback function that will be used to signal PMIC audio
 * events. For example, the OSS audio driver should register a callback
 * function in order to be notified of headset connect/disconnect events.
 *
 * @param[in]   handle          Device handle from pmic_audio_open() call.
 * @param[in]   func            A pointer to the callback function.
 * @param[in]   eventMask       A mask selecting events to be notified.
 *
 * @retval      PMIC_SUCCESS         If the callback was successfully
 *                                   registered.
 * @retval      PMIC_PARAMETER_ERROR If the handle or the eventMask is invalid.
 */
PMIC_STATUS PmicAudioSetCallback(
    const PMIC_AUDIO_HANDLE   handle,
    const PMIC_AUDIO_CALLBACK func,
    const PMIC_AUDIO_EVENTS   eventMask);

/*!
 * @brief Deregisters the existing audio callback function.
 *
 * Deregister the callback function that was previously registered by calling
 * pmic_audio_set_callback().
 *
 * @param[in]   handle          Device handle from pmic_audio_open() call.
 *
 * @retval      PMIC_SUCCESS         If the callback was successfully
 *                                   deregistered.
 * @retval      PMIC_PARAMETER_ERROR If the handle is invalid.
 */
PMIC_STATUS PmicAudioClearCallback(
    const PMIC_AUDIO_HANDLE handle);

/*!
 * @brief Get the current audio callback function settings.
 *
 * Get the current callback function and event mask.
 *
 * @param[in]   handle          Device handle from pmic_audio_open() call.
 * @param[out]  func            The current callback function.
 * @param[out]  eventMask       The current event selection mask.
 *
 * @retval      PMIC_SUCCESS         If the callback information was
 *                                   successfully retrieved.
 * @retval      PMIC_PARAMETER_ERROR If the handle is invalid.
 */
PMIC_STATUS PmicAudioGetCallback(
    const PMIC_AUDIO_HANDLE    handle,
    PMIC_AUDIO_CALLBACK *const func,
    PMIC_AUDIO_EVENTS   *const eventMask);

/*!
 * @brief Enable the anti-pop circuitry to avoid extra noise when inserting
 *        or removing a external device (e.g., a headset).
 *
 * Enable the use of the built-in anti-pop circuitry to prevent noise from
 * being generated when an external audio device is inserted or removed
 * from an audio plug. A slow ramp speed may be needed to avoid extra noise.
 *