[hercules-390] How to query tuntap capabilities?

['\'Fish\' (David B. Trout)' [e-mail] [hercules-390]]

Hi folks!

Does anyone out there know how to query a tuntap device's capabilities?

I'm working on adding multicast and checksum offloading support to Hercules's LCS device handler (source member 'ctc_lcs.c's "LCS_QueryIPAssists" function), but before I set the bits in the response telling the guest (z/OS, z/VM, etc) that multicast is supported, or that inbound and/or outbound Checksum Offloading is supported, etc, I thought it would be a good idea to ask the actual tuntap device that Hercules was actually using whether or not it actually supported such capabilities. After all, I certainly don't want to lie to the guest and say something is supported when it actually isn't!

I've looked through Linux source code but was unable to make sense of it. Can anyone help me out? Or provide a clue or point me in the right direction? Or just explain it in detail or even better provide some example code that does it if you know how?

Thanks!

(This would be for Linux by the way. Once I know how it's done on Linux I would then code identical functionality in Windows CTCI-WIN so the Hercules code for either would be identical.)

[Ivan Warren [e-mail] [hercules-390]]

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]
Hi folks!
Does anyone out there know how to query a tuntap device's capabilities?
I'm working on adding multicast and checksum offloading support to Hercules's LCS device handler (source member 'ctc_lcs.c's "LCS_QueryIPAssists" function), but before I set the bits in the response telling the guest (z/OS, z/VM, etc) that multicast is supported, or that inbound and/or outbound Checksum Offloading is supported, etc, I thought it would be a good idea to ask the actual tuntap device that Hercules was actually using whether or not it actually supported such capabilities. After all, I certainly don't want to lie to the guest and say something is supported when it actually isn't!
I've looked through Linux source code but was unable to make sense of it. Can anyone help me out? Or provide a clue or point me in the right direction? Or just explain it in detail or even better provide some example code that does it if you know how?
Thanks!
(This would be for Linux by the way. Once I know how it's done on Linux I would then code identical functionality in Windows CTCI-WIN so the Hercules code for either would be identical.)

Hey Fish,

LCS already has multicast support ;)

I think Layer 2 tuntap (aka tap) always works in promiscuous mode...
That is, any Eth/802.3 frame sent to it from the network sink (Kernel
Network interface, Network Bridge, etc..) is always distributed to the
user program driving the tap. Furthermore, I don't think the tap does
any kind of modification to the frame whatsoever.

This means any unicast and or multicast filtering is done on the LCS
side (as it is done right now).

As far as any checksum offload is concerned, tap doesn't do any of
that... However, the LCS implementation can very well implement it on
its own (so that the burden of calculating checksums can be shifted from
the IP stack of the program running under hercules directly to hercules
using native host code)... At which point there would be very little or
no difference whether it is the LCS code or the TAP kernel code that
performs the checksum assists.

--Ivan



[Non-text portions of this message have been removed]

['Styma, Robert (Nokia - US/Phoenix)' [e-mail] [hercules-390]]

Post by Ivan Warren ***@vmfacility.fr [hercules-390]
Hey Fish,
LCS already has multicast support ;)
I think Layer 2 tuntap (aka tap) always works in promiscuous mode...
That is, any Eth/802.3 frame sent to it from the network sink (Kernel
Network interface, Network Bridge, etc..) >
This means any unicast and or multicast filtering is done on the LCS
side (as it is done right now).
As far as any checksum offload is concerned, tap doesn't do any of
that... However, the LCS implementation can very well implement it on
its own (so that the burden of calculating checksums can be shifted from
the IP stack of the program running under hercules directly to hercules
using native host code)... At which point there would be very little or
no difference whether it is the LCS code or the TAP kernel code that
performs the checksum assists.
--Ivan

Just as an FYI. I recently switched from CTCI to LCS on a CentOS 7 host using the various notes on the web. To get it to work required one piece of information that was hard to come by. Besides IP forwarding, proxy_arp had to be turned on:

