wiki:802.11/wlan_exp/log

Version 2 (modified by murphpo, 8 years ago) (diff)

--

The 802.11 Reference Design integrates a logging system which can record details of nearly any event that occurs at the node. This system is designed to support MAC and PHY experiments that require a more detailed view of the node's operation than aggregate Tx/Rx statistics.

The logging framework is flexible, designed to record log entries of arbirtary 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. Users can define additional log entry types or modify existing types to support their experiment.

Log Storage

The log is stored in a pre-allocated region of DRAM in each WARP v3 node. As of 802.11 Reference Design v0.9 each node dedicates ~960 MB of DRAM for log storage. The remaining DRAM is set aside for the Tx packet queue and user scratch space.

The logging system enforces a few conventions on its DRAM allocation:

  • The first byte of the log space will always be the first byte of a log entry header (see below). Even when wrapping is enabled individual log entries will always be continuous in DRAM, starting at the beginning of the log DRAM space.
  • The logging system will never truncate a log entry at the end of the DRAM. The logging code remembers the index of the last byte of the last log entry written (called the "soft end" in code).

Indexing

The logging system maintains 3 indexing values:

  • Oldest Address: the address of the first byte of the log entry header for the oldest complete log entry currently in DRAM
  • Next Address: the address where the next log entry will be written, when requested by MAC code
  • Num Wraps""": the number of times the log has wrapped since last reset (see below for more on wrapping)

These indexes are used the logging system to track where new log entries should be written. They are also provided to user code to facilitate retrieval of log data. User code can request these indexes at any time to determine how much new log data should be retrieved.

Important: the logging code does not maintain any state about log retrieval. This is by design. The logging code does not care when users retrieve log data or how many simultaneous log consumers are accessing the same log data. Each log retrieval request includes a byte address and length. The logging code fulfills these requests, then purges all state related to the retrieval. This design enables multiple consumers to retrieve and process log data without burdening the node with tracking state for each consumer.

The 802.11 Reference Design wlan_exp_log Python framework implements suitable methods to track log write indexes and retrieve log data.

Wrapping

For many experiments the pre-allocated DRAM space will suffice to record the full log. However for long experiments the log may reach the end of the DRAM allocation. The logging system implements wrapping which, if enabled, will begin overwriting the oldest log entries as new log entries are created. Wrapping enables experiments to run non-stop for very long periods

Log Entry Format

Each log entry consists of two parts:

  • Log entry header: 8-byte header composed of four fields described below. The header format is defined in the entry_header struct in wlan_mac_event_log.h.
    • Delimiter (2 bytes): a "magic" value defined by the logging system to sanity-check log entries during retrieval and parsing
    • Sequence number (2 bytes): an auto-incremented value inserted by the logging code. This should only be used for sanity-checking log contents, as the 16-bit value will definitely wrap in long logs
    • Entry type ID (2 bytes): User-supplied entry type ID. The value 0 is reserved - all other values are valid.
    • Entry length (2 bytes): Length of user-supplied log data, in bytes. Must be in [0, 65535], inclusive.
  • Log data: log data supplied by the application. The logging system performs no processing of log data - user code must enforce whatever structure is required by the application.

An example of the log memory layout is illustrated below.

The 8-byte log entry headers are shown in blue. In this example there are 3 user-defined log entry types: TYPE_ID_RED, TYPE_ID_GREEN, TYPE_ID_YLW.