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

sc_pool: A pool of packet buffers. More...

Functions

int sc_pool_get_packets (struct sc_packet_list *list, struct sc_pool *pool, int min_packets, int max_packets)
 Get packet buffers from a pool. More...
 
void sc_pool_return_packets (struct sc_pool *pool, struct sc_packet_list *list)
 Return packets to a pool. More...
 
void sc_pool_on_threshold (struct sc_pool *pool, struct sc_callback *event, int threshold)
 Request a callback when the pool is refilled. More...
 
struct sc_packetsc_pool_duplicate_packet (struct sc_pool *pool, struct sc_packet *packet, int snap)
 Duplicate a packet. More...
 
struct sc_packetsc_pool_duplicate_packed_packet (struct sc_pool *pool, const struct sc_packed_packet *psp, int snap)
 Duplicate a packed-stream packet. More...
 
int sc_packet_append_iovec_ptr (struct sc_packet *packet, struct sc_pool *pool, struct sc_iovec_ptr *iovp, int snap)
 Append data to a packet. More...
 
struct sc_nodesc_pool_set_refill_node (struct sc_pool *pool, struct sc_node *node)
 Set the refill node for a pool. More...
 
int sc_pool_wraps_node (struct sc_pool *pool, struct sc_node *node)
 Indicate that a pool is used to wrap packets from a node. More...
 
struct sc_objectsc_pool_to_object (struct sc_pool *pool)
 Convert an sc_pool to an sc_object. More...
 
struct sc_pool * sc_pool_from_object (struct sc_object *obj)
 Convert an sc_object to an sc_pool. More...
 
uint64_t sc_pool_get_buffer_size (struct sc_pool *pool)
 Get the minimum buffer size provided by this pool. More...
 

Detailed Description

sc_pool: A pool of packet buffers.

Function Documentation

int sc_packet_append_iovec_ptr ( struct sc_packet packet,
struct sc_pool *  pool,
struct sc_iovec_ptr iovp,
int  snap 
)

Append data to a packet.

Parameters
packetThe packet to append data to
poolPacket pool to allocate frag buffers from (optional)
iovpIdentifies the data to copy in
snapThe maximum number of bytes to copy in
Returns
0 if all the requested data could be appended.
-1 if more space was needed and it was not possible to allocate fragment buffers
-2 if the packet runs out of space (ie. the fragments chain would exceed the maximum chain length).

If you need to know the number of bytes appended, compare the packet frame_len before and after the call.

struct sc_packet* sc_pool_duplicate_packed_packet ( struct sc_pool *  pool,
const struct sc_packed_packet psp,
int  snap 
)

Duplicate a packed-stream packet.

Parameters
poolThe pool to allocate buffers from
pspThe packed-stream packet to duplicate
snapThe maximum number of bytes to copy
Returns
The duplicated packet or NULL if insufficient buffers.
struct sc_packet* sc_pool_duplicate_packet ( struct sc_pool *  pool,
struct sc_packet packet,
int  snap 
)

Duplicate a packet.

Parameters
poolThe pool to allocate buffers from
packetThe packet to duplicate
snapThe maximum number of bytes to copy
Returns
The duplicated packet or NULL if insufficient buffers.
struct sc_pool* sc_pool_from_object ( struct sc_object obj)

Convert an sc_object to an sc_pool.

Parameters
objAn sc_object instance or NULL
Returns
NULL if obj is NULL otherwise the sc_pool.

Also returns NULL if obj is not of type SC_OBJ_POOL.

uint64_t sc_pool_get_buffer_size ( struct sc_pool *  pool)

Get the minimum buffer size provided by this pool.

Parameters
poolAn sc_pool instance
Returns
The minimum buffer size provided by this pool.

If called at prep time, the size returned returned may be less than the size of buffers provided by this pool.

int sc_pool_get_packets ( struct sc_packet_list list,
struct sc_pool *  pool,
int  min_packets,
int  max_packets 
)

Get packet buffers from a pool.

Parameters
listList where retrieved packets are placed
poolThe packet pool
min_packetsMinimum number of buffers to be returned
max_packetsMaximum number of buffers to be returned
Returns
The number of buffers added to list, or -1 if the minimum could not be satisfied.

list must be initialised on entry (and may already contain some packets), but need not be finalised. The list is finalised on return unless an error is returned (in which case the list is not modified).

Each packet returned is initialised as follows: pkt->flags = 0; pkt->frame_len = 0; pkt->iovlen = 1; pkt->iov[0] gives the base and extent of the DMA area The fragment list is empty

The following packet fields have undefined values: ts_sec, ts_nsec.

void sc_pool_on_threshold ( struct sc_pool *  pool,
struct sc_callback event,
int  threshold 
)

Request a callback when the pool is refilled.

Parameters
poolThe packet pool
eventThe event object
thresholdEvent fires when pool has >= threshold buffers

Registers an event handler that is invoked when the pool fill level reaches the specified threshold. If the pool fill level is already at or above the threshold, the handler will be invoked as soon as possible.

void sc_pool_return_packets ( struct sc_pool *  pool,
struct sc_packet_list list 
)

Return packets to a pool.

Parameters
poolThe packet pool
listList of packets to return

list must be initialised on entry, but can be empty. The packets on the list can have frags.

struct sc_node* sc_pool_set_refill_node ( struct sc_pool *  pool,
struct sc_node node 
)

Set the refill node for a pool.

Parameters
poolA packet pool
nodeA refill node
Returns
The refill node This function sets node to be the refill node for pool. SolarCapture sets up the necessary links so that when packet buffers from pool are freed, they will be forwarded to node.

It is expected that node will normally return packets to the pool by calling sc_pool_return_packets.

This call is only needed if some action needs to be taken before returning freed buffers to the pool. The builtin nodes sc_wrap_undo and sc_ref_count_undo can be used as pool refill nodes.

struct sc_object* sc_pool_to_object ( struct sc_pool *  pool)

Convert an sc_pool to an sc_object.

Parameters
poolAn sc_pool instance or NULL
Returns
NULL if pool is NULL otherwise the sc_object.
int sc_pool_wraps_node ( struct sc_pool *  pool,
struct sc_node node 
)

Indicate that a pool is used to wrap packets from a node.

Parameters
poolA packet pool
nodeA node
Returns
0 on success, or a negative error code.

This function is used to indicate that packets from pool are used to wrap packets that are delivered to node.

This allows SolarCapture to ensure that the packet pools sending packets to node can be configured appropriately. For example, if these wrapped packets reach an sc_injector, it may be necessary to DMA map the underlying packet buffers.