share/man/man9/ethersubr.9

   1 .\"     $NetBSD: ethersubr.9,v 1.18 2008/04/30 13:10:58 martin Exp $
   2 .\"
   3 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Ignatios Souvatzis.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd March 3, 1997
  31 .Dt ETHERSUBR 9
  32 .Os
  33 .Sh NAME
  34 .Nm ethersubr ,
  35 .Nm ether_ifattach ,
  36 .Nm ether_addmulti ,
  37 .Nm ether_delmulti ,
  38 .Nm ETHER_FIRST_MULTI ,
  39 .Nm ETHER_NEXT_MULTI ,
  40 .Nm ETHER_IS_MULTICAST ,
  41 .Nm fddi_ifattach ,
  42 .Nm fddi_addmulti ,
  43 .Nm fddi_delmulti
  44 .Nd Ethernet and FDDI driver support functions and macros
  45 .Sh SYNOPSIS
  46 .In net/if_ether.h
  47 .Ft void
  48 .Fn ether_ifattach "struct ifnet *ifp" "uint8_t *lla"
  49 .Ft int
  50 .Fn ether_addmulti "const struct sockaddr *sa" "struct ethercom *ec"
  51 .Ft int
  52 .Fn ether_delmulti "const struct sockaddr *sa" "struct ethercom *ec"
  53 .Ft void
  54 .Fn ETHER_FIRST_MULTI "struct ether_multistep step" "struct ethercom *ec" "struct ether_multi *enm"
  55 .Ft void
  56 .Fn ETHER_NEXT_MULTI  "struct ether_multistep step" "struct ether_multi *enm"
  57 .Ft int
  58 .Fn ETHER_IS_MULTICAST "uint8_t *addr"
  59 .In net/if_fddi.h
  60 .Ft void
  61 .Fn fddi_ifattach "struct ifnet *ifp" "uint8_t *lla"
  62 .Ft int
  63 .Fn fddi_addmulti "const struct sockaddr *sa" "struct ethercom *ec"
  64 .Ft int
  65 .Fn fddi_delmulti "const struct sockaddr *sa" "struct ethercom *ec"
  66 .Sh DESCRIPTION
  67 The
  68 .Nm
  69 functions provide the interface between the
  70 .Nm
  71 module and the network drivers which need Ethernet support.
  72 Such drivers must request the
  73 .Ar ether
  74 attribute in their
  75 .Ar files
  76 declaration and call the appropriate functions as specified below.
  77 .Pp
  78 FDDI drivers must request the "fddi" attribute in their "files"
  79 declaration and call the functions tagged with "fddi_" or "FDDI_"
  80 instead, where different.
  81 Some macros are shared.
  82 .Pp
  83 Note that you also need the
  84 .Xr arp 9
  85 stuff to support IPv4 on your hardware.
  86 .Bl -tag -width compact
  87 .It Fn ether_ifattach
  88 Perform the device-independent, but Ethernet-specific initialization of
  89 the interface pointed to by
  90 .Fa ifp .
  91 .Pp
  92 Among other duties, this function creates a record for the link level
  93 address in the interface's address list and records the link level address
  94 pointed to by
  95 .Fa lla
  96 there.
  97 .Pp
  98 You must call this function from the driver's attach function.
  99 .It Fn fddi_ifattach
 100 corresponding function for FDDI devices.
 101 .It Fn ether_addmulti
 102 .It Fn ether_delmulti
 103 Add
 104 .Pq Fn ether_addmulti
 105 or delete
 106 .Pq Fn ether_delmulti
 107 the address described by the
 108 .Fa sa
 109 pointer to the Ethernet multicast list belonging to
 110 .Fa ec .
 111 .Pp
 112 These functions must be called from the driver's ioctl function to
 113 handle
 114 .Dv SIOCADDMULTI
 115 and
 116 .Dv SIOCDELMULTI
 117 requests.
 118 If they return
 119 .Er ENETRESET ,
 120 the hardware multicast filter must be reinitialized.
 121 .Pp
 122 These functions accept
 123 .Dv AF_UNSPEC
 124 addresses, which are interpreted as Ethernet addresses, or
 125 .Dv AF_INET
 126 addresses.
 127 In the latter case,
 128 .Dv INADDR_ANY
 129 is mapped to a range describing all the Ethernet address
 130 space reserved for IPv4 multicast addresses.
 131 .Pp
 132 .Fn ether_addmulti
 133 returns
 134 .Er EAFNOSUPPORT
 135 if an unsupported address family is specified,
 136 .Er EINVAL
 137 if a non-multicast address is specified, or
 138 .Er ENETRESET
 139 if
 140 the multicast list really changed and the driver should synchronize
 141 its hardware filter with it.
 142 .Pp
 143 .Fn ether_delmulti
 144 returns, in addition to the above errors,
 145 .Er ENXIO
 146 if the specified address
 147 can't be found in the list of multicast addresses.
 148 .It Fn fddi_addmulti
 149 .It Fn fddi_delmulti
 150 corresponding functions for FDDI devices.
 151 .It Fn ETHER_NEXT_MULTI
 152 is a macro to step through all of the ether_multi records, one at a time.
 153 The current position is remembered in
 154 .Fa step ,
 155 which the caller must provide.
 156 .It Fn ETHER_FIRST_MULTI
 157 must be called to initialize
 158 .Fa step
 159 and get the first record.
 160 Both macros return a
 161 .Dv NULL
 162 .Fa enm
 163 when there are no remaining records.
 164 .It Fn ETHER_IS_MULTICAST
 165 returns 1, if
 166 .Fa addr
 167 points to an Ethernet/FDDI multicast (or broadcast) address.
 168 Implemented as a macro.
 169 .El
 170 .Sh SEE ALSO
 171 .Xr arp 9
 172 .Sh AUTHORS
 173 UCB CSRG (original implementation)
 174 .Pp
 175 Ignatios Souvatzis (support for new ARP system)
 176 .Sh CODE REFERENCES
 177 Ethernet support functions are declared in
 178 .Aq Pa net/if_ether.h
 179 and defined (if not implemented as macro) in
 180 .Pa /usr/src/sys/net/if_ethersubr.c .
 181 .Pp
 182 FDDI support functions are declared in
 183 .Aq Pa net/if_fddi.h
 184 and defined (if not implemented as macro) in
 185 .Pa /usr/src/sys/net/if_fddisubr.c .
 186 .Sh HISTORY
 187 Rewritten to attach to the new ARP system in
 188 .Nx 1.3 .