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