From e15d5a53ea3239e537d3a0c4bdfce8a4ea4e0da6 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:34 -0300 Subject: docs: net: convert two README files to ReST format There are two README files there with doesn't have a .txt extension nor are at ReST format. In order to help with the docs conversion to ReST, rename those and manually convert them to ReST format. As there are lot more to be done for networking to be part of the documentation body, for now mark those two files with :orphan:, in order to supress a build warning. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/networking/caif/README | 109 ---------------- Documentation/networking/caif/caif.rst | 141 +++++++++++++++++++++ Documentation/networking/mac80211_hwsim/README | 68 ---------- .../networking/mac80211_hwsim/mac80211_hwsim.rst | 80 ++++++++++++ MAINTAINERS | 2 +- 5 files changed, 222 insertions(+), 178 deletions(-) delete mode 100644 Documentation/networking/caif/README create mode 100644 Documentation/networking/caif/caif.rst delete mode 100644 Documentation/networking/mac80211_hwsim/README create mode 100644 Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst diff --git a/Documentation/networking/caif/README b/Documentation/networking/caif/README deleted file mode 100644 index 757ccfaa1385..000000000000 --- a/Documentation/networking/caif/README +++ /dev/null @@ -1,109 +0,0 @@ -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// - -* 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//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_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. diff --git a/Documentation/networking/caif/caif.rst b/Documentation/networking/caif/caif.rst new file mode 100644 index 000000000000..07afc8063d4d --- /dev/null +++ b/Documentation/networking/caif/caif.rst @@ -0,0 +1,141 @@ +:orphan: + +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + + +================ +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// + +* 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//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_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. diff --git a/Documentation/networking/mac80211_hwsim/README b/Documentation/networking/mac80211_hwsim/README deleted file mode 100644 index 3566a725d19c..000000000000 --- a/Documentation/networking/mac80211_hwsim/README +++ /dev/null @@ -1,68 +0,0 @@ -mac80211_hwsim - software simulator of 802.11 radio(s) for mac80211 -Copyright (c) 2008, Jouni Malinen - -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) diff --git a/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst b/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst new file mode 100644 index 000000000000..d2266ce5534e --- /dev/null +++ b/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst @@ -0,0 +1,80 @@ +:orphan: + +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +=================================================================== +mac80211_hwsim - software simulator of 802.11 radio(s) for mac80211 +=================================================================== + +:Copyright: |copy| 2008, Jouni Malinen + +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) diff --git a/MAINTAINERS b/MAINTAINERS index 6fa76e6a93cd..6de82f019a52 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -9578,7 +9578,7 @@ F: Documentation/networking/mac80211-injection.txt 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 -- cgit v1.2.3-70-g09d2