echo 1 > /proc/sys/net/ipv4/conf/enp6s4f0/proxy_arp
echo 1 > /proc/sys/net/ipv4/conf/tap0/proxy_arp
Made it permanent in /etc/sysctl.conf
net.ipv4.ip_forward = 1
net.ipv4.conf.enp6s4f0.proxy_arp = 1
net.ipv4.conf.tap0.proxy_arp = 1

(enp6s4f0 is what CentOS 7 calls the NIC. They go away from easy names such as eth0)

Nice thing was that when /dev/net/tap0 got created on the fly after a restart, the proxy_arp was still set.
Hope this helps someone avoid the pain I went through.

For completeness this is from the herc.conf file:
0E20-0E21 LCS -n /dev/net/tun 192.168.200.200
Which is on the same subnet as the host machine NIC.

And this is from the TCP/IP Profile:
DEVICE LCS1 LCS E20
LINK ETH1 ETHERNET 0 LCS1
...

HOME
192.168.200.200 ETH1
...

GATEWAY
192.168.200.1 = ETH1 DEFAULTSIZE HOST
defaultnet 192.168.200.1 ETH1 1492 0


Bob S.

['\'Fish\' (David B. Trout)' [e-mail] [hercules-390]]

Robert Styma wrote:

[...]

Post by 'Styma, Robert (Nokia - US/Phoenix)' ***@nokia.com [hercules-390]
Just as an FYI. I recently switched from CTCI to LCS
on a CentOS 7 host using the various notes on the web.
To get it to work required one piece of information
that was hard to come by. Besides IP forwarding, proxy_arp

So what you're saying is you don't know how?

['Styma, Robert (Nokia - US/Phoenix)' [e-mail] [hercules-390]]

What I am saying is that since the other responders were suggesting switching from CTC to LCS, I would add a piece of information that I went through a lot of pain to get. When you are running LCS, the system behaves as though you have a real NIC connection which supports TCP and UDP without all the funny business.

Your original post indicated you were trying to do something with multicast. I do not know much about it. However, since LCS through the TAP interface acts like a real connection, it may be worth setting it up and seeing if it behaves as you desire. This may be simpler than trying to work out the capabilities.

On a Linux based host you can find out a lot about the TAP or TUN interface by looking in directory /proc/sys/net/ipv4/conf/tap0. Much of the configuration can be examined and set there. On a Windows host, there may be useful information in the device properties.

I was just trying to be helpful and pass along some information that I went through much pain to obtain.

[Harold Grovesteen [e-mail] [hercules-390]]

On Wed, 2017-05-17 at 14:04 +0000, 'Styma, Robert (Nokia - US/Phoenix)'

Post by 'Styma, Robert (Nokia - US/Phoenix)' ***@nokia.com [hercules-390]
I was just trying to be helpful and pass along some information that I
went through much pain to obtain.

That is a shame. The use of proxy ARP with TUN or TAP is not a secret.

But, it seems, though, when a user is having problems, getting the
networking sorted out is always painful. The variables of user
experience and the local environment seem to be too great to make it
less painful.

Harold Grovesteen

['\'Fish\' (David B. Trout)' [e-mail] [hercules-390]]

Post by 'Styma, Robert (Nokia - US/Phoenix)' ***@nokia.com [hercules-390]
What I am saying is that since the other responders were
suggesting switching from CTC to LCS, I would add a piece
of information that I went through a lot of pain to get.

<snip>

Yes, thank you. I'm sure others appreciate that helpful bit of unrelated information.

Unfortunately however, it does not help answer my primary question which is largely all I'm interested in. It's easy for these types of thread to drift off topic and end up being unintentionally hijacked for other purposes. I'm simply trying to prevent that. I hope you understand that just as I hope you understand no disrespect was intended by my previous reply or this reply either.

I'm just trying to keep this thread on topic.

Thanks.

['\'Fish\' (David B. Trout)' [e-mail] [hercules-390]]

[...]

Post by Ivan Warren ***@vmfacility.fr [hercules-390]

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]
Does anyone out there know how to query a tuntap device's
capabilities?

[...]

