AVED Management Interface (AMI) Proxy Driver

Overview

The AMI proxy driver binds in the FAL provided in the initialization and uses this to read requests and write responses back to handle communication to/from the host.

Internally it creates a number of resources, including a mutex for protection, a mailbox to handle asynchronous responses and a task to handle the interaction with the FAL.

The task spawned will:

  • Read requests from the FAL store data associated with the host request internally (using an unique id) and generate event via the AEL to anyone registered for the callback.

  • Service the internal mailbox and handle writing data back to the FAL for the host responses.

The API consists of a number of functions to get the AMI request data, these will be called when the application receives the relevant event via the AEL, once the relevant action has been performed the matching response function can be invoked with the same unique id received in the request. The response API’s will then post an internal message with the data required for the host responses to onto the mailbox and then thread will service this mailbox and form up the response back to the host.

The API also provides a few debug function to handle display and clear of the stat/error counters.

Proxy Driver External APIs

Initialize the AMI proxy driver.

This will open the FAL using the handle provided in the API (pxFwIf) & make use of the OSAL layer to create a mutex, a mailbox and a task.

iAMI_Initialise

/*
 * @brief   Main initialisation point for the AMI Proxy Driver
 *
 * @param   ucProxyId   Unique ID for this Proxy driver
 * @param   pxFwIf      Handle to the Firmware Interface to use
 * @param   ulFwIfPort  Port to use on the Firmware Interface
 * @param   ulTaskPrio  Priority of the Proxy driver task (if RR disabled)
 * @param   ulTaskStack Stack size of the Proxy driver task
 *
 * @return  OK          Proxy driver initialised correctly
 *          ERROR       Proxy driver not initialised, or was already initialised
 *
 * @notes   Proxy drivers can have 0 or more firmware interfaces
 */
int iAMI_Initialise( uint8_t ucProxyId,
                     FW_IF_CFG *pxFwIf,
                     uint32_t ulFwIfPort,
                     uint32_t ulTaskPrio,
                     uint32_t ulTaskStack );

Bind Callbacks

This API can be used to bind into a callback to be notified of events generated by the AMI proxy using the EVL library. The current supported events are:

  • AMI_PROXY_DRIVER_E_PDI_DOWNLOAD_STAMI

  • AMI_PROXY_DRIVER_E_SENSOR_READ

  • AMI_PROXY_DRIVER_E_GET_IDENTITY


iAMI_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 iAMI_BindCallback( AEL_CALLBACK *pxCallback );

PDI Download Response

This will post a message onto the mailbox to be handled within the the internal task to send a response back over the FAL that the PDI download request has completed successfully/failed.

iAMI_SetPdiDownloadCompleteResponse

/* Set Functions **************************************************************/

/*
 * @brief   Set the response after the PDI download has completed
 *
 * @param   pxSignal    Current event occurance (used for tracking)
 * @param   xResult     The result of the pdi download request
 *
 * @return  OK          Data passed to proxy driver successfully
 *          ERROR       Data not passed successfully
 */
int iAMI_SetPdiDownloadCompleteResponse( AEL_SIGNAL *pxSignal, AMI_PROXY_RESULT xResult );

PDI Copy Response

This will post a message onto the mailbox to be handled within the the internal task to send a response back over the FAL that the PDI copy request has completed successfully/failed.

iAMI_SetPdiCopyCompleteResponse

/**
 * @brief   Set the response after the PDI copy has completed
 *
 * @param   pxSignal    Current event occurance (used for tracking)
 * @param   xResult     The result of the pdi copy request
 *
 * @return  OK          Data passed to proxy driver successfully
 *          ERROR       Data not passed successfully
 */
int iAMI_SetPdiCopyCompleteResponse( EVL_SIGNAL *pxSignal, AMI_PROXY_RESULT xResult );

Sensor Complete Response

This will post a message onto the mailbox to be handled within the the internal task to send a response back over the FAL that the sensor read request has completed successfully/failed.

iAMI_SetSensorCompleteResponse

/*
 * @brief   Set the response after the sensor request has completed
 *
 * @param   pxSignal    Current event occurance (used for tracking)
 * @param   xResult     The result of the sensor request
 *
 * @return  OK          Data passed to proxy driver successfully
 *          ERROR       Data not passed successfully
 */
int iAMI_SetSensorCompleteResponse( AEL_SIGNAL *pxSignal, AMI_PROXY_RESULT xResult );

