CSP Library Header

File: csp/csp.h

Description: CSP Library Header File

Defines

CSP_MAX_TIMEOUT

Max timeout

CSP_MAX_DELAY

Max delay

enumerator csp_dedup_types

CSP Debug Types

enumerator CSP_DEDUP_ALL

Deduplication on incoming and forwarding

enumerator CSP_DEDUP_FWD

Deduplication on forwarding only

enumerator CSP_DEDUP_INCOMING

Deduplication on incomfing only

enumerator CSP_DEDUP_OFF

Deduplication off

Typedefs

type csp_conf_t

CSP configuration.

uint32_t conn_dfl_so

Default connection options. Options will always be or’ed onto new connections, see csp_connect()

uint8_t dedup

Enable CSP deduplication. 0 = off, 1 = always on, 2 = only on forwarded packets,

const char *hostname

Host name, returned by the #CSP_CMP_IDENT request

const char *model

Model, returned by the #CSP_CMP_IDENT request

const char *revision

Revision, returned by the #CSP_CMP_IDENT request

uint8_t version

Protocol version to use (either 1 or 2)

Interface Functions

void csp_init(void)

Initialize CSP. This will configure basic structures.

void csp_free_resources(void)

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.

const csp_conf_t *csp_get_conf(void)

Get a read-only reference to the active CSP configuration.

Returns:

Active CSP configuration (read-only).

void csp_id_copy(csp_id_t *target, const csp_id_t *source)

Copy csp id fields from source to target object

csp_conn_t *csp_accept(csp_socket_t *socket, uint32_t timeout)

Wait/accept a new connection.

Parameters:

• socket – socket to accept connections on, created by calling csp_socket().

• timeout – timeout in mS to wait for a connection, use CSP_MAX_TIMEOUT for infinite timeout.

Returns:

New connection on success, NULL on failure or timeout.

csp_packet_t *csp_read(csp_conn_t *conn, uint32_t timeout)

Read packet from a connection. This fuction will wait on the connection’s RX queue for the specified timeout.

Parameters:

• conn – connection

• timeout – timeout in mS to wait for a packet, use CSP_MAX_TIMEOUT for infinite timeout.

Returns:

Packet or NULL in case of failure or timeout.

void csp_send(csp_conn_t *conn, csp_packet_t *packet)

Send packet on a connection. The packet buffer is automatically freed, and cannot be used after the call to csp_send()

Parameters:

• conn – connection

• packet – packet to send

void csp_send_prio(uint8_t prio, csp_conn_t *conn, csp_packet_t *packet)

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.

Parameters:

• prio – priority to set on the connection

• conn – connection

• packet – packet to send

int csp_transaction_w_opts(uint8_t prio, uint16_t dst, uint8_t dst_port, uint32_t timeout, const void *outbuf, int outlen, void *inbuf, int inlen, uint32_t opts)

Perform an entire request & reply transaction. Creates a connection, send outbuf, wait for reply, copy reply to inbuf and close the connection.

Returns: int: 1 or reply size on success, 0 on failure (error, incoming length does not match, timeout)

Parameters:

• prio – priority, see #csp_prio_t

• dst – destination address

• dst_port – destination port

• timeout – timeout in mS to wait for a reply

• outbuf – outgoing data (request)

• outlen – length of data in outbuf (request)

• inbuf – user provided buffer for receiving data (reply)

• inlen – length of expected reply, -1 for unknown size (inbuf MUST be large enough), 0 for no reply.

• opts – connection options, see CSP_CONNECTION_OPTIONS.

static inline int csp_transaction(uint8_t prio, uint16_t dest, uint8_t port, uint32_t timeout, const void *outbuf, int outlen, void *inbuf, int inlen)

Perform an entire request & reply transaction. Creates a connection, send outbuf, wait for reply, copy reply to inbuf and close the connection.

Parameters:

• prio – priority, see #csp_prio_t

• dest – destination address

• port – destination port

• timeout – timeout in mS to wait for a reply

• outbuf – outgoing data (request)

• outlen – length of data in outbuf (request)

• inbuf – user provided buffer for receiving data (reply)

• inlen – length of expected reply, -1 for unknown size (inbuf MUST be large enough), 0 for no reply.