Post by Ivan Warren ***@vmfacility.fr [hercules-390]

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]
I thought it would be a good idea to ask the actual tuntap
device that Hercules was actually using whether or not it
actually supported such capabilities. After all, I certainly
don't want to lie to the guest and say something is supported
when it actually isn't!

[...]

Post by Ivan Warren ***@vmfacility.fr [hercules-390]
Hey Fish,
LCS already has multicast support ;)

So what you're saying is you don't know how?

[Ivan Warren [e-mail] [hercules-390]]

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]
So what you're saying is you don't know how?

No,

I'm saying it's irrelevant to the problem at hand.

--Ivan



[Non-text portions of this message have been removed]

['\'Fish\' (David B. Trout)' [e-mail] [hercules-390]]

Post by Ivan Warren ***@vmfacility.fr [hercules-390]

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]
So what you're saying is you don't know how?

No,
I'm saying it's irrelevant to the problem at hand.

I believe you may be laboring under the false presumption that the problem at hand is multicast support, which is untrue.

The problem at hand is precisely the question I posed on the subject line and as the first question of my original post (and is most certainly NOT irrelevant!):

How does one query a tuntap device (or more generally a network device) for its list of capabilities? (i.e. features)

I apologize if my initial mention of multicast support mislead you. In retrospect I probably shouldn't have even mentioned it.

Most (but not all) network devices today support certain features such as IPv4 and IPv6 Transmit and Receive TCP and UDP Checksum Offloading (not to mention other types of offloading such as Segmentation Offloading, sometimes referred to as Large Send Offload). I'm presuming a tuntap device on Linux is considered to be such a device (i.e. a network device).

I would like to query that device's capabilities. I would like to ask the device "Do you support <feature X>?" (or better, "What features do you support?").

How do I do that?

[Ivan Warren [e-mail] [hercules-390]]

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]

Post by Ivan Warren ***@vmfacility.fr [hercules-390]

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]
So what you're saying is you don't know how?

No,
I'm saying it's irrelevant to the problem at hand.

I would like to query that device's capabilities. I would like to ask the device "Do you support <feature X>?" (or better, "What features do you support?").
How do I do that?

Fish,

I don't really understand the need to fetch such capability.

In case of a LCS/Qeth <-> TUNTAP (on linux), you're sitting in the exact
same position where a RJ45,Optical,Whatever cable would fit (in the case
of TAP... for TUN, you are facing a tunnel sending you IPv4/IPv6
frames). TUNTAP isn't a "network interface" on the User side - it's just
the "wiring" (albeit a completely software wire).

For LCS, and Qeth, any offload feature (Checksum, segment reassembly,
etc..) have to be done in the "Network Interface Adapter" : The LCS or
Qeth code (which would be of great benefit since the IP/TCP/UDP layer
code running under hercules wouldn't have to deal with it - AND - it
wouldn't be dependent on any TUN/TAP implementation).

However, If such capability had to be queried, there would need to be
(maybe some exist) some 802.<something> protocol to allow a switch to
probe NICs for such facilities. [1]

--Ivan

[1] The only reason I see for this is if the tun/tap code is implemented
on a platform which has access to hardware acceleration facilities which
allow expediting processing of ETH/IP/TCP/UDP frames.



[Non-text portions of this message have been removed]

['\'Fish\' (David B. Trout)' [e-mail] [hercules-390]]

Post by Ivan Warren ***@vmfacility.fr [hercules-390]
I don't really understand the need to fetch such capability.
In case of a LCS/Qeth <-> TUNTAP (on linux), you're sitting
in the exact same position where a RJ45, Optical, Whatever cable
would fit (in the case of TAP... for TUN, you are facing a
tunnel sending you IPv4/IPv6 frames). TUNTAP isn't a "network
interface" on the User side - it's just the "wiring" (albeit
a completely software wire).

Oh? Then please the following comments in hostopts.h (which coincidentally *you* added):


/* Because Fish's TUNTAP emulation isn't seen as a network interface */
/* by the host operating system, there is only one MAC address. */
/* (The Windows "tap" is a capture and re-inject mechanism) */
/* For other tuntap implementation, the host and guest have */
/* separate abstracted NIC implementation - and therefore require */
/* a separate MAC address to address that (lest briding won't work) */

