1.\" $NetBSD: ethersubr.9,v 1.28 2020/01/20 18:38:18 thorpej 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 January 19, 2020 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.Nd Ethernet driver support functions and macros 42.Sh SYNOPSIS 43.In net/if_ether.h 44.Ft void 45.Fn ether_ifattach "struct ifnet *ifp" "uint8_t *lla" 46.Ft int 47.Fn ether_addmulti "const struct sockaddr *sa" "struct ethercom *ec" 48.Ft int 49.Fn ether_delmulti "const struct sockaddr *sa" "struct ethercom *ec" 50.Ft void 51.Fn ETHER_FIRST_MULTI "struct ether_multistep step" "struct ethercom *ec" "struct ether_multi *enm" 52.Ft void 53.Fn ETHER_NEXT_MULTI "struct ether_multistep step" "struct ether_multi *enm" 54.Ft int 55.Fn ETHER_IS_MULTICAST "uint8_t *addr" 56.Sh DESCRIPTION 57The 58.Nm 59functions provide the interface between the 60.Nm 61module and the network drivers which need Ethernet support. 62Such drivers must request the 63.Ar ether 64attribute in their 65.Ar files 66declaration and call the appropriate functions as specified below. 67.Pp 68Note that you also need the 69.Xr arp 9 70stuff to support IPv4 on your hardware. 71.Bl -tag -width compact 72.It Fn ether_ifattach "ifp" "lla" 73Perform the device-independent, but Ethernet-specific initialization of 74the interface pointed to by 75.Fa ifp . 76.Pp 77Among other duties, this function creates a record for the link level 78address in the interface's address list and records the link level address 79pointed to by 80.Fa lla 81there. 82Drivers can initialize the link level address by themselves by calling 83the function with 84.Fa lla 85as 86.Dv NULL 87and calling 88.Fn if_set_sadl . 89.Pp 90This function must be called from the driver's attach function. 91.It Fn ether_addmulti "sa" "ec" 92.It Fn ether_delmulti "sa" "ec" 93Add 94.Pq Fn ether_addmulti 95or delete 96.Pq Fn ether_delmulti 97the address described by the 98.Fa sa 99pointer to the Ethernet multicast list belonging to 100.Fa ec . 101.Pp 102These functions must be called from the driver's ioctl function to 103handle 104.Dv SIOCADDMULTI 105and 106.Dv SIOCDELMULTI 107requests. 108If these return 109.Er ENETRESET , 110the hardware multicast filter must be reinitialized. 111.Pp 112These functions accept 113.Dv AF_UNSPEC 114addresses, which are interpreted as Ethernet addresses, or 115.Dv AF_INET 116addresses. 117In the latter case, 118.Dv INADDR_ANY 119is mapped to a range describing all the Ethernet address 120space reserved for IPv4 multicast addresses. 121.Pp 122The 123.Fn ether_addmulti 124returns 125.Er EAFNOSUPPORT 126if an unsupported address family is specified, 127.Er EINVAL 128if a non-multicast address is specified, or 129.Er ENETRESET 130if 131the multicast list really changed and the driver should synchronize 132its hardware filter with it. 133.Pp 134The 135.Fn ether_delmulti 136returns, in addition to the above errors, 137.Er ENXIO 138if the specified address 139can't be found in the list of multicast addresses. 140.It Fn ETHER_NEXT_MULTI "step" "enm" 141A macro to step through all of the 142.Em ether_multi 143records, one at a time. 144The current position is remembered in 145.Fa step , 146which the caller must provide. 147.It Fn ETHER_FIRST_MULTI "step" "ec" "enm" 148A macro that must be called to initialize 149.Fa step 150and get the first record. 151Both macros return a 152.Dv NULL 153.Fa enm 154when there are no remaining records. 155.It Fn ETHER_IS_MULTICAST "addr" 156A macro that returns 1, if 157.Fa addr 158points to an Ethernet/FDDI multicast (or broadcast) address. 159.El 160.Sh CODE REFERENCES 161Ethernet support functions are declared in 162.In net/if_ether.h 163and defined (if not implemented as macro) in 164.Pa sys/net/if_ethersubr.c . 165.Sh SEE ALSO 166.Xr arp 9 167.Sh HISTORY 168Rewritten to attach to the new ARP system in 169.Nx 1.3 . 170.Sh AUTHORS 171UCB CSRG (original implementation) 172.Pp 173.An Ignatios Souvatzis 174(support for new ARP system) 175