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