wmprofiles.h

WM9713 audio codec driver for WinCE 5.0

/*-----------------------------------------------------------------------------
 * Copyright (c) Wolfson Microelectronics plc.  All rights reserved.
 *
 * This software as well as any related documentation is furnished under 
 * license and may only be used or copied in accordance with the terms of the 
 * license. The information in this file is furnished for informational use 
 * only, is subject to change without notice, and should not be construed as 
 * a commitment by Wolfson Microelectronics plc. Wolfson Microelectronics plc
 * assumes no responsibility or liability for any errors or inaccuracies that
 * may appear in this document or any software that may be provided in
 * association with this document. 
 *
 * Except as permitted by such license, no part of this document may be 
 * reproduced, stored in a retrieval system, or transmitted in any form or by 
 * any means without the express written consent of Wolfson Microelectronics plc. 
 *
 * $Id: WMProfiles.h 2370 2005-11-07 17:01:18Z ib $
 *
 * This file contains the profile interface, which allows standard
 * configurations to be prepared in advance and loaded with a single
 * function call.
 *
 * Warning:
 *  This driver is specifically written for Wolfson Codecs. It is not a 
 *  general CODEC device driver.
 *
 *---------------------------------------------------------------------------*/
#ifndef __WMPROFILE_H__
#define __WMPROFILE_H__

/*
 * Include files
 */
#include "WMTypes.h"

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Definitions
 */

/*
 * The action identifier.
 */
typedef enum tagWM_ACT
{
    WMA_WRITE = 1,
    WMA_RESET,
    WMA_SLEEP,
    WMA_WAKE,
    WMA_POWERUP,
    WMA_POWERDOWN,
    WMA_ENABLE_STREAM,
    WMA_DISABLE_STREAM,
    WMA_LOAD_PROFILE,
    WMA_SET_VOLUME,
    WMA_MUTE_SIGNAL
} WM_ACT;

/*
 * The action structure.
 */
typedef struct tagWM_ACTION
{
    WM_ACT          action;
    union
    {
        unsigned int    uintval;
        int             intval;
        WM_REGVAL       regval;
        WM_BOOL         boolval;
        const char      *string;
    } val;
    union
    {
        unsigned int    destval;
        WM_REGTYPE      reg;
        WM_AUDIO_SIGNAL signal;
    } dest;
    WM_REGVAL       mask;
    short           pad0;      /* pad to longword boundary */
} WM_ACTION;

/*
 * Structure describing a named profile.
 */
typedef struct tagWM_PROFILE
{
    const char          *name;
    WM_CHIPTYPE         deviceType;
    const WM_ACTION     *actions;
    unsigned int        nActions;
} WM_PROFILE;

/*
 * The user profiles.  These are typically stored in Wolfson\Common\UserProfiles.c
 * but may be anywhere as long as they have this name and are linked into the image.
 */
extern const WM_PROFILE *g_UserProfiles;
extern unsigned int g_nUserProfiles;

/*
 * A macro to simplify declarations.
 */
#define WM_PROFILE_ENTRY( _name, _chip, _actions )\
    { _name, _chip, _actions, WM_ARRAY_COUNT( _actions ) }

/*-----------------------------------------------------------------------------
 * Macros to simplify declaring actions.
 */

/* Struct initialisation initialises the union from the first type. */
#define _VAL( _v ) { (unsigned int)(_v) }
#define _DEST( _d ) { (unsigned int)(_d) }

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_RESET
 *
 * Declares an action corresponding to a codec reset.
 *
 * Parameters:
 *      none
 *---------------------------------------------------------------------------*/
#define WMACT_RESET() { WMA_RESET }

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_WRITE
 *
 * Declares an action corresponding to a register write.
 *
 * Parameters:
 *      reg     register to write to
 *      value   value to write
 *---------------------------------------------------------------------------*/
#define WMACT_WRITE( reg, value ) { WMA_WRITE, _VAL( value ), _DEST( reg ), 0xFFFF }

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_SET_FIELD
 *
 * Declares an action corresponding to a register write of the bits
 * corresponding to the mask.
 *
 * Parameters:
 *      reg     register to write to
 *      value   value to write
 *      mask    mask of bits to change - e.g. 0xFFFF changes everything
 *---------------------------------------------------------------------------*/
#define WMACT_SET_FIELD( reg, value, mask ) { WMA_WRITE, _VAL( value ), _DEST( reg ), mask }

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_CLEAR_FIELD
 *
 * Declares an action corresponding to clearing the given bits of register,
 * leaving all other bits unchanged.
 *
 * Parameters:
 *      reg     register to write to
 *      bits    bits to clear
 *---------------------------------------------------------------------------*/
#define WMACT_CLEAR_FIELD( reg, mask ) { WMA_WRITE, _VAL( 0 ), _DEST( reg ), mask }

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_SET_BITS
 *
 * Declares an action corresponding to setting the given bits of the register
 * to one, leaving all other bits unchanged.
 *
 * Parameters:
 *      reg     register to write to
 *      bits    register bits to set to 1
 *---------------------------------------------------------------------------*/
#define WMACT_SET_BITS( reg, bits ) { WMA_WRITE, _VAL( bits ), _DEST( reg ), bits }

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_CLEAR_BITS
 *
 * Declares an action corresponding to clearing the given bits of register,
 * leaving all other bits unchanged.
 *
 * Parameters:
 *      reg     register to write to
 *      bits    bits to clear
 *---------------------------------------------------------------------------*/
#define WMACT_CLEAR_BITS    WMACT_CLEAR_FIELD

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_SLEEP
 *
 * Declares an action corresponding to a sleep (declared in seconds).
 *
 * Parameters:
 *      seconds         number of seconds to sleep
 *---------------------------------------------------------------------------*/