Returns:

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, const void *outbuf, int outlen, void *inbuf, int inlen)

Perform an entire request & reply transaction on an existing connection. Send outbuf, wait for reply and copy reply to inbuf.

Parameters:

• conn – connection

• timeout – timeout in mS to wait for a reply

• outbuf – outgoing data (request)

• outlen – length of data in outbuf (request)

• inbuf – user provided buffer for receiving data (reply)

• inlen – length of expected reply, -1 for unknown size (inbuf MUST be large enough), 0 for no reply.

Returns:

1 or reply size on success, 0 on failure (error, incoming length does not match, timeout)

csp_packet_t *csp_recvfrom(csp_socket_t *socket, uint32_t timeout)

Read data from a connection-less server socket.

Parameters:

• socket – connection-less socket.

• timeout – timeout in mS to wait for a packet, use #CSP_MAX_TIMEOUT for infinite timeout.

Returns:

Packet on success, or NULL on failure or timeout.

void csp_sendto(uint8_t prio, uint16_t dst, uint8_t dst_port, uint8_t src_port, uint32_t opts, csp_packet_t *packet)

Send a packet (without connection).

Parameters:

• prio – packet priority, see #csp_prio_t

• dst – destination address

• dst_port – destination port

• src_port – source port

• opts – connection options, see CSP_CONNECTION_OPTIONS.

• packet – packet to send

void csp_sendto_reply(const csp_packet_t *request, csp_packet_t *reply, uint32_t opts)

Send a packet as a reply to a request (without a connection). Calls csp_sendto() with the source address and port from the request.

Parameters:

• request – incoming request

• reply – reply packet

• opts – connection options, see CSP_CONNECTION_OPTIONS.

csp_conn_t *csp_connect(uint8_t prio, uint16_t dst, uint8_t dst_port, uint32_t timeout, uint32_t opts)

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()).

Parameters:

• prio – priority, see #csp_prio_t

• dst – Destination address

• dst_port – Destination port

• timeout – unused.

• opts – connection options, see CSP_CONNECTION_OPTIONS.

Returns:

Established connection or NULL on failure (no free connections, timeout).

int csp_close(csp_conn_t *conn)

Close an open connection. Any packets in the RX queue will be freed.

Parameters:

• conn – connection. Closing a NULL connection is acceptable.

Returns:

#CSP_ERR_NONE on success, otherwise an error code.

int csp_socket_close(csp_socket_t *sock)

Close a socket, freeing it’s RX queue and unbinding it from the associated port.

Parameters:

• sock – Socket

Returns:

#CSP_ERR_NONE on success, otherwise an error code.

int csp_conn_dport(const csp_conn_t *conn)

Return destination port of connection.

Parameters:

• conn – connection

Returns:

destination port of an incoming connection

int csp_conn_sport(const csp_conn_t *conn)

Return source port of connection.

Parameters:

• conn – connection

Returns:

source port of an incoming connection

int csp_conn_dst(const csp_conn_t *conn)

Return destination address of connection.

Parameters:

• conn – connection

Returns:

destination address of an incoming connection

int csp_conn_src(const csp_conn_t *conn)

Return source address of connection.

Parameters:

• conn – connection

Returns:

source address of an incoming connection

int csp_conn_flags(const csp_conn_t *conn)

Return flags of connection.

Parameters:

• conn – connection

Returns:

flags of an incoming connection, see CSP_HEADER_FLAGS

int csp_listen(csp_socket_t *socket, size_t backlog)

Set socket to listen for incoming connections.

Parameters:

• socket – socket

• backlog – max length of backlog queue. The backlog queue holds incoming connections, waiting to be returned by call to csp_accept().

Returns:

#CSP_ERR_NONE on success, otherwise an error code.

int csp_bind(csp_socket_t *socket, uint8_t port)

Bind port to socket.

Parameters:

• socket – socket to bind port to

• port – port number to bind, use #CSP_ANY for all ports. Binding to a specific will take precedence over #CSP_ANY.

Returns:

#CSP_ERR_NONE on success, otherwise an error code.

int csp_bind_callback(csp_callback_t callback, uint8_t port)

Bind port to callback function.

Parameters:

