host_interface_service.h

Go to the documentation of this file.

/*
 * The Clear BSD License
 * Copyright (c) 2016, Freescale Semiconductor, Inc.
 * Copyright 2016-2017 NXP
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted (subject to the limitations in the disclaimer below) provided
 * that the following conditions are met:
 *
 * o Redistributions of source code must retain the above copyright notice, this list
 *   of conditions and the following disclaimer.
 *
 * o Redistributions in binary form must reproduce the above copyright notice, this
 *   list of conditions and the following disclaimer in the documentation and/or
 *   other materials provided with the distribution.
 *
 * o Neither the name of the copyright holder nor the names of its
 *   contributors may be used to endorse or promote products derived from this
 *   software without specific prior written permission.
 *
 * NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY THIS LICENSE.
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/** 
* @file host_interface_service.h
* @brief The host_interface_service.h file describes the structures and definitions for the host.
*/

#ifndef HOST_INTERFACE_SERVICE_H_
#define HOST_INTERFACE_SERVICE_H_
#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include "comm_interface.h"

#define HOST_INTERFACE_OK 0
#define HOST_INTERFACE_VERSION ((1 << 4) | (0 & 0xF)) // Host Interface Version 1.0

/*******************************************************************************
 * Definitions
 ******************************************************************************/
/*  Interface functions Signature.*/
typedef void (*Host_Event_t)(uint32_t event); /*< Pointer to Host Event.*/

/* @brief This defines the handle to host
 */
typedef struct _host_interface_handle_
{
    comm_interface_t *pCommInterface;
    void *pInData;                     /*!< Input data for the callback .*/
    uint32_t status;                   /*!< Current Comm status.*/
    comm_handle_t commHandle;          /*!< pointer to a specific communication channel.*/
    Host_Event_t event;                /*!< Host Event callback: Future implementaion .*/
    comm_instance_type_t instanceType; /*!< COMM Instance Type .*/
} host_interface_handle_t;

/* @brief This defines the host interface config structure
 */
typedef struct _host_interface_config_
{
    uint32_t tbd; // tbd

} host_interface_config_t;

/* @brief This defines the host interface based events
 */
#define HOST_INTERFACE_EVENT_SEND_COMPLETE \
    (1UL << 0) ///< Send completed. Completed the data transfer. Useful for Asynchronous, non blocking calls
#define HOST_INTERFACE_EVENT_RECEIVE_COMPLETE \
    (1UL << 1) ///< Receive completed, Receved specifed bytes of data. Useful for Asynchronous, non blocking calls

typedef void (*BlockRead_t)(host_interface_handle_t *pHandle, void *pData); /*< Pointer to block read function.
User can implement start and end packet detection logic to determine unknown receive length.
This basically a data-interchangbility format dependent such as HDLC, JSON etc..*/
/******************************************************************************/
/*! @brief       The function to Initialize the Host
 *  @details     It initialize the host for the specified communucation channel and data format service.

 *  @param[in]   pHandle - pointer to the  interface handle
 *  @param[in]   type- host communication type
 *  @param[in]   pCommInstance - pointer to a communication object.
 *  @param[in]   inType - instanceType.
 *  @param[in]   event -  event handler callback
 *  @param[in]   pInData  - input data to underlying layers
 *  @return      ::HOST_Initialize() returns the status .
 *
 *  @Constraints None
 *
 *  @Reentrant   Yes
 */
int32_t HOST_Initialize(host_interface_handle_t *pHandle,
                        comm_type_t type,
                        void *pCommInstance,
                        comm_instance_type_t inType,
                        Host_Event_t event,
                        void *pInData);

/******************************************************************************/
/*! @brief       The function to Configure the Host
 *  @details     TBD

 *  @param[in]   pHandle - pointer to the  interface handle
 *  @param[in]   pConfigData - Host configuration information
 *  @return      ::HOST_Configure() returns the status .
 *
 *  @Constraints None
 *
 *  @Reentrant   Yes
 */
int32_t HOST_Configure(host_interface_handle_t *pHandle, void *pConfigData);
/******************************************************************************/
/*! @brief       The function to Send the data to the host
 *  @details     TBD

 *  @param[in]   pHandle - pointer to the  interface handle
 *  @param[in]   pData - pointer to a data to send
 *  @param[in]   size  - number of byte to send
 *  @return      ::HOST_Send() returns the status .
 *
 *  @Constraints None
 *
 *  @Reentrant   Yes
 */
int32_t HOST_Send(host_interface_handle_t *pHandle, uint8_t *pData, uint32_t size);

/*! @brief       The function to receive data from the host.
 *  @details     BlockRead callback function will be called only if Host is initialized with Blocking Call communication
 instance,
                 refer comm_instance_type_t inType HOST_Initialize() function.
                 If the host is initialized with blocking communication instance, This call will be blocked until
 BlockRead_t process returns provided BlockRead_t process is not NULL
                 else it will be blocked until specified number of requested bytes are received. User can implement own
 logic to separate packet start and end de-limiter in
                 BlockRead_t process to determine a stream or use provided Block Read function in the each Data Format.
                 If the host is intialized with NonBlocking Communication instance. This call will be immediately
 returns and Users Needs to Syschronous data based on
                 Host event HOST_INTERFACE_EVENT_RECEIVE_COMPLETE.
 *  @param[in]   pHandle   - pointer to the  interface handle.
 *  @param[out]  pData - pointer to data to be received.
 *  @param[out]  pRecvSize - number of byte received. This field is for the future use.
 *  @param[in]   size  - Nnumber of byte intend to receive, if user know. This argument has no impact if "BlockRead_t
 process" is not NULL and communication instance is Blocking
 *  @param[in]   process  - process function for the block data read. NOTE: This parameter is not valid, if
 communication Read function is Nonblocking.
    The logic in the callback can start and end packet data detection to get the unknown receive length stream data from
 the host.

 *  @return      ::HOST_Receive() returns the status .
 *
 *  @Constraints None
 *
 *  @Reentrant   Yes
 */
// Note: Signature of this function may change based on the implementation and usability.
int32_t HOST_Receive(
    host_interface_handle_t *pHandle, uint8_t *pData, uint32_t *pRecvSize, uint32_t size, BlockRead_t process);

#endif // HOST_INTERFACE_SERVICE_H_