#define WMACT_SLEEP( seconds ) { WMA_SLEEP, _VAL( seconds * 1000 ) }

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_MILLISLEEP
 *
 * Declares an action corresponding to a sleep (declared in milli-seconds).
 *
 * Parameters:
 *      milliseconds    number of milliseconds to sleep
 *---------------------------------------------------------------------------*/
#define WMACT_MILLISLEEP( millisecs ) { WMA_SLEEP, _VAL( millisecs ) }

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_ENABLE_STREAM
 *
 * Declares an action corresponding to enabling the given stream.
 *
 * Parameters:
 *      stream          stream to enable
 *---------------------------------------------------------------------------*/
#define WMACT_ENABLE_STREAM( stream ) { WMA_ENABLE_STREAM, _VAL( stream ) }

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_DISABLE_STREAM
 *
 * Declares an action corresponding to disabling the given stream.
 *
 * Parameters:
 *      stream          stream to disable
 *---------------------------------------------------------------------------*/
#define WMACT_DISABLE_STREAM( stream ) { WMA_DISABLE_STREAM, _VAL( stream ) }

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_SET_VOLUME
 *
 * Declares an action corresponding to setting a signal to a given level.
 *
 * Parameters:
 *      signal          signal to adjust
 *      dbVal           new signal level, in dB relative to full-scale
 *---------------------------------------------------------------------------*/
#define WMACT_SET_VOLUME( signal, dbVal ) { WMA_SET_VOLUME,                     \
                                            _VAL( WM_SIGNAL_LEVEL( dbVal ) ),   \
                                            _DEST( signal )                     \
                                          }

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_MUTE
 *
 * Declares an action muting a given signal.
 *
 * Parameters:
 *      signal          signal to mute
 *---------------------------------------------------------------------------*/
#define WMACT_MUTE( signal ) { WMA_MUTE_SIGNAL, _VAL( TRUE ), _DEST( signal ) }

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_UNMUTE
 *
 * Declares an action unmuting a given signal.
 *
 * Parameters:
 *      signal          signal to mute
 *---------------------------------------------------------------------------*/
#define WMACT_UNMUTE( signal ) { WMA_MUTE_SIGNAL, _VAL( FALSE ), _DEST( signal ) }

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_POWERUP
 *
 * Declares an action corresponding to powering up certain sections.
 *
 * Parameters:
 *      powerflags      power sections to power up - combination of 
 *                      WM_POWER_* constants ORed together.
 *---------------------------------------------------------------------------*/
#define WMACT_POWERUP( powerflags ) { WMA_POWERUP, _VAL( powerflags ) }

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_POWERDOWN
 *
 * Declares an action corresponding to powering down certain sections.
 *
 * Parameters:
 *      powerflags      power sections to power down - combination of 
 *                      WM_POWER_* constants ORed together.
 *---------------------------------------------------------------------------*/
#define WMACT_POWERDOWN( powerflags ) { WMA_POWERDOWN, _VAL( powerflags ) }

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_WAKE
 *
 * Declares an action corresponding to waking up the device (re-enabling the
 * link - corresponds to a warm reset on AC'97 devices).
 *
 * Parameters:
 *      none
 *---------------------------------------------------------------------------*/
#define WMACT_WAKE() { WMA_WAKE }

/*-----------------------------------------------------------------------------
 * Macro:   WMACT_LOAD_PROFILE
 *
 * Declares an action corresponding to loading a named profile.
 *
 * Parameters:
 *      profile         string containing the name of the profile to load.
 *---------------------------------------------------------------------------*/
#define WMACT_LOAD_PROFILE( profile ) { WMA_LOAD_PROFILE, _VAL( profile ) }

/* 
 * Function prototypes
 */

/*-----------------------------------------------------------------------------
 * Function:    WMLoadProfile
 *
 * Loads a pre-prepared configuration (set of register settings/changes)
 * to the device.
 *
 * Note:
 *  - if there is an action with an unrecognised action field, or if there
 *    is a bad parameter to a recognised action, all other actions will
 *    still be executed and this function will effectively skip over the
 *    bad one(s).
 * 
 * Parameters:
 *      hDevice             handle to the device (from WMOpenDevice)
 *      pActions            The actions to take
 *      nActions            Number of actions in the pActions array
 *
 * Returns:     WMSTATUS
 *      The first error status, or WMS_SUCCESS if all actions completed
 *      successfully.  Note: even if this function returns an error status,
 *      some actions may have been executed.
 *---------------------------------------------------------------------------*/
WMSTATUS WMLoadProfile( WM_DEVICE_HANDLE    hDevice,
                        const WM_ACTION     *pActions,
                        unsigned int        nActions
                      );

/*-----------------------------------------------------------------------------
 * Function:    WMLoadNamedProfile
 *
 * Loads the profile with the given name.  When looking for the profiles to
 * load it checks the profiles in g_UserProfiles first, followed by the
 * profiles in the codec's chipdef, and calls WMLoadProfile with the first
 * profile with a matching name and codec. Name comparison is case insensitive.
 *
 * Parameters:
 *      hDevice             handle to the device (from WMOpenDevice)
 *      profile             name of profile to load
 *
 * Returns:     WMSTATUS
 *      WMS_UNKNOWN_PROFILE if there is no profile with that name for the
 *      given device.
 *      The first error status, or WMS_SUCCESS if all actions completed
 *      successfully.  Note: even if this function returns an error status,
 *      some actions may have been executed.
 *---------------------------------------------------------------------------*/
WMSTATUS WMLoadNamedProfile( WM_DEVICE_HANDLE   hDevice,
                             const char         *profile
                           );

#ifdef __cplusplus
}   /* extern "C" */
#endif

#endif	/* __###_H__ */
/*------------------------------ END OF FILE ---------------------------------*/