+++ /dev/null
-Copyright (C) ST-Ericsson AB 2010
-Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
-License terms: GNU General Public License (GPL) version 2
----------------------------------------------------------
-
-=== Start ===
-If you have compiled CAIF for modules do:
-
-$modprobe crc_ccitt
-$modprobe caif
-$modprobe caif_socket
-$modprobe chnl_net
-
-
-=== Preparing the setup with a STE modem ===
-
-If you are working on integration of CAIF you should make sure
-that the kernel is built with module support.
-
-There are some things that need to be tweaked to get the host TTY correctly
-set up to talk to the modem.
-Since the CAIF stack is running in the kernel and we want to use the existing
-TTY, we are installing our physical serial driver as a line discipline above
-the TTY device.
-
-To achieve this we need to install the N_CAIF ldisc from user space.
-The benefit is that we can hook up to any TTY.
-
-The use of Start-of-frame-extension (STX) must also be set as
-module parameter "ser_use_stx".
-
-Normally Frame Checksum is always used on UART, but this is also provided as a
-module parameter "ser_use_fcs".
-
-$ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
-$ ifconfig caif_ttyS0 up
-
-PLEASE NOTE: There is a limitation in Android shell.
- It only accepts one argument to insmod/modprobe!
-
-=== Trouble shooting ===
-
-There are debugfs parameters provided for serial communication.
-/sys/kernel/debug/caif_serial/<tty-name>/
-
-* ser_state: Prints the bit-mask status where
- - 0x02 means SENDING, this is a transient state.
- - 0x10 means FLOW_OFF_SENT, i.e. the previous frame has not been sent
- and is blocking further send operation. Flow OFF has been propagated
- to all CAIF Channels using this TTY.
-
-* tty_status: Prints the bit-mask tty status information
- - 0x01 - tty->warned is on.
- - 0x02 - tty->low_latency is on.
- - 0x04 - tty->packed is on.
- - 0x08 - tty->flow_stopped is on.
- - 0x10 - tty->hw_stopped is on.
- - 0x20 - tty->stopped is on.
-
-* last_tx_msg: Binary blob Prints the last transmitted frame.
- This can be printed with
- $od --format=x1 /sys/kernel/debug/caif_serial/<tty>/last_rx_msg.
- The first two tx messages sent look like this. Note: The initial
- byte 02 is start of frame extension (STX) used for re-syncing
- upon errors.
-
- - Enumeration:
- 0000000 02 05 00 00 03 01 d2 02
- | | | | | |
- STX(1) | | | |
- Length(2)| | |
- Control Channel(1)
- Command:Enumeration(1)
- Link-ID(1)
- Checksum(2)
- - Channel Setup:
- 0000000 02 07 00 00 00 21 a1 00 48 df
- | | | | | | | |
- STX(1) | | | | | |
- Length(2)| | | | |
- Control Channel(1)
- Command:Channel Setup(1)
- Channel Type(1)
- Priority and Link-ID(1)
- Endpoint(1)
- Checksum(2)
-
-* last_rx_msg: Prints the last transmitted frame.
- The RX messages for LinkSetup look almost identical but they have the
- bit 0x20 set in the command bit, and Channel Setup has added one byte
- before Checksum containing Channel ID.
- NOTE: Several CAIF Messages might be concatenated. The maximum debug
- buffer size is 128 bytes.
-
-== Error Scenarios:
-- last_tx_msg contains channel setup message and last_rx_msg is empty ->
- The host seems to be able to send over the UART, at least the CAIF ldisc get
- notified that sending is completed.
-
-- last_tx_msg contains enumeration message and last_rx_msg is empty ->
- The host is not able to send the message from UART, the tty has not been
- able to complete the transmit operation.
-
-- if /sys/kernel/debug/caif_serial/<tty>/tty_status is non-zero there
- might be problems transmitting over UART.
- E.g. host and modem wiring is not correct you will typically see
- tty_status = 0x10 (hw_stopped) and ser_state = 0x10 (FLOW_OFF_SENT).
- You will probably see the enumeration message in last_tx_message
- and empty last_rx_message.
--- /dev/null
+:orphan:
+
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+
+================
+Using Linux CAIF
+================
+
+
+:Copyright: |copy| ST-Ericsson AB 2010
+
+:Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
+
+Start
+=====
+
+If you have compiled CAIF for modules do::
+
+ $modprobe crc_ccitt
+ $modprobe caif
+ $modprobe caif_socket
+ $modprobe chnl_net
+
+
+Preparing the setup with a STE modem
+====================================
+
+If you are working on integration of CAIF you should make sure
+that the kernel is built with module support.
+
+There are some things that need to be tweaked to get the host TTY correctly
+set up to talk to the modem.
+Since the CAIF stack is running in the kernel and we want to use the existing
+TTY, we are installing our physical serial driver as a line discipline above
+the TTY device.
+
+To achieve this we need to install the N_CAIF ldisc from user space.
+The benefit is that we can hook up to any TTY.
+
+The use of Start-of-frame-extension (STX) must also be set as
+module parameter "ser_use_stx".
+
+Normally Frame Checksum is always used on UART, but this is also provided as a
+module parameter "ser_use_fcs".
+
+::
+
+ $ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
+ $ ifconfig caif_ttyS0 up
+
+PLEASE NOTE:
+ There is a limitation in Android shell.
+ It only accepts one argument to insmod/modprobe!
+
+Trouble shooting
+================
+
+There are debugfs parameters provided for serial communication.
+/sys/kernel/debug/caif_serial/<tty-name>/
+
+* ser_state: Prints the bit-mask status where
+
+ - 0x02 means SENDING, this is a transient state.
+ - 0x10 means FLOW_OFF_SENT, i.e. the previous frame has not been sent
+ and is blocking further send operation. Flow OFF has been propagated
+ to all CAIF Channels using this TTY.
+
+* tty_status: Prints the bit-mask tty status information
+
+ - 0x01 - tty->warned is on.
+ - 0x02 - tty->low_latency is on.
+ - 0x04 - tty->packed is on.
+ - 0x08 - tty->flow_stopped is on.
+ - 0x10 - tty->hw_stopped is on.
+ - 0x20 - tty->stopped is on.
+
+* last_tx_msg: Binary blob Prints the last transmitted frame.
+
+ This can be printed with::
+
+ $od --format=x1 /sys/kernel/debug/caif_serial/<tty>/last_rx_msg.
+
+ The first two tx messages sent look like this. Note: The initial
+ byte 02 is start of frame extension (STX) used for re-syncing
+ upon errors.
+
+ - Enumeration::
+
+ 0000000 02 05 00 00 03 01 d2 02
+ | | | | | |
+ STX(1) | | | |
+ Length(2)| | |
+ Control Channel(1)
+ Command:Enumeration(1)
+ Link-ID(1)
+ Checksum(2)
+
+ - Channel Setup::
+
+ 0000000 02 07 00 00 00 21 a1 00 48 df
+ | | | | | | | |
+ STX(1) | | | | | |
+ Length(2)| | | | |
+ Control Channel(1)
+ Command:Channel Setup(1)
+ Channel Type(1)
+ Priority and Link-ID(1)
+ Endpoint(1)
+ Checksum(2)
+
+* last_rx_msg: Prints the last transmitted frame.
+
+ The RX messages for LinkSetup look almost identical but they have the
+ bit 0x20 set in the command bit, and Channel Setup has added one byte
+ before Checksum containing Channel ID.
+
+ NOTE:
+ Several CAIF Messages might be concatenated. The maximum debug
+ buffer size is 128 bytes.
+
+Error Scenarios
+===============
+
+- last_tx_msg contains channel setup message and last_rx_msg is empty ->
+ The host seems to be able to send over the UART, at least the CAIF ldisc get
+ notified that sending is completed.
+
+- last_tx_msg contains enumeration message and last_rx_msg is empty ->
+ The host is not able to send the message from UART, the tty has not been
+ able to complete the transmit operation.
+
+- if /sys/kernel/debug/caif_serial/<tty>/tty_status is non-zero there
+ might be problems transmitting over UART.
+
+ E.g. host and modem wiring is not correct you will typically see
+ tty_status = 0x10 (hw_stopped) and ser_state = 0x10 (FLOW_OFF_SENT).
+
+ You will probably see the enumeration message in last_tx_message
+ and empty last_rx_message.
+++ /dev/null
-mac80211_hwsim - software simulator of 802.11 radio(s) for mac80211
-Copyright (c) 2008, Jouni Malinen <j@w1.fi>
-
-This program is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License version 2 as
-published by the Free Software Foundation.
-
-
-Introduction
-
-mac80211_hwsim is a Linux kernel module that can be used to simulate
-arbitrary number of IEEE 802.11 radios for mac80211. It can be used to
-test most of the mac80211 functionality and user space tools (e.g.,
-hostapd and wpa_supplicant) in a way that matches very closely with
-the normal case of using real WLAN hardware. From the mac80211 view
-point, mac80211_hwsim is yet another hardware driver, i.e., no changes
-to mac80211 are needed to use this testing tool.
-
-The main goal for mac80211_hwsim is to make it easier for developers
-to test their code and work with new features to mac80211, hostapd,
-and wpa_supplicant. The simulated radios do not have the limitations
-of real hardware, so it is easy to generate an arbitrary test setup
-and always reproduce the same setup for future tests. In addition,
-since all radio operation is simulated, any channel can be used in
-tests regardless of regulatory rules.
-
-mac80211_hwsim kernel module has a parameter 'radios' that can be used
-to select how many radios are simulated (default 2). This allows
-configuration of both very simply setups (e.g., just a single access
-point and a station) or large scale tests (multiple access points with
-hundreds of stations).
-
-mac80211_hwsim works by tracking the current channel of each virtual
-radio and copying all transmitted frames to all other radios that are
-currently enabled and on the same channel as the transmitting
-radio. Software encryption in mac80211 is used so that the frames are
-actually encrypted over the virtual air interface to allow more
-complete testing of encryption.
-
-A global monitoring netdev, hwsim#, is created independent of
-mac80211. This interface can be used to monitor all transmitted frames
-regardless of channel.
-
-
-Simple example
-
-This example shows how to use mac80211_hwsim to simulate two radios:
-one to act as an access point and the other as a station that
-associates with the AP. hostapd and wpa_supplicant are used to take
-care of WPA2-PSK authentication. In addition, hostapd is also
-processing access point side of association.
-
-
-# Build mac80211_hwsim as part of kernel configuration
-
-# Load the module
-modprobe mac80211_hwsim
-
-# Run hostapd (AP) for wlan0
-hostapd hostapd.conf
-
-# Run wpa_supplicant (station) for wlan1
-wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf
-
-
-More test cases are available in hostap.git:
-git://w1.fi/srv/git/hostap.git and mac80211_hwsim/tests subdirectory
-(http://w1.fi/gitweb/gitweb.cgi?p=hostap.git;a=tree;f=mac80211_hwsim/tests)
--- /dev/null
+:orphan:
+
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===================================================================
+mac80211_hwsim - software simulator of 802.11 radio(s) for mac80211
+===================================================================
+
+:Copyright: |copy| 2008, Jouni Malinen <j@w1.fi>
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License version 2 as
+published by the Free Software Foundation.
+
+
+Introduction
+============
+
+mac80211_hwsim is a Linux kernel module that can be used to simulate
+arbitrary number of IEEE 802.11 radios for mac80211. It can be used to
+test most of the mac80211 functionality and user space tools (e.g.,
+hostapd and wpa_supplicant) in a way that matches very closely with
+the normal case of using real WLAN hardware. From the mac80211 view
+point, mac80211_hwsim is yet another hardware driver, i.e., no changes
+to mac80211 are needed to use this testing tool.
+
+The main goal for mac80211_hwsim is to make it easier for developers
+to test their code and work with new features to mac80211, hostapd,
+and wpa_supplicant. The simulated radios do not have the limitations
+of real hardware, so it is easy to generate an arbitrary test setup
+and always reproduce the same setup for future tests. In addition,
+since all radio operation is simulated, any channel can be used in
+tests regardless of regulatory rules.
+
+mac80211_hwsim kernel module has a parameter 'radios' that can be used
+to select how many radios are simulated (default 2). This allows
+configuration of both very simply setups (e.g., just a single access
+point and a station) or large scale tests (multiple access points with
+hundreds of stations).
+
+mac80211_hwsim works by tracking the current channel of each virtual
+radio and copying all transmitted frames to all other radios that are
+currently enabled and on the same channel as the transmitting
+radio. Software encryption in mac80211 is used so that the frames are
+actually encrypted over the virtual air interface to allow more
+complete testing of encryption.
+
+A global monitoring netdev, hwsim#, is created independent of
+mac80211. This interface can be used to monitor all transmitted frames
+regardless of channel.
+
+
+Simple example
+==============
+
+This example shows how to use mac80211_hwsim to simulate two radios:
+one to act as an access point and the other as a station that
+associates with the AP. hostapd and wpa_supplicant are used to take
+care of WPA2-PSK authentication. In addition, hostapd is also
+processing access point side of association.
+
+::
+
+
+ # Build mac80211_hwsim as part of kernel configuration
+
+ # Load the module
+ modprobe mac80211_hwsim
+
+ # Run hostapd (AP) for wlan0
+ hostapd hostapd.conf
+
+ # Run wpa_supplicant (station) for wlan1
+ wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf
+
+
+More test cases are available in hostap.git:
+git://w1.fi/srv/git/hostap.git and mac80211_hwsim/tests subdirectory
+(http://w1.fi/gitweb/gitweb.cgi?p=hostap.git;a=tree;f=mac80211_hwsim/tests)
F: include/net/mac80211.h
F: net/mac80211/
F: drivers/net/wireless/mac80211_hwsim.[ch]
-F: Documentation/networking/mac80211_hwsim/README
+F: Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
MAILBOX API
M: Jassi Brar <jassisinghbrar@gmail.com>