share/man/man4/udbp.4

   1 .\" Copyright (c) 1999
   2 .\"     Nick Hibma <n_hibma@FreeBSD.org>. All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd October 20, 2017
  28 .Dt UDBP 4
  29 .Os
  30 .Sh NAME
  31 .Nm udbp
  32 .Nd USB Double Bulk Pipe driver
  33 .Sh SYNOPSIS
  34 To compile this driver into the kernel,
  35 place the following line in your
  36 kernel configuration file:
  37 .Bd -ragged -offset indent
  38 .Cd "device udbp"
  39 .Ed
  40 .Pp
  41 Alternatively, to load the driver as a
  42 module at boot time, place the following line in
  43 .Xr loader.conf 5 :
  44 .Bd -literal -offset indent
  45 udbp_load="YES"
  46 .Ed
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 driver provides support for host-to-host cables
  51 that contain at least two bulk pipes (one for each direction).
  52 This typically includes cables branded for use with
  53 .Sy Windows USB Easy Transfer ,
  54 and many cables based on the Prolific PL2xx1 series of USB bridge chips.
  55 A useful (but non-comprehensive) list of compatible USB host cables
  56 is listed in the
  57 .Sx SEE ALSO
  58 section below.
  59 .Pp
  60 .\" XXX The description of how to add netgraph to the kernel
  61 .\"     is out of place here.  It should be limited to the
  62 .\"     netgraph(4) manpage only.  However, that page does
  63 .\"     not yet give instructions for kldload(8) for the
  64 .\"     clueless.  Working on it -- sheldonh
  65 It requires
  66 .Xr netgraph 4
  67 to be available.
  68 This can be done either by adding
  69 .Cd "options NETGRAPH"
  70 to your kernel configuration file, or alternatively loading
  71 .Xr netgraph 4
  72 as a module, either from
  73 .Pa /boot/loader.conf
  74 or from the command line, before the
  75 .Nm
  76 module.
  77 .Sh EXAMPLES
  78 .Dl options NETGRAPH
  79 .Dl device udbp
  80 .Pp
  81 Add the
  82 .Nm
  83 driver to the kernel.
  84 .Pp
  85 .Dl kldload netgraph
  86 .Dl kldload udbp
  87 .Pp
  88 Load the
  89 .Xr netgraph 4
  90 module and then the
  91 .Nm
  92 driver.
  93 .Pp
  94 .Dl ngctl mkpeer udbp0: eiface data ether
  95 .Dl ifconfig ngeth0 ether aa:dd:xx:xx:xx
  96 .Dl ifconfig ngeth0 inet 169.254.x.x/16
  97 .Pp
  98 Create a new Ethernet network interface node
  99 and connect its ether hook to the data hook of the
 100 .Nm
 101 driver.
 102 .Pp
 103 This enables FreeBSD to communicate with a Linux peer (e.g. using the
 104 .Sy plusb
 105 driver).
 106 The Linux node should be configured to prefer link-local IPv4 addresses
 107 (e.g. using Network Manager in Debian and Red Hat derived distributions).
 108 .Pp
 109 Whilst both FreeBSD and Linux are able to interoperate by
 110 loosely following CDC EEM 1.0 in their behaviour, neither implementation
 111 has been expressly designed to follow its specification.
 112 .Sh SEE ALSO
 113 .Xr netgraph 4 ,
 114 .Xr ng_eiface 4 ,
 115 .Xr ohci 4 ,
 116 .Xr uhci 4 ,
 117 .Xr usb 4 ,
 118 .Xr ngctl 8
 119 .\"
 120 .Rs
 121 .%B Universal Serial Bus: Communications Class Subclass Specification for Ethernet Emulation Model Devices
 122 .%N Revision 1.0
 123 .%D February 2, 2005
 124 .%I USB Implementers Forum, Inc.
 125 .%U http://www.usb.org/developers/docs/devclass_docs/CDC_EEM10.pdf
 126 .Re
 127 .\"
 128 .Rs
 129 .%B Total Commander: Supported cables for USB cable connection
 130 .%I Ghisler Software GmbH.
 131 .%U https://www.ghisler.com/cables/index.htm
 132 .Re
 133 .Sh CAVEATS
 134 The point-to-point nature and additional latency of USB host-host links
 135 makes them unsuitable as a "drop-in" replacement for an Ethernet LAN;
 136 for a USB 3.0 SuperSpeed cable, latency is comparable to 100BaseTX Ethernet
 137 (but often worse), with throughput comparable to 2.5GBASE-T.
 138 .Pp
 139 However, their energy efficiency makes them attractive for embedded applications.
 140 A Plugable PL27A1 cable claims 24mA of USB3 bus power,
 141 as compared to 150mA for a typical USB 3.0 to Gigabit Ethernet interface.
 142 .Sh HISTORY
 143 The
 144 .Nm
 145 driver first appeared in
 146 .Fx 5.0 .
 147 .Sh BUGS
 148 The
 149 .Nm
 150 driver does not support the special packets described in section 5.1
 151 of the CDC EEM specification.
 152 .Sh AUTHORS
 153 .An -nosplit
 154 The
 155 .Nm
 156 driver was written by
 157 .An Doug Ambrisko Aq Mt ambrisko@whistle.com ,
 158 .An Julian Elischer Aq Mt julian@FreeBSD.org
 159 and
 160 .An Nick Hibma Aq Mt n_hibma@FreeBSD.org .
 161 .Pp
 162 This manual page was written by
 163 .An Nick Hibma Aq Mt n_hibma@FreeBSD.org
 164 and updated by
 165 .An Bruce Simpson Aq Mt bms@FreeBSD.org .