/* Copyright (c) 2015, The Linux Foundation. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * 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.
    * Neither the name of The Linux Foundation nor the names of its
      contributors may be used to endorse or promote products derived
      from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER 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.
*/

#ifndef GLINK_H
#define GLINK_H

/**
 * @file glink.h
 *
 * Public API for the GLink
 */

/** \defgroup glink GLink
 * \ingroup SMD
 *
 * GLink reliable, in-order, datagram-based interprocessor communication
 * over a set of supported transport (Shared Memory, UART, BAM, HSIC)
 *
 * All ports preserve message boundaries across the interprocessor channel; one
 * write into the port exactly matches one read from the port.
 */
/*@{*/


#ifdef __cplusplus
extern "C" {
#endif

/*===========================================================================
                        INCLUDE FILES
===========================================================================*/
#include <stdlib.h>

/*===========================================================================
                      MACRO DECLARATIONS
===========================================================================*/
/** GLink status/return codes */
typedef enum {
  GLINK_STATUS_SUCCESS = 0,
  GLINK_STATUS_FAILURE,
  GLINK_STATUS_INVALID_PARAM,
  GLINK_STATUS_NOT_INIT,
  GLINK_STATUS_OUT_OF_RESOURCES,
  GLINK_STATUS_NO_TRANSPORT
}glink_err_type;

/** List of possible suvsystems */
/**
  "apss"   Application Processor Subsystem
  "mpss"   Modem subsystem
  "lpass"  Low Power Audio Subsystem
  "dsps"   Sensors Processor
  "wcnss"  Wireless Connectivity Subsystem
  "rpm"    Resource Power Manager processor
*/

/** Max allowed channel name length */
#define GLINK_CH_NAME_LEN 32

/* Bit position of DTR/CTS/CD/RI bits in control sigs 32 bit signal map */
#define SMD_DTR_SIG_SHFT 31
#define SMD_CTS_SIG_SHFT 30
#define SMD_CD_SIG_SHFT  29
#define SMD_RI_SIG_SHFT  28

/** Version number for the glink_link_id_type structure */
#define GLINK_LINK_ID_VER  0x00000001

/** Macro to initialize the link identifier structure with default values.
 * It memsets the header to 0 and initializes the header field */
#define GLINK_LINK_ID_STRUCT_INIT(link_id) \
                          (link_id).xport = 0; \
                          (link_id).remote_ss = 0; \
                          (link_id).link_notifier = 0; \
                          (link_id).handle = 0; \
                          (link_id).version = GLINK_LINK_ID_VER;

/* GLink tx options */
/* Flag for no options */
#define GLINK_TX_NO_OPTIONS      ( 0 )

/* Whether to block and request for remote rx intent in
 * case it is not available for this pkt tx */
#define GLINK_TX_REQ_INTENT      0x00000001

/* If the tx call is being made from single threaded context. GLink tries to
 * flush data into the transport in glink_tx() context, or returns error if
 * it is not able to do so */
#define GLINK_TX_SINGLE_THREADED 0x00000002

/* This option is to turn on tracer packet */
#define GLINK_TX_TRACER_PKT      0x00000004

/* ======================= glink open cfg options ==================*/

/* Specified transport is just the initial transport and migration is possible
 * to higher-priority transports.  Without this flag, the open will fail if
 * the transport does not exist. */
#define GLINK_OPT_INITIAL_XPORT   0x00000001

/*===========================================================================
                      TYPE DECLARATIONS
===========================================================================*/
/** Enums to identify link state */
typedef enum {
 GLINK_LINK_STATE_UP,  /* Called after specified link is online */
 GLINK_LINK_STATE_DOWN /* Called after SSR (before REMOTE_DISCONNECT) */
} glink_link_state_type;

/** Data structure holding the link state information */
typedef struct          glink_link_info_t {
  const char*           xport;      /* Transport name */
  const char*           remote_ss;  /* Remote subsystem name */
  glink_link_state_type link_state; /* Link state */
}glink_link_info_type;

/* Callback function invoked when link goes up/down */
typedef void (*glink_link_state_notif_cb)
(
  glink_link_info_type *link_info, /* Ptr to link information strcuture */
  void* priv                       /* Client private data */
);

/**
 * Opaque handle returned by glink_register_link_state_cb. Client uses this
 * handle to call glink_deregister_link_state_cb() to deregister their
 * callback
 *
 * Client must not modify or try to interpret this value
 */
typedef struct glink_link_notif_data_type * glink_link_handle_type;

/** Data structure to provide link information for the link to monitor */
typedef struct glink_link_id_t {
  unsigned int              version; /* This fields identifies the verion of
                                        the structure. Initialized by
                                        GLINK_LINK_ID_STRUCT_INIT macro */

  const char*               xport;         /* NULL = any transport */
  const char*               remote_ss;     /* NULL = any subsystem */
  glink_link_state_notif_cb link_notifier; /* Notification callback */
  glink_link_handle_type    handle;  /* Set by glink_register_link_state_cb */
}glink_link_id_type;

/**
 * Opaque handle returned by glink_open. Client uses this handle to call into
 * GLink API for any further activity related to the channel,
 *
 * Client must to modify or try to interpret this value
 */
typedef struct glink_channel_ctx* glink_handle_type;

/** GLink logical link state notifications */
typedef enum {
  /** Channel is fully opened. Both local and remote end have
      opened channel from their respective ends, and data communication
      can now take place */
  GLINK_CONNECTED = 0,

  /** Local side has called glink_close() and remote side has acknowledged
      this end's close. Client may call glink_open() after this point */
  GLINK_LOCAL_DISCONNECTED,

  /** Remote side has called glink_close() to close the channel */
  GLINK_REMOTE_DISCONNECTED
}glink_channel_event_type;

/** Vector buffer provider type*/
typedef void* (*glink_buffer_provider_fn)
(
  void*  iovec,   /* vector buffer */
  size_t offset,  /* offset from the beginning of the vector */
  size_t *size    /* size of the returned contiguous buffer */
);

/** Data receive notification callback type*/
typedef void (*glink_rx_notification_cb)
(
  glink_handle_type handle,     /* handle for the glink channel */
  const void        *priv,      /* priv client data passed in glink_open */
  const void        *pkt_priv,  /* private client data assiciated with the
                                   rx intent that client queued earlier */
  const void        *ptr,       /* pointer to the received buffer */
  size_t            size,       /* size of the packet */
  size_t            intent_used /* size of the intent used for this packet */
);

/** Data receive notification callback type*/
typedef void (*glink_rx_tracer_pkt_notification_cb)
(
  glink_handle_type handle,     /* handle for the glink channel */
  const void        *priv,      /* priv client data passed in glink_open */
  const void        *pkt_priv,  /* private client data assiciated with the
                                   rx intent that client queued earlier */
  const void        *ptr,       /* pointer to the received buffer */
  size_t            size        /* size of the packet */
);

/** Vector receive notification callback type*/
typedef void (*glink_rxv_notification_cb)
(
  glink_handle_type        handle,    /* handle for the glink channel */
  const void               *priv,     /* priv client data passed in glink_open */
  const void               *pkt_priv, /* private client data assiciated with the
                                         rx intent that client queued earlier */
  void                     *iovec,    /* pointer to the received vector */
  size_t                   size,      /* size of the packet */
  size_t                   intent_used, /* size of the intent used for this packet */
  glink_buffer_provider_fn vprovider, /* Buffer provider for virtual space */
  glink_buffer_provider_fn pprovider  /* Buffer provider for physical space */
);

/** Data transmit notification callback type*/
typedef void (*glink_tx_notification_cb)
(
  glink_handle_type handle,    /* handle for the glink channel */
  const void        *priv,     /* priv client data passed in glink_open */
  const void        *pkt_priv, /* private client data assiciated with the
                                  tx pkt that client queued earlier */
  const void        *ptr,      /* pointer to the transmitted buffer */
  size_t            size       /* size of the packet */
);

/** GLink channel state change notification callback type*/
typedef void (*glink_state_notification_cb)
(
  glink_handle_type         handle, /* handle for the glink channel */
  const void                *priv,  /* priv client data passed in glink_open */
  glink_channel_event_type  event   /* Notification event */
);

/** Request for a receive intent of size req_size is queued. The request
 * originates from the remote side GLink client. Return true if intent will
 * be queued or false if intent request will be denied. */
typedef bool (*glink_notify_rx_intent_req_cb)
(
  glink_handle_type         handle,   /* handle for the glink channel */
  const void                *priv,    /* priv client data passed in glink_open */
  size_t                    req_size  /* Requested size */
);

/** New intent arrival notification callback type*/
typedef void (*glink_notify_rx_intent_cb)
(
  glink_handle_type         handle,   /* handle for the glink channel */
  const void                *priv,    /* priv client data passed in glink_open */
  size_t                    size      /* Intent size */
);

/** Control signal change notification - Invoked when remote side
 *  alters its control signals */
typedef void (*glink_notify_rx_sigs_cb)
(
  glink_handle_type  handle,   /* handle for the glink channel */
  const void         *priv,    /* priv client data passed in glink_open  */
  uint32_t             prev,     /* Previous remote state */
  uint32_t             curr      /* Current remote state */
);

/** rx_intent abort notification. This callback would be invoked for
 *  every rx_intent that is queued with GLink core at the time the
 *  remote side or local side decides to close the port */
typedef void(*glink_notify_rx_abort_cb)
(
glink_handle_type  handle,   /* handle for the glink channel */
const void         *priv,    /* priv client data passed in glink_open  */
const void         *pkt_priv /* pkt specific private data */
);

/** tx abort notification. This callback would be invoked if client
 *   had queued a tx buffer with glink and it had not been transmitted i.e.
 *   tx_done callback has not been called for this buffer and remote side
 *   or local side closed the port*/
typedef void(*glink_notify_tx_abort_cb)
(
glink_handle_type  handle,   /* handle for the glink channel */
const void         *priv,    /* priv client data passed in glink_open  */
const void         *pkt_priv /* pkt specific private data */
);

/**
 * Data Structure for GLink logical channel open configuration
 *
 * This structure is used by the clients to open a GLink logical channel
 * when calling glink_open()
 */
typedef struct {
  /** string name for the transport to use (Optional)*/
  const char                          *transport;

  /** string name for the remote subsystem to which the user wants to
      connect */
  const char                          *remote_ss;

  /** string name for the channel */
  const char                          *name;

  /** bitfield for specifying various options */
  unsigned                            options;

  /** Private data for client to maintain context. This data is passed back
      to client in the notification callbacks */
  const void                          *priv;

  /** Data receive notification callback. Optional if notify_rxv is provided */
  glink_rx_notification_cb            notify_rx;

  /** Tracer packet receive notification callback.
   *  Optional if user doesn't need to use this */
  glink_rx_tracer_pkt_notification_cb notify_rx_tracer_pkt;

  /** Vector receive notification callback. Optional if notify_rx is provided */
  glink_rxv_notification_cb           notify_rxv;

  /** Data transmit notification callback */
  glink_tx_notification_cb            notify_tx_done;

  /** GLink channel state notification callback */
  glink_state_notification_cb         notify_state;

  /** Intent request from the remote side. Optional */
  glink_notify_rx_intent_req_cb       notify_rx_intent_req;

  /** New intent arrival from the remote side */
  glink_notify_rx_intent_cb           notify_rx_intent;

  /** Control signal change notification - Invoked when remote side
   *  alters its control signals. Optional */
  glink_notify_rx_sigs_cb             notify_rx_sigs;

  /** rx_intent abort notification. This callback would be invoked for
   *  every rx_intent that is queued with GLink core at the time the
   *  remote side or local side decides to close the port. Optional */
  glink_notify_rx_abort_cb            notify_rx_abort;

  /** tx abort notification. This callback would be invoked if client
  *   had queued a tx buffer with glink and it had not been transmitted i.e.
  *   tx_done callback has not been called for this buffer and remote side
  *   or local side closed the port. Optional */
  glink_notify_tx_abort_cb            notify_tx_abort;

}glink_open_config_type;

/*===========================================================================
                      GLINK PUBLIC API
===========================================================================*/
/**
 * Regsiters a client specified callback to be invoked when the specified
 * transport (link) is up/down.
 *
 * @param[in]    link_id  Pointer to the configuration structure for the
 *                        xport(link) to be monitored. See glink.h
 * @param[in]    priv     Callback data returned to client when callback
 *                        is invoked.
 *
 * @return       Standard GLink error codes
 *
 * @sideeffects  Puts the callback in a queue which gets scanned when a
 *               transport(link) comes up OR an SSR happnes.
 */
glink_err_type glink_register_link_state_cb
(
  glink_link_id_type *link_id,
  void* priv
);

/**
 * Degsiter the link UP/DOWN notification callback associated with the
 * provided handle.
 *
 * @param[in]    handle  Callback handler returned by
 *                       glink_register_link_state_cb
 *
 * @return       Standard GLink error codes
 *
 * @sideeffects  Removes the callback in a queue which gets scanned when a
 *               transport(link) comes up OR an SSR happnes.
 */
glink_err_type glink_deregister_link_state_cb
(
  glink_link_handle_type handle
);

/**
 * Opens a logical GLink based on the specified config params
 *
 * @param[in]    cfg_ptr  Pointer to the configuration structure for the
 *                        GLink. See glink.h
 * @param[out]   handle   GLink handle associated with the logical channel
 *
 * @return       Standard GLink error codes
 *
 * @sideeffects  Allocates channel resources and informs remote host about
 *               channel open.
 */
glink_err_type glink_open
(
  glink_open_config_type *cfg_ptr,
  glink_handle_type      *handle
);

/**
 * Closes the GLink logical channel specified by the handle.
 *
 * @param[in]    handle   GLink handle associated with the logical channel
 *
 * @return       Standard GLink error codes
 *
 * @sideeffects  Closes local end of the channel and informs remote host
 */
glink_err_type glink_close
(
  glink_handle_type handle
);

/**
 * Transmit the provided buffer over GLink.
 *
 * @param[in]    handle    GLink handle associated with the logical channel
 *
 * @param[in]   *pkt_priv  Per packet private data
 *
 * @param[in]   *data      Pointer to the data buffer to be transmitted
 *
 * @param[in]   size       Size of buffer
 *
 * @param[in]   options    Flags specifying how transmission for this buffer
 *                         would be handled. See GLINK_TX_* flag definitions.
 *
 * @return       Standard GLink error codes
 *
 * @sideeffects  Causes remote host to wake-up and process rx pkt
 */
glink_err_type glink_tx
(
  glink_handle_type handle,
  const void        *pkt_priv,
  const void        *data,
  size_t            size,
  uint32_t            options
);

/**
 * Transmit the provided vector buffer over GLink.
 *
 * @param[in]    handle    GLink handle associated with the logical channel
 *
 * @param[in]   *pkt_priv  Per packet private data
 *
 * @param[in]   *iovec     Pointer to the vector buffer to be transmitted
 *
 * @param[in]   size       Size of buffer
 *
 * @param[in]   vprovider  Buffer provider for virtual space
 *
 * @param[in]   pprovider  Buffer provider for physical space
 *
 * @param[in]   options    Flags specifying how transmission for this buffer
 *                         would be handled. See GLINK_TX_* flag definitions.
 *
 * @return       Standard GLink error codes
 *
 * @sideeffects  Causes remote host to wake-up and process rx pkt
 */
glink_err_type glink_txv
(
  glink_handle_type        handle,
  const void               *pkt_priv,
  void                     *iovec,
  size_t                   size,
  glink_buffer_provider_fn vprovider,
  glink_buffer_provider_fn pprovider,
  uint32_t                   options
);

/**
 * Queue one or more Rx intent for the logical GPIC Link channel.
 *
 * @param[in]    handle   GLink handle associated with the logical channel
 *
 * @param[in]   *pkt_priv Per packet private data
 *
 * @param[in]   size      Size of buffer
 *
 * @return       Standard GLink error codes
 *
 * @sideeffects  GLink XAL allocates rx buffers for receiving packets
 */
glink_err_type glink_queue_rx_intent
(
  glink_handle_type handle,
  const void        *pkt_priv,
  size_t            size
);

/**
 * Client uses this to signal to GLink layer that it is done with the received
 * data buffer. This API should be called to free up the receive buffer, which,
 * in zero-copy mode is actually remote-side's transmit buffer.
 *
 * @param[in]   handle   GLink handle associated with the logical channel
 *
 * @param[in]   *ptr     Pointer to the received buffer
 *
 * @param[in]   reuse    Reuse intent
 *
 * @return       Standard GLink error codes
 *
 * @sideeffects  GLink XAL frees the Rx buffer
 */
glink_err_type glink_rx_done
(
  glink_handle_type handle,
  const void        *ptr,
  bool           reuse
);

/**
 * Set the 32 bit control signal field. Depending on the transport, it may
 * take appropriate actions on the set bit-mask, or transmit the entire
 * 32-bit value to the remote host.
 *
 * @param[in]   handle     GLink handle associated with the logical channel
 *
 * @param[in]   sig_value  32 bit signal word
 *
 * @return       Standard GLink error codes
 *
 * @sideeffects  None
 */
glink_err_type glink_sigs_set
(
  glink_handle_type handle,
  uint32_t            sig_value
);

/**
 * Get the local 32 bit control signal bit-field.
 *
 * @param[in]   handle      GLink handle associated with the logical channel
 *
 * @param[out]  *sig_value  Pointer to a 32 bit signal word to get sig value
 *
 * @return      Standard GLink error codes
 *
 * @sideeffects  None
 */
glink_err_type glink_sigs_local_get
(
  glink_handle_type handle,
  uint32_t            *sig_value
);

/**
 * Get the remote 32 bit control signal bit-field.
 *
 * @param[in]   handle      GLink handle associated with the logical channel
 *
 * @param[out]  *sig_value  Pointer to a 32 bit signal word to get sig value
 *
 * @return      Standard GLink error codes
 *
 * @sideeffects  None
 */
glink_err_type glink_sigs_remote_get
(
  glink_handle_type handle,
  uint32_t            *sig_value
);

#ifdef __cplusplus
}
#endif

#endif //GLINK_H