SolarCapture C Bindings User Guide  SF-115721-CD
Issue 1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
stream.h File Reference

This header file defines sc_stream objects for directing packets to a sc_vi instance. A packet must match all the stream criteria for it to be directed by the stream to an sc_vi instance. More...

Functions

int sc_stream_alloc (struct sc_stream **stream_out, const struct sc_attr *attr, struct sc_session *scs)
 Create a new stream object for this session. More...
 
int sc_stream_free (struct sc_stream *stream)
 Free a previously created stream. More...
 
int sc_stream_reset (struct sc_stream *stream)
 Reinitialise a stream. More...
 
int sc_stream_set_str (struct sc_stream *stream, const char *str)
 Set the stream to match packets identified by a string. More...
 
int sc_stream_all (struct sc_stream *stream)
 Configure stream to match packets not explicitly steered elsewhere. More...
 
int sc_stream_mismatch (struct sc_stream *stream)
 Configure stream to match packets not steered elsewhere and not requested by the kernel network stack. More...
 
int sc_stream_ip_dest_hostport (struct sc_stream *stream, int protocol, const char *dhost, const char *dport)
 Configure this stream to capture all packets with the matching protocol, destination hostname and destination port. More...
 
int sc_stream_ip_source_hostport (struct sc_stream *stream, const char *shost, const char *sport)
 Configure this stream to capture all packets with the matching protocol, source hostname and source port. More...
 
int sc_stream_eth_dhost (struct sc_stream *stream, const uint8_t *mac_addr)
 Add the destination MAC address to the set of fields matched. More...
 
int sc_stream_eth_vlan_id (struct sc_stream *stream, int vlan_id)
 Add the VLAN ID to the set of fields matched. More...
 
int sc_stream_eth_shost (struct sc_stream *stream, const uint8_t *mac_addr)
 Add the source MAC address to the set of fields matched. More...
 
int sc_stream_eth_type (struct sc_stream *stream, uint16_t eth_type)
 Add the Ethernet ether_type field to the set of fields matched. More...
 
int sc_stream_ip_dest_host (struct sc_stream *stream, const char *dhost)
 Add the IPv4 destination to the set of fields matched. More...
 
int sc_stream_ip_dest_port (struct sc_stream *stream, const char *dport)
 Add the TCP or UDP destination port to the set of fields matched. More...
 
int sc_stream_ip_source_host (struct sc_stream *stream, const char *shost)
 Add the IPv4 source to the set of fields matched. More...
 
int sc_stream_ip_source_port (struct sc_stream *stream, const char *sport)
 Add the TCP or UDP source port to the set of fields matched. More...
 
int sc_stream_ip_protocol (struct sc_stream *stream, int protocol)
 Add the IP protocol to the set of fields matched. More...
 

Detailed Description

This header file defines sc_stream objects for directing packets to a sc_vi instance. A packet must match all the stream criteria for it to be directed by the stream to an sc_vi instance.

Function Documentation

int sc_stream_all ( struct sc_stream stream)

Configure stream to match packets not explicitly steered elsewhere.

Parameters
streamA stream object.

This stream captures packets that would otherwise be delivered to the OS kernel network stack, and also packets that would normally be discarded by the adapter when not in promiscuous mode.

Returns
0 on success, or a negative error code.
int sc_stream_alloc ( struct sc_stream **  stream_out,
const struct sc_attr attr,
struct sc_session *  scs 
)

Create a new stream object for this session.

Parameters
stream_outOn success, the created stream.
attrAttributes to pass in.
scsThe session this stream is for.
Returns
0 on success, or a negative error code.
int sc_stream_eth_dhost ( struct sc_stream stream,
const uint8_t *  mac_addr 
)

Add the destination MAC address to the set of fields matched.

Parameters
streamA stream object.
mac_addrThe destination MAC address to match.
Returns
0 on success, or a negative error code.
int sc_stream_eth_shost ( struct sc_stream stream,
const uint8_t *  mac_addr 
)

Add the source MAC address to the set of fields matched.

Parameters
streamA stream object.
mac_addrThe source MAC address to match.
Returns
0 on success, or a negative error code.
int sc_stream_eth_type ( struct sc_stream stream,
uint16_t  eth_type 
)

Add the Ethernet ether_type field to the set of fields matched.

Parameters
streamA stream object.
eth_typeThe ether_type to match (host endian).
Returns
0 on success, or a negative error code.
int sc_stream_eth_vlan_id ( struct sc_stream stream,
int  vlan_id 
)

Add the VLAN ID to the set of fields matched.

Parameters
streamA stream object.
vlan_idThe VLAN ID to match against.
Returns
0 on success, or a negative error code.
int sc_stream_free ( struct sc_stream stream)

Free a previously created stream.

Parameters
streamThe stream to free.
Returns
0, always.
int sc_stream_ip_dest_host ( struct sc_stream stream,
const char *  dhost 
)

Add the IPv4 destination to the set of fields matched.

Parameters
streamA stream object.
dhostThe destination host name or IP to match.
Returns
0 on success, or a negative error code.
int sc_stream_ip_dest_hostport ( struct sc_stream stream,
int  protocol,
const char *  dhost,
const char *  dport 
)

