ralink/rt2x00/rt2x00dump.h

0001 /* SPDX-License-Identifier: GPL-2.0-or-later */
0002 /*
0003     Copyright (C) 2004 - 2009 Ivo van Doorn <IvDoorn@gmail.com>
0004     <http://rt2x00.serialmonkey.com>
0005
0006  */
0007
0008 /*
0009     Module: rt2x00dump
0010     Abstract:
0011         Data structures for the rt2x00debug & userspace.
0012
0013         The declarations in this file can be used by both rt2x00
0014         and userspace and therefore should be kept together in
0015         this file.
0016  */
0017
0018 #ifndef RT2X00DUMP_H
0019 #define RT2X00DUMP_H
0020
0021 /**
0022  * DOC: Introduction
0023  *
0024  * This header is intended to be exported to userspace,
0025  * to make the structures and enumerations available to userspace
0026  * applications. This means that all data types should be exportable.
0027  *
0028  * When rt2x00 is compiled with debugfs support enabled,
0029  * it is possible to capture all data coming in and out of the device
0030  * by reading the frame dump file. This file can have only a single reader.
0031  * The following frames will be reported:
0032  *   - All incoming frames (rx)
0033  *   - All outgoing frames (tx, including beacon and atim)
0034  *   - All completed frames (txdone including atim)
0035  *
0036  * The data is send to the file using the following format:
0037  *
0038  *   [rt2x00dump header][hardware descriptor][ieee802.11 frame]
0039  *
0040  * rt2x00dump header: The description of the dumped frame, as well as
0041  *  additional information useful for debugging. See &rt2x00dump_hdr.
0042  * hardware descriptor: Descriptor that was used to receive or transmit
0043  *  the frame.
0044  * ieee802.11 frame: The actual frame that was received or transmitted.
0045  */
0046
0047 /**
0048  * enum rt2x00_dump_type - Frame type
0049  *
0050  * These values are used for the @type member of &rt2x00dump_hdr.
0051  * @DUMP_FRAME_RXDONE: This frame has been received by the hardware.
0052  * @DUMP_FRAME_TX: This frame is queued for transmission to the hardware.
0053  * @DUMP_FRAME_TXDONE: This frame indicates the device has handled
0054  *  the tx event which has either succeeded or failed. A frame
0055  *  with this type should also have been reported with as a
0056  *  %DUMP_FRAME_TX frame.
0057  * @DUMP_FRAME_BEACON: This beacon frame is queued for transmission to the
0058  *  hardware.
0059  */
0060 enum rt2x00_dump_type {
0061     DUMP_FRAME_RXDONE = 1,
0062     DUMP_FRAME_TX = 2,
0063     DUMP_FRAME_TXDONE = 3,
0064     DUMP_FRAME_BEACON = 4,
0065 };
0066
0067 /**
0068  * struct rt2x00dump_hdr - Dump frame header
0069  *
0070  * Each frame dumped to the debugfs file starts with this header
0071  * attached. This header contains the description of the actual
0072  * frame which was dumped.
0073  *
0074  * New fields inside the structure must be appended to the end of
0075  * the structure. This way userspace tools compiled for earlier
0076  * header versions can still correctly handle the frame dump
0077  * (although they will not handle all data passed to them in the dump).
0078  *
0079  * @version: Header version should always be set to %DUMP_HEADER_VERSION.
0080  *  This field must be checked by userspace to determine if it can
0081  *  handle this frame.
0082  * @header_length: The length of the &rt2x00dump_hdr structure. This is
0083  *  used for compatibility reasons so userspace can easily determine
0084  *  the location of the next field in the dump.
0085  * @desc_length: The length of the device descriptor.
0086  * @data_length: The length of the frame data (including the ieee802.11 header.
0087  * @chip_rt: RT chipset
0088  * @chip_rf: RF chipset
0089  * @chip_rev: Chipset revision
0090  * @type: The frame type (&rt2x00_dump_type)
0091  * @queue_index: The index number of the data queue.
0092  * @entry_index: The index number of the entry inside the data queue.
0093  * @timestamp_sec: Timestamp - seconds
0094  * @timestamp_usec: Timestamp - microseconds
0095  */
0096 struct rt2x00dump_hdr {
0097     __le32 version;
0098 #define DUMP_HEADER_VERSION 3
0099
0100     __le32 header_length;
0101     __le32 desc_length;
0102     __le32 data_length;
0103
0104     __le16 chip_rt;
0105     __le16 chip_rf;
0106     __le16 chip_rev;
0107
0108     __le16 type;
0109     __u8 queue_index;
0110     __u8 entry_index;
0111
0112     __le32 timestamp_sec;
0113     __le32 timestamp_usec;
0114 };
0115
0116 #endif /* RT2X00DUMP_H */