VPP/cpel

CPEL Performance Event Log Files

This page describes the CPEL file format. Over the last decade, we've constructed a set of tools to collect, display and report fine-grained performance event data. As the toolset has grown, limitations inherent in previous file formats have become an issue.

CPEL files consist of a set of sections, similar to ELF-files. Specific tools may or may not understand a particular section. Sections are TLV's: (tag, length, value) tuples. Specific tools can skip or copy sections without needing to know anything about the data therein.

File Format

Octet offset	Data
0x0	Endian bit (0x80), File Version, 7 bits (0x1...0x7F)
0x1	Unused, 8 bits
0x2-0x3	Number of sections (16 bits) (NSECTIONS)
0x4	File date (32-bits) (POSIX "epoch" format)
0x8	Type of first section (32 bits)
0xC	Length of first section (32 bits), not including type and length
0x10	First section data
NSECTIONS-1, or up to 64K-2 additional sections
...	Type of next section (32 bits)
...	Length of next section (32 bits)
...	Next section data

File format notes

1. When set, the endian bit (0x80 of the first octet of the file) means that data throughout the file is in little endian byte order. Tools SHOULD support little-endian data but may not. Tools MUST either support little-endian data or announce that they do not.
2. The [historical] Gist event-log format is easily distinguished from this format. Gist event-logs are big-endian; the first 4 octets of the file contain the number of events in the file. Therefore, Gist event-logs containing less than 2**24 [?16 million] events will always appear to have a CPEL version of zero. Due to TFTP-server limitations, one strongly suspects that all extant Gist event-logs contain less than 2**24 events.
3. Sections may appear in any order

Section Formats

CPEL files are intended to stand alone, meaning that one should not need to preserve event definition header files, remember CPU clock rates, and so forth to use the data later. In addition to beefing up the event section type, we define additional section types to enable additional functions in the G2 graphical event viewer.

String Table Section - Section Type 1

String table sections concatenate NULL terminated strings and (possibly) arbitrary binary data. The first string in a string table is the table s name. Event definition and event sections refer to strings in a string section by offset from the base of the section.

String table sections MUST be padded to a 4-octet boundary by the addition of 1-3 NULL bytes, as needed.

Tools, particularly visualization tools such as the g2 event viewer MUST support multiple string sections. Tools MAY choose to combine string tables.

Symbol Table Section - Section Type 2

Symbol table sections allow tools to translate arbitrary hexadecimal values into function+offset format. Symbol table sections MUST be numerically sorted by the value field. The section data portion of a symbol table section has the following format:

 struct symbol_section_header {
 	char string_table_name[64];
 	unsigned long number_of_symbols;
 };

 struct symbol_section_entry {
 	 	unsigned long value;
 	unsigned long name_offset_in_string_table;
 };
   

See the next section for a usage description.

Event Definition Section - Section Type 3

Event definition sections provide display and formatting information for events found in event sections. The section data portion of an event definition section has the following format:

 struct event_definition_section_header {
     char string_table_name[64];
     unsigned long number_of_event_definitions;
 };

 struct event_definition_entry {
     unsigned long event_code;
     unsigned long event_format_offset_in_string_table;
     unsigned long datum_format_offset_in_string_table;
 };

These definitions generalize the stylized header-file definition scheme a bit by completely decoupling event formatting from datum formatting.

String sections enable visualization and reporting tools to neatly represent text events [e.g. syslog strings]. Symbol table sections function likewise when reporting hexadecimal data in routine+offset format.

Visualization tools SHOULD interpret the following printf-like (sub)strings as described: