From owner-svn-src-stable-11@freebsd.org Mon Mar 19 07:37:37 2018 Return-Path: Delivered-To: svn-src-stable-11@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 75EDCF58145; Mon, 19 Mar 2018 07:37:37 +0000 (UTC) (envelope-from eadler@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 28E3880E54; Mon, 19 Mar 2018 07:37:37 +0000 (UTC) (envelope-from eadler@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 mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 23C653DE6; Mon, 19 Mar 2018 07:37:37 +0000 (UTC) (envelope-from eadler@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id w2J7bb8c022331; Mon, 19 Mar 2018 07:37:37 GMT (envelope-from eadler@FreeBSD.org) Received: (from eadler@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id w2J7bbX0022330; Mon, 19 Mar 2018 07:37:37 GMT (envelope-from eadler@FreeBSD.org) Message-Id: <201803190737.w2J7bbX0022330@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: eadler set sender to eadler@FreeBSD.org using -f From: Eitan Adler Date: Mon, 19 Mar 2018 07:37:37 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-11@freebsd.org Subject: svn commit: r331199 - stable/11/share/man/man4 X-SVN-Group: stable-11 X-SVN-Commit-Author: eadler X-SVN-Commit-Paths: stable/11/share/man/man4 X-SVN-Commit-Revision: 331199 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-stable-11@freebsd.org X-Mailman-Version: 2.1.25 Precedence: list List-Id: SVN commit messages for only the 11-stable src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 19 Mar 2018 07:37:37 -0000 Author: eadler Date: Mon Mar 19 07:37:36 2018 New Revision: 331199 URL: https://svnweb.freebsd.org/changeset/base/331199 Log: MFC r324860: 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. Modified: stable/11/share/man/man4/udbp.4 Directory Properties: stable/11/ (props changed) Modified: stable/11/share/man/man4/udbp.4 ============================================================================== --- stable/11/share/man/man4/udbp.4 Mon Mar 19 07:37:13 2018 (r331198) +++ stable/11/share/man/man4/udbp.4 Mon Mar 19 07:37:36 2018 (r331199) @@ -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 .