Identity Response

This will post a message onto the mailbox to be handled within the the internal task to send a response back over the FAL that the identity read request has completed successfully/failed.

iAMI_SetIdentityResponse

/*
 * @brief   Set the identity response
 *
 * @param   pxSignal                Current event occurance (used for tracking)
 * @param   xResult                 The result of the identity request
 * @param   pxIdentityResponse      The structure containing the major/minor version
 *
 * @return  OK                      Data passed to proxy driver successfully
 *          ERROR                   Data not passed successfully
 */
int iAMI_SetIdentityResponse( AEL_SIGNAL *pxSignal, AMI_PROXY_RESULT xResult, AMI_PROXY_IDENTITY_ *pxIdentity );

Boot Select Response

This will post a message onto the mailbox to be handled within the the internal task to send a back over the FAL that the boot select request has completed successfully/failed.

iAMI_SetBootSelectCompleteResponse

/**
 * @brief   Set the response after the Boot select has completed
 *
 * @param   pxSignal    Current event occurance (used for tracking)
 * @param   xResult     The result of the boot select request
 *
 * @return  OK          Data passed to proxy driver successfully
 *          ERROR       Data not passed successfully
 */
int iAMI_SetBootSelectCompleteResponse( EVL_SIGNAL *pxSignal, AMI_PROXY_RESULT xResult );

EEPROM read/write Response

This will post a message onto the mailbox to be handled within the the internal task to send a back over the FAL that the EEPROM read/write request has completed successfully/failed.

iAMI_SetEepromReadWriteCompleteResponse

/**
 * @brief   Set the response after the EEPROM read/write has completed
 *
 * @param   pxSignal    Current event occurance (used for tracking)
 * @param   xResult     The result of the boot select request
 *
 * @return  OK          Data passed to proxy driver successfully
 *          ERROR       Data not passed successfully
 */
int iAMI_SetEepromReadWriteCompleteResponse( EVL_SIGNAL *pxSignal, AMI_PROXY_RESULT xResult );

Module read/write Response

This will post a message onto the mailbox to be handled within the the internal task to send a back over the FAL that the Module read/write request has completed successfully/failed.

iAMI_SetModuleReadWriteCompleteResponse

/**
 * @brief Set the response after the module read/write has completed
 *
 * @param pxSignal Current event occurance (used for tracking)
 * @param xResult The result of the module rd/wr request
 *
 * @return OK Data passed to proxy driver successfully
 * ERROR Data not passed successfully
 */
int iAMI_SetModuleReadWriteCompleteResponse( EVL_SIGNAL *pxSignal, AMI_PROXY_RESULT xResult );

PDI Download Request

This API will be used by the application to obtain the data associated with the PDI download request, which is stored internally within the proxy before the event is raised.

iAMI_GetPdiDownloadRequest

/*
 * @brief   Get the PDI download request
 *
 * @param   pxSignal                Current event occurrence (used for tracking)
 * @param   pxDownloadRequest       Pointer to download pdi structure
 *
 * @return  OK                      Data retrieved from proxy driver successfully
 *          ERROR                   Data not retrieved successfully
 *
 */
int iAMI_GetPdiDownloadRequest( AEL_SIGNAL *pxSignal, AMI_PROXY_PDI_DOWNLOAD_REQUEST *pxDownloadRequest );

PDI Copy Request

This API will be used by the application to obtain the data associated with the PDI copy request, which is stored internally within the proxy before the event is raised.

iAMI_GetPdiCopyRequest

/**
 * @brief   Get the PDI copy request
 *
 * @param   pxSignal                Current event occurrence (used for tracking)
 * @param   pxCopyRequest           Pointer to copy pdi structure
 *
 * @return  OK                      Data retrieved from proxy driver successfully
 *          ERROR                   Data not retrieved successfully
 */
int iAMI_GetPdiCopyRequest( EVL_SIGNAL *pxSignal,
                            AMI_PROXY_PDI_COPY_REQUEST *pxCopyRequest );

Sensor Request

This API will be used by the application to obtain the data associated with the Get Sensor request, which is stored internally within the proxy before the event is raised.

iAMI_GetSensorRequest

/*
 * @brief   Get the Sensor request
 *
 * @param   pxSignal                Current event occurrence (used for tracking)
 * @param   pxSensorRequest         Pointer sensor request structure
 *
 * @return  OK                      Data retrieved from proxy driver successfully
 *          ERROR                   Data not retrieved successfully
 *
 */
