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