On Wed, Nov 9 2016, 06:00 PM, Greg KH wrote:

On Wed, Nov 09, 2016 at 04:20:07PM +0200, Amir Levy wrote:

quoted

Adding Thunderbolt(TM) networking documentation.

Signed-off-by: Amir Levy <redacted>
---
 Documentation/00-INDEX                   |   2 +
 Documentation/thunderbolt/networking.txt | 132
+++++++++++++++++++++++++++++++

Note, new files should be in .rst format, and live in the new subdirectory for
them (somewhere in Documentation, don't know off the top of my head...)

quoted

 2 files changed, 134 insertions(+)
 create mode 100644 Documentation/thunderbolt/networking.txt

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index

3acc4f1..0239e68 100644

--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX

@@ -440,6 +440,8 @@ this_cpu_ops.txt
 	- List rationale behind and the way to use this_cpu operations.
 thermal/
 	- directory with information on managing thermal issues (CPU/temp)
+thunderbolt/
+	- directory with info regarding Thunderbolt.
 trace/
 	- directory with info on tracing technologies within linux

unaligned-memory-access.txt

This change is probably not needed.

quoted

diff --git a/Documentation/thunderbolt/networking.txt

b/Documentation/thunderbolt/networking.txt
new file mode 100644
index 0000000..88d1c12

--- /dev/null
+++ b/Documentation/thunderbolt/networking.txt

@@ -0,0 +1,132 @@
+Intel Thunderbolt(TM) Networking driver
+=======================================
+
+Copyright(c) 2013 - 2016 Intel Corporation.
+
+Contact Information:
+Intel Thunderbolt mailing list <thunderbolt-software@lists.01.org>
+Edited by Amir Levy <amir.jer.levy@intel.com>
+
+Overview
+========
+
+* The Thunderbolt Networking driver enables peer to peer networking
+on non-Apple
+  platforms running Linux.
+
+* The driver creates a virtual Ethernet device that enables computer
+to computer
+  communication over the Thunderbolt cable.
+
+* Using Thunderbolt Networking you can perform high speed file
+transfers between
+  computers, perform PC migrations and/or set up small workgroups
+with shared
+  storage without compromising any other Thunderbolt functionality.
+
+* The driver is located in drivers/thunderbolt/icm.
+
+* This driver will function only on non-Apple platforms with firmware
+based
+  Thunderbolt controllers that support Thunderbolt Networking.
+
+  +----------------+            +----------------+
+  |Host 1          |            |Host 2          |
+  |                |            |                |
+  |   +-------+    |            |    +-------+   |
+  |   |Network|    |            |    |Network|   |
+  |   |Stack  |    |            |    |Stack  |   |
+  |   +-------+    |            |    +-------+   |
+  |       ^        |            |        ^       |
+  |       |        |            |        |       |
+  |       v        |            |        v       |
+  | +-----------+  |            |  +-----------+ |
+  | |Thunderbolt|  |            |  |Thunderbolt| |
+  | |Networking |  |            |  |Networking | |
+  | |Driver     |  |            |  |Driver     | |
+  | +-----------+  |            |  +-----------+ |
+  |       ^        |            |        ^       |
+  |       |        |            |        |       |
+  |       v        |            |        v       |
+  | +-----------+  |            |  +-----------+ |
+  | |Thunderbolt|  |            |  |Thunderbolt| |
+  | |Controller |<-+------------+->|Controller | |
+  | |with ICM   |  |            |  |with ICM   | |
+  | |enabled    |  |            |  |enabled    | |
+  | +-----------+  |            |  +-----------+ |
+  +----------------+            +----------------+
+
+Files
+=====
+
+The following files are located in the drivers/thunderbolt/icm directory:
+
+- icm_nhi.c/h:	These files allow communication with the firmware

(Intel

quoted

+  Connection Manager) based controller. They also create an interface
+for
+  netlink communication with a user space daemon.
+
+- net.c/net.h:	These files implement the 'eth' interface for the
+  Thunderbolt(TM) Networking.

You don't have to list the files, right?

quoted

+
+Interface to User Space
+=======================
+
+The interface to the user space module is implemented through a Generic

Netlink.

Huh?  Not a normal network device?

quoted

+This is the communications protocol between the Thunderbolt driver
+and the user space application.

What userspace application?

quoted

+Note that this interface mediates user space communication with ICM.

What is ICM?

quoted

+(Existing Linux tools can be used to configure the network
+interface.)

Why aren't they sufficient for everything here?

quoted

+
+The Thunderbolt Daemon utilizes this interface to communicate with the

driver.

What "Thunderbolt Daemon"?  What is "this"?

quoted

+To be accessed by the user space module, both kernel and user space
+modules have to register with the same GENL_NAME.

What userspace modules?

How do you set GENL_NAME?  What is that?

quoted

+For the purpose of the Thunderbolt Network driver, "thunderbolt" is

used.

What do you mean?

quoted

+The registration is done at driver initialization time for all
+instances of the Thunderbolt controllers.

Who does this?

quoted

The communication is carried through pre-defined
+Thunderbolt messages. Each specific message has a callback function
+that is called when the related message is received.

Is this the internal structure of the driver?  If so, why not just put it all in the
code itself and build the documentation from it?

quoted

+
+Message Definitions:
+* NHI_CMD_UNSPEC: Not used.
+* NHI_CMD_SUBSCRIBE: Subscription request from daemon to driver to
+open the
+  communication channel.
+* NHI_CMD_UNSUBSCRIBE: Request from daemon to driver to

unsubscribe

quoted

+and
+  to close communication channel.
+* NHI_CMD_QUERY_INFORMATION: Request information from the driver

such

quoted

+as
+  driver version, FW version offset, number of ports in the
+controller
+  and DMA port.
+* NHI_CMD_MSG_TO_ICM: Message from user space module to FW.
+* NHI_CMD_MSG_FROM_ICM: Response from FW to user space module.
+* NHI_CMD_MAILBOX: Message that uses mailbox mechanism such as

FW

quoted

+policy
+  changes or disconnect path.
+* NHI_CMD_APPROVE_TBT_NETWORKING: Request from user space

module to

quoted

+FW to
+  establish path.
+* NHI_CMD_ICM_IN_SAFE_MODE: Indication that the FW has entered

safe mode.

quoted

+
+Communication with Intel Connection Manager(ICM) Firmware

+=========================================================

quoted

+
+There are several circular buffers in Thunderbolt each using Direct
+Memory Access (DMA).

Again, internal documentation?

Isn't this just a "normal" network device?  Why document any of this in a
separate way?  What can a user do with this?  Who is the audience of this
file?

still confused,

greg k-h

This document was one of the suggestions we got from internal-Intel kernel developers.
If you think it isn't needed, I'll remove it from next patch set.