1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source. A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2016 Joyent, Inc.
.\"
.Dd May 31, 2016
.Dt MC_UNICST 9E
.Os
.Sh NAME
.Nm mc_unicst
.Nd set device unicast address
.Sh SYNOPSIS
.In sys/mac_provider.h
.Ft int
.Fo prefix_m_unicst
.Fa "void *driver"
.Fa "const uint8_t *mac"
.Fc
.Sh INTERFACE LEVEL
illumos DDI specific
.Sh PARAMETERS
.Bl -tag -width Fa
.It Fa driver
A pointer to the driver's private data that was passed in via the
.Sy m_pdata
member of the
.Xr mac_register 9S
structure to the
.Xr mac_register 9F
function.
.It Fa mac
A pointer to an array of bytes that contains the new unicast address of
the device. It is guaranteed to be at least a number of bytes long equal
to the length of the MAC plugin's address length. For Ethernet devices that
length is six bytes,
.Sy ETHERADDRL .
.El
.Sh DESCRIPTION
The
.Fn mc_unicst
entry point is used by the GLDv3 to indicate that the device driver
should update the primary MAC address of the device. In the basic mode
of operation, this entry point is required and the device has a single
primary MAC address. If multiple MAC addresses are required, the
device will be placed into promiscuous mode. This call should overwrite
the existing MAC address that is programmed into the device.
.Pp
As noted in the
.Sx PARAMETERS
section, the
.Fa mac
array is guaranteed to be at least as many bytes as is required to
specify an address; however, it should be assumed to be no longer than
that value.
.Pp
The device driver can optionally assert that the address is in the
valid form for a unicast address and then program the device. The device
driver can access its device soft state by casting the
.Fa device
pointer to the appropriate structure. As this may be called while other
operations are ongoing, the device driver should employ the appropriate
locking while updating the data.
.Pp
It is recommended that device drivers always maintain a copy of the
current unicast address in its soft state so that way it can recover
from various device reset and errors or handle requests to suspend and
resume the device that may result in device registers being cleared.
.Pp
Some devices support multiple MAC address filters. The
.Fn mc_unicst
entry point only supports a single MAC address. In this case, devices
should only use a single MAC address and replace that MAC address.
Support for using more than a single MAC address filter will be provided
by future interfaces.
.Sh RETURN VALUES
Upon successful completion, the device driver should have updated its
unicast filter and return
.Sy 0 .
Otherwise, the MAC address should remain unchanged and the driver should
return an appropriate error number.
.Sh ERRORS
The device driver may return one of the following errors. While this list
is not intended to be exhaustive, it is recommended to use one of these
if possible.
.Bl -tag -width Er
.It Er EINVAL
The address
.Fa mac
is not a valid unicast address.
.It Er EIO
The driver encountered a device or transport error while trying to
update the device's state.
.El
.Sh SEE ALSO
.Xr mac 9E ,
.Xr mac_register 9F ,
.Xr mac_register 9S
|
