usr/src/man/man9e/mc_getcapab.9e

   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
  29 illumos DDI specific
  30 .Sh PARAMETERS
  31 .Bl -tag -width Fa
  32 .It Fa driver
  33 A pointer to the driver's private data that was passed in via the
  34 .Sy m_pdata
  35 member of the
  36 .Xr mac_register 9S
  37 structure to the
  38 .Xr mac_register 9F
  39 function.
  40 .It Fa capab
  41 A value which indicates the capability being asked about.
  42 For a full list of capabilities, see the
  43 .Sx CAPABILITIES
  44 section of
  45 .Xr mac 9E .
  46 .It Fa cap_data
  47 Capability specific data that may need to be filled in.
  48 The type of data used is listed in the
  49 .Sx CAPABILITIES
  50 section of
  51 .Xr mac 9E .
  52 .El
  53 .Sh DESCRIPTION
  54 The
  55 .Fn mc_getcapab
  56 entry point is called to determine whether or not a device supports a
  57 specific capability.
  58 The capability in question is specified in
  59 .Fa capab
  60 and the list of possible capabilities is listed in the
  61 .Sx CAPABILITIES
  62 section of
  63 .Xr mac 9E .
  64 .Pp
  65 Capabilities are generally only queried once for a given device.
  66 An instance of a device cannot change whether or not it supports a given
  67 capability after it has been queried by the system.
  68 .Pp
  69 Each capability has its own specific kind of data that a device driver
  70 needs to fill in as part of declaring that it supports a given capability.
  71 That data is present in
  72 .Fa cap_data .
  73 The device driver should cast
  74 .Fa cap_data
  75 to the appropriate structure and fill it in.
  76 The structures to use for a given capability are all listed in the
  77 .Sx CAPABILITIES
  78 section of
  79 .Xr mac 9E .
  80 .Pp
  81 The return value is used to indicate whether or not a device driver
  82 supports the given capability.
  83 If it does, then the device driver should return
  84 .Sy B_TRUE
  85 after filling in
  86 .Fa cap_data .
  87 Otherwise, whenever it encounters an unsupported or unknown capability,
  88 it should return
  89 .Sy B_FALSE .
  90 Many device drivers employ
  91 .Sy switch
  92 statements and return
  93 .Sy B_FALSE
  94 from their default case statement.
  95 The system will present unknown capabilities to device drivers and they must
  96 properly return
  97 .Sy B_FALSE .
  98 .Pp
  99 The driver has access to its soft state by casting the
 100 .Fa driver
 101 argument to the specific structure.
 102 The device driver is responsible for any necessary locking.
 103 .Pp
 104 Many capabilities are related to features of hardware.
 105 However, all hardware and firmware has the possibility of having bugs.
 106 It is recommended that any capability that is supported have some form of
 107 tunable, whether in the form of a
 108 .Sy MAC_PROP_PRIVATE
 109 driver-specific property and/or a
 110 .Xr driver.conf 5
 111 property to disable it.
 112 This way when problems are discovered in the field, they can be worked around
 113 without requiring initial changes to the device driver.
 114 .Sh CONTEXT
 115 This function is generally only called from
 116 .Sy kernel
 117 context.
 118 .Sh RETURN VALUES
 119 If the device driver supports the specified capability
 120 .Fa capab ,
 121 then it should return
 122 .Sy B_TRUE .
 123 Otherwise, it should return
 124 .Sy B_FALSE .
 125 .Sh EXAMPLES
 126 The following example shows how a driver might structure its
 127 .Fn mc_getcapab
 128 entry 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(9F) entry point called.
 139  */
 140
 141 #define EXAMPLE_LSO_MAX         65535
 142
 143 static boolean_t
 144 example_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