/* If at one point, a TUNTAP implementation comes up and is then */
/* seen as a proper network interface by Windows, then this option */
/* will have to go away - or anyway "undefined" for windows */
#define OPTION_TUNTAP_LCS_SAME_ADDR 1


and the following in ctc_lcs.c's LCS_LanStats function (which again *you* added):


/* Respond with a different MAC address for the LCS side */
/* unless the TAP mechanism is designed as such */
/* cf : hostopts.h for an explanation */

#if !defined( OPTION_TUNTAP_LCS_SAME_ADDR )

reply.MAC_Address[5]++;

#endif


It was my understanding that tuntap devices on Linux are treated just like any other network adapter/device, having their own MAC address, etc. Are you saying this is not true?

For the sake of argument and to illustrate my point, presume for the moment that a given tuntap device does not support Checksum Offloading (hereafter referred to as 'CO') and further presume the real Linux host doesn't either (i.e. none of its REAL network adapters support it). What happens if we tell the guest (MVS, VM, VSE, etc) that its LCS device *does* support CO?

The guest is going to write its packets to the LCS device without any checksums since it's expecting the device to do that for it. (You did after all say CO was supported in your LCS_QueryIPAssists response!) which Hercules would then write to the tuntap device (which I'm presuming would then write them to the host's real network adapter). Such packets would have invalid checksums and Hercules's networking would be broken!

Conversely, if the devices Hercules is using for its emulation *does* support CO, then if don't tell the guest its LCS device supports it, it's going to waste valuable CPU cycles calculating checksums using emulated instructions for all of its inbound and outbound packets, when in reality that *could* have been done much more efficiently by the tuntap device (or the host's real network adapter).

I believe Hercules's LCS device emulation code is much, much more than "just the wiring".

Thus my question (which *still* hasn't been answered by anyone) still remains very much relevant:

How does one determine what features and/or capabilities a tuntap device supports? My CYCI-WIN code on Windows does it. It asks the host's network adapter directly whether or not it supports CO and makes whatever internal adjustments are necessary to provide seamless CO support to Hercules (which Hercules is currently not using but I'd like to change that!).

Or is it truly not possible on Linux?

[Ivan Warren [e-mail] [hercules-390]]

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]

Post by Ivan Warren ***@vmfacility.fr [hercules-390]
I don't really understand the need to fetch such capability.
In case of a LCS/Qeth <-> TUNTAP (on linux), you're sitting
in the exact same position where a RJ45, Optical, Whatever cable
would fit (in the case of TAP... for TUN, you are facing a
tunnel sending you IPv4/IPv6 frames). TUNTAP isn't a "network
interface" on the User side - it's just the "wiring" (albeit
a completely software wire).

/* Because Fish's TUNTAP emulation isn't seen as a network interface */
/* by the host operating system, there is only one MAC address. */
/* (The Windows "tap" is a capture and re-inject mechanism) */
/* For other tuntap implementation, the host and guest have */
/* separate abstracted NIC implementation - and therefore require */
/* a separate MAC address to address that (lest briding won't work) */
/* If at one point, a TUNTAP implementation comes up and is then */
/* seen as a proper network interface by Windows, then this option */
/* will have to go away - or anyway "undefined" for windows */
#define OPTION_TUNTAP_LCS_SAME_ADDR 1
/* Respond with a different MAC address for the LCS side */
/* unless the TAP mechanism is designed as such */
/* cf : hostopts.h for an explanation */
#if !defined( OPTION_TUNTAP_LCS_SAME_ADDR )
reply.MAC_Address[5]++;
#endif
It was my understanding that tuntap devices on Linux are treated just like any other network adapter/device, having their own MAC address, etc. Are you saying this is not true?
For the sake of argument and to illustrate my point, presume for the moment that a given tuntap device does not support Checksum Offloading (hereafter referred to as 'CO') and further presume the real Linux host doesn't either (i.e. none of its REAL network adapters support it). What happens if we tell the guest (MVS, VM, VSE, etc) that its LCS device *does* support CO?
The guest is going to write its packets to the LCS device without any checksums since it's expecting the device to do that for it. (You did after all say CO was supported in your LCS_QueryIPAssists response!) which Hercules would then write to the tuntap device (which I'm presuming would then write them to the host's real network adapter). Such packets would have invalid checksums and Hercules's networking would be broken!
Conversely, if the devices Hercules is using for its emulation *does* support CO, then if don't tell the guest its LCS device supports it, it's going to waste valuable CPU cycles calculating checksums using emulated instructions for all of its inbound and outbound packets, when in reality that *could* have been done much more efficiently by the tuntap device (or the host's real network adapter).
I believe Hercules's LCS device emulation code is much, much more than "just the wiring".
How does one determine what features and/or capabilities a tuntap device supports? My CYCI-WIN code on Windows does it. It asks the host's network adapter directly whether or not it supports CO and makes whatever internal adjustments are necessary to provide seamless CO support to Hercules (which Hercules is currently not using but I'd like to change that!).
Or is it truly not possible on Linux?