int iAMI_GetSensorRequest( AEL_SIGNAL *pxSignal, AMI_PROXY_SENSOR_REQUEST *pxSensorRequest );

Boot Select Request

This API will be used by the application to obtain the data associated with the boot selection request, which is stored internally within the proxy before the event is raised.

iAMI_GetBootSelectRequest

/**
 * @brief   Get the Boot Select request
 *
 * @param   pxSignal                Current event occurance (used for tracking)
 * @param   pxBootSelectRequest     Pointer boot select request structure
 *
 * @return  OK                      Data retrieved from proxy driver successfully
 *          ERROR                   Data not retrieved successfully
 *
 */
int iAMI_GetBootSelectRequest( EVL_SIGNAL *pxSignal, AMI_PROXY_BOOT_SELECT_REQUEST *pxBootSelectRequest );

Eeprom Read Write Request

This API will be used by the application to obtain the data associated with the EEPROM read write request, which is stored internally within the proxy before the event is raised.

iAMI_GetEepromReadWriteRequest

/**
 * @brief   Get the eeprom read write request
 *
 * @param   pxSignal                    Current event occurance (used for tracking)
 * @param   pxEepromReadWriteRequest    Pointer sensor request structure
 *
 * @return  OK                          Data retrieved from proxy driver successfully
 *          ERROR                       Data not retrieved successfully
 *
 */
int iAMI_GetEepromReadWriteRequest( EVL_SIGNAL *pxSignal,
                                    AMI_PROXY_EEPROM_RW_REQUEST *pxEepromReadWriteRequest );

Module Read Write Request

This API will be used by the application to obtain the data associated with the Module read write request, which is stored internally within the proxy before the event is raised.

iAMI_GetModuleReadWriteRequest

/**
 * @brief Get the module read write request
 *
 * @param pxSignal Current event occurance (used for tracking)
 * @param pxModuleReadWriteRequest Pointer sensor request structure
 *
 * @return OK Data retrieved from proxy driver successfully
 * ERROR Data not retrieved successfully
 *
 */
int iAMI_GetModuleReadWriteRequest( EVL_SIGNAL *pxSignal, AMI_PROXY_MODULE_RW_REQUEST *pxModuleReadWriteRequest );

Clear Statistics

Debug function used to clear the all statistics counters back to zero.

iAMI_ClearStatistics

/*
 * @brief   Clear all the stats in the application
 *
 * @return  OK          Stats cleared successfully
 *          ERROR       Stats not cleared successfully
 *
 * @notes   None
 */
int iAMI_ClearStatistics( void );

Sequence Diagrams

AMI Proxy Initialization

The initialization function (iAMI_Initialise) is called from the main task when all the other proxies are being initialized.

It obtains a handle to the FAL and creates the resources needed by the driver including spawning the AMI proxy task.

image2

AMI Proxy Task

The task within the AMI proxy has two different responsibilities:

  • To check for requests incoming via the FAL.

  • To service the internal mailbox and form up responses to go back out to the FAL.

image3

AMI Handling Requests

The request API’s allows an application to get a copy of the internal proxy request data received via the FAL.

  • iAMI_GetPdiDownloadRequest( )

  • iAMI_GetSensorRequest( )

The requests data is stored within the AMI proxy when the event is generated and the callback has been invoked to notify any registered users.

When the request from the application is made a protected copy of the data is made and returned that will allow the user to perform the relevant action.

image4

AMI Handling Responses

The response API’s are used by the application to respond back to the request with data/result code once the relevant action has been performed.

  • iAMI_SetPdiDownloadCompleteResponse( )

  • iAMI_SetSensorCompleteResponse( )

  • iAMI_SetIdentityResponse( )

Within each response a mailbox message is formed with the unique instance id, the type, and the result and posted to be handled by the internal task.

image5

Examples

Initialize Driver

The initialize function needs a unique id for the proxy, a handle to a FW_IF (already created and initialized), and a task priority/size passed in.

iAMI_Initialise Example

#define AMC_EVENT_UNIQUE_ID_AMI ( 1 )   /* each proxy needs an unique id */
#define AMC_TASK_PRIO_DEFAULT   ( 5 )
#define AMC_TASK_DEFAULT_STACK  ( 0x1024 )

