Add the tap driver.

The tap driver is used to present a virtual Ethernet interface to the
system. Packets presented by the network stack to the interface are
made available to a character device in /dev. With tap and the bridge
code, you can make remote bridge configurations where both sides of
the bridge are separated by userland daemons.

This driver also has a special naming hack to allow it to serve a similar
purpose to the vmware port.

Submitted by:	myevmenkin@att.com, vsilyaev@mindspring.com

1 files changed, 217 insertions, 0 deletions

diff --git a/share/man/man4/tap.4 b/share/man/man4/tap.4
new file mode 100644
index 0000000..fba5466
--- /dev/null
+++ b/share/man/man4/tap.4
@@ -0,0 +1,217 @@
+.\" $FreeBSD$
+.\" Based on PR#2411
+.\"
+.Dd July 9, 2000
+.Os
+.Dt TAP 4
+.Sh NAME
+.Nm tap
+.Nd Ethernet tunnel software network interface
+.Sh SYNOPSIS
+.Cd pseudo-device tap
+.Sh DESCRIPTION
+The
+.Nm tap
+interface is a software loopback mechanism that can be loosely
+described as the network interface analog of the
+.Xr pty 4 ,
+that is,
+.Nm tap
+does for network interfaces what the
+.Nm pty
+driver does for terminals.
+.Pp
+The
+.Nm tap
+driver, like the
+.Nm pty
+driver, provides two interfaces: an interface like the usual facility
+it is simulating
+.Po
+an Ethernet network interface in the case of
+.Nm tap ,
+or a terminal for
+.Nm pty
+.Pc ,
+and a character-special device
+.Dq control
+interface.
+.Pp
+The network interfaces are named
+.Sy tap Ns Ar 0 ,
+.Sy tap Ns Ar 1 ,
+etc, as many as were made by
+.Xr MAKEDEV 8 .
+Each one supports the usual Ethernet network-interface
+.Xr ioctl 2 Ns s ,
+such as
+.Dv SIOCSIFADDR
+and
+.Dv SIOCSIFNETMASK ,
+and thus can be used with
+.Xr ifconfig 8
+like any other Ethernet interface. When the system chooses to transmit
+an Ethernet frame on the network interface, the frame can be read from 
+the control device
+.Po
+it appears as
+.Dq input
+there
+.Pc ;
+writing an Ethernet frame to the control device generates an input frame on
+the network interface, as if the
+.Pq non-existent
+hardware had just received it.
+.Pp
+The Ethernet tunnel device, normally
+.Pa /dev/tap Ns Sy N ,
+is exclusive-open
+.Po
+it cannot be opened if it is already open
+.Pc
+and is restricted to the super-user.
+A
+.Fn read
+call will return an error
+.Pq Er EHOSTDOWN
+if the interface is not
+.Dq ready .
+Once the interface is ready,
+.Fn read
+will return an Ethernet frame if one is available; if not, it will 
+either block until one is or return
+.Er EWOULDBLOCK ,
+depending on whether non-blocking I/O has been enabled. If the frame
+is longer than is allowed for in the buffer passed to
+.Fn read ,
+the extra data will be silently dropped.
+.Pp
+A
+.Xr write 2
+call passes an Ethernet frame in to be
+.Dq received
+on the pseudo-interface.  Each
+.Fn write
+call supplies exactly one frame; the frame length is taken from the
+amount of data provided to
+.Fn write .
+Writes will not block; if the frame cannot be accepted
+for a transient reason
+.Pq e.g., no buffer space available ,
+it is silently dropped; if the reason is not transient
+.Pq e.g., frame too large ,
+an error is returned.
+The following
+.Xr ioctl 2
+calls are supported
+.Pq defined in Aq Pa net/if_tap.h Ns :
+.Bl -tag -width VMIO_SIOCSETMACADDR
+.It Dv TAPSDEBUG
+The argument should be a pointer to an
+.Va int ;
+this sets the internal debugging variable to that value.  What, if
+anything, this variable controls is not documented here; see the source
+code.
+.It Dv TAPGDEBUG
+The argument should be a pointer to an
+.Va int ;
+this stores the internal debugging variable's value into it.
+.It Dv FIONBIO
+Turn non-blocking I/O for reads off or on, according as the argument
+.Va int Ns 's
+value is or isn't zero
+.Pq Writes are always nonblocking .
+.It Dv FIOASYNC
+Turn asynchronous I/O for reads
+.Po
+i.e., generation of
+.Dv SIGIO
+when data is available to be read
+.Pc
+off or on, according as the argument
+.Va int Ns 's
+value is or isn't zero.
+.It Dv FIONREAD
+If any frames are queued to be read, store the size of the first one into the argument
+.Va int ;
+otherwise, store zero.
+.It Dv TIOCSPGRP
+Set the process group to receive
+.Dv SIGIO
+signals, when asynchronous I/O is enabled, to the argument
+.Va int
+value.
+.It Dv TIOCGPGRP
+Retrieve the process group value for
+.Dv SIGIO
+signals into the argument
+.Va int
+value.
+.It SIOCGIFADDR
+Retrieve the Media Access Control
+.Pq MAC 
+address. This command should be executed on descriptor, associated with
+control device
+.Pq Pa /dev/tap Ns Sy N .
+The
+.Va buffer ,
+which is passed as argument, is expected to have enought space to store
+.Pq MAC
+address.
+.It SIOCSIFADDR
+Set the Media Access Control
+.Pq MAC
+address. This command should be executed on a descriptor, associated with
+control device
+.Pq Pa /dev/tap Ns Sy N .
+.El
+.Pp
+The control device also supports
+.Xr select 2
+for read; selecting for write is pointless, and always succeeds, since
+writes are always non-blocking.
+.Pp
+On the last close of the data device, by default, the interface is
+brought down
+.Po
+as if with  
+.Dq ifconfig tap Ns Sy N No down
+.Pc .
+All queued frames are thrown away. If the interface is up when the data 
+device is not open output frames are always thrown away rather than 
+letting them pile up.
+.Pp
+The 
+.Nm tap
+device is also can be used with VMware port as a replacement
+of VMnet device driver. The driver uses minor number to select between
+.Nm tap
+and
+.Nm vmnet
+devices. VMnet minor numbering is
+.Va 0x10000 
++
+.Va N . 
+Where
+.Va N 
+is a VMnet unit number. In this case control device is expected to be 
+.Pa /dev/vmnet Ns Sy N ,
+and network interface will be
+.Sy vmnet Ns Ar N .
+Everything else is the same. 
+.Pp
+In addition to mentioned above
+.Xr ioctl 2
+there are additional one for VMware port.
+.Bl -tag -width VMIO_SIOCSETMACADDR
+.It VMIO_SIOCSIFFLAGS
+VMware 
+.Dv SIOCSIFFLAGS .
+.El
+.Sh SEE ALSO
+.Xr inet 4 ,
+.Xr intro 4
+.\" .Sh BUGS
+.Sh AUTHORS
+This man page has been obtained from
+.Bx Free .