Fish,

tuntap has *TWO* sides, as well as any LCS/Qeth :

- The network interface side to which the OS talks to. For TUNTAP,
That's what you'll see as interface tapN and the linux kernel IP layer
or the bridging module talks to. For LCS it's CCW driven and for Qeth
it's QDIO driven.
- The wire side : LCS and Qeth talk to each other on the tuntap "wire"
side. Whatever happens to the frames sent and received on the "wire"
side depend on how each "network" interface is configured.

The BIG difference between the a linux tuntap (in layer 2 mode) and your
windows tuntap emulation is that you are directly bridged and dependent
on a physicial network interface (since it relies on intercept/injection
of traffic on the physical network interface). On linux you can very
well create one or several completely independent virtual networks
*WITHOUT* any intervening physical adapter, with or without intervention
of the underlying OS IP stack. Under linux, the tuntap is *NOT* related
to a physical network interface.

Being able to use the MAC address of the "tuntap" or to use the MAC
adddress+1 is simply a convenience. You can also specify your own MAC
address (completely unrelated to the one used by the tuntap) and it will
still work.

The main thing to remember is : on linux, the tuntap is a SOFTWARE only
contraption and does *NOT* rely on any physical adapter.

--Ivan



[Non-text portions of this message have been removed]

[Ivan Warren [e-mail] [hercules-390]]

Fish,

As we talked on the phone, I think we got about everything covered.
However, I'd like to add something :

tuntap *DOES* seem to have a mechanism to offload some of the checksum
calculation when injecting frames from hercules to the tuntap.

The following IOCTLS exist :

#define TUNSETOFFLOAD _IOW('T', 208, unsigned int)

and...

/* Features for GSO (TUNSETOFFLOAD). */
#define TUN_F_CSUM 0x01 /* You can hand me unchecksummed packets. */
#define TUN_F_TSO4 0x02 /* I can handle TSO for IPv4 packets */
#define TUN_F_TSO6 0x04 /* I can handle TSO for IPv6 packets */
#define TUN_F_TSO_ECN 0x08 /* I can handle TSO with ECN bits. */
#define TUN_F_UFO 0x10 /* I can handle UFO packets */

However, it is unclear whether these apply to Layer 2 or Layer 3 tun/tap
or both and if these are present in all kernels and all versions of tuntap.

These IOCTLs are severly lacking documentation !

--Ivan



[Non-text portions of this message have been removed]

['\'Fish\' (David B. Trout)' [e-mail] [hercules-390]]

Post by Ivan Warren ***@vmfacility.fr [hercules-390]
Fish,
As we talked on the phone, I think we got about everything
covered.

Yes! Almost! THANK YOU for calling!

For the benefit of others who might be following this thread, I was laboring under a false presumption myself regarding what tuntap actually was and how it worked.

