Files
externals/linux/include/celoxica/gmac.h
T
2017-10-04 14:16:02 -04:00

1187 lines
48 KiB
C

/****************************************************************
* *
* Copyright (C) 1991-2007 Celoxica Ltd. All rights reserved. *
* *
*****************************************************************
* *
* Project : Generic AMDC *
* Date : 18 FEB 2008 *
* File : ob.h *
* Author : Patrik Beck (PB) *
* Contributors: *
* *
* Description: *
* *
* Date Version Author Reason for change *
* 18 FEB 2008 1.00 PB Created *
* 26 NOV 2010 1.01 LM Everything now in GMAC_UserAPI *
* *
****************************************************************/
#ifndef __CELOXICA_GMAC_H__
#define __CELOXICA_GMAC_H__
#include "gmac_version.h"
#ifdef __cplusplus
extern "C"
{
#endif
/**
* \ingroup GMAC_UserAPI
* @author Patrik Beck
*/
struct __GMACHandle;
/**
* \ingroup GMAC_UserAPI
* \brief GMAC Handle
*/
typedef struct __GMACHandle GMACHandle;
struct __GMACChannelImpl;
/**
* \brief GMAC Channel
*/
typedef struct __GMACChannelImpl GMACChannel;
#include <assert.h>
#include "gmac_template.h"
#include "config_file.h"
#include "ade.h" //for ADE stats
/**
* \ingroup GMAC_UserAPI
* \brief Start sequence number set to this constant if undefined
*/
#define SEQUENCE_UNDEFINED (~((uint64_t)0))
/**
* \ingroup GMAC_UserAPI
* \brief Sequence number set to this constant for reset
*/
#define SEQUENCE_RESET ((~((uint64_t)0))-1)
/**
* \brief Decimal places
*
* Prices are passed in native coding.
* After applying the price factor, the prices will have GMAC_DECIMAL_PLACES.
*/
#define GMAC_DECIMAL_PLACES 8
#define GMAC_DECIMAL_FACTOR ((int64_t) 1e8)
/**
* \brief Maximum number of channels
*/
#define MAX_CHANNELS (4*1024)
/**
* \brief Maximum number of multicasts
*/
#define MAX_MULTICASTS MAX_CHANNELS
/**
* \brief Maximum number of different markets
*/
#define MAX_MARKETS 255
/**
* \brief Maximum number of hardware queues
* Maximum number of hardware queues all the boards can stream to.
*/
#define MAX_HWQUEUES 16
/**
* \ingroup GMAC_UserAPI
* \brief GMAC Return Status
*/
typedef enum {
GMAC_STATUS_OK = 0,
GMAC_STATUS_INIT_ERROR = 1, /**< \brief Initialization Error */
GMAC_STATUS_NODATA = 2,
GMAC_STATUS_MALLOC_ERROR = 3,
GMAC_STATUS_NOLINK = 4,
GMAC_STATUS_ADE_ERROR = 5,
GMAC_STATUS_CONTROL = 6, /**< \brief Control data returned */
GMAC_STATUS_USER_BUFFERING = 7, /**< \brief Data are being buffered on user request. Data pointer set to last packet received. */
GMAC_STATUS_CORE_BUFFERING = 8, /**< \brief GMAC is buffering data within the recovery mechanism to fill the gap */
GMAC_STATUS_PARAM_ERROR = 9, /**< \brief Parameter Error */
GMAC_STATUS_CONFIG_ERROR = 10, /**< \brief Configuration file Error */
GMAC_STATUS_PARTIALLY_INITIALIZED = 11, /**< \brief Partially Initialized */
GMAC_STATUS_NOT_IMPLEMENTED = 12, /**< \brief Not Implemented */
GMAC_STATUS_CONNECTION_ERROR = 13, /**< \brief Connection Error */
GMAC_STATUS_PAYLOAD_ERROR = 14, /**< \brief Payload Error */
GMAC_STATUS_RUNTIME_ERROR = 15, /**< \brief Runtime Error */
GMAC_STATUS_RELEASE_FIRST = 16, /**< \brief GMAC is waiting for \ref GMACQueueRelease to be called */
GMAC_STATUS_RECOVERY_FAILED = 17, /**< \brief Recovery failed on the channel specified in the packet header */
GMAC_STATUS_NOT_FOUND = 18, /**< \brief Market name translation is not possible */
GMAC_STATUS_BUFFER_FULL = 19, /**< \brief Buffer pool for the queue reached the limit in the config file. All data is discarded in the reorder/recovery buffers and all the corresponding channel's expected sequence number are set to UNDEFINED */
GMAC_STATUS_RECONNECT = 20, /**< \brief Returned by GMAC when the tcp connection has been lost. Also informing user that a new connection is in asynchronous opening state. When the connection becomes available the GMAC will start to decode and provide market data. If the GMAC is unable to successfully create a new connection within the timeout the GMAC will return this code again. */
GMAC_STATUS_NO_CHANNELS = 21, /**< \brief ADE reports no multicasts in queue for GMACQueueRead() */
GMAC_STATUS_PARTIAL = 22, /**< \brief Packet requires further processing (internal use only). */
GMAC_STATUS_MULTICAST_OPEN_ERROR = 23, /**< \brief Error related to the opening of a multicast */
GMAC_STATUS_PACKET_DROPPED =24 /**< \brief Packets have been dropped by underlying transport. */
} GMACStatus;
/**
* \ingroup GMAC_UserAPI
* \brief Filtering mode enumeration
*
* Enumeration is returned by \ref GMACFilteringSupportedMode for a specified market.
* When needed the symbols and/or indexes has to be provided using the
* \ref GMACFilteringInstrumentRequired ()
*
*/
typedef enum
{
GMAC_FILTERING_NOT_SUPPORTED = 0, /** \brief Filtering is not supported on the market */
GMAC_FILTERING_NOT_ENABLED, /** \brief Filtering is not enabled */
GMAC_FILTERING_SYMBOL, /** \brief Filtering is enabled and symbol names need to be provided */
GMAC_FILTERING_INDEX /** \brief Filtering is enabled and indexes need to be provided */
} GMACFilteringMode;
typedef enum
{
GMAC_TRANSCODING_TYPE_DEEP_BOOK = 0,
GMAC_TRANSCODING_TYPE_CONSOLIDATED_BOOK = 1,
GMAC_TRANSCODING_TYPE_UNNORMALISED = 2
} GMACTranscodingType;
/**
* \ingroup GMAC_UserAPI
* \brief Multicast data type specifier
*/
typedef enum
{
GMAC_MULTICAST_TYPE_UNKNOWN, /**< \brief The type is unknown */
GMAC_MULTICAST_TYPE_LIVE, /**< \brief Usually just incremental data, on some markets also snapshot data */
GMAC_MULTICAST_TYPE_SNAPSHOT, /**< \brief Snapshot data */
GMAC_MULTICAST_TYPE_DATAREF, /**< \brief Data referential data */
GMAC_MULTICAST_TYPE_REREQUEST /**< \brief Data re-requested */
}
GMACMulticastType;
struct _GMACStats;
/**
* \ingroup GMACUser_API
* \brief GMAC Statistics structure
*
* The structure can be retrieved from GMAC for each channel
* separately (\ref GMACStatsMulticast) or global one, for all channels (\ref GMACStatsGlobal)
*/
typedef struct _GMACStats GMACStats;
struct _GMACStats {
/* Identification */
GMACMulticastID MulticastID; /**< \brief The multicast id */
GMACMulticastID RedirectedToID; /**< \brief Set to ~0 for no redirection. Otherwise the destination multicast id */
GMACMulticastID MultiContextRef; /**< \brief Set to originating MultiContext multicast. Otherwise set to ~0*/
GMACMulticastType Type; /**< \brief Data type specifier */
int Buffered; /**< \brief Set to 1 when the multicast is currently being buffered. Otherwise set to 0 */
int Disabled; /**< \brief Set to 1 when the multicast is disabled. Otherwise set to 0 */
int IgnoreGaps; /**< \brief Set to 1 when the multicast is ignoring gaps. Otherwise set to 0 */
int IsMultiContext; /**< \brief Set to 1 when the multicast has multiple sequence number contexts */
int ExpectRepackaged; /**< \brief Set to 1 when the user expected repackaged data due to arbitration - feature not supported */
GMACChannelID ChannelID; /**< \brief The channel id */
int LocalChannelID; /**< \brief Channel id number private for transcoder */
char LocalChannelChar; /**< \brief Set to 'A' or 'B' when arbitration is enabled, otherwise ' ' or '-' */
const char *AdePlugin; /**< \brief Name of plugin, points back to Multicast */
int Tainted; /**< \brief Set to non-zero value when the GMAC detected any gap or problem in the data (this flag has unspecified behaviour) */
int FilteringModuleInUse; /**< \brief Set to non-zero when filtering is enabled in the config file and is supported by the plug-in. */
int FilteringEnabled; /**< \brief Set to non-zero when filtering is enabled for the channel and is running. */
/* Reception counters */
uint64_t PacketsReceivedTotal; /**< \brief Number of packets received by GMAC on its inputs */
uint64_t PacketsReceivedADE; /**< \brief Number of packets received by GMAC from ADE */
uint64_t PacketsReceivedTimeout; /**< \brief Number of packets generated by GMAC as timeouts */
uint64_t PacketsReceivedRedirected; /**< \brief Number of packets redirected to a different multicast */
uint64_t PacketsDelivered; /**< \brief Number of packets delivered by GMAC to user */
uint64_t PacketsInReorderQueue; /**< \brief Number of packets stored currently in GMAC reorder queue */
uint64_t PacketsReceivedControl; /**< \brief Number of packets received from the control queue */
uint64_t GapsDetected; /**< \brief Number of gaps GMAC detected after the timeout for reordering expired */
uint64_t GapsPassed; /**< \brief Number of gaps GMAC passed to the user */
/* Drop counters */
uint64_t PacketsDroppedPayloadError; /**< \brief Number of packets which couldn't be transcoded */
uint64_t PacketsDroppedInTranscoder; /**< \brief Number of packets dropped by the transcoder (probably because the sequence number would confuse) */
uint64_t PacketsDroppedSimulated; /**< \brief Number of packets GMAC dropped intentionally on user request */
uint64_t PacketsDroppedAsDuplicates; /**< \brief Number of packets received with lower sequence number than expected */
uint64_t PacketsDroppedInReorderQueue; /**< \brief Number of packets dropped from the reorder queue (reset, buffer full, sync, duplicate, strange sqn) */
uint64_t ExpectedSequenceNumber;
/* Underlying ADE stats */
ADEStats *RawPacketStats; /**< \brief Statistics gathered by low level input library */
};
/**
* \ingroup GMAC_UserAPI
* \brief GMAC Default Market Status Values
*
* Default status values for Market, Sector, Segment, Channel and Instrument.
* A client can use these as the initial values until they are known.
* Values for Sector, Segment and Channel are 'Open' where these levels are not used.
*
* Returned by \ref GMACGetDefaultStatus()
*/
typedef struct
{
GMACTradingStatus MarketStatus; /**< \brief Default (initial) status for the Market */
GMACTradingStatus SectorStatus; /**< \brief Default (initial) status for each Sector */
GMACTradingStatus SegmentStatus; /**< \brief Default (initial) status for each Segment */
GMACTradingStatus ChannelStatus; /**< \brief Default (initial) status for each Channel */
GMACTradingStatus InstrumentStatus; /**< \brief Default (initial) status for each Instrument */
} GMACDefaultMarketStatus;
/**
* \ingroup GMAC_UserAPI
* \brief Initialises GMAC
*
* Opens all markets specified in the configuration file.
*
* @param GMACH Pointer to the pointer where internal data are created.
* @param GMACConfigPtr Pointer to the market configuration
* @return GMAC_STATUS_OK on success, GMAC_STATUS_PARTIALLY_INITIALIZED if one of the markets fails to initialise
*/
extern GMACStatus __GMACOpen(GMACHandle **GMACH, const Config *GMACConfigPtr, char const* const ClientVersion, char const* const ClientBuildNumber);
static inline GMACStatus GMACOpen(GMACHandle **GMACH, const Config *GMACConfigPtr)
{
return __GMACOpen(GMACH, GMACConfigPtr, CELOXICA_GMAC_VERSION, CELOXICA_GMAC_BUILD_NUMBER);
}
/**
* \ingroup GMAC_UserAPI
* \brief Initialises GMAC
*
* Opens all markets specified in the configuration file.
* equivalant to GMACOpen without need to instanciate Config*
*
* @param GMACH Pointer to the pointer where internal data are created.
* @param GMACConfigFilePath path to configuration file
* @return GMAC_STATUS_OK on success, GMAC_STATUS_PARTIALLY_INITIALIZED if one of the markets fails to initialise
*/
extern GMACStatus GMACInit(GMACHandle** GMACH, const char* GMACConfigFilePath);
/**
* \ingroup GMAC_UserAPI
* \brief Closes all markets.
*
* @param GMACH GMAC Handle
* @return GMAC_STATUS_OK on success
*/
extern GMACStatus GMACClose(GMACHandle *GMACH);
/**
* \ingroup GMAC_DataAPI
* \brief Opens a new reading queue
*
* Allocates the resources required for the queue.
*
* @param GMACH GMAC Handle
* @param Queue Queue number
* @return GMAC_STATUS_OK on success
*/
extern GMACStatus GMACQueueOpen (GMACHandle *GMACH, int Queue);
/**
* \ingroup GMAC_DataAPI
* \brief Opens a new reading queue
*
* Allocates the resources required for the queue.
*
* @param GMACH GMAC Handle
* @param Queue Queue number
* @param BoundCPU The cpu to bound the queue upon starts from 0
* @return GMAC_STATUS_OK on success
*/
extern GMACStatus GMACQueueInit (GMACHandle* GMACH, int Queue, int BoundCPU);
typedef enum
{
/* ADE_ARB_NONE value is assigned by GMACConfigChannelRead
* to GMACConfigChannel::LocalChannelArbMode
* if no arbitration was specified in the GMAC config file.
* Example:
*
* <channel> 0 0 lldt ac0 233.54.12.50:26477 </channel>
* <channel> 1 0 lldt ac0 233.54.12.102:26477 </channel>
*
*/
GMAC_ARB_NONE, /** \brief No arbitration */
/* ADE_ARB_REDUNDANCY value is assigned by GMACConfigChannelRead
* to GMACConfigChannel::LocalChannelArbMode
* if user configued arbitrage.
* Example:
*
* <channel> 0A 0 lldt ac0 233.54.12.50:26477 </channel>
* <channel> 0B 0 lldt ac0 233.54.12.102:26477 </channel>
*
*/
GMAC_ARB_REDUNDANCY, /** \brief Redundancy arbitration */
/* If
* - user requests arbitrage via GMAC config file,
* - hardware does not support it
* - but GMAC is capable to do software arbitrage,
* then the Init function of the plugin is obliged to change value of GMACConfigChannel::LocalChannelArbMode
* from ADE_ARB_REDUNDANCY to ADE_ARB_SW.
*
* This is done, e.g. in "itch.h".
*/
GMAC_ARB_SW /** \brief Software arbitration */
}
GMACArbType;
/*
* Structure and functions used to dynamically open and close multicasts
* (after the GMAC Queue has been opened).
*
* These should be used with care as otherwise they could confuse the code
* which transcodes the message stream for this market.
*/
/**
* \ingroup GMAC_UserAPI
* \brief GMAC Dynamic Multicast Descriptor
*
* Used to hold several values for a multicast to be opened dynamically
* (after the GMAC Queue has been opened).
*
* Used by \ref GMACOpenMulticast()
* Initialised to default values by \ref GMACInitDynamicMcDesc()
*/
typedef struct
{
char OriginalChar; /** For Arbitrage, 'A'/'B'/'-' default '-' */
GMACArbType OriginalArbMode; /** Arbitrage mode, default ADE_ARB_NONE */
GMACMulticastType Type; /** Multicast type, default GMAC_MULTICAST_TYPE_LIVE */
char *Plugin; /** ADE plugin name, default "lldt" */
uint64_t StartSeq; /** Initial sequence number, default SEQUENCE_UNDEFINED */
} GMACDynamicMcDesc;
/**
* \ingroup GMAC_DataAPI
* \brief Initialise GMACDynamicMcDesc structure
*
* Initialise a GMACDynamicMcDesc structure to default values
* as described with \ref GMACDynamicMcDesc.
*
* @param McDesc address of McDesc structure to initialise.
*/
extern void GMACInitDynamicMcDesc(GMACDynamicMcDesc *McDesc);
/**
* \ingroup GMAC_DataAPI
* \brief Opens a multicast
*
* Enables multicasts to be dynamically opened and closed.
* May be called after the GMAC Queue has been opened).
*
* These functions should be used with care as otherwise they could confuse
* the code which transcodes the message stream for this market.
*
* @param GMACH GMAC Handle
* @param MarketIndex Multicast
* @param LocMid A number to group multicasts for processing (within GMAC)
* @param Queue GMAC Queue number
* @param McDesc address of McDesc structure. Can be Null to use defaults.
* @param Interface Interface to use, eg "ac0"
* @param AdditionalInfo Generally the IP and port address, eg "1.2.3.4:5"
* @param ChannelID Channel (as distinct from Multicast), used to logically group multicasts after GMAC
* May be specified as 0xFFFFFFFF when it will be assigned automatically.
* @param MID address to write the new MulticastID
* @return GMAC_STATUS_OK on success
*/
extern GMACStatus GMACOpenMulticast(
GMACHandle *GMACH, // client has this
int MarketIndex, // as in config file
int LocMid, // LocalChannelId
int Queue, // client must specify
GMACDynamicMcDesc *McDesc, // Descriptor structure - see above
char *Interface, // client must specify (eg ac0)
char *AdditionalInfo, // client must specify (IP/Port address)
GMACChannelID DesiredChannelID, // client probably needs to specify this
GMACMulticastID *MID); // return id of opened multicast
/**
* \ingroup GMAC_DataAPI
* \brief Closes a multicast
*
* Enables multicasts to be dynamically closed.
* No errors returned, the multicast will not be open.
*
* These functions should be used with care as otherwise they could confuse
* the code which transcodes the message stream for this market.
*
* @param GMACH GMAC Handle
* @param MulticastID Multicast
*/
extern void GMACCloseMulticast(GMACHandle *GMACH, GMACMulticastID MulticastID);
/**
* \ingroup GMAC_DataAPI
* \brief Sets the expected sequence number for a multicast
*
* Sets the expected sequence value to NewSequenceNumber. (SEQUENCE_UNDEFINED as most common usage)
*
* @param GMACH GMAC Handle
* @param MulticastID Multicast
* @param uint64_t New Sequence Number
*/
extern void GMACSetExpectedSequenceMulticast(GMACHandle *GMACH, GMACMulticastID MulticastID, uint64_t NewSequenceNumber);
/**
* \ingroup GMAC_DataAPI
* \brief Closes the reading queue
*
* @param GMACH GMAC Handle
* @param Queue Queue number
* @return GMAC_STATUS_OK on success
*/
extern GMACStatus GMACQueueClose (GMACHandle *GMACH, int Queue);
/**
* \ingroup GMAC_DataAPI
* \brief Returns data on the specific hardware queue.
*
* This function polls data from the hardware queue. It checks channel/queue relations
* to prevent multiple CPUs processing the same part of the book. It is guaranteed
* that no other CPU polling on a different hardware queue is processing data from the same channel
* until \ref GMACQueueRelease is called.
*
* The function calls the market specific transcoder and returns the data in the Celoxica
* normalised format. It provides sequence integrity checking and recovery. The returned
* data are guaranteed to be in the correct order without gaps.
*
* The Data pointer is set if return code is GMAC_STATUS_OK or GMAC_STATUS_CONTROL.
* The Data pointer is set to the first packet in the reorder list if the return code is
* GMAC_STATUS_RECOVERY_BUFFERING or GMAC_STATUS_RECOVERY_FAILED.
* This data should not be processed as market data since it will be returned again with GMAC_STATUS_OK.
* The user should not call \ref GMACQueueRelease until GMAC_STATUS_OK or GMAC_STATUS_OK_LIVE is returned.
*
* If the return code is GMAC_STATUS_OK or GMAC_STATUS_OK_LIVE, the user must call \ref GMACQueueRelease,
* after processing the passed data.
*
* GMAC_STATUS_CONTROL is returned with the Data pointer provided by user in call \ref GMACControlQueueWrite.
* In this case the mechanism to free the data is the user's responsibility.
*
* GMAC_STATUS_NO_CHANNELS is now returned (previously GMAC_STATUS_ADE_ERROR) when there are no inputs open
* on a GMAC/ADE queue. This can occur if there are no inputs (multicasts) on this queue. Note that in
* cases where GMAC needs to dynamically open/close multicasts this may be a 'soft' error. Handling is up
* to the caller.
*
* If a duplicate packet is found and consequently dropped in the reordering buffer, GMAC_STATUS_NODATA
* is returned, and the PacketsDroppedAsDuplicates counter is incremented.
*
* The function is non-blocking.
*
* @param GMACH GMAC Handle
* @param Queue Id of the HW queue to read from
* @param Data Pointer where the returned data are to be stored
* @param ChannelID Channel the data were received from
* @return GMAC_STATUS_OK or GMAC_STATUS_CONTROL on success, GMAC_NODATA if no data available,
* GMAC_STATUS_NO_CHANNELS if no inputs open on a GMAC/ADE queue, one of the error codes on error.
*/
GMACStatus GMACQueueRead(GMACHandle *GMACH, int Queue, char **Data, GMACChannelID *ChannelID);
/**
* \ingroup GMAC_DataAPI
* \brief Returns data on the specific hardware queue.
*
* This function polls data from the hardware queue. It checks channel/queue relations
* to prevent multiple CPUs processing the same part of the book. It is guaranteed
* that no other CPU polling on a different hardware queue is processing data from the same channel
* until \ref GMACQueueRelease is called.
*
* The function calls the market specific transcoder and returns the data in the Celoxica
* normalised format. It provides sequence integrity checking and recovery. The returned
* data are guaranteed to be in the correct order without gaps.
*
* The Data pointer is set if return code is GMAC_STATUS_OK or GMAC_STATUS_CONTROL.
* The Data pointer is set to the first packet in the reorder list if the return code is
* GMAC_STATUS_RECOVERY_BUFFERING or GMAC_STATUS_RECOVERY_FAILED.
* This data should not be processed as market data since it will be returned again with GMAC_STATUS_OK.
* The user should not call \ref GMACQueueRelease until GMAC_STATUS_OK or GMAC_STATUS_OK_LIVE is returned.
*
* GMAC_STATUS_CONTROL is returned with the Data pointer provided by user in call \ref GMACControlQueueWrite.
* In this case the mechanism to free the data is the user's responsibility.
*
* GMAC_STATUS_NO_CHANNELS is now returned (previously GMAC_STATUS_ADE_ERROR) when there are no inputs open
* on a GMAC/ADE queue. This can occur if there are no inputs (multicasts) on this queue. Note that in
* cases where GMAC needs to dynamically open/close multicasts this may be a 'soft' error. Handling is up
* to the caller.
*
* If a duplicate packet is found and consequently dropped in the reordering buffer, GMAC_STATUS_NODATA
* is returned, and the PacketsDroppedAsDuplicates counter is incremented.
*
* The function is non-blocking.
*
* @param GMACH GMAC Handle
* @param Queue Id of the HW queue to read from
* @param Data Pointer where the returned data are to be stored
* @return GMAC_STATUS_OK or GMAC_STATUS_CONTROL on success, GMAC_NODATA if no data available,
* GMAC_STATUS_NO_CHANNELS if no inputs open on a GMAC/ADE queue, one of the error codes on error.
*/
GMACStatus GMACQueuePoll(GMACHandle *GMACH, int queue, const char** data);
/**
* \ingroup GMAC_DataAPI
* \brief Releases data returned from \ref GMACQueueRead
*
* @param GMACH GMAC Handle
* @param Data Pointer returned by \ref GMACQueueRead
*/
extern void GMACQueueRelease(GMACHandle *GMACH, char *Data);
/**
* \ingroup GMAC_DataAPI
* \brief Writes a control message
*
* Writes a message to the control queue, the message will be read by the thread responsible for the specified channel.
* The data will then be read by \ref GMACQueueRead call with highest priority.
*
* This function allows the user to send control messages to the CPUs responsible for specific channels.
*
* Function \ref GMACQueueRead will return GMAC_STATUS_CONTROL and supplied data pointer will be given to the user.
* Any data manipulation alloc/free must by done by the user. \ref GMACQueueRelease mustn't be called.
*
* Warning: The behaviour after supplying NULL pointer is undefined.
*
* @param GMACH GMAC Handle
* @param Data Pointer to a control message
* @param ChannelID The channel the control message applies to
*
* @return GMAC_STATUS_OK on successful completion.
*/
extern GMACStatus GMACControlQueueWrite (GMACHandle *GMACH, char *Data, GMACChannelID ChannelID);
/**
* \ingroup GMAC_DataAPI
* \brief Writes a control message
*
* Sends the message on all channels the market has, using \ref GMACControlQueueWrite function.
* Each channel receives the same copy of the data (same supplied pointer). User should ensure, that
* data are freed only after read certain times.
*
* @param GMACH GMAC Handle
* @param Data Pointer to a control message
* @param MarketID Market specification the messages will be send on.
*
* @return GMAC_STATUS_OK on successful completion.
*/
extern GMACStatus GMACControlQueueWriteMarket (GMACHandle *GMACH, char *Data, int MarketID);
/**
* \ingroup GMAC_DataAPI
* \brief Sets the taint flag for a multicast
*
* @param GMACH GMAC Handle
* @param MulticastID Multicast
* @param Taint The taint can bet set or reset
* @return GMAC_STATUS_OK or GMAC_STATUS_PARAM_ERROR
*/
extern GMACStatus GMACMulticastSetTaint (GMACHandle *GMACH, GMACMulticastID MulticastID, int Taint);
/**
* \ingroup GMAC_UserAPI
* \brief Converts \ref GMACStatus to string.
*
* @param GMACS Status Code
* @return String representation of the status
*/
extern const char* GMACStatusToString(GMACStatus GMACS);
/**
* \ingroup GMAC_UserAPI
* \brief Converts \ref GMACMulticastType to string.
*
* @param Type The multicast type
* @return String representation of the type
*/
extern const char* GMACMulticastTypeToString (GMACMulticastType Type);
/**
* \ingroup GMAC_DataAPI
* \brief Translates market local name to EISIN
*
* Translates the market local name to EISIN if this feature is supported for the specific feed.
*
* @param GMACH GMAC Handle
* @param ChannelID The channel on which the market update was published
* @param Src Market local name
* @param Dst Pointer to where the ISIN will be copied (must be allocated by caller)
* @return GMAC_STATUS_OK on success
*/
extern GMACStatus GMACTranslateMarketToEISIN(GMACHandle *GMACH, GMACChannelID ChannelID, GMACLocalName Src, GMACEISIN Dst);
/**
* \ingroup GMAC_DataAPI
* \brief Translates market local name to EISIN
*
* Translates the market local name to EISIN if this feature is supported for the specific feed.
*
* @param GMACH GMAC Handle
* @param MarketID The destination market
* @param Src Market local name
* @param Dst Pointer to where the ISIN will be copied (must be allocated by caller)
* @return GMAC_STATUS_OK on success
*/
extern GMACStatus GMACTranslateMarketToEISINEx (GMACHandle *GMACH, int MarketID, GMACLocalName Src, GMACEISIN Dst);
/**
* \ingroup GMAC_DataAPI
* \brief Translates EISIN to market local name
*
* Translates EISIN to market local name if this feature is supported for the specific feed.
*
* @param GMACH GMAC Handle
* @param ChannelID The channel on which the market update was published
* @param Src EISIN
* @param Dst Pointer to where the market local name will be copied (must be allocated by caller)
* @return GMAC_STATUS_OK on success
*/
extern GMACStatus GMACTranslateEISINToMarket(GMACHandle *GMACH, GMACChannelID ChannelID, GMACEISIN Src, GMACLocalName Dst);
/**
* \ingroup GMAC_DataAPI
* \brief Translates EISIN to market local name
*
* Translates EISIN to market local name using Market ID if this feature is supported for the specific feed.
*
* @param GMACH GMAC Handle
* @param MarketID The destination market
* @param Src EISIN
* @param Dst Pointer to where the market local name will be copied (must be allocated by caller)
* @return GMAC_STATUS_OK on success
*/
extern GMACStatus GMACTranslateEISINToMarketEx (GMACHandle *GMACH, int MarketID, GMACEISIN Src, GMACLocalName Dst);
/**
* \ingroup GMAC_UserAPI
* \brief Returns the native coding of an order ID
*
* This function returns the native coding of an order ID. It is the user's responsibility to provide the Buffer,
* for which the recommended size is 32 bytes. In the event that the buffer is too small to hold the native order ID,
* the function will return GMAC_STATUS_PARAM_ERROR.
*
* Celoxica strongly recommends use of transcoded order IDs. Using this function to recover
* native order IDs will affect performance.
*
* @param GMACH GMAC Handle
* @param MarketID Market ID
* @param OrderID The actual transcoded order ID
* @param Buffer Text buffer to hold the native order ID, null terminated when returned
* @param Length The length of the buffer supplied. Recommended size = 32 (bytes)
* @return GMAC_STATUS_OK on success or GMAC_STATUS_PARAM_ERROR if the buffer is not sufficiently large to hold
* the native order ID. If this feature is not supported Buffer is set to an empty string with status GMAC_STATUS_OK
*/
extern GMACStatus GMACGetNativeOrderID (GMACHandle *GMACH, int MarketID, uint64_t OrderID, char* Buffer, int Length);
/**
* \ingroup GMAC_UserAPI
* \brief Sends a timestamp for latency measurement
*
* @param GMACH GMAC Handle
* @param MulticastID Multicast id of the received data
* @param Timestamp Received timestamp from GMACPacketHeader
*/
extern void GMACLatencyTick (GMACHandle *GMACH, GMACMulticastID MulticastID, uint32_t Timestamp);
/**
* \ingroup GMAC_UserAPI
* \brief Returns the real-time latency
*
* Function gives the latency reported by the hardware automatically every 0.5 seconds.
* It reports number of time stamps sent and the total latency in the 0.5 second time window.
* Calling it multiple times within 0.5 second will result in seeing the same value.
*
* Function is fast to return and can be called in time critical section.
*
* @param GMACH GMAC Handle
* @param Queue Queue number
* @param Plugin Name of the ADE plugin ('lldt' for accelerator card)
* @param TSCount Number of reported timestamps
* @param LatencyTotal Total of all reported latencies in ns
* @return GMAC_STATUS_OK on success
*/
extern GMACStatus GMACLatencyRealtime (GMACHandle *GMACH, int Queue, char *Plugin, uint64_t *TSCount, uint64_t *Latency);
/**
* \ingroup GMAC_UserAPI
* \brief Returns the sum of all latencies since the last call
*
* Returns the sum of all latencies since the last reset, or application start. It can be safely
* called from any thread. The caller should make sure the GMAC does not close during the call.
*
* The values are retrieved from card registers and the function is considerably slow,
* it should not be called from time critical sections.
*
* @param GMACH GMAC Handle
* @param Queue Queue number
* @param Plugin Name of the ADE plugin ('lldt' for accelerator card)
* @param TSCount Number of reported timestamps
* @param LatencyTotal Total of all reported latencies in ns
* @param Reset If set to non-zero, the counters will be reset by this read
* @return GMAC_STATUS_OK on success
*/
extern GMACStatus GMACLatencyTotal (GMACHandle *GMACH, int Queue, char *Plugin, uint64_t *TSCount, uint64_t *LatencyTotal, int Reset);
/**
* \ingroup GMAC_DataAPI
* \brief Returns the default price factor for the market specified
*
* Returns -1 if the price factor is unknown and needs to be determined
* from a data referential message.
*
* @param GMACH GMAC Handle
* @param ChannelID Channel the data were received on
* @param PriceFactor Pointer, where the price factor is returned
* @return GMAC_STATUS_OK on success or GMAC_STATUS_PARAM_ERROR if invalid channel is supplied
*/
extern GMACStatus GMACDefaultPriceFactor (GMACHandle *GMACH, GMACChannelID ChannelID, GMACPriceFactor *PriceFactor);
/**
* \ingroup GMAC_DataAPI
* \brief Returns the default currency for the market specified
*
* Returns NULL if the currency is unknown and needs to be determined from a
* data referential message.
*
* @param GMACH GMAC Handle
* @param ChannelID Channel the data were received on
* @param Currency Pointer, where the currency is returned
* @return GMAC_STATUS_OK on success or GMAC_STATUS_PARAM_ERROR if invalid channel is supplied
*/
extern GMACStatus GMACDefaultCurrency (GMACHandle *GMACH, GMACChannelID ChannelID, char **Currency);
/**
* \ingroup GMAC_UserAPI
* \brief Returns 1 if recovery is enabled at GMAC level
*
* @param GMACH GMAC Handle
* @return 1/0
*/
extern int GMACIsRecovery(GMACHandle *GMACH);
/**
* \ingroup GMAC_UserAPI
* \brief Returns 1 if recovery is enabled for the specified multicast id (overrrides GMAC level)
*
* @param GMACH GMAC Handle
* @param MulticastID The ID of the multicast
* @return 1/0
*/
extern int GMACIsRecoveryMulticast(GMACHandle *GMACH, GMACMulticastID MulticastID);
/**
* \ingroup GMAC_UserAPI
* \brief Returns next expected sequence number for the channel
*
* @param GMACH GMAC Handle
* @param MulticastID Multicast querying from
* @param Sequence Next expected sequence
* @return GMAC Status
*/
extern GMACStatus GMACNextExpected (GMACHandle *GMACH, GMACMulticastID MulticastID, uint64_t *Sequence);
/**
* \ingroup GMAC_UserAPI
* \brief Returns encoding type for the channel
*
* Encoding type can be:
* <ul>
* <li>type '0' - Deep Book Messages, types starting with GMAC_TYPE_</li>
* <li>type '1' - Consolidated Book Messages, types starting with GMAC_C_TYPE_</li>
* <li>type '2' - Unnormalised Messages.</li>
* </ul>
*
* Each of the feed is disjointly transcoded into one of those 2 formats.
*
* @param GMACH GMAC Handle
* @param ChannelID Channel ID
* @param Enc Pointer where result is stored
* @return GMAC_STATUS_OK or GMAC_STATUS_PARAM_ERROR
*/
extern GMACStatus GMACChannelGetTranscodingType(GMACHandle *GMACH, GMACChannelID ChannelID, int *Enc);
/**
* \ingroup GMAC_UserAPI
* \brief Error handler type
*
* Error handler can be registered using \ref GMACRegisterErrorHandler
*
* Error handler is called before any function within GMAC as about to return an error.
* The ser can change what the function returns by using a different GMACStatus.
* Msg parameter may contain string description of the error.
*/
typedef GMACStatus (*GMACErrorHandler)(GMACHandle *GMACH, GMACStatus StatusCode, const char *Function, const char *Msg);
/**
* \ingroup GMAC_UserAPI
* \brief Register an error handler
*
* Error handler is called before some status codes are returned.
* It allows user to change the error code being returned, as well as react on it.
*
* For performance reasons, the error handler is not called when one of following status codes is returned:
* <ul>
* <li>GMAC_STATUS_OK</li>
* <li>GMAC_STATUS_NODATA</li>
* </ul>
*
* @param GMACH GMAC Handle
* @param Handler The new error handler
*/
extern void GMACRegisterErrorHandler(GMACHandle *GMACH, GMACErrorHandler Handler);
/**
* \ingroup GMAC_UserAPI
* \brief GMAC Default Error handler
*
* This is the default error handler that gets called if an error occurs.
* It can be overwritten using the \ref GMACRegisterErrorHandler function.
*
* @param GMACH GMAC Handle
* @param StatusCode Status code
* @param Function Function the error happened in
* @param Msg Specific message
* @return StatusCode
*/
extern GMACStatus GMACDefaultErrorHandler(GMACHandle* _GMACH, GMACStatus _statusCode, const char* _function, const char* _msg);
/**
* \ingroup GMAC_UserAPI
* \brief Returns local channel id and arbitration params
*
* @param GMACH GMAC Handle
* @param MulticastID Multicast ID returned in \ref GMACPacketHeader
* @param BaseMulticastID The multicast id where this multicast is redirected to (-1 when not assigned)
* @param LocalChannelID Pointer where 'channel number' is stored
* @param LocalChannelChar 'A' or 'B', or ' ' for no arbitration
* @param LocalChannelMode 0-arbitration off, 1-redundancy, 2-lag
* @return GMAC_STATUS_OK or GMAC_STATUS_PARAM_ERROR if invalid Channel ID supplied
*/
extern GMACStatus GMACGetLocalChannelIDEx (GMACHandle *GMACH, GMACMulticastID MulticastID,
GMACMulticastID *BaseMulticastID, int *LocalChannelID, char *LocalChannelChar, int *ArbitrationMode,
const char **ArbitrationModeDesc);
/**
* \ingroup GMAC_DataAPI
* \brief Sets the expected sequence number for specific multicast
*
* This function allows the user to sync on specific sequence number, to take advantage of snapshot messages for example.
* If there are any data buffered in GMAC until this sequence number, those will be dropped.
* Any data received with sequence number lower then this one will be dropped as well.
*
* This command will be processed by CPU currently responsible for the specific channel asynchronously.
*
* If the user tries to sync on sequence number lower than the next expected one (means GMAC doesn't have the required
* data anymore), GMAC tries to recover the missing messages with respect of re-request timeout. The data in the
* reorder buffer are aging and it can easily happen that the gap is too old to be re-requested.
*
* To avoid synchronizing on deprecated sequence numbers, it is recommended to use this function in combination with
* \ref GMACMulticastBuffer.
*
* @param GMACH GMAC Handle
* @param MulticastID Multicast ID
* @param Sequence Sequence to sync to
* @return GMAC_STATUS_OK
*/
extern GMACStatus GMACMulticastSync (GMACHandle *GMACH, GMACMulticastID MulticastID, uint64_t Sequence);
/**
* \ingroup GMAC_DataAPI
* \brief Starts buffering data on specific multicast
*
* This function helps to synchronize onto specific sequence number with the \ref GMACMulticastSync function.
*
* The function call will cause all data on the specific channel to be buffered.
*
* Each time a new packet is buffered, GMACQueueRead will return status GMAC_STATUS_BUFFERING with a pointer
* to the first buffered packet data, which allows user to get sequence number of the first buffered packet.
* \ref GMACQueueRelease should not be called.
*
* To disable buffering and start receiving data, user should use the \ref GMACMulticastSync function.
*
* Buffered data will be stored in reorder/user buffer pool, the size can be set in the configuration file,
* node GMAC.bufferpool. Note: The bufferpool is shared between all channels on a single core.
*
* If there is no space in the buffer pool, the data will be dropped and recovered later using recovery mechanisms.
* Using buffering will increase the latency and affect the performance so it only should be used for synchronization
* reasons.
*
* @param GMACH GMAC Handle
* @param MulticastID Multicast ID
* @return GMAC_STATUS_OK
*/
extern GMACStatus GMACMulticastBuffer (GMACHandle *GMACH, GMACMulticastID MulticastID);
/**
* \ingroup GMAC_UserAPI
* \brief Get the version number of the firmware
*
* @param BoardNum Selecting the board number
* @param Revision Pointer to the location where the revision number should be stored if the call is successful
* @param VersionMajor Pointer to the location where the version number should be stored if the call is successful
* @param VersionMinor Pointer to the location where the version number should be stored if the call is successful
* @param Name The bitfile name
* @return GMAC_STATUS_OK or GMAC_STATUS_PARAM_ERROR if invalid pointer or handle supplied
*/
extern GMACStatus GMACGetFirmwareVersion (int BoardNum, int * Revision, int *VersionMajor, int *VersionMinor, char Name[5]);
/**
* \ingroup GMAC_UserAPI
* \brief Get the number of board installed
*
* @param MaxBoardNum Pointer to store total amount of boards available
* @return GMAC_STATUS_OK or GMAC_STATUS_PARAM_ERROR if invalid pointer or handle supplied
*/
extern GMACStatus GMACGetMaxBoardNum (int *MaxBoardNum);
/**
* \ingroup GMAC_UserAPI
* \brief Output the information about library and board
*
* @param f File pointer where the information should be written
* @return GMAC_STATUS_OK or GMAC_STATUS_PARAM_ERROR if invalid pointer or handle supplied
*/
extern GMACStatus GMACIdentify (FILE *f);
/**
* \ingroup GMAC_UserAPI
* \brief Convert generic symbol suffix in to market specific suffix if present
*
* The generic suffixes currently supported are as follows. The '?' characted should be interpreted as any
* lowercase character where applicable this will be converted to an uppercase character for the native suffix.
*
* ? - Class or Series ?
* ?_v - Class or Series ? Convertible
* ?_w - Class or Series ? When Issued
* pp - Partial Paid
* _p - Preferred
* _pC? - Preferred Class ?
* _p? - Preferred Class ?
* _p?v - Preferred Class ? Convertible
* _p?w - Preferred Class ? When Issued
* _p_v - Preferred Convertible
* _pW - Preferred When Distributed
* _p_w - Preferred When Issued
* _r - Rights
* _r_w - Rights When Issued
* _u - Units
* _t - Warrents
* _t? - Warrents Series ?
* _t_w - Warrents When Issued
* W - When Distributed
* _w - When Issued
*
* @param GMACH GMAC Handle
* @param MarketID The Market ID of the symbol to be converted.
* @param GenericSymbol The generic symbol to be converted
* @param Dst A pointer to the character array where the resulting string should be stored (Must be valid memory address)
* @return GMAC_STATUS_OK on success or GMAC_STATUS_PARAM_ERROR if invalid pointer or handle supplied
*/
extern GMACStatus GMACSymbolSuffixGenericToNative(GMACHandle *GMACH, unsigned MarketID, const char * GenericSymbol, char * Dst);
/**
* \ingroup GMAC_UserAPI
* \brief Convert market specific symbol suffix in to generic suffix if present
*
* Please see \ref GMACSymbolSuffixGenericToNative() for a list of available generic suffixes
*
* @param GMACH GMAC Handle
* @param MarketID The Market ID of the symbol to be converted.
* @param NativeSymbol The market specific symbol to be converted
* @param Dst A pointer to the character array where the resulting string should be stored (Must be valid memory address)
* @return GMAC_STATUS_OK on success or GMAC_STATUS_PARAM_ERROR if invalid pointer or handle supplied
*/
extern GMACStatus GMACSymbolSuffixNativeToGeneric(GMACHandle *GMACH, unsigned MarketID, const char * NativeSymbol, char * Dst);
/**
* \ingroup GMAC_DataAPI
* \brief Returns the default round lot size for the market specified
*
* Returns -1 if the round lot size is unknown and needs to be determined
* from a data referential message. Feed that do not use round lots will return a round lot size of 1 here.
*
* @param GMACH GMAC Handle
* @param ChannelID Channel the data were received on
* @param RoundLotSize Pointer, where the round lot size is returned
* @return GMAC_STATUS_OK on success or GMAC_STATUS_PARAM_ERROR if invalid channel is supplied,
* or GMAC_STATUS_NOT_IMPLEMENTED if the function is not implemented for this market.
*/
extern GMACStatus GMACDefaultRoundLotSize (GMACHandle *GMACH, GMACChannelID ChannelID, uint64_t *RoundLotSize);
/**
* \ingroup GMAC_DataAPI
* \brief Returns the default status values for Market, Sector, Segment, Channel and Instrument.
* A client can use these as the initial values until they are known.
* Values for Sector, Segment and Channel are 'Open' where these levels are not used.
*
* @param GMACH GMAC Handle
* @param MarketID Market ID to get defaults for
* @param DefStatus Pointer to structure to contain status values
* @return GMAC_STATUS_OK on success or GMAC_STATUS_PARAM_ERROR if invalid market is supplied
*/
extern GMACStatus GMACGetDefaultStatus (GMACHandle *GMACH, int MarketID, GMACDefaultMarketStatus *DefStatus);
/**
* \ingroup GMAC_DataAPI
* \brief Returns a plugin-specific property from the underlying ADE channel
*
* Returns a plugin-specific property from the underlying ADE channel.
*
* Example: We want to obtain the timestamps recorded in a pcap file that we are reading in via the
* file plugin.
*
* <code>
* struct timeval *tv; <br>
* GMACGetADEProperty(..., 0, (void**)&tv);
* </code>
*
* Here we pass 0 as property and a pointer to <code>struct timeval *</code> as Result.
* The function will return the local timestamp of the last read packet, as recorded in the PCAP file.
*
* @param GMACH GMAC Handle
* @param MulticastID Multicast ID
* @param Property Property index - ADE plugin specific
* @param Result Pointer where data are returned
* @return GMAC_STATUS_OK on success
*/
extern GMACStatus GMACGetADEProperty (GMACHandle *GMACH, GMACMulticastID MulticastID, int Property, void **Result);
typedef enum {
GMAC_REFRESH_REQUEST_DEFAULT, /** \brief Default type refresh. (Typically instrument)*/
GMAC_REFRESH_REQUEST_SEGMENT, /** \brief Segment type refresh. */
GMAC_REFRESH_REQUEST_RELOAD_REFERENCE_DATA, /** \brief Reload <symbol-reference-file> data if possible. */
GMAC_REFRESH_REQUEST_RELOAD_PCAP_REFERENCE_DATA, /** \brief Reload reference data from file plugin in <channels>. */
} GMACRefreshRequest;
typedef enum {
GMAC_REFRESH_TYPE_DEFAULT,
GMAC_REFRESH_TYPE_SYMBOL_STATUS,
GMAC_REFRESH_TYPE_INSTRUMENT,
GMAC_REFRESH_TYPE_TRADES,
GMAC_REFRESH_TYPE_STATISTICS,
GMAC_REFRESH_TYPE_ANNOUNCEMENTS,
GMAC_REFRESH_TYPE_AUCTION_INFORMATION,
GMAC_REFRESH_TYPE_DAILY_SCHEDULE,
} GMACRefreshType;
/**
* \ingroup GMAC_UserAPI
* \brief GMAC refresh channel raw handle.
*
* This handle represents a refresh channel. Note the MulticastID is for the live incremental channel associated with the snapshot/refresh channel and
* <b>NOT</b> the refresh channel itself. Ensure that the handle is zeroed before passing as argument.
*/
typedef struct
{
/* Multicast ID has to be first */
GMACMulticastID MulticastID; /**< \brief Multicast ID for the live incremental channel */
GMACLocalName InstrumentID; /**< \brief The instrument ID */
uint64_t Sequence; /**< \brief Sequence number (if applicable) */
GMACRefreshRequest RefreshRequest; /**< \brief Request type (if applicable and/or supported by plugin) */
GMACRefreshType RefreshType; /**< \brief Refresh type (if applicable and/or supported by plugin) */
} GMACRefreshHandle;
/**
* \ingroup GMAC_UserAPI
* \brief Enables a refresh channel.
*
* When passed a valid \ref GMACRefreshHandle, this function enables refresh from the snapshot/refresh channel.
* The \ref GMACMulticastID in the \ref GMACRefreshHandle is for the live incremental channel.
*
* @param GMACH GMAC Handle
* @param GRH GMAC Refresh Handle
* @return GMAC_STATUS_OK on success
*/
extern GMACStatus GMACMulticastRefreshRequest(GMACHandle *GMACH, GMACRefreshHandle *GRH);
/**
* \ingroup GMAC_UserAPI
* \brief Disables a refresh channel.
*
* Disables refresh from the \ref GMACRefreshHandle. See \ref GMACMulticastRefreshRequest.
*
* @param GMACH GMAC Handle
* @param GRH GMAC Refresh Handle
* @return GMAC_STATUS_OK on success
*/
extern GMACStatus GMACMulticastRefreshComplete(GMACHandle *GMACH, GMACRefreshHandle *GRH);
/**
* \ingroup GMAC_UserAPI
* \brief Returns refresh status for a Multicast.
*
* Returns whether the multicast has refresh enabled or disabled.
*
* @param GMACH GMAC Handle
* @param MulticastID GMAC Multicast ID
* @return int '1' when enabled
*/
extern int GMACMulticastIsRefresh (GMACHandle *GMACH, GMACMulticastID MulticastID);
/**
* \ingroup GMAC_UserAPI
* \brief Returns the market status based on the opening hours and last timestamp received
*
* Returns the inferred status of the market, based on the market hours specified via
* config node config.gmac.markets.market.market-hours (see GMAC Config Guide for details)
* and the last timestamp received from the exchange.<br>
* *MarketOpenPtr is set to -1 when market hours are not configured, to 0 when the market
* is inferred as being closed or the timestamp is unknown, and to 1 when the market is
* inferred as being open.
*
* @param GMACH GMAC Handle
* @param MarketID GMAC Market ID
* @param MarketOpenPtr Pointer to the open indicator set by the function
* @param ExchangeTimestamp Exchange timestamp to examine
* @return GMAC_STATUS_OK on success otherwise GMAC_STATUS_PARAM_ERROR
*/
extern GMACStatus GMACQueryMarketHours (GMACHandle *GMACH, int MarketID, int *MarketOpenPtr, uint64_t ExchangeTimestamp);
#ifdef __cplusplus
}
#endif
#include "gmac_deprecated.h"
#endif