Changeset d420777 for lib/libtrace.h.in


Ignore:
Timestamp:
08/19/15 13:37:05 (6 years ago)
Author:
Shane Alcock <salcock@…>
Branches:
4.0.1-hotfixes, cachetimestamps, develop, dpdk-ndag, etsilive, libtrace4, master, ndag_format, pfring, rc-4.0.1, rc-4.0.2, rc-4.0.3, rc-4.0.4, ringdecrementfix, ringperformance, ringtimestampfixes
Children:
461582b
Parents:
c24de65 (diff), 6210f82 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.
Message:

Merge remote branch 'parallel/develop' into libtrace4

File:
1 edited

Legend:

Unmodified
Added
Removed
  • lib/libtrace.h.in

    r0277ab8 rd420777  
    6363
    6464#include <sys/types.h>
     65#include <stddef.h>
     66#include <stdio.h>
     67/* Compile time assertion. Sourced from:
     68 * http://www.pixelbeat.org/programming/gcc/static_assert.html */
     69#define ct_assert(e) extern char (*ct_assert(void)) [sizeof(char[1 - 2*!(e)])]
     70
    6571#ifndef WIN32
    6672#include <sys/time.h>
     
    117123/** DAG driver version installed on the current system */
    118124#define DAG_DRIVER_V "@DAG_VERSION_NUM@"
     125
     126/**
     127  * A version of assert that always runs the first argument even
     128  * when not debugging, however only asserts the condition if debugging
     129  * Intended for use mainly with pthread locks etc. which have error
     130  * returns but *should* never actually fail.
     131  */
     132#ifdef NDEBUG
     133#define ASSERT_RET(run, cond) run
     134#else
     135#define ASSERT_RET(run, cond) assert(run cond)
     136//#define ASSERT_RET(run, cond) run
     137#endif
    119138   
    120139#ifdef __cplusplus
     
    197216#endif
    198217
     218#ifndef CACHE_LINE_SIZE
     219#define CACHE_LINE_SIZE 64
     220#endif
     221#define ALIGN_STRUCT(x) __attribute__((aligned(x)))
     222
    199223#ifdef _MSC_VER
    200224    #ifdef LT_BUILDING_DLL
     
    225249/** Opaque structure holding information about a bpf filter */
    226250typedef struct libtrace_filter_t libtrace_filter_t;
     251
     252/** Opaque structure holding information about libtrace thread */
     253typedef struct libtrace_thread_t libtrace_thread_t;
    227254
    228255/** If the packet has allocated its own memory the buffer_control should be
     
    512539        uint8_t transport_proto;        /**< Cached transport protocol */
    513540        uint32_t l4_remaining;          /**< Cached transport remaining */
     541        uint64_t order; /**< Notes the order of this packet in relation to the input */
     542        uint64_t hash; /**< A hash of the packet as supplied by the user */
     543        int error; /**< The error status of pread_packet */
    514544} libtrace_packet_t;
    515545
     
    12491279        /** If enabled, the libtrace event API will ignore time gaps between
    12501280         * packets when reading from a trace file */
    1251         TRACE_OPTION_EVENT_REALTIME
     1281        TRACE_OPTION_EVENT_REALTIME,
     1282
     1283        /** The hasher function for a parallel libtrace. It is recommended to
     1284         * access this option via trace_set_hasher(). */
     1285        TRACE_OPTION_HASHER
    12521286} trace_option_t;
    12531287
     
    12571291 * @param value         The value to set the option to
    12581292 * @return -1 if option configuration failed, 0 otherwise
    1259  * This should be called after trace_create, and before trace_start
     1293 *
     1294 * This should be called after trace_create(), and before trace_start()
     1295 *
     1296 * @note Please consider using the newer trace_set_X() functions to access
     1297 * this function.
    12601298 */
    12611299DLLEXPORT int trace_config(libtrace_t *libtrace,
    12621300                trace_option_t option,
    12631301                void *value);
     1302
     1303/** Maximum number of bytes to be captured for any given packet
     1304 *
     1305 * @param libtrace The trace object to apply the option to
     1306 * @param snaplen The snap length to set
     1307 * @return -1 if option configuration failed, 0 otherwise
     1308 */
     1309DLLEXPORT int trace_set_snaplen(libtrace_t *trace, int snaplen);
     1310
     1311/** If enabled, places a live capture interface into promiscuous mode
     1312 *
     1313 * @param libtrace The trace object to apply the option to
     1314 * @param promisc
     1315 * @return -1 if option configuration failed, 0 otherwise
     1316 */
     1317DLLEXPORT int trace_set_promisc(libtrace_t *trace, bool promisc);
     1318
     1319/** Apply this filter to all packets read from this trace
     1320 *
     1321 * @param libtrace The trace object to apply the option to
     1322 * @param filter The filter to apply
     1323 * @return -1 if option configuration failed, 0 otherwise
     1324 */
     1325DLLEXPORT int trace_set_filter(libtrace_t *trace, libtrace_filter_t *filter);
     1326
     1327/** Defines the frequency of meta-data reporting, e.g. DUCK packets
     1328 *
     1329 * @param libtrace The trace object to apply the option to
     1330 * @param freq The meta data frequency
     1331 * @return -1 if option configuration failed, 0 otherwise
     1332 */
     1333DLLEXPORT int trace_set_meta_freq(libtrace_t *trace, int freq);
     1334
     1335/** If enabled, the libtrace event API will ignore time gaps between
     1336 * packets when reading from a trace file.
     1337 *
     1338 * @param libtrace The trace object to apply the option to
     1339 * @param realtime True ignores gaps
     1340 * @return -1 if option configuration failed, 0 otherwise
     1341 */
     1342DLLEXPORT int trace_set_event_realtime(libtrace_t *trace, bool realtime);
    12641343
    12651344/** Valid compression types
     
    12861365} trace_option_output_t;
    12871366
     1367/* To add a new stat field update this list, and the relevent places in
     1368 * libtrace_stat_t structure.
     1369 */
     1370/** An X Macro set for libtrace stat fields */
     1371#define LIBTRACE_STAT_FIELDS \
     1372        X(accepted) \
     1373        X(filtered) \
     1374        X(received) \
     1375        X(dropped) \
     1376        X(captured) \
     1377        X(errors)
     1378
     1379/**
     1380 * Statistic counters are cumulative from the time the trace is started.
     1381 * Trace pause will reset the counters, to zero.
     1382 * Always check \a{field}_valid is set before attempting to read the stored value.
     1383 *
     1384 * @note Always allocate this structure using trace_create_statistics().
     1385 *       This allows us to extend the structure in the future.
     1386 */
     1387typedef struct libtrace_stat_t {
     1388#define X(name) LT_BITFIELD64 name ##_valid : 1;
     1389        LIBTRACE_STAT_FIELDS
     1390#undef X
     1391        /* We use the remaining space as magic to ensure the structure
     1392         * was alloc'd by us. We can easily decrease the no. bits without
     1393         * problems as long as we update any asserts as needed */
     1394        LT_BITFIELD64 reserved1: 26; /**< Bits reserved for future fields */
     1395        LT_BITFIELD64 reserved2: 24; /**< Bits reserved for future fields */
     1396        LT_BITFIELD64 magic: 8; /**< A number stored against the format to
     1397                                  ensure the struct was allocated correctly */
     1398
     1399        /* These must all be uint64_t's, match this order with the X macro */
     1400        uint64_t accepted;
     1401        /**< The number of packets that have been read from the input trace
     1402         * using trace_read_packet(). In the parallel framework this may include
     1403         * some packets waiting in a batch yet to be seen by the user's
     1404         * application.
     1405         *
     1406         * This does not include filtered packets because these do not make it
     1407         * to trace_read_packet().
     1408         *
     1409         * @note This field replaces trace_get_accepted_packets()
     1410         */
     1411        uint64_t filtered;
     1412        /**< The number of packets that were captured, but discarded for not
     1413         * matching a provided filter.
     1414         *
     1415         * @note This field replaces trace_get_filtered_packets()
     1416         */
     1417        uint64_t received;
     1418        /**< The total number of good packets which have been recevied. Including
     1419         * those which are dropped and filtered. This does not include errors.
     1420         *
     1421         * @note This may include a small number of buffered packets
     1422         *       not yet included in accepted.
     1423         *
     1424         * @note This field replaces trace_get_received_packets()
     1425         */
     1426        uint64_t dropped;
     1427        /**< The number of packets that have been dropped on an input trace
     1428         * due to lack of buffer space on the capturing device. This does not
     1429         * included errored packets which are dropped directly by the card.
     1430         *
     1431         * @note This field replaces trace_get_dropped_packets()
     1432         */
     1433        uint64_t captured;
     1434        /**< The number of received packets that have not been dropped. This
     1435         * includes filtered packets.
     1436         *
     1437         * This is equivalent to received-dropped.
     1438         *
     1439         * @note This may include a small number of buffered packets
     1440         *       not yet included in accepted.
     1441         */
     1442        uint64_t errors;
     1443        /**< The number of packets that have been discarded by the network card
     1444         * because they are invalid. That includes FCS mismatches, incorrect
     1445         * packet lengths etc.
     1446         */
     1447} libtrace_stat_t;
     1448
     1449ct_assert(offsetof(libtrace_stat_t, accepted) == 8);
     1450
    12881451/** Sets an output config option
    12891452 *
     
    13771540 *
    13781541 * If the number is not known, this function will return UINT64_MAX
    1379  */
    1380 DLLEXPORT
     1542 *
     1543 * @deprecated This function is deprecated: Use trace_get_statistics(), this
     1544 *             allows all statistic counters to be read in an atomic manner.
     1545 */
     1546DLLEXPORT DEPRECATED
    13811547uint64_t trace_get_received_packets(libtrace_t *trace);
    13821548
     
    13881554 *
    13891555 * If the number is not known, this function will return UINT64_MAX
    1390  */
    1391 DLLEXPORT
     1556 *
     1557 * @deprecated This function is deprecated: Use trace_get_statistics(), this
     1558 *             allows all statistic counters to be read in an atomic manner.
     1559 */
     1560DLLEXPORT DEPRECATED
    13921561uint64_t trace_get_filtered_packets(libtrace_t *trace);
    13931562
     
    13991568 *
    14001569 * If the number is not known, this function will return UINT64_MAX
    1401  */
    1402 DLLEXPORT
     1570 *
     1571 * @deprecated This function is deprecated: Use trace_get_statistics(), this
     1572 *             allows all statistic counters to be read in an atomic manner.
     1573 */
     1574DLLEXPORT DEPRECATED
    14031575uint64_t trace_get_dropped_packets(libtrace_t *trace);
    14041576
     
    14101582 *
    14111583 * If the number is not known, this function will return UINT64_MAX
     1584 *
     1585 * @deprecated This function is deprecated: Use trace_get_statistics(), this
     1586 *             allows all statistic counters to be read in an atomic manner.
     1587 */
     1588DLLEXPORT DEPRECATED
     1589uint64_t trace_get_accepted_packets(libtrace_t *trace);
     1590
     1591/**
     1592 * Returns statistic counters for a trace, for a parallel trace this is a
     1593 * combined total.
     1594 * Where possible these are retrived atomically, however this behaviour depends
     1595 * on the underlying trace format.
     1596 *
     1597 * @param trace The input trace to examine.
     1598 * @param stats Optional, Filled upon return with statistics about the trace,
     1599 *              check the flags included to see if a given statistic is valid.
     1600 *              If NULL a statistic structure owned by libtrace is returned, this
     1601 *              should not be free'd and will become invalid if the trace is
     1602 *              destroyed.
     1603 *
     1604 * @return A pointer to the statistics structure.
     1605 * @note Use trace_create_stat() to create the stats object, this way future
     1606 *       versions of libtrace can add to the structure without breaking existing
     1607 *       code.
    14121608 */
    14131609DLLEXPORT
    1414 uint64_t trace_get_accepted_packets(libtrace_t *trace);
     1610libtrace_stat_t *trace_get_statistics(libtrace_t *trace, libtrace_stat_t *stats);
     1611
     1612
     1613/**
     1614 * Returns statistic counters for a single thread of a trace.
     1615 * Where possible these are retrived atomically, however this behaviour depends
     1616 * on the underlying trace format.
     1617 *
     1618 * @param trace The input trace to examine.
     1619 * @param t An optional thread to received stats for or NULL to retrive stats
     1620 *          for the current thread
     1621 * @param stats Filled upon return with statistics about the trace, check the
     1622 *              flags included to see if a given statistic is valid.
     1623 *
     1624 * @note Use trace_create_stat() to create the stats object, this way future
     1625 *       versions of libtrace can add to the structure without breaking existing
     1626 *       code.
     1627 */
     1628DLLEXPORT
     1629void trace_get_thread_statistics(libtrace_t *trace, libtrace_thread_t *t,
     1630                                 libtrace_stat_t *stats);
     1631
     1632/**
     1633 * Creates and returns a zeroed libtrace_stat_t structure.
     1634 *
     1635 * This allows us to add extra fields increasing the size of the structure
     1636 * without breaking existing libtrace applications.
     1637 *
     1638 * This structure should be free'd using free().
     1639 *
     1640 * @return A valid pointer to a libtrace_stat_t struct otherwise NULL if
     1641 *         memory was not available.
     1642 */
     1643DLLEXPORT libtrace_stat_t* trace_create_statistics(void);
     1644
     1645/**
     1646 * Performs the operation c=a-b accounting for valid fields.
     1647 * c is allowed to be a or b.
     1648 *
     1649 * @param a The minuend
     1650 * @param b The subtrahend
     1651 * @param c The resulting difference
     1652 */
     1653DLLEXPORT
     1654void trace_subtract_statistics(const libtrace_stat_t *a,
     1655                               const libtrace_stat_t *b, libtrace_stat_t *c);
     1656
     1657/**
     1658 * Performs operation c=a+b accounting for valid fields.
     1659 * c is allowed to be a or b.
     1660 *
     1661 * @param a The first operand
     1662 * @param b The second operand
     1663 * @param c The result
     1664 */
     1665DLLEXPORT
     1666void trace_add_statistics(const libtrace_stat_t *a,
     1667                          const libtrace_stat_t *b, libtrace_stat_t *c);
     1668
     1669/**
     1670 * Prints all valid stats to a file stream, (which could be stdout/err).
     1671 * By default the format "name: value" is used.
     1672 *
     1673 * @param s The statistic structure to print
     1674 * @param f The output file stream
     1675 * @param format An optional format string such as the default ("%s: %"PRIu64"\n")
     1676 *               This is passed to fprintf and called with two arguments
     1677 *               first a char* (%s) and second a uint64_t (%PRIu64).
     1678 *
     1679 * @return -1 if an error occurs when writing to the file stream, check errno.
     1680 *         Otherwise 0.
     1681 */
     1682DLLEXPORT
     1683int trace_print_statistics(const libtrace_stat_t *s, FILE *f,
     1684                           const char *format);
    14151685
    14161686
Note: See TracChangeset for help on using the changeset viewer.