I was under the false impression that tuntap *itself* was "the network device" (i.e. the NIC, i.e. "tap0"), but in actuality (please correct me if I'm wrong!), tuntap is simply the "freight company" that ships and delivers networking packets to/from the actual networking device (tap0). Tuntap is *not* the network device (NIC), but rather is, as Ivan explained, simply "the virtual wire" (so to speak) that packets traverse across to reach the actual NIC (i.e. tap0).

Yes, it (tuntap) does indeed *create* a virtual software NIC (tap0) when you open it, but that's only so it has something to talk to. But it itself is *not* the NIC. It simply *talks* to the NIC (tap0) which then talks to the Linux Kernel to shuffle packets from NIC to NIC (real or virtual), etc.

Still, it would nevertheless be nice if tuntap could tell you whether the software NIC it was talking to (i.e. tap0, the software NIC it was delivering packets to/from) supported a given feature or not (e.g. Checksum Offloading, etc) so Hercules could know whether it needed to calculate the checksum or whether the tap0 device tuntap was talking to was going to do it. I mean, regardless of who does it, *someone* is going to have to calculate the checksum. If the NIC (tap0) is going to do it anyway, then Hercules doesn't need to. It can just write the packets to tuntap and they'll get delivered to the NIC (tap0) and it'll calculate the checksums. But if it's not going to do it and tuntap itself is not going to do it, then Hercules is obviously going to need to do it itself. THAT is the point I was trying to make and thus the reason for my question.

I hope that explains my confusion.

Post by Ivan Warren ***@vmfacility.fr [hercules-390]
tuntap *DOES* seem to have a mechanism to offload some of the
checksum calculation when injecting frames from hercules to the
tuntap.
#define TUNSETOFFLOAD _IOW('T', 208, unsigned int)

I saw that. But I couldn't find anything to explain how it works (i.e. what it does, etc). Does it enable both send *and* receive checksum offloading? Does it enable it for both IP *and* *TCP *and* UDP? Is it just for IPv4 or for IPv6 too? Is there a way to *query* whether or not it's already enabled or not, or should one simply always request it and simply presume it's not available if it fails? Etc.

Post by Ivan Warren ***@vmfacility.fr [hercules-390]
and...
/* Features for GSO (TUNSETOFFLOAD). */
#define TUN_F_CSUM 0x01 /* You can hand me unchecksummed packets. */
#define TUN_F_TSO4 0x02 /* I can handle TSO for IPv4 packets */
#define TUN_F_TSO6 0x04 /* I can handle TSO for IPv6 packets */
#define TUN_F_TSO_ECN 0x08 /* I can handle TSO with ECN bits. */
#define TUN_F_UFO 0x10 /* I can handle UFO packets */
However, it is unclear whether these apply to Layer 2 or Layer 3
tun/tap or both and if these are present in all kernels and all
versions of tuntap.

Precisely!

And what *are* those flags? Read-only flags returned to you as a result of issuing the "TUNGETFEATURES" ioctl? (and if so, where are they returned? Which field of the 'ifreq' structure are they returned in?), or are they also request flags used with "TUNSETOFFLOAD"? (or some other ioctl?)

Post by Ivan Warren ***@vmfacility.fr [hercules-390]
These IOCTLs are severly lacking documentation !

No kidding!

Hence my question: does anyone know (can anyone tell us with any authority (or semi-authority), based on personal experience perhaps) how to (or whether it's *possible* to) tell whether or not "feature X" (in this case checksum offloading, etc) is available or supported or *enabled* for a given tuntap device?

Thanks in advance to *anyone* out there who can help shed some light on this seemingly mysterious topic!

['\'Fish\' (David B. Trout)' [e-mail] [hercules-390]]

Fish wrote:

[...]

Is there a way to *query* whether or not it's already enabled
or not, or should one simply always request it and simply presume
it's not available if it fails? Etc.

And what if you only want to REPORT whether it was already enabled or not? Or report whether or not it was ABLE (capable) of doing checksum offloading, but you didn't really want to enable it?

Do you trying enabling it and if it works, then disable afterwards? What if someone else asked to enable it! You'd then be undoing what they asked to do! Not good! There need to be a "query" function that returns the current settings *without* actually changing any of those settings!

Same with capabilities: you *don't* necessarily want to know whether a given feature is currently enabled, but rather only wish to know whether it *could* be enabled. After all, what if the device was *ABLE* (capable) or enabling "Feature-X" but that feature was not currently enabled? Both of those are completely different things and must be reported separately from one another.

Is Linux not able to do this? Is it not able to report these things? And if it is, how the heck do you do it?!

Does anyone know?

Help! :)

['\'Fish\' (David B. Trout)' [e-mail] [hercules-390]]

Ivan Warren wrote:

[...]

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]

