498 lines
20 KiB
C
498 lines
20 KiB
C
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
|
/* */
|
|
/* file: aLink.h */
|
|
/* */
|
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
|
/* */
|
|
/* description: Definition for BrainStem packet FIFO queue. */
|
|
/* */
|
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
|
/* */
|
|
/* Copyright (c) 2018 Acroname Inc. - All Rights Reserved */
|
|
/* */
|
|
/* This file is part of the BrainStem release. See the license.txt */
|
|
/* file included with this package or go to */
|
|
/* https://acroname.com/software/brainstem-development-kit */
|
|
/* for full license details. */
|
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
|
|
|
#ifndef _aLink_H_
|
|
#define _aLink_H_
|
|
|
|
#include "aDefs.h"
|
|
#include "aError.h"
|
|
#include "aPacket.h"
|
|
#include "aStream.h"
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// BrainStem Link Interface
|
|
|
|
/** \defgroup aLink Link Interface
|
|
* \ref aLink "aLink.h" provides the interface for creating and maintaining
|
|
* the link to a BrainStem module, and the BrainStem network. It includes
|
|
* facilities for starting and stopping links, as well as sending and receiving
|
|
* BrainStem protocol packets.
|
|
*/
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Typedef #aLinkRef Opaque reference to a BrainStem link.
|
|
//typedef void* aLinkRef;
|
|
|
|
/// Typedef for aLinkRef for an opaque reference to BrainStem Link.
|
|
typedef uint32_t aLinkRef;
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Enum #linkStatus.
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Typedef #aHBCallbackProc.
|
|
|
|
/**
|
|
* This callback is called from the link processing thread,
|
|
* Implementations should get in and out of this callback as fast as
|
|
* possible. Do not do anything lengthy here.
|
|
* param bOn The representation of an up or down beat.
|
|
*/
|
|
typedef void (*aHBCallbackProc) (bool bOn);
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Typedef #packetFilterProc.
|
|
|
|
/**
|
|
* This callback is called from the link processing thread,
|
|
* Implementations should get in and out of this callback as fast as
|
|
* possible. Do not do anything lengthy here.
|
|
* param packet Pointer to the current packet
|
|
* param ref User supplied reference.
|
|
* return Indicated wether the packet was accepted (True) or rejected (False).
|
|
* Accepted packets will be destroyed after returning.
|
|
* Rejected packets will be sent through normal BrainStem process.
|
|
*/
|
|
typedef bool (*packetFilterProc)(const aPacket* packet, void* ref);
|
|
|
|
/**
|
|
* Represents the current state of the BrainStem link.
|
|
*/
|
|
typedef enum {
|
|
STOPPED, /**< Link currently stopped. */
|
|
INITIALIZING, /**< Starting communication with module. */
|
|
RUNNING, /**< Link running. */
|
|
STOPPING, /**< Link is in the process of stopping. */
|
|
SYNCING, /**< Packet framing lost re-syncing. */
|
|
INVALID_LINK_STREAM, /**< Link stream provided is not valid. */
|
|
IO_ERROR, /**< Communication error occured on link, could not resync. */
|
|
RESETTING, /**< Resetting the link connection */
|
|
UNKNOWN_ERROR /**< Something really bad happened, but we couldn't determin what. */
|
|
} linkStatus;
|
|
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Create a USB BrainStem link reference.
|
|
|
|
/**
|
|
* Creates a reference to a USB BrainStem link. The linkStream is now
|
|
* maintained by the BrainStem link. If the link already exists, the
|
|
* use count for that link will be incremented and the linkRef for
|
|
* that entry will be returned.
|
|
*
|
|
* Links created with this procedure must use aLink_Destroy to properly
|
|
* dispose of the link reference and associated connections.
|
|
*
|
|
* \param serialNumber Unique identifier of the device.
|
|
*
|
|
* \return aLinkRef identifier if successful or 0 otherwise.
|
|
*/
|
|
aLIBEXPORT aLinkRef aLink_CreateUSB(const uint32_t serialNumber);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Create a Server BrainStem link reference.
|
|
|
|
/**
|
|
* Creates a reference to a Server BrainStem link. The linkStream is now
|
|
* maintained by the BrainStem link. Under the hood this functions
|
|
* calls aLink_CreateUSB. Once the reference is created it is intended
|
|
* to be used in conjunction with aLink_CreateClient
|
|
*
|
|
* Links created with this procedure must use aLink_Destroy to properly
|
|
* dispose of the link reference and associated connections.
|
|
*
|
|
* \param deviceId aLinkRef handle for the primary-device that this server
|
|
* shall reference.
|
|
* \param assignedPort Variable to be filled with the server assigned port.
|
|
* \param networkInterface Network interface (IPv4 address) to be used for the server.
|
|
* If isLocal == false AND this value == 0 or LOCALHOST_IP_ADDRESS
|
|
* The variable will be filled with the auto selected interface.
|
|
* \param isLocal Defines the servers exposure; True = Local; False = Exposed to internet.
|
|
* Setting this variable to false will have firewall implications.
|
|
*
|
|
* \return aLinkRef identifier if successful or 0 otherwise.
|
|
*/
|
|
aLIBEXPORT aLinkRef aLink_CreateServer(aLinkRef deviceId,
|
|
uint16_t* assignedPort,
|
|
uint32_t* networkInterface,
|
|
const bool isLocal);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Create a Client BrainStem link reference.
|
|
|
|
/**
|
|
* Creates a reference to a Client BrainStem link. The linkStream is now
|
|
* maintained by the BrainStem link.
|
|
*
|
|
* Links created with this procedure must use aLink_Destroy to properly
|
|
* dispose of the link reference and associated connections.
|
|
*
|
|
* \param address IPv4 address as to where the corresponding Server resides
|
|
* \param port Port of the corresponding server resides.
|
|
* \param ref Reference to an exiting link, for use with BrainStem I2C networking. 0 is ignored.
|
|
*
|
|
* \return aLinkRef identifier if successful or 0 otherwise.
|
|
*/
|
|
aLIBEXPORT aLinkRef aLink_CreateClient(const uint32_t address,
|
|
const uint16_t port,
|
|
const aLinkRef ref);
|
|
|
|
/**
|
|
* Creates a reference to a BrainStem link. The linkStream is now
|
|
* maintained by the BrainStem link. If the link already exists, the
|
|
* use count for that link will be incremented and the linkRef for
|
|
* that entry will be returned.
|
|
*
|
|
* Links created with this procedure must use aLink_Destroy to properly
|
|
* dispose of the link reference and associated connections.
|
|
*
|
|
* \param serialNumber the device serial number
|
|
* \param address the TCPIP address
|
|
* \param port the TCPIP port
|
|
*
|
|
* \return aLinkRef identifier if successful or 0 otherwise.
|
|
*/
|
|
aLIBEXPORT aLinkRef aLink_CreateTCPIP(const uint32_t serialNumber,
|
|
const uint32_t address,
|
|
const uint16_t port);
|
|
|
|
|
|
|
|
/**
|
|
* Creates a reference to a BrainStem link. The linkStream is now
|
|
* maintained by the BrainStem link. If the link already exists, the
|
|
* use count for that link will be incremented and the linkRef for
|
|
* that entry will be returned.
|
|
*
|
|
* Links created with this procedure must use aLink_Destroy to properly
|
|
* dispose of the link reference and associated connections.
|
|
*
|
|
* \param serialNumber the device serial number
|
|
* \param port the Serial port in a character array
|
|
* \param baud the serial port baudrate
|
|
*
|
|
* \return aLinkRef identifier if successful or 0 otherwise.
|
|
*/
|
|
aLIBEXPORT aLinkRef aLink_CreateSerial(const uint32_t serialNumber,
|
|
const char* port,
|
|
const uint32_t baud);
|
|
|
|
/**
|
|
* Creates a reference to a BrainStem link. -- *** DEPRECATED *** --
|
|
* The linkStream is now maintained by the BrainStem link.
|
|
* The aLink_Create(aStreamRef linkStream) is maintained for backward
|
|
* compatibility, but linkStream CANNOT be NULL. Once the linkStream
|
|
* has been used in the create, caller must not use or delete the stream.
|
|
* Each call to this routine will create an new link entry,
|
|
* independent of any other link to the same device.
|
|
*
|
|
* Links created with this procedure must use aLink_Destroy to properly
|
|
* dispose of the link reference and associated connections.
|
|
*
|
|
* \param linkStream a StreamRef the transport stream (NON-NULL).
|
|
*
|
|
* \return aLinkRef identifier if successful or 0 otherwise.
|
|
*/
|
|
aLIBEXPORT aLinkRef aLink_Create(aStreamRef linkStream);
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Create a BrainStem link reference heartbeat callback
|
|
|
|
/**
|
|
* Sets a callback for notification about heartbeats.
|
|
* the callback should return quickly, it executes in the
|
|
* link processing thread context.
|
|
*
|
|
* \param linkRef Link to set the callback on.
|
|
* \param hbCallBack a aHBCallbackProc the callback procedure.
|
|
*
|
|
* \return aHBCallbackProc NULL if none was set or the previous one if set.
|
|
*/
|
|
aLIBEXPORT aHBCallbackProc aLink_SetHBCallback(aLinkRef linkRef, aHBCallbackProc hbCallBack);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Destroy a BrainStem link reference.
|
|
|
|
/**
|
|
* Destroys a Link reference. deallocating associated resources cleanly.
|
|
*
|
|
* Links created with aLink_Create must use aLink_Destroy to clean up
|
|
* resources used by the link Ref.
|
|
*
|
|
* \param linkRef a Pointer to a valid LinkRef. The linkRef will be set to
|
|
* NULL on succesful completion of the Destroy call.
|
|
* \return aStreamRef Return value will always be NULL. The return
|
|
* value has been left for backwards compatability.
|
|
*/
|
|
aLIBEXPORT aErr aLink_Destroy(aLinkRef* linkRef);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Reset a connection to a BrainStem module.
|
|
|
|
/**
|
|
* Stop the active connection to the BrainStem if the Link contains a valid
|
|
* stream Reference, and clear out the communication buffers, and restart
|
|
* the link.
|
|
*
|
|
* \param linkRef A valid LinkRef.
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone the call completed successfully, a subsequent
|
|
* call to aLink_GetStatus should return the current
|
|
* state of the link.
|
|
* \retval aErrParam No valid LinkRef provided.
|
|
*/
|
|
aLIBEXPORT aErr aLink_Reset(const aLinkRef linkRef);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Return the current status of the BrainStem link.
|
|
|
|
/**
|
|
* Return the current status of the BrainStem link.
|
|
*
|
|
* \param linkRef A valid LinkRef.
|
|
* \return linkStatus See the possible linkStatus values.
|
|
*/
|
|
aLIBEXPORT linkStatus aLink_GetStatus(const aLinkRef linkRef);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Return the first packet in the Link incomming FIFO.
|
|
|
|
/**
|
|
* Return the first packet in the Link incomming FIFO. This call is non blocking,
|
|
* and will return immediately.
|
|
*
|
|
* \param linkRef A valid LinkRef.
|
|
* \return aPacket Returns a BrainStem packet on success or NULL.
|
|
*/
|
|
aLIBEXPORT aPacket* aLink_GetPacket(const aLinkRef linkRef);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Return the first packet in the Link incomming FIFO.
|
|
|
|
/**
|
|
* Return the first packet in the Link incomming FIFO. This call blocks waiting
|
|
* for msTimeout milliseconds.
|
|
*
|
|
* \param linkRef A valid LinkRef.
|
|
* \param msTimeout The maximum amount of time in milliseconds to wait for a packet.
|
|
* \return aPacket Returns a BrainStem packet on success or NULL.
|
|
*/
|
|
aLIBEXPORT aPacket* aLink_AwaitPacket(const aLinkRef linkRef,
|
|
const unsigned long msTimeout);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Return the first packet matched by proc in the Link incomming FIFO.
|
|
|
|
/**
|
|
* Return the first packet matched by proc in the Link incomming FIFO. This call
|
|
* is non blocking and returns immediatly.
|
|
*
|
|
* \param linkRef A valid LinkRef.
|
|
* \param proc The callback used for determining a matching packet.
|
|
* \param vpRef A resource passed to the callback proc.
|
|
* \return aPacket Returns the first packet that is matched by proc or NULL.
|
|
*/
|
|
aLIBEXPORT aPacket* aLink_GetFirst(const aLinkRef linkRef,
|
|
aPacketMatchPacketProc proc,
|
|
const void* vpRef);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Return the first packet matched by proc in the Link incomming FIFO.
|
|
|
|
/**
|
|
* Return the first packet matched by proc in the Link incomming FIFO. This call
|
|
* blocks for up to msTimeout milliseconds waiting for a matching packet.
|
|
*
|
|
* \param linkRef A valid LinkRef.
|
|
* \param proc The callback used for determining a matching packet.
|
|
* \param vpRef A resource passed to the callback proc.
|
|
* \param msTimeout The maximum amount of time in milliseconds to wait for a
|
|
* matching packet.
|
|
* \return aPacket Returns the first packet that is matched by proc or NULL.
|
|
*/
|
|
aLIBEXPORT aPacket* aLink_AwaitFirst(const aLinkRef linkRef,
|
|
aPacketMatchPacketProc proc,
|
|
const void* vpRef,
|
|
const unsigned long msTimeout);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Drain all matching packets from the incomming FIFO.
|
|
|
|
/**
|
|
* Drain all matching packets from the incomming FIFO. This call does not block.
|
|
*
|
|
* \param linkRef A valid LinkRef.
|
|
* \param proc The callback used for determining a matching packet.
|
|
* \param vpRef A resource passed to the callback proc.
|
|
* \return aPacket Returns the first packet that is matched by proc or NULL.
|
|
*/
|
|
aLIBEXPORT size_t aLink_DrainPackets(const aLinkRef linkRef,
|
|
aPacketMatchPacketProc proc,
|
|
const void* vpRef);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Put a packet into the outgoingBackend link FIFO.
|
|
|
|
/**
|
|
* Put a packet into the outgoingBackend link FIFO.
|
|
*
|
|
* \param linkRef A valid LinkRef.
|
|
* \param packet A BrainStem packet.
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone Call successfully added the packet.
|
|
* \retval aErrParam Invalid LinkRef or packet.
|
|
* \retval aErrResource Unable to create memory for packet in FIFO.
|
|
*/
|
|
aLIBEXPORT aErr aLink_PutPacket(const aLinkRef linkRef, const aPacket* packet);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// User defined packet filter.
|
|
|
|
/**
|
|
* If implemented the users filter will be executed before all other packet types.
|
|
* It is the users responsibility to properly ignore packets that it does not care about.
|
|
* Directly calling this function will interfere with the BrainStem stream interface.
|
|
*
|
|
* \param linkRef A valid LinkRef.
|
|
* \param callback User defined callback
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone Call successfully filter installation.
|
|
*/
|
|
aLIBEXPORT aErr aLink_InstallUserPacketFilter(const aLinkRef linkRef,
|
|
packetFilterProc callback,
|
|
void* ref);
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Pooled Packet Enable.
|
|
|
|
/**
|
|
* Enables pooling of outgoing BrainStem packets.
|
|
* Allowing multiple packets to be packed into a single transaction frame.
|
|
*
|
|
* \param linkRef A valid LinkRef.
|
|
* \param enable True = Enables; False = Disables;
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone Call successfully enabled pooled packets
|
|
*/
|
|
aLIBEXPORT aErr aLink_EnablePooledPackets(const aLinkRef linkRef, const bool enable);
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/////////////////////////////////////////////////////////////////////
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Enum type of debug packet entry.
|
|
typedef enum {
|
|
PACKET_LOG_OUTBOUND = 0x01, // packet sent to device
|
|
PACKET_LOG_INBOUND = 0x02, // packet from device
|
|
PACKET_LOG_NOTE = 0x03,
|
|
PACKET_LOG_UNKNOWN_TYPE = 0x80, // unknown type of data
|
|
} packetLogType;
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Packet debug routines
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Enable logging of packets to/from the device.
|
|
|
|
/**
|
|
* Enable logging of packets to/from the device.
|
|
*
|
|
* \param linkRef A valid LinkRef.
|
|
* \param log_size Size of buffer to use for logging packets.
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone Call successfully set log size.
|
|
* \retval aErrParam Invalid LinkRef.
|
|
* \retval aErrResource Unable to create memory for logging.
|
|
*/
|
|
aLIBEXPORT aErr aLink_PacketDebug_SetLogSize(const aLinkRef linkRef, int32_t log_size);
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Enable logging of packets to/from the device.
|
|
|
|
/**
|
|
* Enable logging of packets to/from the device.
|
|
*
|
|
* \param linkRef A valid LinkRef.
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone Call successfully enabled logging.
|
|
* \retval aErrParam Invalid LinkRef.
|
|
* \retval aErrResource Unable to create memory for logging.
|
|
*/
|
|
aLIBEXPORT aErr aLink_PacketDebug_Enable(const aLinkRef linkRef);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Disable logging of packets to/from the device.
|
|
|
|
/**
|
|
* Disable logging of packets to/from the device.
|
|
*
|
|
* \param linkRef A valid LinkRef.
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone Call successfully disabled logging.
|
|
* \retval aErrParam Invalid LinkRef.
|
|
* \retval aErrNotReady Logging was never enabled.
|
|
*/
|
|
aLIBEXPORT aErr aLink_PacketDebug_Disable(const aLinkRef linkRef);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Read next entry from the log.
|
|
|
|
/**
|
|
* Read next entry from the log.
|
|
*
|
|
* \param linkRef A valid LinkRef.
|
|
* \param type The type of data stored in the buffer upon return.
|
|
* \param data_size Data buffer size.
|
|
* \param data Buffer for data to be stored in upon return.
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone Call successfully read next entry.
|
|
* \retval aErrParam Invalid LinkRef.
|
|
* \retval aErrNotReady Logging was never enabled.
|
|
* \retval aErrOverrun Data in entry is larger than buffer supplied
|
|
*/
|
|
aLIBEXPORT aErr aLink_PacketDebug_Read(const aLinkRef linkRef, packetLogType *type, uint32_t *data_size, uint8_t *data);
|
|
|
|
aLIBEXPORT aErr aLink_PacketDebug_Write(const aLinkRef linkRef, packetLogType type, const uint32_t data_size, const uint8_t *data);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* _aLink_H_ */
|
|
|