Source code for csp.h

/*****************************************************************************
 * **File:** csp/csp.h
 *
 * **Description:** CSP Library Header File
 ****************************************************************************/
#pragma once

#include <csp/csp_error.h>
#include <csp/csp_debug.h>
#include <csp/csp_buffer.h>
#include <csp/csp_rtable.h>
#include <csp/csp_iflist.h>
#include <csp/csp_sfp.h>
#include <csp/csp_promisc.h>

#ifdef __cplusplus
extern "C" {
#endif

[docs]/** Max timeout */
#define CSP_MAX_TIMEOUT (UINT32_MAX)

[docs]/** Max delay */
#define CSP_MAX_DELAY CSP_MAX_TIMEOUT
#define CSP_INFINITY CSP_MAX_TIMEOUT


[docs]/**
 * CSP Debug Types
 */
enum csp_dedup_types {
[docs]   CSP_DEDUP_OFF,              /**< Deduplication off */
[docs]   CSP_DEDUP_FWD,              /**< Deduplication on forwarding only */
[docs]   CSP_DEDUP_INCOMING,         /**< Deduplication on incomfing only */
[docs]   CSP_DEDUP_ALL,              /**< Deduplication on incoming and forwarding*/
};

[docs]/**
 * CSP configuration.
 */
typedef struct csp_conf_s {
[docs]   uint8_t version;            /**< Protocol version to use (either 1 or 2) */
[docs]   const char *hostname;       /**< Host name, returned by the #CSP_CMP_IDENT request */
[docs]   const char *model;          /**< Model, returned by the #CSP_CMP_IDENT request */
[docs]   const char *revision;       /**< Revision, returned by the #CSP_CMP_IDENT request */
[docs]   uint32_t conn_dfl_so;       /**< Default connection options. Options will always be or'ed onto new connections, see csp_connect() */
[docs]   uint8_t dedup;              /**< Enable CSP deduplication. 0 = off, 1 = always on, 2 = only on forwarded packets,  */
} csp_conf_t;

extern csp_conf_t csp_conf;

[docs]/**
 * Initialize CSP.
 * This will configure basic structures.
 */
void csp_init(void);

[docs]/**
 * Free allocated resorces in CSP.
 * This is intended for testing of CSP, in order to be able re-initialize CSP by calling csp_init() again.
 */
void csp_free_resources(void);

[docs]/**
 * Get a \a read-only reference to the active CSP configuration.
 *
 * @return Active CSP configuration (read-only).
 */
const csp_conf_t * csp_get_conf(void);

[docs]/**
 * Copy csp id fields from source to target object
 */
void csp_id_copy(csp_id_t * target, csp_id_t * source);

[docs]/**
 * Wait/accept a new connection.
 *
 * @param[in] socket socket to accept connections on, created by calling csp_socket().
 * @param[in] timeout  timeout in mS to wait for a connection, use CSP_MAX_TIMEOUT for infinite timeout.
 * @return New connection on success, NULL on failure or timeout.
 */
csp_conn_t *csp_accept(csp_socket_t *socket, uint32_t timeout);

[docs]/**
 * Read packet from a connection.
 * This fuction will wait on the connection's RX queue for the specified timeout.
 *
 * @param[in] conn  connection
 * @param[in] timeout timeout in mS to wait for a packet, use CSP_MAX_TIMEOUT for infinite timeout.
 * @return Packet or NULL in case of failure or timeout.
 */
csp_packet_t *csp_read(csp_conn_t *conn, uint32_t timeout);

[docs]/**
 * Send packet on a connection.
 * The packet buffer is automatically freed, and cannot be used after the call to csp_send()
 *
 * @param[in] conn connection
 * @param[in] packet packet to send
*/
void csp_send(csp_conn_t *conn, csp_packet_t *packet);

[docs]/**
 * Change the default priority of the connection and send a packet.
 *
 * .. note:: The priority of the connection will be changed.
 *           If you need to change it back, call csp_send_prio() again.
 *
 * @param[in] prio priority to set on the connection
 * @param[in] conn connection
 * @param[in] packet packet to send
 */
void csp_send_prio(uint8_t prio, csp_conn_t *conn, csp_packet_t *packet);

[docs]/**
 * Perform an entire request & reply transaction.
 * Creates a connection, send \a outbuf, wait for reply, copy reply to \a inbuf and close the connection.
*
* @param[in] prio priority, see #csp_prio_t
* @param[in] dst destination address
* @param[in] dst_port destination port
* @param[in] timeout timeout in mS to wait for a reply
* @param[in] outbuf outgoing data (request)
* @param[in] outlen length of data in \a outbuf (request)
* @param[out] inbuf user provided buffer for receiving data (reply)
* @param[in] inlen length of expected reply, -1 for unknown size (inbuf MUST be large enough), 0 for no reply.
* @param[in] opts connection options, see @ref CSP_CONNECTION_OPTIONS.
*
* Returns:
*   int: 1 or reply size on success, 0 on failure (error, incoming length does not match, timeout)
*/
int csp_transaction_w_opts(uint8_t prio, uint16_t dst, uint8_t dst_port, uint32_t timeout, void *outbuf, int outlen, void *inbuf, int inlen, uint32_t opts);

[docs]/**
 * Perform an entire request & reply transaction.
 * Creates a connection, send \a outbuf, wait for reply, copy reply to \a inbuf and close the connection.
 *
 * @param[in] prio priority, see #csp_prio_t
 * @param[in] dest destination address
 * @param[in] port destination port
 * @param[in] timeout timeout in mS to wait for a reply
 * @param[in] outbuf outgoing data (request)
 * @param[in] outlen length of data in \a outbuf (request)
 * @param[out] inbuf user provided buffer for receiving data (reply)
 * @param[in] inlen length of expected reply, -1 for unknown size (inbuf MUST be large enough), 0 for no reply.
 * @return 1 or reply size on success, 0 on failure (error, incoming length does not match, timeout)
 */
static inline int csp_transaction(uint8_t prio, uint16_t dest, uint8_t port, uint32_t timeout, void * outbuf, int outlen, void * inbuf, int inlen) {
   return csp_transaction_w_opts(prio, dest, port, timeout, outbuf, outlen, inbuf, inlen, 0);
}

[docs]/**
 * Perform an entire request & reply transaction on an existing connection.
 * Send \a outbuf, wait for reply and copy reply to \a inbuf.
 *
 * @param[in] conn connection
 * @param[in] timeout timeout in mS to wait for a reply
 * @param[in] outbuf outgoing data (request)
 * @param[in] outlen length of data in \a outbuf (request)
 * @param[out] inbuf user provided buffer for receiving data (reply)
 * @param[in] inlen length of expected reply, -1 for unknown size (inbuf MUST be large enough), 0 for no reply.
 * @return 1 or reply size on success, 0 on failure (error, incoming length does not match, timeout)
 */
int csp_transaction_persistent(csp_conn_t *conn, uint32_t timeout, void *outbuf, int outlen, void *inbuf, int inlen);

[docs]/**
 * Read data from a connection-less server socket.
 *
 * @param[in] socket connection-less socket.
 * @param[in] timeout timeout in mS to wait for a packet, use #CSP_MAX_TIMEOUT for infinite timeout.
 * @return Packet on success, or NULL on failure or timeout.
 */
csp_packet_t *csp_recvfrom(csp_socket_t *socket, uint32_t timeout);

[docs]/**
 * Send a packet (without connection).
 *
 * @param[in] prio packet priority, see #csp_prio_t
 * @param[in] dst destination address
 * @param[in] dst_port destination port
 * @param[in] src_port source port
 * @param[in] opts connection options, see @ref CSP_CONNECTION_OPTIONS.
 * @param[in] packet packet to send
 */
void csp_sendto(uint8_t prio, uint16_t dst, uint8_t dst_port, uint8_t src_port, uint32_t opts, csp_packet_t *packet);

[docs]/**
 * Send a packet as a reply to a request (without a connection).
 * Calls csp_sendto() with the source address and port from the request.
 *
 * @param[in] request incoming request
 * @param[out] reply reply packet
 * @param[in] opts connection options, see @ref CSP_CONNECTION_OPTIONS.
 */
void csp_sendto_reply(const csp_packet_t * request, csp_packet_t * reply, uint32_t opts);

[docs]/**
 * Establish outgoing connection.
 * The call will return immediately, unless it is a RDP connection (#CSP_O_RDP) in which case it will wait until the other
 * end acknowleges the connection (timeout is determined by the current connection timeout set by csp_rdp_set_opt()).
 *
 * @param[in] prio priority, see #csp_prio_t
 * @param[in] dst Destination address
 * @param[in] dst_port Destination port
 * @param[in] timeout unused.
 * @param[in] opts connection options, see @ref CSP_CONNECTION_OPTIONS.
 * @return Established connection or NULL on failure (no free connections, timeout).
*/
csp_conn_t *csp_connect(uint8_t prio, uint16_t dst, uint8_t dst_port, uint32_t timeout, uint32_t opts);

[docs]/**
 * Close an open connection.
 * Any packets in the RX queue will be freed.
 *
 * @param[in] conn connection. Closing a NULL connection is acceptable.
 * @return #CSP_ERR_NONE on success, otherwise an error code.
 */
int csp_close(csp_conn_t *conn);

[docs]/**
 * Close a socket, freeing it's RX queue and unbinding it from the associated
 * port.
 *
 * @param[in] sock Socket
 * @return #CSP_ERR_NONE on success, otherwise an error code.
 */
int csp_socket_close(csp_socket_t* sock);

[docs]/**
 * Return destination port of connection.
 *
 * @param[in] conn connection
 * @return destination port of an incoming connection
 */
int csp_conn_dport(csp_conn_t *conn);

[docs]/**
 * Return source port of connection.
 *
 * @param[in] conn connection
 * @return source port of an incoming connection
 */
int csp_conn_sport(csp_conn_t *conn);

[docs]/**
 * Return destination address of connection.
 *
 * @param[in] conn connection
 * @return destination address of an incoming connection
 */
int csp_conn_dst(csp_conn_t *conn);

[docs]/**
 * Return source address of connection.
 *
 * @param[in] conn connection
 * @return source address of an incoming connection
 */
int csp_conn_src(csp_conn_t *conn);

[docs]/**
 * Return flags of connection.
 *
 * @param[in] conn connection
 * @return flags of an incoming connection, see @ref CSP_HEADER_FLAGS
 */
int csp_conn_flags(csp_conn_t *conn);

[docs]/**
 * Set socket to listen for incoming connections.
 *
 * @param[in] socket socket
 * @param[in] backlog max length of backlog queue. The backlog queue holds incoming connections, waiting to be returned by call to csp_accept().
 * @return #CSP_ERR_NONE on success, otherwise an error code.
*/
int csp_listen(csp_socket_t *socket, size_t backlog);

[docs]/**
 * Bind port to socket.
 *
 * @param[in] socket socket to bind port to
 * @param[in] port port number to bind, use #CSP_ANY for all ports. Binding to a specific will take precedence over #CSP_ANY.
 * @return #CSP_ERR_NONE on success, otherwise an error code.
 */
int csp_bind(csp_socket_t *socket, uint8_t port);


[docs]/**
 * Bind port to callback function.
 *
 * @param[in] callback pointer to callback function
 * @param[in] port port number to bind, use #CSP_ANY for all ports. Binding to a specific will take precedence over #CSP_ANY.
 * @return #CSP_ERR_NONE on success, otherwise an error code.
 */
int csp_bind_callback(csp_callback_t callback, uint8_t port);

[docs]/**
 * Route packet from the incoming router queue and check RDP timeouts.
 * In order for incoming packets to routed and RDP timeouts to be checked, this function must be called reguarly.
 * @return #CSP_ERR_NONE on success, otherwise an error code.
 */
int csp_route_work(void);

[docs]/**
 * Set the bridge interfaces.
 *
 * @param[in] if_a CSP Interface `A`
 * @param[in] if_b CSP Interface `B`
 */
void csp_bridge_set_interfaces(csp_iface_t * if_a, csp_iface_t * if_b);

[docs]/**
 * Bridge packet from an interface to the other.
 */
void csp_bridge_work(void);

[docs]/**
 * Handle CSP service request.
 * If the given packet is a service-request (the destination port matches one of CSP service ports #csp_service_port_t),
 * the packet will be processed by the specific CSP service handler.
 * The packet will either process it or free it, so this function is typically called in the last "default" clause of
 * a switch/case statement in a CSP listener task.
 * In order to listen to csp service ports, bind your listener to the specific services ports #csp_service_port_t or
 * use #CSP_ANY to all ports.
 *
 * @param[in] packet first packet, obtained by using csp_read()
 */
void csp_service_handler(csp_packet_t *packet);

[docs]/**
 * Send a single ping/echo packet.
 *
 * @param[in] node address of subsystem.
 * @param[in] timeout timeout in ms to wait for reply.
 * @param[in] size payload size in bytes.
 * @param[in] opts connection options, see @ref CSP_CONNECTION_OPTIONS.
 * @return >=0 echo time in mS on success, otherwise -1 for error.
 */
int csp_ping(uint16_t node, uint32_t timeout, unsigned int size, uint8_t opts);

[docs]/**
 * Send a single ping/echo packet without waiting for reply.
 * Payload is 1 byte.
 *
 * @param[in] node address of subsystem.
 */
void csp_ping_noreply(uint16_t node);

[docs]/**
 * Request process list.
 *
 * .. note:: This is currently only supported on FreeRTOS systems.
 *
 * @param[in] node address of subsystem.
 * @param[in] timeout timeout in mS to wait for replies. The function will not return until the timeout occurrs.
 */
void csp_ps(uint16_t node, uint32_t timeout);

[docs]/**
 * Request free memory.
 *
 * @param[in] node address of subsystem.
 * @param[in] timeout timeout in mS to wait for reply.
 * @param[out] size free memory on subsystem.
 * @return #CSP_ERR_NONE on success, otherwise an error code.
 */
int csp_get_memfree(uint16_t node, uint32_t timeout, uint32_t * size);

[docs]/**
 * Request free memory and print to stdout.
 *
 * @param[in] node address of subsystem.
 * @param[in] timeout timeout in mS to wait for reply.
 */
void csp_memfree(uint16_t node, uint32_t timeout);

[docs]/**
 * Request free buffers.
 *
 * @param[in] node address of subsystem.
 * @param[in] timeout timeout in mS to wait for reply.
 * @param[out] size free buffers.
 * @return #CSP_ERR_NONE on success, otherwise an error code.
 */
int csp_get_buf_free(uint16_t node, uint32_t timeout, uint32_t * size);

[docs]/**
 * Request free buffers and print to stdout.
 *
 * @param[in] node address of subsystem.
 * @param[in] timeout timeout in mS to wait for reply.
 */
void csp_buf_free(uint16_t node, uint32_t timeout);

[docs]/**
 * Reboot subsystem.
 * If handled by the standard CSP service handler, the reboot handler set by csp_sys_set_reboot() on the subsystem, will be invoked.
 *
 * @param[in] node address of subsystem.
 *
 */
void csp_reboot(uint16_t node);

[docs]/**
 * Shutdown subsystem.
 * If handled by the standard CSP service handler, the shutdown handler set by csp_sys_set_shutdown() on the subsystem, will be invoked.
 *
 * @param[in] node address of subsystem.
 *
 */
void csp_shutdown(uint16_t node);

[docs]/**
 * Request uptime and print to stdout.
 *
 * @param[in] node address of subsystem.
 * @param[in] timeout timeout in mS to wait for reply.
 *
 */
void csp_uptime(uint16_t node, uint32_t timeout);

[docs]/**
 * Request uptime
 *
 * @param[in] node address of subsystem.
 * @param[in] timeout timeout in mS to wait for reply.
 * @param[out] uptime uptime in seconds.
 * @return #CSP_ERR_NONE on success, otherwise an error code.
 */
int csp_get_uptime(uint16_t node, uint32_t timeout, uint32_t * uptime);

[docs]/**
 * Set RDP options.
 * The RDP options are used from the connecting/client side. When a RDP connection
 * is established, the client tranmits the options to the server.
 *
 * @param[in] window_size window size
 * @param[in] conn_timeout_ms connection timeout in mS
 * @param[in] packet_timeout_ms packet timeout in mS.
 * @param[in] delayed_acks enable/disable delayed acknowledgements.
 * @param[in] ack_timeout acknowledgement timeout when delayed ACKs is enabled
 * @param[in] ack_delay_count send acknowledgement for every ack_delay_count packets.
 *
 */
void csp_rdp_set_opt(unsigned int window_size, unsigned int conn_timeout_ms,
	  unsigned int packet_timeout_ms, unsigned int delayed_acks,
	  unsigned int ack_timeout, unsigned int ack_delay_count);

[docs]/**
 * Get RDP options. @see csp_rdp_set_opt()
 *
 * @param[out] window_size Window size
 * @param[out] conn_timeout_ms connection timeout in ms
 * @param[out] packet_timeout_ms packet timeout in ms
 * @param[out] delayed_acks enable/disable delayed acknowledgements
 * @param[out] ack_timeout acknowledgement timeout when delayed ACKs is enabled
 * @param[out] ack_delay_count send acknowledgement for every ack_delay_count packets
 */
void csp_rdp_get_opt(unsigned int *window_size, unsigned int *conn_timeout_ms,
	  unsigned int *packet_timeout_ms, unsigned int *delayed_acks,
	  unsigned int *ack_timeout, unsigned int *ack_delay_count);

[docs]/**
 * Set platform specific memory copy function.
 */
void csp_cmp_set_memcpy(csp_memcpy_fnc_t fnc);

#if (CSP_ENABLE_CSP_PRINT)

/**
 * Print connection table to stdout.
 */
void csp_conn_print_table(void);

/**
 * Hex dump memory to stdout.
 *
 * @param[in] desc description printed on first line.
 * @param[in] addr memory address.
 * @param[in] len number of bytes to dump, starting from \a addr.
 *
 */
void csp_hex_dump(const char *desc, void *addr, int len);

#else

[docs]inline void csp_conn_print_table(void) {}
[docs]inline void csp_hex_dump(const char *desc, void *addr, int len) {}

#endif

#if (CSP_HAVE_STDIO)
/**
 * Print connection table to string.
 */
int csp_conn_print_table_str(char * str_buf, int str_size);
#else
[docs]inline int csp_conn_print_table_str(char * str_buf, int str_size) {
   if (str_buf != NULL && str_size > 0) {
	  str_buf[0] = '\0';
   }

   return CSP_ERR_NONE;
}
#endif

#ifdef __cplusplus
}
#endif