1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright (c) 2017, Joyent, Inc. 13.\" Copyright 2022 Oxide Computer Company 14.\" 15.Dd July 2, 2022 16.Dt MAC_CALLBACKS 9S 17.Os 18.Sh NAME 19.Nm mac_callbacks , 20.Nm mac_callbacks_t 21.Nd networking device driver entry points structure 22.Sh SYNOPSIS 23.In sys/mac_provider.h 24.Sh INTERFACE LEVEL 25illumos DDI specific 26.Sh DESCRIPTION 27The 28.Sy mac_callbacks 29structure is used by GLDv3 networking device drivers implementing and 30using the 31.Xr mac 9E 32framework and interfaces. 33.Pp 34The structure is normally allocated statically by drivers as a single 35global entry. 36A pointer to it is passed as the 37.Fa m_callbacks 38member of the 39.Vt mac_register_t 40structure. 41.Sh TYPES 42The following types define the function pointers in use in the 43.Vt mac_register_t . 44.Bd -literal -offset indent 45typedef int (*mac_getstat_t)(void *, uint_t, uint64_t *); 46typedef int (*mac_start_t)(void *); 47typedef void (*mac_stop_t)(void *); 48typedef int (*mac_setpromisc_t)(void *, boolean_t); 49typedef int (*mac_multicst_t)(void *, boolean_t, const uint8_t *); 50typedef int (*mac_unicst_t)(void *, const uint8_t *); 51typedef void (*mac_ioctl_t)(void *, queue_t *, mblk_t *); 52typedef void (*mac_resources_t)(void *); 53typedef mblk_t *(*mac_tx_t)(void *, mblk_t *); 54typedef boolean_t (*mac_getcapab_t)(void *, mac_capab_t, void *); 55typedef int (*mac_open_t)(void *); 56typedef void (*mac_close_t)(void *); 57typedef int (*mac_set_prop_t)(void *, const char *, mac_prop_id_t, 58 uint_t, const void *); 59typedef int (*mac_get_prop_t)(void *, const char *, mac_prop_id_t, 60 uint_t, void *); 61typedef void (*mac_prop_info_t)(void *, const char *, mac_prop_id_t, 62 mac_prop_info_handle_t); 63.Ed 64.Sh STRUCTURE MEMBERS 65.Bd -literal -offset indent 66uint_t mc_callbacks; /* Denotes which callbacks are set */ 67mac_getstat_t mc_getstat; /* Get the value of a statistic */ 68mac_start_t mc_start; /* Start the device */ 69mac_stop_t mc_stop; /* Stop the device */ 70mac_setpromisc_t mc_setpromisc; /* Enable or disable promiscuous mode */ 71mac_multicst_t mc_multicst; /* Enable or disable a multicast addr */ 72mac_unicst_t mc_unicst; /* Set the unicast MAC address */ 73mac_tx_t mc_tx; /* Transmit a packet */ 74void *mc_reserved; /* Reserved, do not use */ 75mac_ioctl_t mc_ioctl; /* Process an unknown ioctl */ 76mac_getcapab_t mc_getcapab; /* Get capability information */ 77mac_open_t mc_open; /* Open the device */ 78mac_close_t mc_close; /* Close the device */ 79mac_set_prop_t mc_setprop; /* Set a device property */ 80mac_get_prop_t mc_getprop; /* Get a device property */ 81mac_prop_info_t mc_propinfo; /* Get property information */ 82.Ed 83.Pp 84The 85.Fa mc_callbacks 86member is used to denote which of a series of optional callbacks are 87present. 88This method allows additional members to be added to the 89.Vt mac_callbacks_t 90structure while maintaining ABI compatibility with existing modules. 91If a member is not mentioned below, then it is a part of the base version 92of the structure and device drivers do not need to set anything to 93indicate that it is present. 94The 95.Fa mc_callbacks 96member should be set to the bitwise inclusive OR of the following 97pre-processor values: 98.Bl -tag -width Dv -offset indent 99.It Dv MC_IOCTL 100Indicates that the 101.Fa mc_ioctl 102structure member has been set. 103.It Dv MC_GETCAPAB 104Indicates that the 105.Fa mc_getcapab 106structure member has been set. 107.It Dv MC_OPEN 108Indicates that the 109.Fa mc_open 110structure member has been set. 111.It Dv MC_CLOSE 112Indicates that the 113.Fa mc_close 114structure member has been set. 115.It Dv MC_SETPROP 116Indicates that the 117.Fa mc_setprop 118structure member has been set. 119.It Dv MC_GETPROP 120Indicates that the 121.Fa mc_getprop 122structure member has been set. 123.It Dv MC_PROPINFO 124Indicates that the 125.Fa mc_propinfo 126structure member has been set. 127.It Dv MC_PROPERTIES 128Indicates that the 129.Fa mc_getprop , 130.Fa mc_propinfo , 131and 132.Fa mc_setprop 133structure members have been set. 134.El 135.Pp 136The 137.Fa mc_getstat 138function defines an entry point used to receive statistics about the 139device. 140A list of statistics that it is required to support is available in 141.Xr mac 9E . 142For more information on the requirements of the function, see 143.Xr mc_getstat 9E . 144.Pp 145The 146.Fa mc_start 147member defines an entry point that is used to start the device. 148For more information on the requirements of the function, see 149.Xr mc_start 9E . 150.Pp 151The 152.Fa mc_stop 153member defines an entry point that is used to stop the device. 154It is the opposite of the 155.Fa mc_start 156member. 157For more information on the requirements of the function, see 158.Xr mc_stop 9E . 159.Pp 160The 161.Fa mc_setpromisc 162member is used to enable and disable promiscuous mode on the device. 163For more information on the requirements of the function, see 164.Xr mc_setpromisc 9E . 165.Pp 166The 167.Fa mc_multicst 168member is used to enable or disable multicast addresses in the device's 169filters. 170For more information on the requirements of the function, see 171.Xr mc_multicst 9E . 172.Pp 173The 174.Fa mc_unicst 175member is used to set the primary unicast MAC address of the device. 176For more information on the requirements of the function, see 177.Xr mc_unicst 9E . 178.Pp 179The 180.Fa mc_tx 181member is used to transmit a single message on the wire. 182For more information on the requirements of the function, see 183.Xr mc_tx 9E . 184.Pp 185The 186.Fa mc_ioctl 187member is used to process device specific ioctls. 188The MAC framework does not define any ioctls that devices should handle; 189however, there may be private ioctls for this device. 190This entry point is optional. 191For it to be considered, the 192.Dv MC_IOCTL 193value must be present in the 194.Fa mc_callbacks 195member. 196For more information on the requirements of the function, see 197.Xr mc_ioctl 9E . 198.Pp 199The 200.Fa mc_getcapab 201member is used to determine device capabilities. 202Each capability has its own data and semantics associated with it. 203A list of capabilities is provided in 204.Xr mac 9E . 205This entry point is optional. 206For it to be used, the 207.Dv MC_GETCAPAB 208value must be present in the 209.Fa mc_callbacks 210member. 211For more information on the requirements of the function, see 212.Xr mc_getcapab 9E . 213.Pp 214The 215.Fa mc_open 216member is used to provide specific actions to take when the device is 217opened. 218Note that most device drivers will not have a need to implement this. 219It is not required for this function to be implemented for this device to be 220used with 221.Xr dlpi 4P . 222This entry point is optional. 223For it to be used, the 224.Dv MC_OPEN 225value must be present in the 226.Fa mc_callbacks 227member. 228For more information on the requirements of the function, see 229.Xr mc_open 9E . 230.Pp 231The 232.Fa mc_close 233member is used to provide specific actions to take when the device is 234closed. 235Note that most device drivers will not have a need to implement this. 236It is not required for this function to be implemented for this device to be 237used with 238.Xr dlpi 4P . 239This entry point is optional. 240For it to be used, the 241.Dv MC_CLOSE 242value must be present in the 243.Fa mc_callbacks 244member. 245For more information on the requirements of the function, see 246.Xr mc_close 9E . 247.Pp 248The 249.Fa mc_getprop 250member is used to get the current value of a property from the device. 251A list of properties, their sizes, and their interpretation is available in 252.Xr mac 9E . 253This entry point is optional. 254For it to be used, the 255.Dv MC_GETPROP 256value must be present in the 257.Fa mc_callbacks 258member. 259For more information on the requirements of the function, see 260.Xr mc_getprop 9E . 261.Pp 262The 263.Fa mc_setprop 264member is used to set the value of a device property. 265A list of properties, their sizes, and their interpretation is available in 266.Xr mac 9E . 267This entry point is optional. 268For it to be used, the 269.Dv MC_SETPROP 270value must be present in the 271.Fa mc_callbacks 272member. 273For more information on the requirements of the function, see 274.Xr mc_setprop 9E . 275.Pp 276The 277.Fa mc_propinfo 278member is used to obtain metadata about a property such as its default 279value, whether or not it is writable, and more. 280A list of properties, their sizes, and their interpretation is available in 281.Xr mac 9E . 282This entry point is optional. 283For it to be used, the 284.Dv MC_PROPINFO 285value must be present in the 286.Fa mc_callbacks 287member. 288For more information on the requirements of the function, see 289.Xr mc_propinfo 9E . 290.Ss Required Members 291Many members in the structure are optional; however, the following 292members must be set or a call to 293.Xr mac_register 9F 294will fail. 295.Bl -bullet -offset indent 296.It 297.Fa mc_getstat 298.It 299.Fa mc_start 300.It 301.Fa mc_stop 302.It 303.Fa mc_setpromisc 304.It 305.Fa mc_multicst 306.It 307.Fa mc_tx 308.It 309.Fa mc_unicst 310.El 311.Pp 312Devices which implement the 313.Dv MAC_CAPAB_RINGS 314capability for receive rings must not implement the 315.Fa mc_unicst 316entry point. 317Devices which implement the 318.Dv MAC_CAPAB_RINGS 319capability for transmit rings must not implement the 320.Fa mc_tx 321entry points. 322For more information about the capability, please see 323.Xr mac_capab_rings 9E . 324.Pp 325Generally, a device that implements one of 326.Fa mc_getprop , 327.Fa mc_setprop , 328or 329.Fa mc_propinfo 330will want to implement all three endpoints to ensure that the property 331is fully integrated into user land utilities such as 332.Xr dladm 8 . 333.Sh SEE ALSO 334.Xr dlpi 4P , 335.Xr dladm 8 , 336.Xr mac 9E , 337.Xr mac_capab_rings 9E , 338.Xr mc_close 9E , 339.Xr mc_getcapab 9E , 340.Xr mc_getprop 9E , 341.Xr mc_getstat 9E , 342.Xr mc_ioctl 9E , 343.Xr mc_multicst 9E , 344.Xr mc_open 9E , 345.Xr mc_propinfo 9E , 346.Xr mc_setpromisc 9E , 347.Xr mc_setprop 9E , 348.Xr mc_start 9E , 349.Xr mc_stop 9E , 350.Xr mc_tx 9E , 351.Xr mc_unicst 9E , 352.Xr mac_register 9F , 353.Xr mac_register 9S 354