datapump.h

Go to the documentation of this file.

#ifndef EVE_DATAPUMP_H_INCLUDED
#define EVE_DATAPUMP_H_INCLUDED
/**********************************************************************/
/*
 * Copyright (c) 2016, Jetro AS
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. 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.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONRIBUTORS ``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 AUTHOR 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.
 *
 * This file is part of the EVE platform.
 */

/**
 * \file
 * \brief Header file for datapump interface.
 *
 * \author SE, Jetro AS
 */ /******************************************************************/

#include <lib/rbuf.h>
#include <core/rtos.h>

/**
 * \defgroup datapump Data pump
 * \ingroup net
 * \{
 *
 */

/* Internal datapump flags for task synchronization */
#define DATAPUMP_FLAGS_CAN_READ  (1 << 0)  /*!< Datapump slave pump task can read data */
#define DATAPUMP_FLAGS_CAN_WRITE (1 << 1)  /*!< Datapump master pump task can write data */
#define DATAPUMP_FLAGS_CLOSE     (1 << 2)  /*!< Request for datapump pump tasks to terminate */
#define DATAPUMP_FLAGS_CLOSED    (1 << 3)  /*!< Datapump slave task has been terminated */

/*forward*/ struct datapump_t;

/**
 * A callback which will be called in a task context to open a socket for connection
 *
 * @param Pump    A socket to be created for this datapump
 * @return Socket descriptor in CONNECTED state or -1 if connect failed
 */
typedef int (*datapump_connect_task_cb)(struct datapump_t *Pump);

/**
 * Datapump virtual table
 */
struct datapump_vtbl_t
{
  bool (*Handshake)(struct datapump_t *Pump, int Sock);
  int (*Send)(struct datapump_t *Pump, const uint8_t *Ptr, size_t Len);
  int (*Recv)(struct datapump_t *Pump, uint8_t *Ptr, size_t Len);
  void (*Close)(struct datapump_t *Pump);
};

/**
 * Pump tasks configuration
 */
struct datapump_cfg_t
{
  datapump_connect_task_cb ConnectCb;   /*!< A callback called by a task to establish connection. */
  uint32_t ConnectTimeout;              /*!< Connect / handshake timeout */
  uint32_t SendTimeout;                 /*!< Send timeout */
  uint32_t ReceiveTimeout;              /*!< Receive timeout */
  uint16_t RbufInSize;                  /*!< Size of IN part of datapump_conn_t::RbufData ring buffer */
  uint16_t RbufOutSize;                 /*!< Size of OUT part of datapump_conn_t::RbufData ring buffer */
  uint8_t EventOnClosed;                /*!< Contiki event ID to be sent to an owner process at socket closing */
  uint8_t EventOnReceived;              /*!< Contiki event ID to be sent to an owner process at data reception */
};

/**
 * datapump data pump instance.
 */
struct datapump_t
{
  const struct datapump_cfg_t *PumpCfg; /*!< Pump tasks configuration */
  const struct datapump_vtbl_t *Vtbl;   /*!< Virtual table */
  struct rbuf_t RbufIn;                 /*!< IN ring buffer control structure */
  struct rbuf_t RbufOut;                /*!< OUT ring buffer control structure */
  struct process *ContikiProcess;       /*!< Owner Contiki process, will receive  datapump_cfg_t::EventOn... events */
  EventGroupHandle_t EventGroup;        /*!< DATAPUMP_FLAGS_xxx waitable bits */
  TaskHandle_t MasterTask;              /*!< Master task, used for connect, handshake and write */
  TaskHandle_t SlaveTask;               /*!< Slave task, used for read */
  uint8_t RbufData[0];                  /*!< Ring buffer data. Must be allocated w.r.t.
                                         *   datapump_pump_cfg_t::RbufInSize, datapump_pump_cfg_t::RbufOutSize */
};

/**
 * @internal
 */
bool DatapumpInitImpl(struct datapump_t *Pump);

/**
 * Initializes a connection and starts data pump tasks
 *
 * @param Pump Pointer to an uninitialized data pump instance
 * @param Vtbl Pointer to a virtual function table
 * @param PumpCfg Constant pointer to a data pump configuration
 * @return true if finished successfully, false otherwise
 */
static inline bool DatapumpInit(struct datapump_t *Pump, const struct datapump_vtbl_t *Vtbl, const struct datapump_cfg_t *PumpCfg)
{
  Pump->Vtbl = Vtbl;
  Pump->PumpCfg = PumpCfg;
  return DatapumpInitImpl(Pump);
}

/**
 * Deallocates resources, associated with a datapump.
 *
 * @param Pump Pointer to a data pump instance
 */
void DatapumpFree(struct datapump_t* Pump);

/**
 * Receives data from a datapump connection.
 *
 * The function can be called from a Contiki process.
 * It always read complete data blocks.
 *
 * @param Pump Pointer to a datapump instance
 * @param Buffer  A buffer to put data into
 * @param Length  Length of the buffer (number of bytes to read)
 * @return true if data was read, false otherwise.
 */
bool DatapumpRead(struct datapump_t* Pump, uint8_t* Buffer, size_t Length);

/**
 * Sends data to a datapump connection.
 *
 * The function can be called from a Contiki process.
 * It always read complete data blocks.
 *
 * @param Pump Pointer to a datapump instance
 * @param Buffer  A buffer to put data into
 * @param Length  Length of the buffer (number of bytes to read)
 * @return true if data was read, false otherwise.
 */
bool DatapumpWrite(struct datapump_t* Pump, const uint8_t* Buffer, size_t Length);

/**
 * Returns the number of bytes ready in the incoming buffer.
 *
 * @param  Pump Pointer to a datapump data pump instance
 * @return Number of bytes ready in the incoming buffer
 */
size_t DatapumpBytesIn(struct datapump_t* Pump);

/** \} */

#endif