AVED Clock Control (ACC) Proxy Driver¶
Overview¶
The ACC proxy driver will store an internal list of sensors required for the throttling algorithm during initialization. It will also create a number of resources, including a mutex for protection, a mailbox to handle asynchronous responses and a task to implement the clock control features.
The ACC proxy task will:
Implement clock shutdown for fatal and critical threshold levels.
Enable/Disable clock shutdown feature.
Re-enable clock shutdown.
The proxy API consists of a number of functions to report to the ACC that a sensor has exceeded various threshold limits. The APIs will post an internal message with the required data onto the mailbox. The ACC proxy will service this mailbox and implement the appropriate clock control features. The required sensor ID and Type passed into the APIs, are checked against the internal list of clock shutdown sensors by the ACC proxy task.
The API also provides two debug functions to display and clear of the stat/error counters.
Note: Clock shutdown is currently not implemented.
API¶
Initialize Driver¶
iACC_Initialise
/**
* @brief Main initialisation point for the ACC Proxy Driver
*
* @param ucProxyId Unique ID for this Proxy driver
* @param ulTaskPrio Priority of the Proxy driver task ( if RR disabled )
* @param ulTaskStack Stack size of the Proxy driver task
* @param pxShutdownData Sensor IDs required to monitor for shutdown
* @param User Clock Control Base Address
*
* @return OK Proxy driver initialised correctly
* ERROR Proxy driver not initialised, or was already initialised
*
* @note Proxy drivers can have 0 or more firmware interfaces
*/
int iACC_Initialise( uint8_t ucProxyId, uint32_t ulTaskPrio, uint32_t ulTaskStack,
ACC_PROXY_DRIVER_SHUTDOWN_SENSOR_DATA* pxShutdownData,
void* pvUCCBaseAddress );
Bind Callbacks¶
iACC_BindCallback
/**
* @brief Bind into this proxy driver
*
* @param pxCallback Callback to bind into the proxy driver
*
* @return OK Callback successfully bound
* ERROR Callback not bound
*
*/
int iACC_BindCallback( EVL_CALLBACK *pxCallback );
Print Statistics¶
iACC_PrintStatistics
/**
* @brief Print all the stats gathered in this driver
*
* @return OK Stats retrieved from proxy driver successfully
* ERROR Stats not retrieved successfully
*
*/
int iACC_PrintStatistics( void );
Clear Statistics¶
iACC_ClearStatistics
/**
* @brief Clear all the stats in this driver
*
* @return OK Stats cleared successfully
* ERROR Stats not cleared successfully
*
*/
int iACC_ClearStatistics( void );
Enable Clock Shutdown¶
iACC_EnableShutdown
/**
* @brief Enable Clock Shutdown for threshold crossing
*
* @return OK Shutdown enabled successfully
* ERROR Shutdown enable unsuccessful
*
*/
int iACC_EnableShutdown( void );
Disable Clock Shutdown¶
iACC_DisableShutdown
/**
* @brief Disable Clock Shutdown for threshold crossing
*
* @return OK Shutdown disabled successfully
* ERROR Shutdown disable unsuccessful
*
*/
int iACC_DisableShutdown( void );
Sensor exceeded fatal limit¶
iACC_FatalLimitExceeded
/**
* @brief Report to ACC that a sensor has exceeded fatal limit
*
* @param ucSensorId The ID to identify the sensor
* @param ucSensorType The type of sensor, temp, current, voltage or power
*
* @return OK Fatal Limit reported successfully
* ERROR Fatal Limit report was unsuccessful
*/
int iACC_FatalLimitExceeded( uint8_t ucSensorId, uint8_t ucSensorType );
Sensor exceeded critical limit¶
iACC_CriticalLimitExceeded
/**
* @brief Report to ACC that a sensor has exceeded critical limit
*
* @param ucSensorId The ID to identify the sensor
* @param ucSensorType The type of sensor, temp, current, voltage or power
*
* @return OK Critical Limit reported successfully
* ERROR Critical Limit report was unsuccessful
*/
int iACC_CriticalLimitExceeded( uint8_t ucSensorId, uint8_t ucSensorType );
Sensor has exceeded warning limit¶
iACC_WarningLimitExceeded
/**
* @brief Report to ACC that a sensor has exceeded warning limit
*
* @param ucSensorId The ID to identify the sensor
* @param ucSensorType The type of sensor, temp, current, voltage or power
*
* @return OK Warning Limit reported successfully
* ERROR Warning Limit report was unsuccessful
*/
int iACC_WarningLimitExceeded( uint8_t ucSensorId, uint8_t ucSensorType );
Reset Limit¶
iACC_ResetLimit
/**
* @brief Re-enable the clock if previously shutdown
*
* @return OK Reset Limit successful
* ERROR Reset Limit was unsuccessful
*/
int iACC_ResetLimit( void );
Sequence Diagrams¶
ACC Proxy Initialisation¶
Two ACC API functions are called from the AMC main task (iACC_Initialise, iACC_BindCallback), in order to initialise the proxy.
iACC_Initialise will create a shared proxy mutex and mailbox, and create the proxy task. It will also copy the provided number of sensors and their provided data, along with setting an initialized flag.
iACC_BindCallback will bind the appropriate top-level callback function.
ACC Proxy Task¶
The Task within ACC has a number of responsibilities:
Pend to its mailbox, and handle the incoming messages.
Implement clock shutdown for fatal and critical threshold levels.
Enable/Disable clock shutdown feature.
Re-enable clock shutdown.
The sequence flow diagram below outlines the top-level functionality of the ACC proxy task.
Examples¶
Initialize Driver¶
This function should only be called once. It requires a unique ID for the proxy, used for signaling new events, a task priority and stack size. It also requires pointers to three structures, clock throttling sensor IDs, profile, default parameters, and a final pointer to the clock control base address.
iAQC_Initialise Example
if( OK == iACC_Initialise( AMC_EVENT_UNIQUE_ID_ACC, AMC_TASK_PRIO_DEFAULT, AMC_TASK_DEFAULT_STACK,
&xThrottlingSensors, &xClockThrottlingProfile,
&xClockThrottlingParams, ( void * )HAL_USER_CLOCK_CONTROL_BASE_ADDRESS ) )
{
AMC_PRINTF( "ACC Proxy Driver initialised\r\n" );
}
else
{
AMC_PRINTF( "Error initialising ACC Proxy Driver\r\n" );
}
Register For Callback¶
Define a function based on the function pointer prototype and bind in using the API.
iACC_BindCallback Example
/* Define a callback to handle the events */
static int iAccCallback( EVL_SIGNAL *pxSignal )
{
int iStatus = ERROR;
if( ( NULL != pxSignal ) && ( AMC_EVENT_UNIQUE_ID_ACC == pxSignal->ucModule ) )
{
/* AMC_PRINTF( "ACC Proxy Driver (0x%02X), Instance %d, ", pxSignal->ucModule, pxSignal->ucInstance ); */
switch( pxSignal->ucEventType )
{
case ACC_PROXY_DRIVER_E_CLOCK_SHUTDOWN_ENABLED:
{
AMC_PRINTF( "Event ACC_PROXY_DRIVER_E_CLOCK_SHUTDOWN_ENABLED (0x%02X)\r\n", pxSignal->ucEventType );
iStatus = OK;
break;
}
case ACC_PROXY_DRIVER_E_CLOCK_SHUTDOWN_DISABLED:
{
AMC_PRINTF( "Event ACC_PROXY_DRIVER_E_CLOCK_SHUTDOWN_DISABLED (0x%02X)\r\n", pxSignal->ucEventType );
iStatus = OK;
break;
}
case ACC_PROXY_DRIVER_E_CLOCK_SHUTDOWN_ACTIVATED:
{
AMC_PRINTF( "Event ACC_PROXY_DRIVER_E_CLOCK_SHUTDOWN_ACTIVATED (0x%02X)\r\n", pxSignal->ucEventType );
iStatus = OK;
break;
}
case ACC_PROXY_DRIVER_E_CLOCK_SHUTDOWN_CLOCK_REENABLED:
{
AMC_PRINTF( "Event ACC_PROXY_DRIVER_E_CLOCK_SHUTDOWN_CLOCK_REENABLED (0x%02X)\r\n", pxSignal->ucEventType );
iStatus = OK;
break;
}
default:
break;
}
}
return iStatus;
}
/* Bind into the callback during the application initialisation */
if( OK == iACC_BindCallback( &iAccCallback ) )
{
AMC_PRINTF( "ACC Proxy Driver initialised and bound\r\n" );
}
else
{
AMC_PRINTF( "Error binding to ACC Proxy Driver\r\n" );
}
Enable Clock Shutdown¶
Simply call iACC_EnableShutdown to Enable Clock Shutdown for threshold crossing, no params are required.
iACC_EnableShutdown Example
if( OK != iACC_EnableShutdown() )
{
ACC_DBG_PRINTF( "Error calling EnableShutdown\r\n" );
}
Disable Clock Shutdown¶
Simply call iACC_DisableShutdown to Disable Clock Shutdown for threshold crossing, no params are required.
iACC_DisableShutdown Example
if( OK != iACC_DisableShutdown() )
{
ACC_DBG_PRINTF( "Error calling DisableShutdown\r\n" );
}
Sensor exceeded fatal limit¶
Example calling ACC Fatal Limit Exceeded, taking two params, iSensorId and iSensorType.
iACC_FatalLimitExceeded Example
int iSensorId = 0; /* Set Sensor Id (0 - 255) */
int iSensorType = 0; /* Set Sensor Type (0-Temp, 1-Voltage, 2-Current, 4-Power) */
if( OK != iACC_FatalLimitExceeded( ( uint8_t )iSensorId, ( uint32_t )iSensorType ) )
{
ACC_DBG_PRINTF( "Error calling iACC_FatalLimitExceeded\r\n" );
}
else
{
ACC_DBG_PRINTF( "iACC_FatalLimitExceeded called successfully \r\n" );
}
Sensor exceeded critical limit¶
Example calling ACC Critical Limit Exceeded, taking two params, iSensorId and iSensorType.
iACC_CriticalLimitExceeded Example
int iSensorId = 0; /* Set Sensor Id (0 - 255) */
int iSensorType = 0; /* Set Sensor Type (0-Temp, 1-Voltage, 2-Current, 4-Power) */
if( OK != iACC_CriticalLimitExceeded( ( uint8_t )iSensorId, ( uint32_t )iSensorType ) )
{
ACC_DBG_PRINTF( "Error calling iACC_CriticalLimitExceeded\r\n" );
}
else
{
ACC_DBG_PRINTF( "iACC_CriticalLimitExceeded called successfully \r\n" );
}
Sensor has exceeded warning limit¶
Example calling ACC Warning Limit Exceeded, taking two params, iSensorId and iSensorType.
iACC_WarningLimitExceeded Example
int iSensorId = 0; /* Set Sensor Id (0 - 255) */
int iSensorType = 0; /* Set Sensor Type (0-Temp, 1-Voltage, 2-Current, 4-Power) */
if( OK != iACC_WarningLimitExceeded( ( uint8_t )iSensorId, ( uint32_t )iSensorType ) )
{
ACC_DBG_PRINTF( "Error calling iACC_WarningLimitExceeded\r\n" );
}
else
{
ACC_DBG_PRINTF( "iACC_WarningLimitExceeded called successfully \r\n" );
}
Reset Limit¶
Simply call iACC_ResetLimit to re-enable the clock if previously shutdown, no params are required.
iACC_ResetLimit Example
if( OK != iACC_ResetLimit( ) )
{
ACC_DBG_PRINTF( "Error calling iACC_ResetLimit\r\n" );
}
else
{
ACC_DBG_PRINTF( "iACC_ResetLimit called successfully \r\n" );
}
Page Revision: v. 19