Changeset 6a082f8 for lib/libtrace.h.in
- Timestamp:
- 03/06/15 09:35:51 (6 years ago)
- 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:
- 4ce6fca
- Parents:
- ab3fa18
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
lib/libtrace.h.in
r62b3c4e r6a082f8 3461 3461 /*@}*/ 3462 3462 3463 typedef struct libtrace_result_t libtrace_result_t;3464 /**3465 * A collection of types for convenience used in place of a3466 * simple void* to allow a any type of data to be stored.3467 *3468 * This is expected to be 8 bytes in length.3469 */3470 typedef union {3471 /* Pointers */3472 void *ptr;3473 libtrace_packet_t *pkt;3474 libtrace_result_t *res;3475 3476 /* C99 Integer types */3477 /* NOTE: Standard doesn't require 64-bit3478 * but x32 and x64 gcc does */3479 int64_t sint64;3480 uint64_t uint64;3481 3482 uint32_t uint32s[2];3483 int32_t sint32s[2];3484 uint32_t uint32;3485 int32_t sint32;3486 3487 uint16_t uint16s[4];3488 int16_t sint16s[4];3489 uint16_t uint16;3490 int16_t sint16;3491 3492 uint8_t uint8s[8];3493 int8_t sint8s[8];3494 uint8_t uint8;3495 int8_t sint8;3496 3497 size_t size;3498 3499 /* C basic types - we cannot be certian of the size */3500 int sint;3501 unsigned int uint;3502 3503 signed char schars[8];3504 unsigned char uchars[8];3505 signed char schar;3506 unsigned char uchar;3507 3508 /* Real numbers */3509 float rfloat;3510 double rdouble;3511 } libtrace_generic_t;3512 ct_assert(sizeof(libtrace_generic_t) == 8);3513 3514 typedef struct libtrace_message_t {3515 int code;3516 libtrace_generic_t additional;3517 libtrace_thread_t *sender;3518 } libtrace_message_t;3519 3520 /** Structure holding information about a result */3521 struct libtrace_result_t {3522 uint64_t key;3523 libtrace_generic_t value;3524 int type;3525 };3526 #define RESULT_NORMAL 03527 #define RESULT_PACKET 13528 #define RESULT_TICK 23529 3530 /**3531 * The definition for the main function that the user supplies to process3532 * packets.3533 *3534 * @param trace The trace the packet is related to.3535 * @param thread The thread the trace is related to.3536 * @param mesg_code The type of data ready, the most important being MESSAGE_PACKET.3537 * In this case data.pkt contains the packet.3538 * @param data A generic union of types that fit into 8 bytes, containing3539 * information dependent upon the mesg_code.3540 * @param sender The thread that the message originated from.3541 *3542 * The values of data and sender depend upon the mesg_code. Please see the3543 * documentation for the message as to what value these will contain.3544 */3545 typedef void* (*fn_per_pkt)(libtrace_t* trace,3546 libtrace_thread_t *thread,3547 int mesg_code,3548 libtrace_generic_t data,3549 libtrace_thread_t *sender);3550 typedef void (*fn_reporter)(libtrace_t* trace,3551 int mesg_code,3552 libtrace_generic_t data,3553 libtrace_thread_t *sender);3554 typedef uint64_t (*fn_hasher)(const libtrace_packet_t* packet, void *data);3555 3556 DLLEXPORT int trace_pstart(libtrace_t *libtrace, void* global_blob, fn_per_pkt per_pkt, fn_reporter reporter);3557 DLLEXPORT int trace_ppause(libtrace_t *libtrace);3558 DLLEXPORT int trace_pstop(libtrace_t *libtrace);3559 DLLEXPORT void trace_join(libtrace_t * trace);3560 3561 DLLEXPORT void libtrace_result_set_key(libtrace_result_t * result, uint64_t key);3562 DLLEXPORT uint64_t libtrace_result_get_key(libtrace_result_t * result);3563 DLLEXPORT void libtrace_result_set_value(libtrace_result_t * result, libtrace_generic_t value);3564 DLLEXPORT libtrace_generic_t libtrace_result_get_value(libtrace_result_t * result);3565 DLLEXPORT void libtrace_result_set_key_value(libtrace_result_t * result, uint64_t key, libtrace_generic_t value);3566 DLLEXPORT void trace_destroy_result(libtrace_result_t ** result);3567 3568 // Ways to access Global and TLS storage that we provide the user3569 DLLEXPORT void * trace_get_global(libtrace_t *trace);3570 DLLEXPORT void * trace_set_global(libtrace_t *trace, void * data);3571 DLLEXPORT void * trace_set_tls(libtrace_thread_t *t, void * data);3572 DLLEXPORT void * trace_get_tls(libtrace_thread_t *t);3573 3574 3575 DLLEXPORT void trace_publish_result(libtrace_t *libtrace, libtrace_thread_t *t, uint64_t key, libtrace_generic_t value, int type);3576 typedef struct libtrace_vector libtrace_vector_t;3577 3578 DLLEXPORT int trace_post_reporter(libtrace_t *libtrace);3579 DLLEXPORT int libtrace_thread_get_message_count(libtrace_t * libtrace);3580 DLLEXPORT int libtrace_thread_get_message(libtrace_t * libtrace, libtrace_message_t * message);3581 DLLEXPORT int libtrace_thread_try_get_message(libtrace_t * libtrace, libtrace_message_t * message);3582 DLLEXPORT int trace_send_message_to_reporter(libtrace_t * libtrace, libtrace_message_t * message);3583 DLLEXPORT int trace_send_message_to_perpkts(libtrace_t * libtrace, libtrace_message_t * message);3584 DLLEXPORT int trace_send_message_to_thread(libtrace_t * libtrace, libtrace_thread_t *t, libtrace_message_t * message);3585 DLLEXPORT int trace_finished(libtrace_t * libtrace);3586 DLLEXPORT uint64_t trace_packet_get_order(libtrace_packet_t * packet);3587 DLLEXPORT uint64_t trace_packet_get_hash(libtrace_packet_t * packet);3588 DLLEXPORT void trace_packet_set_order(libtrace_packet_t * packet, uint64_t order);3589 DLLEXPORT void trace_packet_set_hash(libtrace_packet_t * packet, uint64_t hash);3590 DLLEXPORT uint64_t tv_to_usec(struct timeval *tv);3591 3592 DLLEXPORT int retrive_first_packet(libtrace_t *libtrace, libtrace_packet_t **packet, struct timeval **tv);3593 3594 DLLEXPORT void libtrace_make_packet_safe(libtrace_packet_t *pkt);3595 DLLEXPORT void libtrace_make_result_safe(libtrace_result_t *res);3596 3597 typedef enum {3598 /**3599 * Sets the hasher function, if NULL(default) no hashing is used a3600 * cores will get packets on a first in first served basis3601 */3602 TRACE_OPTION_SET_HASHER,3603 3604 /**3605 * Libtrace set perpkt thread count3606 */3607 TRACE_OPTION_SET_PERPKT_THREAD_COUNT,3608 3609 /**3610 * Delays packets so they are played back in trace-time rather than as fast3611 * as possible.3612 */3613 TRACE_OPTION_TRACETIME,3614 3615 /**3616 * Specifies the interval between tick packets in milliseconds, if 03617 * or less this is ignored.3618 */3619 TRACE_OPTION_TICK_INTERVAL,3620 TRACE_OPTION_GET_CONFIG,3621 TRACE_OPTION_SET_CONFIG3622 } trace_parallel_option_t;3623 3624 enum libtrace_messages {3625 MESSAGE_PACKET,3626 MESSAGE_RESULT,3627 MESSAGE_STARTING,3628 MESSAGE_RESUMING,3629 MESSAGE_STOPPING,3630 MESSAGE_PAUSING,3631 MESSAGE_DO_PAUSE,3632 MESSAGE_DO_STOP,3633 MESSAGE_FIRST_PACKET,3634 MESSAGE_PERPKT_ENDED,3635 MESSAGE_PERPKT_RESUMED,3636 MESSAGE_PERPKT_PAUSED,3637 MESSAGE_PERPKT_EOF,3638 MESSAGE_POST_REPORTER,3639 MESSAGE_POST_RANGE,3640 MESSAGE_TICK,3641 MESSAGE_USER = 10003642 };3643 3644 enum hasher_types {3645 /**3646 * Balance load across CPUs best as possible, this is basically to say do3647 * not care about hash. This might still might be implemented3648 * using a hash or round robin etc. under the hood depending on the format3649 */3650 HASHER_BALANCE,3651 3652 /** Use a hash which is bi-directional for TCP flows, that is packets with3653 * the same hash are sent to the same thread. All non TCP packets will be3654 * sent to the same thread. UDP may or may not be sent to separate3655 * threads like TCP, this depends on the format support.3656 */3657 HASHER_BIDIRECTIONAL,3658 3659 /**3660 * Use a hash which is uni-directional across TCP flows, that means the3661 * opposite directions of the same 5 tuple might end up on separate cores.3662 * Otherwise is identical to HASHER_BIDIRECTIONAL3663 */3664 HASHER_UNIDIRECTIONAL,3665 3666 /**3667 * Always use the user supplied hasher, this currently disables native3668 * support and is likely significantly slower.3669 */3670 HASHER_CUSTOM,3671 3672 /**3673 * This is not a valid option, used internally only!!! TODO remove3674 * Set by the format if the hashing is going to be done in hardware3675 */3676 HASHER_HARDWARE3677 };3678 3679 typedef struct libtrace_info_t {3680 /**3681 * True if a live format (i.e. packets have to be tracetime).3682 * Otherwise false, indicating packets can be read as fast3683 * as possible from the format.3684 */3685 bool live;3686 3687 /**3688 * The maximum number of threads supported by a parallel trace. 13689 * if parallel support is not native (in this case libtrace will simulate3690 * an unlimited number of threads), -1 means unlimited and 0 unknown.3691 */3692 int max_threads;3693 3694 /* TODO hash fn supported list */3695 3696 /* TODO consider time/clock details?? */3697 } libtrace_info_t;3698 3699 DLLEXPORT int trace_parallel_config(libtrace_t *libtrace, trace_parallel_option_t option, void *value);3700 DLLEXPORT libtrace_packet_t* trace_result_packet(libtrace_t * libtrace, libtrace_packet_t * packet);3701 DLLEXPORT void trace_free_result_packet(libtrace_t * libtrace, libtrace_packet_t * packet);3702 DLLEXPORT int trace_set_hasher(libtrace_t *trace, enum hasher_types type, fn_hasher hasher, void *data);3703 DLLEXPORT libtrace_info_t *trace_get_information(libtrace_t * libtrace);3704 3705 /**3706 * Tuning the parallel sizes3707 */3708 struct user_configuration {3709 // Packet memory cache settings (ocache_init) total3710 /**3711 * See diagrams, this sets the maximum size of freelist used to3712 * maintain packets and their memory buffers.3713 * NOTE setting this to less than recommend could cause deadlock a3714 * trace that manages its own packets.3715 * A unblockable error message will be printed.3716 */3717 size_t packet_cache_size;3718 /**3719 * Per thread local cache size for the packet freelist3720 */3721 size_t packet_thread_cache_size;3722 /**3723 * If true the total number of packets that can be created by a trace is limited3724 * to the packet_cache_size, otherwise once packet_cache_size is exceeded alloc3725 * and free will be used to create and free packets, this will be slower than3726 * using the freelist and could run a machine out of memory.3727 *3728 * However this does make it easier to ensure that deadlocks will not occur3729 * due to running out of packets3730 */3731 bool fixed_packet_count;3732 /**3733 * When reading from a single threaded input source to reduce3734 * lock contention a 'burst' of packets is read per pkt thread3735 * this determines the bursts size.3736 */3737 size_t burst_size;3738 // Each perpkt thread has a queue leading into the reporter3739 //size_t reporter_queue_size;3740 3741 /**3742 * The tick interval - in milliseconds3743 * When a live trace is used messages are sent at the tick3744 * interval to ensure that all perpkt threads receive data3745 * this allows results to be printed in cases flows are3746 * not being directed to a certian thread, while still3747 * maintaining order.3748 */3749 size_t tick_interval;3750 3751 /**3752 * Like the tick interval but used in the case of file format3753 * This specifies the number of packets before inserting a tick to3754 * every thread.3755 */3756 size_t tick_count;3757 3758 /**3759 * The number of per packet threads requested, 0 means use default.3760 * Default typically be the number of processor threads detected less one or two.3761 */3762 size_t perpkt_threads;3763 3764 /**3765 * See diagrams, this sets the maximum size of buffers used between3766 * the single hasher thread and the buffer.3767 * NOTE setting this to less than recommend could cause deadlock a3768 * trace that manages its own packets.3769 * A unblockable warning message will be printed to stderr in this case.3770 */3771 /** The number of packets that can queue per thread from hasher thread */3772 size_t hasher_queue_size;3773 3774 /**3775 * If true use a polling hasher queue, that means that we will spin/or yeild3776 * when rather than blocking on a lock. This applies to both the hasher thread3777 * and perpkts reading the queues.3778 */3779 bool hasher_polling;3780 3781 /**3782 * If true the reporter thread will continuously poll waiting for results3783 * if false they are only checked when a message is received, this message3784 * is controlled by reporter_thold.3785 */3786 bool reporter_polling;3787 3788 /**3789 * Perpkt thread result queue size before triggering the reporter step to read results3790 */3791 size_t reporter_thold;3792 3793 /**3794 * Prints a line to standard error for every state change3795 * for both the trace as a whole and for each thread.3796 */3797 bool debug_state;3798 };3799 #include <stdio.h>3800 DLLEXPORT void parse_user_config(struct user_configuration* uc, char * str);3801 DLLEXPORT void parse_user_config_file(struct user_configuration* uc, FILE *file);3802 DLLEXPORT int libtrace_get_perpkt_count(libtrace_t* t);3803 3804 /**3805 * The methods we use to combine multiple outputs into a single output3806 * This is not considered a stable API however is public.3807 * Where possible use built in combiners3808 *3809 * NOTE this structure is duplicated per trace and as such can3810 * have functions rewritten, and in fact should if possible.3811 */3812 typedef struct libtrace_combine libtrace_combine_t;3813 struct libtrace_combine {3814 3815 /**3816 * Called at the start of the trace to allow datastructures3817 * to be initilised and allow functions to be swapped if approriate.3818 *3819 * Also factors such as whether the trace is live or not can3820 * be used to determine the functions used.3821 * @return 0 if successful, -1 if an error occurs3822 */3823 int (*initialise)(libtrace_t *,libtrace_combine_t *);3824 3825 /**3826 * Called when the trace ends, clean up any memory here3827 * from libtrace_t * init.3828 */3829 void (*destroy)(libtrace_t *, libtrace_combine_t *);3830 3831 /**3832 * Publish a result against it's a threads queue.3833 * If null publish directly, expected to be used3834 * as a single threaded optimisation and can be3835 * set to NULL by init if this case is detected.3836 */3837 void (*publish)(libtrace_t *, int thread_id, libtrace_combine_t *, libtrace_result_t *);3838 3839 /**3840 * Read as many results as possible from the trace.3841 * Directy calls the users code to handle results from here.3842 *3843 * THIS SHOULD BE NON-BLOCKING AND READ AS MANY AS POSSIBLE3844 * If publish is NULL, this probably should be NULL also otherwise3845 * it will not be called.3846 */3847 void (*read)(libtrace_t *, libtrace_combine_t *);3848 3849 /**3850 * Called when the trace is finished to flush the final3851 * results to the reporter thread.3852 *3853 * There may be no results, in which case this should3854 * just return.3855 *3856 * Libtrace state:3857 * Called from reporter thread3858 * No perpkt threads will be running, i.e. publish will not be3859 * called again.3860 *3861 * If publish is NULL, this probably should be NULL also otherwise3862 * it will not be called.3863 */3864 void (*read_final)(libtrace_t *, libtrace_combine_t *);3865 3866 /**3867 * Pause must make sure any results of the type packet are safe.3868 * That means trace_copy_packet() and destroy the original.3869 * This also should be NULL if publish is NULL.3870 */3871 void (*pause)(libtrace_t *, libtrace_combine_t *);3872 3873 /**3874 * Data storage for all the combiner threads3875 */3876 void *queues;3877 3878 /**3879 * Configuration options, what this does is upto the combiner3880 * chosen.3881 */3882 libtrace_generic_t configuration;3883 };3884 3885 DLLEXPORT void trace_set_combiner(libtrace_t *trace, const libtrace_combine_t *combiner, libtrace_generic_t config);3886 3887 #define READ_EOF 03888 #define READ_ERROR -13889 #define READ_MESSAGE -23890 // Used for inband tick message3891 #define READ_TICK -33892 3893 #define ZERO_USER_CONFIG(config) memset(&config, 0, sizeof(struct user_configuration));3894 3895 3463 #ifdef __cplusplus 3896 3464 } /* extern "C" */
Note: See TracChangeset
for help on using the changeset viewer.