| | 42 | |
| | 43 | == Defining New Entry Types == |
| | 44 | |
| | 45 | 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. |
| | 46 | |
| | 47 | === Entry Types in C === |
| | 48 | The wlan_exp C code impose simple requirements on log entry formats: |
| | 49 | * Each entry type must have a unique ID |
| | 50 | * Each use of the entry type should be a multiple of 4 bytes long (32-bit aligned at start and end) |
| | 51 | |
| | 52 | 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. |
| | 53 | |
| | 54 | 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. |
| | 55 | |
| | 56 | See below for an example custom log entry type. |
| | 57 | |
| | 58 | === Entry Types in Python === |
| | 59 | 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. |
| | 60 | |
| | 61 | Defining a new log entry type in Python requires two steps: |
| | 62 | 1. Create an instance of the {{{WlanExpLogEntryType}}} with a unique ID and name: |
| | 63 | {{{import wlan_exp.log.entry_types as entry_types |
| | 64 | my_new_entry_type = entry_types.WlanExpLogEntryType(name='MY_NEW_ENTRY', entry_type_id=1001) |
| | 65 | }}} |
| | 66 | 2. Add field definitions which describe the log entry format: |
| | 67 | {{{ |
| | 68 | my_new_entry_type.append_field_defs([ |
| | 69 | ('timestamp', 'Q', 'uint64', 'Microsecond timer value at time of log entry creation'), |
| | 70 | ('val_A', 'I', 'uint32', 'Data Value A'), |
| | 71 | ('val_B', 'I', 'uint32', 'Data Value B')]) |
| | 72 | }}} |
| | 73 | |
| | 74 | 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: |
| | 75 | * {{{field_name}}}: A short string name for the field, preferably all lower case with only letters and underscores |
| | 76 | * {{{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] |
| | 77 | * {{{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] |
| | 78 | * {{{description}}}: String describing the field, used when auto-generating documentation. Set to empty string ({{{''}}}) to ignore |
| | 79 | |
| | 80 | Common values for the {{{data_type_struct}}} and {{{data_type_np}}} fields are listed below. |
| | 81 | |
| | 82 | ||= C type =||= struct type =||= numpy type =|| |
| | 83 | || u8 / unsigned char || B || uint8 || |
| | 84 | || u16 / unsigned short || H || uint16 || |
| | 85 | || u32 / unsigned int || I || uint32 || |
| | 86 | || u64 / unsigned long long || Q || uint64 || |
| | 87 | || s8 / signed char || b || int8 || |
| | 88 | || s16 / signed short || h || int16 || |
| | 89 | || s32 / signed int || i || int32 || |
| | 90 | |
| | 91 | === Custom Entry Type Example === |
