1.\" $NetBSD: ethersubr.9,v 1.24 2010/12/02 12:54:13 wiz 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 67The 68.Nm 69functions provide the interface between the 70.Nm 71module and the network drivers which need Ethernet support. 72Such drivers must request the 73.Ar ether 74attribute in their 75.Ar files 76declaration and call the appropriate functions as specified below. 77.Pp 78FDDI drivers must request the "fddi" attribute in their "files" 79declaration and call the functions tagged with "fddi_" or "FDDI_" 80instead, where different. 81Some macros are shared. 82.Pp 83Note that you also need the 84.Xr arp 9 85stuff to support IPv4 on your hardware. 86.Bl -tag -width compact 87.It Fn ether_ifattach "ifp" "lla" 88Perform the device-independent, but Ethernet-specific initialization of 89the interface pointed to by 90.Fa ifp . 91.Pp 92Among other duties, this function creates a record for the link level 93address in the interface's address list and records the link level address 94pointed to by 95.Fa lla 96there. 97.Pp 98This function must be called from the driver's attach function. 99.It Fn fddi_ifattach "ifp" "lla" 100Corresponding function for FDDI devices. 101.It Fn ether_addmulti "sa" "ec" 102.It Fn ether_delmulti "sa" "ec" 103Add 104.Pq Fn ether_addmulti 105or delete 106.Pq Fn ether_delmulti 107the address described by the 108.Fa sa 109pointer to the Ethernet multicast list belonging to 110.Fa ec . 111.Pp 112These functions must be called from the driver's ioctl function to 113handle 114.Dv SIOCADDMULTI 115and 116.Dv SIOCDELMULTI 117requests. 118If these return 119.Er ENETRESET , 120the hardware multicast filter must be reinitialized. 121.Pp 122These functions accept 123.Dv AF_UNSPEC 124addresses, which are interpreted as Ethernet addresses, or 125.Dv AF_INET 126addresses. 127In the latter case, 128.Dv INADDR_ANY 129is mapped to a range describing all the Ethernet address 130space reserved for IPv4 multicast addresses. 131.Pp 132The 133.Fn ether_addmulti 134returns 135.Er EAFNOSUPPORT 136if an unsupported address family is specified, 137.Er EINVAL 138if a non-multicast address is specified, or 139.Er ENETRESET 140if 141the multicast list really changed and the driver should synchronize 142its hardware filter with it. 143.Pp 144The 145.Fn ether_delmulti 146returns, in addition to the above errors, 147.Er ENXIO 148if the specified address 149can't be found in the list of multicast addresses. 150.It Fn fddi_addmulti "sa" "ec" 151.It Fn fddi_delmulti "sa" "ec" 152Corresponding functions for FDDI devices. 153.It Fn ETHER_NEXT_MULTI "step" "enm" 154A macro to step through all of the 155.Em ether_multi 156records, one at a time. 157The current position is remembered in 158.Fa step , 159which the caller must provide. 160.It Fn ETHER_FIRST_MULTI "step" "ec" "enm" 161A macro that must be called to initialize 162.Fa step 163and get the first record. 164Both macros return a 165.Dv NULL 166.Fa enm 167when there are no remaining records. 168.It Fn ETHER_IS_MULTICAST "addr" 169A macro that returns 1, if 170.Fa addr 171points to an Ethernet/FDDI multicast (or broadcast) address. 172.El 173.Sh SEE ALSO 174.Xr arp 9 175.Sh HISTORY 176Rewritten to attach to the new ARP system in 177.Nx 1.3 . 178.Sh AUTHORS 179UCB CSRG (original implementation) 180.Pp 181Ignatios Souvatzis (support for new ARP system) 182.Sh CODE REFERENCES 183Ethernet support functions are declared in 184.In net/if_ether.h 185and defined (if not implemented as macro) in 186.Pa sys/net/if_ethersubr.c . 187.Pp 188FDDI support functions are declared in 189.In net/if_fddi.h 190and defined (if not implemented as macro) in 191.Pa sys/net/if_fddisubr.c . 192