Post by Ivan Warren ***@vmfacility.fr [hercules-390]
These IOCTLs are severly lacking documentation !

No kidding!

This is the ONLY official documentation I could find:

https://www.kernel.org/doc/Documentation/networking/tuntap.txt


There are a few places that provide a tiny bit of dirt simple example code, but none of them explain in detail how to use all 24 of the ioctl codes or what the many flag #defines mean and how they're used:

https://github.com/torvalds/linux/blob/master/include/uapi/linux/if_tun.h


I guess all users of tuntap are expected to be psychic?

Or waste hours/days/weeks studying uncommented kernel code to figure it out for themselves? (and hope to hell they're understanding it correctly?)

Sheesh. :(

['\'Fish\' (David B. Trout)' [e-mail] [hercules-390]]

[...]

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]
I guess all users of tuntap are expected to be psychic?
Or waste hours/days/weeks studying uncommented kernel code
to figure it out for themselves? (and hope to hell they're
understanding it correctly?)

[...]

The answer is "waste hours/days/weeks studying uncommented
kernel code." This is the only answer when faced with the
absence of documentation.

Of course. I was just lamenting that fact. :(


[...]

How do you think I figured out how to do QETH? It wasn't due
to the copious documentation I can tell you that.

Yeah... (sigh)

And in case my previous thousand and one "Thank you!"s weren't enough, let me thank you yet again for the untold hours/days/weeks studying poorly commented kernel code that it originally took you to put that document together for us. Hercules's QETH driver would not even exist today were it not for your tremendous effort, so thank you once again for the 1002nd time. You're a nice guy, Harold, and I for one appreciate the unglamorous but oh so incredibly valuable behind the scenes work you do to help the Hercules project. You're a true Herculean.

FYI: the following is the most comprehensive tuntap "documentation" I could find ANYWHERE:

https://ldpreload.com/p/tuntap-notes.txt

[Harold Grovesteen [e-mail] [hercules-390]]

On Fri, 2017-05-26 at 21:01 -0700, ''Fish' (David B. Trout)'

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]
[...]

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]
I guess all users of tuntap are expected to be psychic?
Or waste hours/days/weeks studying uncommented kernel code
to figure it out for themselves? (and hope to hell they're
understanding it correctly?)

[...]

The answer is "waste hours/days/weeks studying uncommented
kernel code." This is the only answer when faced with the
absence of documentation.

Of course. I was just lamenting that fact. :(
[...]

How do you think I figured out how to do QETH? It wasn't due
to the copious documentation I can tell you that.

Yeah... (sigh)
And in case my previous thousand and one "Thank you!"s weren't enough, let me thank you yet again for the untold hours/days/weeks studying poorly commented kernel code that it originally took you to put that document together for us. Hercules's QETH driver would not even exist today were it not for your tremendous effort, so thank you once again for the 1002nd time. You're a nice guy, Harold, and I for one appreciate the unglamorous but oh so incredibly valuable behind the scenes work you do to help the Hercules project. You're a true Herculean.

Thanks for the kind words.

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]
https://ldpreload.com/p/tuntap-notes.txt

Yes, this is better than nothing. My concerns about what you are trying
to do is that the Linux tuntap driver provides a NIC card interacting
with the Linux network stack. On Windows, the tuntap.c interface is
providing an interface from Hercules to the physical NIC.

