From owner-svn-src-head@freebsd.org Sun Oct 22 11:40:56 2017 Return-Path: Delivered-To: svn-src-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 9C417E507A0; Sun, 22 Oct 2017 11:40:56 +0000 (UTC) (envelope-from bms@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 5DF903997; Sun, 22 Oct 2017 11:40:56 +0000 (UTC) (envelope-from bms@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id v9MBetYL020761; Sun, 22 Oct 2017 11:40:55 GMT (envelope-from bms@FreeBSD.org) Received: (from bms@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v9MBet9s020760; Sun, 22 Oct 2017 11:40:55 GMT (envelope-from bms@FreeBSD.org) Message-Id: <201710221140.v9MBet9s020760@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: bms set sender to bms@FreeBSD.org using -f From: Bruce M Simpson Date: Sun, 22 Oct 2017 11:40:55 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r324860 - head/share/man/man4 X-SVN-Group: head X-SVN-Commit-Author: bms X-SVN-Commit-Paths: head/share/man/man4 X-SVN-Commit-Revision: 324860 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 22 Oct 2017 11:40:56 -0000 Author: bms Date: Sun Oct 22 11:40:55 2017 New Revision: 324860 URL: https://svnweb.freebsd.org/changeset/base/324860 Log: Modernise this man page somewhat. 1. Add a reference to a good 3rd party list of compatible cables, but provide suggestions for 'known good' vendors. 2. Change IP-based USB host-host example to a modern Ethernet one which works 'out of box' with current Linux systems. 3. Explain that USB 3.0 is host-host, even though point-to-point soft Ethernet can be achieved. MFC after: 3 weeks Modified: head/share/man/man4/udbp.4 Modified: head/share/man/man4/udbp.4 ============================================================================== --- head/share/man/man4/udbp.4 Sun Oct 22 11:21:31 2017 (r324859) +++ head/share/man/man4/udbp.4 Sun Oct 22 11:40:55 2017 (r324860) @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd November 22, 2006 +.Dd October 20, 2017 .Dt UDBP 4 .Os .Sh NAME @@ -48,9 +48,14 @@ udbp_load="YES" The .Nm driver provides support for host-to-host cables -that contain at least two bulk pipes (one for each direction), -for example -the EzLink cable and the NetChip 1080 chip. +that contain at least two bulk pipes (one for each direction). +This typically includes cables branded for use with +.Sy Windows USB Easy Transfer , +and many cables based on the Prolific PL2xx1 series of USB bridge chips. +A useful (but non-comprehensive) list of compatible USB host cables +is listed in the +.Sx SEE ALSO +section below. .Pp .\" XXX The description of how to add netgraph to the kernel .\" is out of place here. It should be limited to the @@ -86,30 +91,64 @@ module and then the .Nm driver. .Pp -.Dl ngctl mkpeer udbp0: iface data inet -.Dl ifconfig ng0 10.0.0.1 10.0.0.2 +.Dl ngctl mkpeer udbp0: eiface data ether +.Dl ifconfig ngeth0 ether aa:dd:xx:xx:xx +.Dl ifconfig ngeth0 inet 169.254.x.x/16 .Pp -Create a new network interface node -and connect its inet hook to the data hook of the +Create a new Ethernet network interface node +and connect its ether hook to the data hook of the .Nm -node. -.Xr ifconfig 8 -configures the resulting network interface ng0 with a local -IP address of 10.0.0.1 and a remote IP address of 10.0.0.2. -On the remote host, the two -IP addresses should of course be reversed. +driver. +.Pp +This enables FreeBSD to communicate with a Linux peer (e.g. using the +.Sy plusb +driver). +The Linux node should be configured to prefer link-local IPv4 addresses +(e.g. using Network Manager in Debian and Red Hat derived distributions). +.Pp +Whilst both FreeBSD and Linux are able to interoperate by +loosely following CDC EEM 1.0 in their behaviour, neither implementation +has been expressly designed to follow its specification. .Sh SEE ALSO .Xr netgraph 4 , -.Xr ng_iface 4 , +.Xr ng_eiface 4 , .Xr ohci 4 , .Xr uhci 4 , .Xr usb 4 , .Xr ngctl 8 +.\" +.Rs +.%B Universal Serial Bus: Communications Class Subclass Specification for Ethernet Emulation Model Devices +.%N Revision 1.0 +.%D February 2, 2005 +.%I USB Implementers Forum, Inc. +.%U http://www.usb.org/developers/docs/devclass_docs/CDC_EEM10.pdf +.Re +.\" +.Rs +.%B Total Commander: Supported cables for USB cable connection +.%I Ghisler Software GmbH. +.%U https://www.ghisler.com/cables/index.htm +.Re +.Sh CAVEATS +The point-to-point nature and additional latency of USB host-host links +makes them unsuitable as a "drop-in" replacement for an Ethernet LAN; +for a USB 3.0 SuperSpeed cable, latency is comparable to 100BaseTX Ethernet +(but often worse), with throughput comparable to 2.5GBASE-T. +.Pp +However, their energy efficiency makes them attractive for embedded +applications. A Plugable PL27A1 cable claims 24mA of USB3 bus power, +as compared to 150mA for a typical USB 3.0 to Gigabit Ethernet interface. .Sh HISTORY The .Nm driver first appeared in .Fx 5.0 . +.Sh BUGS +The +.Nm +driver does not support the special packets described in section 5.1 +of the CDC EEM specification. .Sh AUTHORS .An -nosplit The @@ -121,4 +160,6 @@ and .An Nick Hibma Aq Mt n_hibma@FreeBSD.org . .Pp This manual page was written by -.An Nick Hibma Aq Mt n_hibma@FreeBSD.org . +.An Nick Hibma Aq Mt n_hibma@FreeBSD.org +and updated by +.An Bruce Simpson Aq Mt bms@FreeBSD.org .