collector.h (15052B)
1 /* 2 * 3 * 4 * This license is set out in https://raw.githubusercontent.com/Broadcom-Network-Switching-Software/OpenBCM/master/Legal/LICENSE file. 5 * 6 * Copyright 2007-2020 Broadcom Inc. All rights reserved. 7 * 8 */ 9 10 #ifndef __BCM_COLLECTOR_H__ 11 #define __BCM_COLLECTOR_H__ 12 13 #include <bcm/types.h> 14 15 #ifndef BCM_HIDE_DISPATCHABLE 16 17 /* Initializes collector module. */ 18 extern int bcm_collector_init( 19 int unit); 20 21 /* Detach collector module. */ 22 extern int bcm_collector_detach( 23 int unit); 24 25 #endif /* BCM_HIDE_DISPATCHABLE */ 26 27 /* 28 * Wire formats that are supported for exporting stats data to the 29 * collector 30 */ 31 typedef enum bcm_collector_wire_format_e { 32 bcmCollectorWireFormatIpfix = 0, /* Ipfix wire format. */ 33 bcmCollectorWireFormatProtoBuf = 1, /* Protocol Buffer wire format . */ 34 bcmCollectorWireFormatCount = 2 /* Last Value. Not Usable. */ 35 } bcm_collector_wire_format_t; 36 37 /* Export profile flags. */ 38 #define BCM_COLLECTOR_EXPORT_PROFILE_FLAGS_USE_NUM_RECORDS (1 << 0) /* Use num_records field 39 in export profile 40 instead of 41 max_packet_length. */ 42 43 /* PROTOBUF system ID flag. */ 44 #define BCM_COLLECTOR_PROTOBUF_MAX_SYSTEM_ID_LENGTH 32 /* Max ProtoBuf system Id 45 length. */ 46 47 /* Export profile information of stats data sent to the collector. */ 48 typedef struct bcm_collector_export_profile_s { 49 uint32 flags; /* Export profile flags, see 50 BCM_COLLECTOR_EXPORT_PROFILE_FLAGS_XXX. */ 51 bcm_collector_wire_format_t wire_format; /* wire format of export profile. */ 52 uint32 export_interval; /* export interval of export profile in 53 micro seconds. */ 54 uint32 max_packet_length; /* Maximum length of export packet sent 55 to collector. */ 56 int num_records; /* Number of records to be sent in one 57 packet, can be used instead of 58 max_packet_length. */ 59 } bcm_collector_export_profile_t; 60 61 /* 62 * Defines used to define invalid/default values for export profile 63 * structure parameters. 64 */ 65 #define BCM_COLLECTOR_EXPORT_INTERVAL_INVALID 0xffffffff /* Invalid export 66 interval. Used to 67 initialize export 68 interval. */ 69 70 /* Initializes a export profile information structure. */ 71 extern void bcm_collector_export_profile_t_init( 72 bcm_collector_export_profile_t *export_profile_info); 73 74 /* 75 * Options that can be passed via options parameter during collector 76 * export profile creation. 77 */ 78 #define BCM_COLLECTOR_EXPORT_PROFILE_WITH_ID (1 << 0) /* Creates a collector 79 export profile with 80 ID. */ 81 #define BCM_COLLECTOR_EXPORT_PROFILE_REPLACE (1 << 1) /* Replaces a collector 82 export profile with 83 ID. */ 84 85 #ifndef BCM_HIDE_DISPATCHABLE 86 87 /* Creates an export profile with given export information. */ 88 extern int bcm_collector_export_profile_create( 89 int unit, 90 uint32 options, 91 int *export_profile_id, 92 bcm_collector_export_profile_t *export_profile_info); 93 94 /* Fetches an export profile information whose ID is provided. */ 95 extern int bcm_collector_export_profile_get( 96 int unit, 97 int export_profile_id, 98 bcm_collector_export_profile_t *export_profile_info); 99 100 /* Get all the configured collector export profiles. */ 101 extern int bcm_collector_export_profile_ids_get_all( 102 int unit, 103 int max_size, 104 int *export_profile_ids_list, 105 int *list_size); 106 107 /* Destroy a collector export profile. */ 108 extern int bcm_collector_export_profile_destroy( 109 int unit, 110 int export_profile_id); 111 112 #endif /* BCM_HIDE_DISPATCHABLE */ 113 114 /* 115 * Macros for bcm_collector_eth_header_t.vlan_tag_structure to indicate 116 * the tag structure of vlans. 117 */ 118 #define BCM_COLLECTOR_ETH_HDR_UNTAGGED 0x1 119 #define BCM_COLLECTOR_ETH_HDR_SINGLE_TAGGED 0x2 120 #define BCM_COLLECTOR_ETH_HDR_DOUBLE_TAGGED 0x3 121 122 /* 123 * Ethernet header in the encap used to send the stats data packet to the 124 * collector. 125 */ 126 typedef struct bcm_collector_eth_header_s { 127 bcm_mac_t dst_mac; 128 bcm_mac_t src_mac; 129 uint8 vlan_tag_structure; 130 uint16 outer_tpid; 131 uint16 inner_tpid; 132 bcm_vlan_tag_t outer_vlan_tag; 133 bcm_vlan_tag_t inner_vlan_tag; 134 } bcm_collector_eth_header_t; 135 136 /* 137 * IPv4 header in the encap used to send the stats data packet to the 138 * collector. 139 */ 140 typedef struct bcm_collector_ipv4_header_s { 141 bcm_ip_t src_ip; 142 bcm_ip_t dst_ip; 143 uint8 dscp; 144 uint8 ttl; 145 } bcm_collector_ipv4_header_t; 146 147 /* 148 * IPv6 header in the encap used to send the stats data packet to the 149 * collector. 150 */ 151 typedef struct bcm_collector_ipv6_header_s { 152 bcm_ip6_t src_ip; 153 bcm_ip6_t dst_ip; 154 uint8 traffic_class; 155 uint32 flow_label; 156 uint8 hop_limit; 157 } bcm_collector_ipv6_header_t; 158 159 /* UDP header flags. */ 160 #define BCM_COLLECTOR_UDP_FLAGS_CHECKSUM_ENABLE (1 << 0) /* Add UDP checksum in 161 the export packet */ 162 163 /* 164 * UDP header in the encap used to send the stats data packet to the 165 * collector. 166 */ 167 typedef struct bcm_collector_udp_header_s { 168 uint32 flags; /* UDP header flags, see 169 BCM_COLLECTOR_UDP_FLAGS_XXX. */ 170 bcm_l4_port_t src_port; 171 bcm_l4_port_t dst_port; 172 } bcm_collector_udp_header_t; 173 174 /* IPFIX observation domain. */ 175 typedef uint32 bcm_collector_ipfix_observation_domain_t; 176 177 /* 178 * IPFIX header in the encap used to send the data packet to the remote 179 * collector. 180 */ 181 typedef struct bcm_collector_ipfix_header_s { 182 int version; /* Ipfix Protocol Version. */ 183 int initial_sequence_num; /* Ipfix initial sequence number. */ 184 bcm_collector_ipfix_observation_domain_t observation_domain_id; /* IPFIX observation domain from which 185 this collector is receiving the 186 export data.. */ 187 uint32 enterprise_number; /* IPFIX enterprise number. */ 188 } bcm_collector_ipfix_header_t; 189 190 /* ProtoBuf config structure. */ 191 typedef struct bcm_collector_protobuf_header_s { 192 int system_id_length; /* system_id_length. */ 193 uint8 system_id[BCM_COLLECTOR_PROTOBUF_MAX_SYSTEM_ID_LENGTH]; /* System Id. */ 194 uint32 component_id; /* Component Id. */ 195 } bcm_collector_protobuf_header_t; 196 197 /* Software ID given for a Collector configuration. */ 198 typedef int bcm_collector_t; 199 200 /* 201 * Transport types that are supported for exporting stats data to the 202 * collector 203 */ 204 typedef enum bcm_collector_transport_type_e { 205 bcmCollectorTransportTypeIpv4Udp = 0, /* The encap will be of the format UDP 206 over IPv4. */ 207 bcmCollectorTransportTypeIpv6Udp = 1, /* The encap will be of the format UDP 208 over IPv6. */ 209 bcmCollectorTransportTypeRaw = 2, /* Indicates no encap. This will be 210 useful when the raw stats data PDUs 211 need to be transported to the local 212 CPU. */ 213 bcmCollectorTransportTypeCount = 3 /* Last Value. Not Usable. */ 214 } bcm_collector_transport_type_t; 215 216 /* Collector types. */ 217 typedef enum bcm_collector_type_e { 218 bcmCollectorRemote = 0, /* The collector is a remote machine expecting flow 219 information records using encap scheme defined 220 through TransportTypeXxx. */ 221 bcmCollectorLocal = 1, /* The collector is local CPU receiving flow 222 information records usually without any encap. 223 TransportTypeRaw. */ 224 bcmCollectorCount = 2 /* Last Value. Not Usable. */ 225 } bcm_collector_type_t; 226 227 /* The different timestamp sources in collector to compute ToD */ 228 typedef enum bcm_collector_timestamp_source_e { 229 bcmCollectorTimestampSourceLegacy = 0, /* Legacy source */ 230 bcmCollectorTimestampSourceNTP = 1, /* Network Time Protocol source */ 231 bcmCollectorTimestampSourcePTP = 2, /* Precision Time Protocol source */ 232 bcmCollectorTimestampSourceCount = 3 /* Always Last. Not a usable value */ 233 } bcm_collector_timestamp_source_t; 234 235 #define BCM_COLLECTOR_TIMESTAMP_SOURCE_STRINGS \ 236 { \ 237 "Legacy", \ 238 "NTP", \ 239 "PTP" \ 240 } 241 242 /* Collector information. */ 243 typedef struct bcm_collector_info_s { 244 bcm_collector_type_t collector_type; /* Collector type. Remote vs Local */ 245 bcm_collector_transport_type_t transport_type; /* Transport type used for exporting 246 data to the collector. This 247 identifies the usable fields within 248 the encap structure member defined 249 below. */ 250 bcm_collector_eth_header_t eth; /* Ethernet encapsulation of the packet 251 sent to collector. */ 252 bcm_collector_ipv4_header_t ipv4; /* IPv4 encapsulation of the packet sent 253 to collector. */ 254 bcm_collector_ipv6_header_t ipv6; /* IPv6 encapsulation of the packet sent 255 to collector. */ 256 bcm_collector_udp_header_t udp; /* UDP encapsulation of the packet sent 257 to collector. */ 258 bcm_collector_ipfix_header_t ipfix; /* IPFIX encapsulation of the packet 259 sent to collector. */ 260 bcm_collector_protobuf_header_t protobuf; /* Protobuf header information. */ 261 bcm_collector_timestamp_source_t src_ts; /* Timestamp source info. */ 262 int max_records_reserve; /* Maximum number of export record 263 entries reserved in the hardware FIFO 264 for the collector. */ 265 } bcm_collector_info_t; 266 267 /* Initializes a collector information structure. */ 268 extern void bcm_collector_info_t_init( 269 bcm_collector_info_t *collector_info); 270 271 /* 272 * Options that can be passed via options parameter during collector 273 * creation. 274 */ 275 #define BCM_COLLECTOR_WITH_ID (1 << 0) /* Create a collector with ID. */ 276 #define BCM_COLLECTOR_REPLACE (1 << 1) /* Replace a collector with ID. */ 277 278 #ifndef BCM_HIDE_DISPATCHABLE 279 280 /* Create a collector. */ 281 extern int bcm_collector_create( 282 int unit, 283 uint32 options, 284 bcm_collector_t *collector_id, 285 bcm_collector_info_t *collector_info); 286 287 /* Gets a Collector information. */ 288 extern int bcm_collector_get( 289 int unit, 290 bcm_collector_t id, 291 bcm_collector_info_t *collector_info); 292 293 /* Get all the configured collectors. */ 294 extern int bcm_collector_get_all( 295 int unit, 296 int max_size, 297 bcm_collector_t *collector_list, 298 int *list_size); 299 300 /* Destroys a collector. */ 301 extern int bcm_collector_destroy( 302 int unit, 303 bcm_collector_t id); 304 305 #endif /* BCM_HIDE_DISPATCHABLE */ 306 307 /* 308 * Max size of the data record received at the CPU through the FIFO DMA 309 * reception. 310 */ 311 #define BCM_COLLECTOR_EXPORT_RECORD_LENGTH BITS2BYTES(1024) /* Maximum length of a 312 data record. 1024 313 bits. */ 314 315 /* 316 * Collector Export record structure. Data record info passed to 317 * application software by SDK Software. The unprocessed data record will 318 * be presented in network byte order. 319 */ 320 typedef struct bcm_collector_export_record_s { 321 int size; /* Number of valid octets in the 322 data_record array for the device. */ 323 uint8 data_record[BCM_COLLECTOR_EXPORT_RECORD_LENGTH]; /* Raw data record in network byte 324 order. */ 325 } bcm_collector_export_record_t; 326 327 /* bcm_collector_export_record_t_init */ 328 extern void bcm_collector_export_record_t_init( 329 bcm_collector_export_record_t *record); 330 331 /* 332 * Defines for priorities of registered handlers for Collector export 333 * records. Callback handlers are always called from highest priority to 334 * lowest priority until one of the handlers returns record_handled or 335 * record_handled_owned. 336 * 337 * 338 * When callback handling proecedure starts, a default callback handler 339 * is installed at BCM_COLLECTOR_EXPORT_CB_PRIO_MIN priority that simply 340 * discards the record. 341 */ 342 #define BCM_COLLECTOR_EXPORT_CB_PRIO_MIN ((uint8)0) 343 #define BCM_COLLECTOR_EXPORT_CB_PRIO_MAX ((uint8)255) 344 345 /* Export callback options */ 346 typedef struct bcm_collector_callback_options_s { 347 int callback_prio; /* Priority of the callback function in the list. */ 348 } bcm_collector_callback_options_t; 349 350 /* bcm_collector_callback_options_t_init */ 351 extern void bcm_collector_callback_options_t_init( 352 bcm_collector_callback_options_t *callback_options); 353 354 /* Return values from export record callout routines. */ 355 typedef enum bcm_collector_export_record_handle_e { 356 BCM_COLLECTOR_EXPORT_RECORD_INVALID = 0, /* Invalid return value. */ 357 BCM_COLLECTOR_EXPORT_RECORD_NOT_HANDLED = 1, /* Export record not processed. */ 358 BCM_COLLECTOR_EXPORT_RECORD_HANDLED = 2, /* Export record handled, not owned. */ 359 BCM_COLLECTOR_EXPORT_RECORD_HANDLED_OWNED = 3 /* Export record handled and owned. */ 360 } bcm_collector_export_record_handle_t; 361 362 /* Callback routine for collector record exported to local collector. */ 363 typedef bcm_collector_export_record_handle_t (*bcm_collector_export_record_cb_f)( 364 int unit, 365 bcm_collector_t collector_id, 366 bcm_collector_export_record_t *record, 367 void *userdata); 368 369 #ifndef BCM_HIDE_DISPATCHABLE 370 371 /* Register callback routine for Local collector record export. */ 372 extern int bcm_collector_export_record_register( 373 int unit, 374 bcm_collector_t collector_id, 375 bcm_collector_callback_options_t callback_options, 376 bcm_collector_export_record_cb_f callback_fn, 377 void *userdata); 378 379 /* Unregister callback routine for Local collector record export. */ 380 extern int bcm_collector_export_record_unregister( 381 int unit, 382 bcm_collector_t collector_id, 383 bcm_collector_callback_options_t callback_options, 384 bcm_collector_export_record_cb_f callback_fn); 385 386 #endif /* BCM_HIDE_DISPATCHABLE */ 387 388 #endif /* __BCM_COLLECTOR_H__ */