{{{#!comment
[[Include(wiki:802.11/beta-note)]]
}}}

[[TracNav(802.11/TOC)]]

= 802.11 Reference Design:  Event Log Entry Types = 

The 802.11 Reference Design logging framework is designed to record log entries of arbitrary length and type. The MAC code in CPU High is responsible for defining the log entry types and populating each log entry at run time.

The reference code for CPU High defines a number of useful log entry types and implements logging of many run time events, including all Tx and Rx activity. The entry types defined in the reference implementation are listed below.

Users can define new log entry types or modify existing types to support their experiment. The requirements for this are documented below.

== Reference Design Entry Types ==
The sections below document the log entry types defined in the latest 802.11 Reference Design C and Python code.

This listing is generated directly from the [source:/ReferenceDesigns/w3_802.11/python/wlan_exp/log/entry_types.py entry_types.py] file in the wlan_exp Python package. You can generate a text version of the entry type list with this code:
{{{#!python
from wlan_exp.log.entry_types import log_entry_types as log_entry_types

for tid in log_entry_types.keys():
    if(type(tid) is int and tid != 0): #only take int type IDs and skip NULL
        print(log_entry_types[tid].generate_entry_doc(fmt='txt'))
}}}


{{{#!comment
Note to selves:

The list of entry types is drawn directly from svn. To update the docs:
 1) Update the entry type description and entry field descriptions in wlan_exp/log/entry_types.py
 2) CD to wlan_exp/log/
 3) Run 'python gen_entry_type_wiki_docs.py > entry_type_wiki_docs.txt'
 4) svn commit the changes; the .py and .txt should always be committed together

}}}

----

[[Include(source:/ReferenceDesigns/w3_802.11/python/wlan_exp/log/entry_type_wiki_docs.txt,  text/x-trac-wiki)]]

{{{#!comment
###########
END of entry type list
###########
}}}



== Defining New Entry Types ==

New log entry formats can be defined to suit a research application. In order to both create log entries and process log data containing the entries, matching log entry type definitions must be added to both the C and Python code.

=== Entry Types in C ===
The wlan_exp C code impose simple requirements on log entry formats:
 * Each entry type must have a unique ID
 * Each use of the entry type should be a multiple of 4 bytes long (32-bit aligned at start and end)

By convention we use C struct definitions to describe the format of entry types. This isn't required, but is very convenient. The reference entry types are defined in [source:/ReferenceDesigns/w3_802.11/c/wlan_mac_high_framework/include/wlan_mac_entries.h wlan_mac_high_framework/include/wlan_mac_entries.h]. You can add additional types to this file or elsewhere in the C code. Always ensure new types use entry type IDs that do not conflict with the existing {{{#define ENTRY_TYPE_...}}} values in wlan_mac_entries.h.

After defining your entry type format, new log entries can be created with the {{{void* entry_ptr event_log_get_next_empty_entry( u16 entry_type, u16 entry_size )}}} function. This function returns a pointer to a memory location dedicated to the new log entry. The calling code must stay within the requested entry_size. This function may return NULL if the log entry cannot be created.

See below for an example custom log entry type.

=== Entry Types in Python ===
Log entry types are fully described in Python using instances of the {{{WlanExpLogEntryType}}} class. The reference log entry types are defined in the [source:/ReferenceDesigns/w3_802.11/python/wlan_exp/log/entry_types.py entry_types.py module]. You can add custom entry types to this file or elsewhere in your Python code. The {{{WlanExpLogEntryType}}} constructor will automatically add your custom types to the global dictionary of types.

Defining a new log entry type in Python requires two steps:
 1. Create an instance of the {{{WlanExpLogEntryType}}} with a unique ID and name:
{{{#!python
import wlan_exp.log.entry_types as entry_types
my_new_entry_type = entry_types.WlanExpLogEntryType(name='MY_NEW_ENTRY', entry_type_id=1001)
}}}
 2. Add field definitions which describe the log entry format:
{{{#!python
my_new_entry_type.append_field_defs([
            ('timestamp',      'Q',      'uint64',  'Microsecond timer value at time of log entry creation'),
            ('val_A',          'I',      'uint32',  'Data Value A'),
            ('val_B',          'I',      'uint32',  'Data Value B')])
}}}

The argument to the {{{append_field_defs}}} method must be a list of 4-tuples. Each 4-tuple must have the format {{{field_name, data_type_struct, data_type_np, description}}}, where:
 * {{{field_name}}}: A short string name for the field, preferably all lower case with only letters and underscores
 * {{{data_type_struct}}}: String specifying the format for the field using the [https://docs.python.org/2.7/library/struct.html#format-characters Python struct module format codes]
 * {{{data_type_np}}}: String specifying the format for the field using the [http://docs.scipy.org/doc/numpy/reference/arrays.scalars.html#arrays-scalars-built-in numpy dtype module format codes]
 * {{{description}}}: String describing the field, used when auto-generating documentation. Set to empty string ({{{''}}}) to ignore

Common values for the {{{data_type_struct}}} and {{{data_type_np}}} fields are listed below.

||=  C type  =||=  struct type  =||=  numpy type  =||
|| u8 / unsigned char || B || uint8 ||
|| u16 / unsigned short || H || uint16 ||
|| u32 / unsigned int || I || uint32 ||
|| u64 / unsigned long long || Q || uint64 ||
|| s8 / signed char || b || int8 ||
|| s16 / signed short || h || int16 ||
|| s32 / signed int || i || int32 ||