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