Configure this stream to capture all packets with the matching protocol, destination hostname and destination port.

Parameters
streamA stream object.
protocolThe transport layer protocol to match against.
dhostThe destination hostname to match against.
dportThe destination port to match against.
Returns
0 on success, or a negative error code.
int sc_stream_ip_dest_port ( struct sc_stream stream,
const char *  dport 
)

Add the TCP or UDP destination port to the set of fields matched.

Parameters
streamA stream object.
dportThe destination port to match.
Returns
0 on success, or a negative error code.
int sc_stream_ip_protocol ( struct sc_stream stream,
int  protocol 
)

Add the IP protocol to the set of fields matched.

Parameters
streamA stream object.
protocolThe IP protocol to match.
Returns
0 on success, or a negative error code.
int sc_stream_ip_source_host ( struct sc_stream stream,
const char *  shost 
)

Add the IPv4 source to the set of fields matched.

Parameters
streamA stream object.
shostThe source host name or IP to match.
Returns
0 on success, or a negative error code.
int sc_stream_ip_source_hostport ( struct sc_stream stream,
const char *  shost,
const char *  sport 
)

Configure this stream to capture all packets with the matching protocol, source hostname and source port.

Parameters
streamA stream object.
shostThe source hostname to match against.
sportThe source port to match against.
Returns
0 on success, or a negative error code.
int sc_stream_ip_source_port ( struct sc_stream stream,
const char *  sport 
)

Add the TCP or UDP source port to the set of fields matched.

Parameters
streamA stream object.
sportThe source port to match.
Returns
0 on success, or a negative error code.
int sc_stream_mismatch ( struct sc_stream stream)

Configure stream to match packets not steered elsewhere and not requested by the kernel network stack.

Parameters
streamA stream object.

This stream matches packets that would normally be discarded by the network adapter when it is not in promiscuous mode.

Returns
0 on success, or a negative error code.
int sc_stream_reset ( struct sc_stream stream)

Reinitialise a stream.

Parameters
streamThe stream to reinitialise.
Returns
0 on success, or a negative error code.
int sc_stream_set_str ( struct sc_stream stream,
const char *  str 
)

Set the stream to match packets identified by a string.

Parameters
streamA stream object.
strMatch criteria.
Returns
0 on success, or a negative error code.

This call is the preferred way of configuring a stream, since it offers the most flexibility.

Different adapter types support matching on different combinations of header fields. The combinations supported also depend on firmware version and firmware variant. (The firmware variant is selected using the sfboot utility). In the tables below the firmware variants are identified as follows:

  • FF: Full-featured firmware variant
  • ULL: Ultra-low latency firmware variant
  • CPS: Capture-packed-stream firmware variant

The abbreviated syntax uses one of the formats shown in the table below. The table also shows the adapter firmware variants that support each format.

Abbreviated syntax SFN7xxx
eth:<dest-mac> FF ULL CPS
eth:vid=<vlan>,<dest-mac> FF ULL
{udp|tcp}:<dest-host>:<dest-port> FF ULL CPS
{udp|tcp}:<dest-host>:<dest-port>,<source-host>:<source-port> FF ULL
{udp|tcp}:vid=<vlan>,<dest-host>:<dest-port> FF
{udp|tcp}:vid=<vlan>,<dest-host>:<dest-port>,<source-host>:<source-port> FF

The full syntax allows more flexibility. A stream is constructed as a comma separated list of key-value pairs, except for the special cases "all", "mismatch", "ip", "tcp", and "udp". Available keys are shown in the table below:

Key or key-value pairs Description
dmac=xx:xx:xx:xx:xx:xx Match Ethernet destination MAC address.
smac=xx:xx:xx:xx:xx:xx Match Ethernet source MAC addres.
vid=INT Match Ethernet outer VLAN ID.
eth_type=ip|arp|INT Match Ethernet ether_type.
shost=hostname Match IPv4 source host.
dhost=hostname Match IPv4 destination host.
ip_protocol=udp|tcp|INT Match IPv4 protocol (implies eth_type=ip).
sport=INT Match TCP or UDP source port.
dport=INT Match TCP or UDP destination port.
all All packets not steered elsewhere.
mismatch All packets not steered elsewhere and not requested by the kernel network stack.
ip Shorthand for eth_type=ip.
tcp Shorthand for ip_protocol=tcp.
udp Shorthand for ip_protocol=udp.

IPv4 addresses may be given as a dotted quad or a host name that can resolved with getaddrinfo().

Supported combinations of keys are shown in the table below, together with the firmware variants required:

Key combination SFN7xxx
all FF ULL CPS
mismatch FF ULL CPS
vid FF CPS
dmac FF ULL CPS
dmac, vid FF ULL
ip_protocol, dhost, dport FF ULL CPS
ip_protocol, dhost, dport, shost, sport FF ULL
[vid,] [dmac,] ip_protocol, dhost, dport FF
[vid,] [dmac,] ip_protocol, dhost, dport, shost, sport FF
eth_type FF ULL
eth_type, vid FF ULL CPS
eth_type, dmac FF ULL
ip_protocol FF ULL
ip_protocol, vid FF ULL CPS
[vid,] ip_protocol, dmac FF