• callback – pointer to callback function

• port – port number to bind, use #CSP_ANY for all ports. Binding to a specific will take precedence over #CSP_ANY.

Returns:

#CSP_ERR_NONE on success, otherwise an error code.

int csp_route_work(void)

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.

Returns:

#CSP_ERR_NONE on success, otherwise an error code.

void csp_bridge_set_interfaces(csp_iface_t *if_a, csp_iface_t *if_b)

Set the bridge interfaces.

Parameters:

• if_a – CSP Interface A

• if_b – CSP Interface B

void csp_bridge_work(void)

Bridge packet from an interface to the other.

void csp_service_handler(csp_packet_t *packet)

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.

Parameters:

• packet – first packet, obtained by using csp_read()

int csp_ping(uint16_t node, uint32_t timeout, unsigned int size, uint8_t opts)

Send a single ping/echo packet.

Parameters:

• node – address of subsystem.

• timeout – timeout in ms to wait for reply.

• size – payload size in bytes.

• opts – connection options, see CSP_CONNECTION_OPTIONS.

Returns:

>=0 echo time in mS on success, otherwise -1 for error.

void csp_ping_noreply(uint16_t node)

Send a single ping/echo packet without waiting for reply. Payload is 1 byte.

Parameters:

• node – address of subsystem.

void csp_ps(uint16_t node, uint32_t timeout)

Request process list.

Note

This is currently only supported on FreeRTOS systems.

Parameters:

• node – address of subsystem.

• timeout – timeout in mS to wait for replies. The function will not return until the timeout occurrs.

int csp_get_memfree(uint16_t node, uint32_t timeout, uint32_t *size)

Request free memory.

Parameters:

• node – address of subsystem.

• timeout – timeout in mS to wait for reply.

• size – free memory on subsystem.

Returns:

#CSP_ERR_NONE on success, otherwise an error code.

void csp_memfree(uint16_t node, uint32_t timeout)

Request free memory and print to stdout.

Parameters:

• node – address of subsystem.

• timeout – timeout in mS to wait for reply.

int csp_get_buf_free(uint16_t node, uint32_t timeout, uint32_t *size)

Request free buffers.

Parameters:

• node – address of subsystem.

• timeout – timeout in mS to wait for reply.

• size – free buffers.

Returns:

#CSP_ERR_NONE on success, otherwise an error code.

void csp_buf_free(uint16_t node, uint32_t timeout)

Request free buffers and print to stdout.

Parameters:

• node – address of subsystem.

• timeout – timeout in mS to wait for reply.

void csp_reboot(uint16_t node)

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.

Parameters:

• node – address of subsystem.

void csp_shutdown(uint16_t node)

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.

Parameters:

• node – address of subsystem.

void csp_uptime(uint16_t node, uint32_t timeout)

Request uptime and print to stdout.

Parameters:

• node – address of subsystem.

• timeout – timeout in mS to wait for reply.

int csp_get_uptime(uint16_t node, uint32_t timeout, uint32_t *uptime)

Request uptime

Parameters:

• node – address of subsystem.

• timeout – timeout in mS to wait for reply.

• uptime – uptime in seconds.

Returns:

#CSP_ERR_NONE on success, otherwise an error code.

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)

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.

Parameters:

• window_size – window size

• conn_timeout_ms – connection timeout in mS

• packet_timeout_ms – packet timeout in mS.

• delayed_acks – enable/disable delayed acknowledgements.

• ack_timeout – acknowledgement timeout when delayed ACKs is enabled

• 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)

Get RDP options.

csp_rdp_set_opt()

Parameters:

• window_size – Window size

• conn_timeout_ms – connection timeout in ms

• packet_timeout_ms – packet timeout in ms

• delayed_acks – enable/disable delayed acknowledgements

• ack_timeout – acknowledgement timeout when delayed ACKs is enabled

• ack_delay_count – send acknowledgement for every ack_delay_count packets

void csp_cmp_set_memcpy(csp_memcpy_fnc_t fnc)

Set platform specific memory copy function.

inline void csp_conn_print_table(void)

inline void csp_hex_dump(const char *desc, void *addr, int len)

inline int csp_conn_print_table_str(char *str_buf, int str_size)