Changes between Initial Version and Version 1 of 802.11/wlan_exp/Extending

Timestamp:

Dec 14, 2015, 12:20:45 PM (8 years ago)

Author:

murphpo

Comment:

--

802.11/wlan_exp/Extending

@@ +1 @@
+{{{#!comment
+[[Include(wiki:802.11/beta-note)]]
+}}}
+
+[[TracNav(802.11/TOC)]]
+
+= Extending the Experiments Framework =
+
+The 802.11 Reference Design Experiments Framework provides a variety of commands to control and observe WARP v3 nodes in real time. However many experiments will require additional commands, especially when users extend the reference code with new behaviors. Starting in 802.11 Reference Design v1.4 we have greatly simplified the process of implementing extensions to the experiments framework.
+
+There are two kinds of framework extensions:
+ * '''User Commands''': commands interact with the MAC High Framework and the upper-level MAC running in CPU High
+ * '''Low Params''': a write-only path for setting parameters in the MAC Low Framework and the lower-level MAC running in CPU Low
+
+== User Commands ==
+
+The 802.11 MAC code running on the WARP node handles user commands at two levels.
+
+If the command behavior is common to all MAC applications, the command is handled in the {{{process_user_cmd()}}} function in {{{wlan_exp_user.c}}}. You should modify {{{process_user_cmd()}}} to handle any new framework-level commands required for your application. Any command IDs not hanlded in {{{process_user_cmd()}}} will be passed through to the MAC application.
+
+If a command behavior depends on the upper-level MAC application, the command is handled in the {{{wlan_exp_process_user_cmd()}}} callback function in the top-level MAC. You should modify the {{{wlan_exp_process_user_cmd()}}} function in the {{{wlan_mac_ap.c}}}, {{{wlan_mac_sta.c}}} and {{{wlan_mac_ibss.c}}} files to implement any MAC-specific command behaviors.
+
+A user command consists of the following elements:
+ * Command ID: an arbitrary 24-bit integer defined in the Python and C code
+ * Command arguments: an optional list of arguments supplied by the Python code that is passed to the C code handler. Each argument must be an unsigned 32-bit integer. Python and C can reinterpret the {{{u32}}} values as needed.
+
+
+=== Example Command: Reading Tx Queue Status ===
+
+{{{my_node}}} is an instance of a wlan_exp node object that has already been initialized. 
+
+{{{#!python
+
+#Define a command ID (must be integer in [0, 65535])
+CMDID_USER_TX_QUEUE_STATUS = 100
+
+my_node.send_user_command(CMDID_USR_QUEUE_STATUS, args=None)
+
+}}}
+
+
+Each upper-level MAC application implements its own callback function for handling application-specific user commands. By default these functions are empty. You must modify the C code to implement the behaviors required for your custom command.
+
+In this example the custom command will query the lengths of Tx queues. 
+Modify the {{{wlan_exp_user_ap_process_cmd()}}} function in {{{wlan_mac_ap.c}}}.
+{{{#!c
+
+
+}}}
+
+
+== Low Params ==
+The User Command flow described above is can configure and reading state in CPU High. Some applications will also require interacting with CPU Low.