/* NOTE: The handle to the FW_IF needs to have been initialised and created before being passed in */
if( OK == iAMI_Initialise( AMC_EVENT_UNIQUE_ID_AMI, &myIf, 0, AMC_TASK_PRIO_DEFAULT, AMC_TASK_DEFAULT_STACK ) )
{
    printf( "AMI Proxy Driver initialised\r\n" );
}
else
{
    printf( "Error initialising AMI Proxy Driver\r\n" );
}

Register For Callback

Define a function based on the function pointer prototype and bind in using the API.

iAMI_BindCallback Example

/* Define a callback to handle the events */
int iAmiCallback( AEL_SIGNAL *pxSignal )
{
    int iStatus = ERROR;

    if( ( NULL != pxSignal )
    {
        printf( "AMI Proxy Driver (0x%02X), Instance %d\r\n", pxSignal->ucModule, pxSignal->ucInstance );

        switch( pxSignal->ucEventType )
        {
        case AMI_PROXY_DRIVER_E_SENSOR_READ:
        case AMI_PROXY_DRIVER_E_PDI_DOWNLOAD_STAMI:
        case AMI_PROXY_DRIVER_E_GET_IDENTITY:
            /* TODO: handle the events */
            iStatus = OK;
            break;

        default:
            break;
        }
    }

    return iStatus;
}

/* Bind into the callback during the application initialisation */
int iApplication_Initialise( void )
{
    int iStatus = ERROR;

    /* The rest of init depending on application before or after the callback binding */

    iStatus = iAMI_BindCallback( &iAmiCallback );
    if( OK == iStatus )
    {
        printf( "AMI Proxy Driver bound\r\n" );
    }
    else
    {
        printf( "Error binding to AMI Proxy Driver\r\n" );
    }

    return iStatus;
}

Generating Responses

Example of calling the response (iAMI_SetSensorCompleteResponse) from within the callback to send the result back towards the host.

iAMI_SetSensorCompleteResponse Example

/* Define a callback to handle the events */
int iAmiCallback( AEL_SIGNAL *pxSignal )
{
    int iStatus = ERROR;
    if( ( NULL != pxSignal )
    {   AMI_PROXY_RESULT xResult = AMI_PROXY_RESULT_INVALID_ARG;
        printf( "AMI Proxy Driver (0x%02X), Instance %d\r\n", pxSignal->ucModule, pxSignal->ucInstance );

        switch( pxSignal->ucEventType )
        {
        case AMI_PROXY_DRIVER_E_SENSOR_READ:
            /* TODO: collect the sensor data */

            /* TODO: Set the result code based on the collection */

            /* Send the response back using same pxSignal structure passed into callback & the result */
            iStatus = iAMI_SetSensorCompleteResponse( pxSignal, xResult );
            break;

        case AMI_PROXY_DRIVER_E_PDI_DOWNLOAD_STAMI:
        case AMI_PROXY_DRIVER_E_GET_IDENTITY:
            /* TODO: handle the other events */
            break;

        default:
            break;
        }
    }

    return iStatus;
}

Handling Requests

Example of requesting the data associated with an event (iAMI_GetSensorRequest) from within the callback and to send the result back towards the host.

iAMI_GetSensorRequest Example

/* Define a callback to handle the events */
int iAmiCallback( AEL_SIGNAL *pxSignal )
{
    int iStatus = ERROR;
    if( ( NULL != pxSignal )
    {   AMI_PROXY_RESULT xResult = AMI_PROXY_RESULT_INVALID_ARG;
        printf( "AMI Proxy Driver (0x%02X), Instance %d\r\n", pxSignal->ucModule, pxSignal->ucInstance );

        switch( pxSignal->ucEventType )
        {
        case AMI_PROXY_DRIVER_E_SENSOR_READ:
            iStatus = iAMI_GetSensorRequest( pxSignal, &xSensorRequest );

            if( OK == iStatus )
            {
                /* TODO: use data from xSensorRequest to collect the correct sensor data */

                /* Set the result code based on the collection */
                xResult = AMI_PROXY_RESULT_SUCCESS;

                /* Send the response back using same pxSignal structure passed into callback & the result*/
                iStatus = iAMI_SetSensorCompleteResponse( pxSignal, xResult );
            }
            break;

        case AMI_PROXY_DRIVER_E_PDI_DOWNLOAD_STAMI:
        case AMI_PROXY_DRIVER_E_GET_IDENTITY:
            /* TODO: handle the other events */
            break;

        default:
            break;
        }
    }

    return iStatus;
}

Page Revision: v. 49