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 June 02, 2016 15.Dt MC_GETCAPAB 9E 16.Os 17.Sh NAME 18.Nm mc_getcapab 19.Nd get device capabilities 20.Sh SYNOPSIS 21.In sys/mac_provider.h 22.Ft boolean_t 23.Fo prefix_m_getcapab 24.Fa "void *driver" 25.Fa "mac_capab_t capab" 26.Fa "void *cap_data" 27.Fc 28.Sh INTERFACE LEVEL 29illumos DDI specific 30.Sh PARAMETERS 31.Bl -tag -width Fa 32.It Fa driver 33A pointer to the driver's private data that was passed in via the 34.Sy m_pdata 35member of the 36.Xr mac_register 9S 37structure to the 38.Xr mac_register 9F 39function. 40.It Fa capab 41A value which indicates the capability being asked about. 42For a full list of capabilities, see the 43.Sx CAPABILITIES 44section of 45.Xr mac 9E . 46.It Fa cap_data 47Capability specific data that may need to be filled in. 48The type of data used is listed in the 49.Sx CAPABILITIES 50section of 51.Xr mac 9E . 52.El 53.Sh DESCRIPTION 54The 55.Fn mc_getcapab 56entry point is called to determine whether or not a device supports a 57specific capability. 58The capability in question is specified in 59.Fa capab 60and the list of possible capabilities is listed in the 61.Sx CAPABILITIES 62section of 63.Xr mac 9E . 64.Pp 65Capabilities are generally only queried once for a given device. 66An instance of a device cannot change whether or not it supports a given 67capability after it has been queried by the system. 68.Pp 69Each capability has its own specific kind of data that a device driver 70needs to fill in as part of declaring that it supports a given capability. 71That data is present in 72.Fa cap_data . 73The device driver should cast 74.Fa cap_data 75to the appropriate structure and fill it in. 76The structures to use for a given capability are all listed in the 77.Sx CAPABILITIES 78section of 79.Xr mac 9E . 80.Pp 81The return value is used to indicate whether or not a device driver 82supports the given capability. 83If it does, then the device driver should return 84.Sy B_TRUE 85after filling in 86.Fa cap_data . 87Otherwise, whenever it encounters an unsupported or unknown capability, 88it should return 89.Sy B_FALSE . 90Many device drivers employ 91.Sy switch 92statements and return 93.Sy B_FALSE 94from their default case statement. 95The system will present unknown capabilities to device drivers and they must 96properly return 97.Sy B_FALSE . 98.Pp 99The driver has access to its soft state by casting the 100.Fa driver 101argument to the specific structure. 102The device driver is responsible for any necessary locking. 103.Pp 104Many capabilities are related to features of hardware. 105However, all hardware and firmware has the possibility of having bugs. 106It is recommended that any capability that is supported have some form of 107tunable, whether in the form of a 108.Sy MAC_PROP_PRIVATE 109driver-specific property and/or a 110.Xr driver.conf 5 111property to disable it. 112This way when problems are discovered in the field, they can be worked around 113without requiring initial changes to the device driver. 114.Sh CONTEXT 115This function is generally only called from 116.Sy kernel 117context. 118.Sh RETURN VALUES 119If the device driver supports the specified capability 120.Fa capab , 121then it should return 122.Sy B_TRUE . 123Otherwise, it should return 124.Sy B_FALSE . 125.Sh EXAMPLES 126The following example shows how a driver might structure its 127.Fn mc_getcapab 128entry point. 129.Bd -literal 130#include <sys/types.h> 131#include <sys/mac_provider.h> 132 133/* 134 * Note, this example merely shows the structure of the function. For 135 * the purpose of this example, we assume that we have a device which 136 * has members that indicate whether the various capabilities have been 137 * enabled and that they are read-only after the driver has had its 138 * mc_start(9E) entry point called. 139 */ 140 141#define EXAMPLE_LSO_MAX 65535 142 143static boolean_t 144example_m_getcapab(void *arg, mac_capab_t cap, void *cap_data) 145{ 146 example_t *ep = arg; 147 148 switch (cap) { 149 case MAC_CAPAB_HCKSUM: { 150 uint32_t *txflags = cap_data; 151 152 /* 153 * The actual flags used here should be replaced with 154 * what the device actually supports. If the device 155 * doesn't support checksums, then this case statement 156 * shouldn't exist. 157 */ 158 *txflags = 0; 159 if (ep->ep_tx_hcksum_enable == B_TRUE) 160 *txflags = HCKSUM_IPHDRCKSUM; 161 break; 162 } 163 164 case MAC_CAPAB_LSO: { 165 mac_capab_lso_t *lso = cap_data; 166 167 if (ep->ep_lso_enable == B_TRUE) { 168 lso->lso_flags = LSO_TX_BASIC_TCP_IPV4; 169 lso->lso_basic_tcp_ipv4.lso_max = EXAMPLE_LSO_MAX; 170 } else { 171 return (B_FALSE); 172 } 173 break; 174 } 175 176 default: 177 return (B_FALSE); 178 } 179 180 return (B_TRUE); 181} 182.Ed 183.Sh SEE ALSO 184.Xr mac 9E , 185.Xr mac_register 9F , 186.Xr mac_register 9S 187