These two perspectives are the exact opposites of each other. Where is
the "NIC" for Hercules on Linux? To the extent it exists, it exists in
the Hercules tuntap.c module. On Linux, enabling check sum offload is
really enabling it for the Linux network stack side of the connection,
not the Hercules end of the connection. To provide check sum offload
for the Hercules guest connection, it would have to be implemented
within tuntap.c. As it exists today, the tuntap.c I/F on Linux simply
passes unchanged packets or frames. Additionally, for the guest to
benefit there has to be a mainframe mechanism that communicates to the
OS that offloading is available. Otherwise, the guest is going to do
the checksum processing anyway. While it is not implemented, the QETH
I/F protocol allows enabling offloading. I don't know about PTP, or
LCS. It doesn't exist for CTC. This isn't really a network interface
at all. It is a channel-to-channel interface that happens to transmit
and receive IP packets.

Harold

['\'Fish\' (David B. Trout)' [e-mail] [hercules-390]]

[...]

Post by Ivan Warren ***@vmfacility.fr [hercules-390]

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]
Does anyone out there know how to query a tuntap device's
capabilities?

[...]

Post by Ivan Warren ***@vmfacility.fr [hercules-390]

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]
I thought it would be a good idea to ask the actual tuntap
device that Hercules was actually using whether or not it
actually supported such capabilities. After all, I certainly
don't want to lie to the guest and say something is supported
when it actually isn't!

[...]

Post by Ivan Warren ***@vmfacility.fr [hercules-390]
Hey Fish,
LCS already has multicast support ;)

[...]

I'm inclined to agree. I've been using it as my preferred means
of connecting various guest systems for quite a long time, and
have never seen anything object that stuff isn't getting through.

So what you're saying is you don't know how either?

[Harold Grovesteen [e-mail] [hercules-390]]

This post might be inappropriate. Click to display it.

['\'Fish\' (David B. Trout)' [e-mail] [hercules-390]]

Post by Harold Grovesteen ***@tx.rr.com [hercules-390]

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]
Does anyone out there know how to query a tuntap device's
capabilities?

There are four ways on Linux to communicate with a device

[...]

Post by Harold Grovesteen ***@tx.rr.com [hercules-390]
Those are your options.
The details are all in the Linux file drivers/net/tun.c.
You have to do some reverse engineering to understand the
Linux options.

Thank you Harold. Your reply was the most helpful so far.

Unfortunately though, based on what you wrote, it appears the sysfs flags option (depending on the flags of course(*)) and such a technique isn't exactly portable. I would be unable to code a similar interface on Windows.

I was really hoping for some type of ioctl() or similar type API I could call, but based on what you've told me I'm beginning to suspect no such interface may exist.

Thanks for replying.

Can anyone else offer any insight?

[Harold Grovesteen [e-mail] [hercules-390]]

On Wed, 2017-05-17 at 09:43 -0700, ''Fish' (David B. Trout)'

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]

Post by Harold Grovesteen ***@tx.rr.com [hercules-390]

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]
Does anyone out there know how to query a tuntap device's
capabilities?

There are four ways on Linux to communicate with a device

[...]

Post by Harold Grovesteen ***@tx.rr.com [hercules-390]
Those are your options.
The details are all in the Linux file drivers/net/tun.c.
You have to do some reverse engineering to understand the
Linux options.

Thank you Harold. Your reply was the most helpful so far.
Unfortunately though, based on what you wrote, it appears the sysfs flags option (depending on the flags of course(*)) and such a technique isn't exactly portable. I would be unable to code a similar interface on Windows.
I was really hoping for some type of ioctl() or similar type API I could call, but based on what you've told me I'm beginning to suspect no such interface may exist.

I believe however it is done it would be different under the covers for
Windows and other OS's. A generic interface in tuntap.c could adjust
accordingly. In my view tuntap.c would be right place for it. The
drivers that use tuntap.c could all use the same interface.

On the bottom side of tuntap.c which interacts with the OS directly, it
would likely have to be different.

Post by '\'Fish\' (David B. Trout)' ***@gmail.com [hercules-390]
Thanks for replying.
Can anyone else offer any insight?