1.\" $NetBSD: ethersubr.9,v 1.27 2016/12/28 11:44:58 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 December 28, 2016 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. 97Drivers can initialize the link level address by themselves by calling 98the function with 99.Fa lla 100as 101.Dv NULL 102and calling 103.Fn if_set_sadl . 104.Pp 105This function must be called from the driver's attach function. 106.It Fn fddi_ifattach "ifp" "lla" 107Corresponding function for FDDI devices. 108.It Fn ether_addmulti "sa" "ec" 109.It Fn ether_delmulti "sa" "ec" 110Add 111.Pq Fn ether_addmulti 112or delete 113.Pq Fn ether_delmulti 114the address described by the 115.Fa sa 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 these 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 139The 140.Fn ether_addmulti 141returns 142.Er EAFNOSUPPORT 143if an unsupported address family is specified, 144.Er EINVAL 145if a non-multicast address is specified, or 146.Er ENETRESET 147if 148the multicast list really changed and the driver should synchronize 149its hardware filter with it. 150.Pp 151The 152.Fn ether_delmulti 153returns, in addition to the above errors, 154.Er ENXIO 155if the specified address 156can't be found in the list of multicast addresses. 157.It Fn fddi_addmulti "sa" "ec" 158.It Fn fddi_delmulti "sa" "ec" 159Corresponding functions for FDDI devices. 160.It Fn ETHER_NEXT_MULTI "step" "enm" 161A macro to step through all of the 162.Em ether_multi 163records, one at a time. 164The current position is remembered in 165.Fa step , 166which the caller must provide. 167.It Fn ETHER_FIRST_MULTI "step" "ec" "enm" 168A macro that must be called to initialize 169.Fa step 170and get the first record. 171Both macros return a 172.Dv NULL 173.Fa enm 174when there are no remaining records. 175.It Fn ETHER_IS_MULTICAST "addr" 176A macro that returns 1, if 177.Fa addr 178points to an Ethernet/FDDI multicast (or broadcast) address. 179.El 180.Sh CODE REFERENCES 181Ethernet support functions are declared in 182.In net/if_ether.h 183and defined (if not implemented as macro) in 184.Pa sys/net/if_ethersubr.c . 185.Pp 186FDDI support functions are declared in 187.In net/if_fddi.h 188and defined (if not implemented as macro) in 189.Pa sys/net/if_fddisubr.c . 190.Sh SEE ALSO 191.Xr arp 9 192.Sh HISTORY 193Rewritten to attach to the new ARP system in 194.Nx 1.3 . 195.Sh AUTHORS 196UCB CSRG (original implementation) 197.Pp 198.An Ignatios Souvatzis 199(support for new ARP system) 200