1.\" $NetBSD: ethersubr.9,v 1.19 2009/03/09 17:17:02 joerg 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 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 98You must call this function from the driver's attach function. 99.It Fn fddi_ifattach 100corresponding function for FDDI devices. 101.It Fn ether_addmulti 102.It Fn ether_delmulti 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 they 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 132.Fn ether_addmulti 133returns 134.Er EAFNOSUPPORT 135if an unsupported address family is specified, 136.Er EINVAL 137if a non-multicast address is specified, or 138.Er ENETRESET 139if 140the multicast list really changed and the driver should synchronize 141its hardware filter with it. 142.Pp 143.Fn ether_delmulti 144returns, in addition to the above errors, 145.Er ENXIO 146if the specified address 147can't be found in the list of multicast addresses. 148.It Fn fddi_addmulti 149.It Fn fddi_delmulti 150corresponding functions for FDDI devices. 151.It Fn ETHER_NEXT_MULTI 152is a macro to step through all of the ether_multi records, one at a time. 153The current position is remembered in 154.Fa step , 155which the caller must provide. 156.It Fn ETHER_FIRST_MULTI 157must be called to initialize 158.Fa step 159and get the first record. 160Both macros return a 161.Dv NULL 162.Fa enm 163when there are no remaining records. 164.It Fn ETHER_IS_MULTICAST 165returns 1, if 166.Fa addr 167points to an Ethernet/FDDI multicast (or broadcast) address. 168Implemented as a macro. 169.El 170.Sh SEE ALSO 171.Xr arp 9 172.Sh AUTHORS 173UCB CSRG (original implementation) 174.Pp 175Ignatios Souvatzis (support for new ARP system) 176.Sh CODE REFERENCES 177Ethernet support functions are declared in 178.Aq Pa net/if_ether.h 179and defined (if not implemented as macro) in 180.Pa /usr/src/sys/net/if_ethersubr.c . 181.Pp 182FDDI support functions are declared in 183.Aq Pa net/if_fddi.h 184and defined (if not implemented as macro) in 185.Pa /usr/src/sys/net/if_fddisubr.c . 186.Sh HISTORY 187Rewritten to attach to the new ARP system in 188.Nx 1.3 . 189