include/sys/mii.h

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License (the "License").
   6  * You may not use this file except in compliance with the License.
   7  *
   8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9  * or http://www.opensolaris.org/os/licensing.
  10  * See the License for the specific language governing permissions
  11  * and limitations under the License.
  12  *
  13  * When distributing Covered Code, include this CDDL HEADER in each
  14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15  * If applicable, add the following below this CDDL HEADER, with the
  16  * fields enclosed by brackets "[]" replaced with your own identifying
  17  * information: Portions Copyright [yyyy] [name of copyright owner]
  18  *
  19  * CDDL HEADER END
  20  */
  21 /*
  22  * Copyright 2010 Sun Microsystems, Inc.  All rights reserved.
  23  * Use is subject to license terms.
  24  */
  25
  26 /*
  27  * mii.h
  28  * Generic MII/PHY Support for MAC drivers.
  29  */
  30
  31 #ifndef _SYS_MII_H
  32 #define _SYS_MII_H
  33
  34 #include <sys/mac_provider.h>
  35 #include <sys/netlb.h>
  36
  37 #ifdef  __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 /*
  42  * NOTES
  43  *
  44  * The device driver is required to protect its own registers.  The
  45  * MII common code will call MII entry points asynchronously, from a
  46  * taskq, and holds an internal lock across such calls (except the
  47  * notify entry point).  Therefore, device drivers MUST NOT hold any
  48  * locks across calls into the MII framework.
  49  *
  50  * If a device must be suspended (e.g. due to DDI_SUSPEND) the MII
  51  * layer can be suspended by calling mii_stop().  After this point,
  52  * the monitoring task will be suspended and the driver can be assured
  53  * that MII will not interfere until restarted with mii_start().
  54  *
  55  * Note that monitoring is not started until mii_start() is called.
  56  * The mii_start() function may be called multiple times.  It performs
  57  * an implicit reset of the MII bus and PHY.
  58  *
  59  * Once started, if not already done, a probe of the MII bus is done to
  60  * find a suitable PHY.  If no PHY is found, then you won't have any
  61  * link!  Once a suitable PHY is selected, any other PHYs are isolated and
  62  * powered down.  The device driver can cause MII to re-probe the bus for
  63  * changes to the available PHYs by calling mii_probe().  Note that this
  64  * will also cause a full reset of all PHYs.
  65  *
  66  * The mii_reset entry point, which is optional, is used to notify the
  67  * driver when the MII layer has reset the device.  This can allow
  68  * certain drivers the opportunity to "fix up" things after reset.
  69  * Note however, that when possible, it is better if the logic is
  70  * encoded into a vendor specific PHY module.
  71  */
  72
  73 #ifdef  _KERNEL
  74
  75 typedef struct mii_handle *mii_handle_t;
  76 typedef struct mii_ops mii_ops_t;
  77
  78 struct mii_ops {
  79         int             mii_version;
  80         uint16_t        (*mii_read)(void *, uint8_t, uint8_t);
  81         void            (*mii_write)(void *, uint8_t, uint8_t, uint16_t);
  82         void            (*mii_notify)(void *, link_state_t);
  83         void            (*mii_reset)(void *);
  84 };
  85 #define MII_OPS_VERSION 0
  86
  87 /*
  88  * Support routines.
  89  */
  90
  91 /*
  92  * mii_alloc
  93  *
  94  *      Allocate an MII handle.  Called during driver's attach(9e)
  95  *      handling, this routine is valid in kernel context only.
  96  *
  97  * Arguments
  98  *
  99  *      private         A private state structure, provided back to
 100  *                      entry points.
 101  *      dip             The dev_info node for the MAC driver.
 102  *      ops             Entry points into the MAC driver.
 103  *
 104  * Returns
 105  *      Handle to MII bus on success, NULL on failure.
 106  */
 107 mii_handle_t mii_alloc(void *private, dev_info_t *dip, mii_ops_t *ops);
 108
 109 /*
 110  * mii_alloc
 111  *
 112  *      Allocate an MII handle.  Called during driver's attach(9e)
 113  *      handling, this routine is valid in kernel context only.  This
 114  *      routine is an alternative to mii_alloc() for use when the
 115  *      instance number (PPA) is not the same as the devinfo instance
 116  *      number, and hence needs to be overridden.
 117  *
 118  * Arguments
 119  *
 120  *      private         A private state structure, provided back to
 121  *                      entry points.
 122  *      dip             The dev_info node for the MAC driver.
 123  *      instance        The instance (PPA) of the interface.
 124  *      ops             Entry points into the MAC driver.
 125  *
 126  * Returns
 127  *      Handle to MII bus on success, NULL on failure.
 128  */
 129 mii_handle_t mii_alloc_instance(void *private, dev_info_t *dip, int instance,
 130     mii_ops_t *ops);
 131
 132 /*
 133  * mii_free
 134  *
 135  *      Free an MII handle and associated resources.  Call from
 136  *      detach(9e) handling, this routine is valid in kernel context
 137  *      only.
 138  */
 139 void mii_free(mii_handle_t mii);
 140
 141 /*
 142  * mii_set_pauseable
 143  *
 144  *      Lets the MII know if the MAC layer can support pause or
 145  *      asymetric pause capabilities.  The MII layer will use this to
 146  *      determine what capabilities should be negotiated for (along
 147  *      with user preferences, of course.)  If not called, the MII
 148  *      will assume the device has no support for flow control.
 149  *
 150  * Arguments
 151  *
 152  *      mii             MII handle.
 153  *      cap             B_TRUE if the device supports symmetric of pause.
 154  *      asym            B_TRUE if the device supports asymmetric pause.
 155  */
 156 void mii_set_pauseable(mii_handle_t mii, boolean_t cap, boolean_t asym);
 157
 158 /*
 159  * mii_reset
 160  *
 161  *      Schedules a reset of the MII bus.  Normally not needed, but
 162  *      can be used to perform a full master reset, including
 163  *      rescanning for PHYs.  This function may be called in any
 164  *      context except high level interrupt context, but must be
 165  *      called without any locks held.  The reset will probably not
 166  *      be complete until sometime after the call returns.
 167  *
 168  *      Note that if mii_start has not been called, then the reset
 169  *      will not be performed until _after_ the MII is started.
 170  */
 171 void mii_reset(mii_handle_t mii);
 172
 173
 174 /*
 175  * mii_start
 176  *
 177  *      Starts monitoring of the MII bus.  Normally this is called as
 178  *      a result of a driver's mac_start() entry point, but it may also
 179  *      be called when a PHY needs to be reset or during handling of
 180  *      DDI_RESUME.   This function may be called in any context except
 181  *      high level interrupt context, but
 182  *      must be called without any locks held.
 183  */
 184 void mii_start(mii_handle_t mii);
 185
 186 /*
 187  * mii_stop
 188  *
 189  *      Stops monitoring of the MII bus.  Normally this is called as a
 190  *      result of a driver's mac_stop() entry point.  As a side
 191  *      effect, also isolates and powers down any active PHY.  On
 192  *      return, the MII layer is guaranteed not to be executing any
 193  *      code in the MII entry points.  This function may be called in
 194  *      any context except high level interrupt context, but must be
 195  *      called without any locks held.
 196  */
 197 void mii_stop(mii_handle_t mii);
 198
 199 /*
 200  * mii_resume
 201  *
 202  *      Starts monitoring of the MII bus.  Normally this is called as
 203  *      a part of a driver's DDI_RESUME handling.  This function may
 204  *      be called in any context except high level interrupt context,
 205  *      but must be called without any locks held.
 206  */
 207 void mii_resume(mii_handle_t mii);
 208
 209 /*
 210  * mii_suspend
 211  *
 212  *      Suspends monitoring of the MII bus.  Normally this is called
 213  *      as a part of a driver's DDI_SUSPEND handling.  On return, the
 214  *      MII layer is guaranteed not to be executing any code in the
 215  *      MII entry points.  This function may be called in any context
 216  *      except high level interrupt context, but must be called
 217  *      without any locks held.
 218  */
 219 void mii_suspend(mii_handle_t mii);
 220
 221 /*
 222  * mii_probe
 223  *
 224  *      Used to reset the entire MII bus and probe for PHYs.  This
 225  *      routine should be called if the driver has reason to believe that
 226  *      PHYs have changed.  This is implicitly executed the first time
 227  *      monitoring is started on the MII bus, and normally need not be
 228  *      explicitly called. This function may be called in any context
 229  *      except high level interrupt context, but must be called
 230  *      without any locks held.
 231  */
 232 void mii_probe(mii_handle_t mii);
 233
 234 /*
 235  * mii_check
 236  *
 237  *      Used to alert the MII layer that it should check for changes.
 238  *      This can be called by drivers in response to link status
 239  *      interrupts, for example, giving a quicker response to link
 240  *      status changes without waiting for the MII timer to expire.
 241  *      This function may be called in any context except high level
 242  *      interrupt context, but must be called without any locks held.
 243  */
 244 void mii_check(mii_handle_t mii);
 245
 246 /*
 247  * mii_get_addr
 248  *
 249  *      Used to get the PHY address that is currently active for the MII
 250  *      bus.  This function may be called in any context.
 251  *
 252  * Returns
 253  *
 254  *      The PHY address (0-31) if a PHY is active on the MII bus.  If
 255  *      no PHY is active, -1 is returned.
 256  */
 257 int mii_get_addr(mii_handle_t mii);
 258
 259 /*
 260  * mii_get_id
 261  *
 262  *      Used to get the identifier of the active PHY.  This function
 263  *      may be called in any context.
 264  *
 265  * Returns
 266  *
 267  *      The PHY identifier register contents, encoded with the high
 268  *      order (PHYIDH) bits in the upper word and the low order bits
 269  *      in the lower word.  If no PHY is active, the value -1 will be
 270  *      returned.
 271  */
 272 uint32_t mii_get_id(mii_handle_t mii);
 273
 274 /*
 275  * mii_get_speed
 276  *
 277  *      Used to get the speed of the active PHY.  This function may be
 278  *      called in any context.
 279  *
 280  * Returns
 281  *
 282  *      The speed, in Mbps, if the active PHY has link (10, 100, or 1000),
 283  *      otherwise 0.
 284  */
 285 int mii_get_speed(mii_handle_t mii);
 286
 287 /*
 288  * mii_get_duplex
 289  *
 290  *      Used to get the duplex of the active PHY.  This function may
 291  *      be called in any context.
 292  *
 293  * Returns
 294  *
 295  *      The duplex, if the active PHY has link (LINK_DUPLEX_FULL or
 296  *      LINK_DUPLEX_HALF), otherwise LINK_DUPLEX_UNKNOWN.
 297  */
 298 link_duplex_t mii_get_duplex(mii_handle_t mii);
 299
 300 /*
 301  * mii_get_state
 302  *
 303  *      Used to get the state of the link on the active PHY.  This
 304  *      function may be called in any context.
 305  *
 306  * Returns
 307  *
 308  *      The link state (LINK_STATE_UP or LINK_STATE_DOWN), if known,
 309  *      otherwise LINK_STATE_UNKNOWN.
 310  */
 311 link_state_t mii_get_state(mii_handle_t mii);
 312
 313 /*
 314  * mii_get_flowctrl
 315  *
 316  *      Used to get the state of the negotiated flow control on the
 317  *      active PHY.  This function may be called in any context.
 318  *
 319  * Returns
 320  *
 321  *      The flowctrl state (LINK_FLOWCTRL_NONE, LINK_FLOWCTRL_RX,
 322  *      LINK_FLOWCTRL_TX, or LINK_FLOWCTRL_BI.
 323  */
 324 link_flowctrl_t mii_get_flowctrl(mii_handle_t mii);
 325
 326 /*
 327  * mii_get_loopmodes
 328  *
 329  *      This function is used to support the LB_GET_INFO_SIZE and
 330  *      LB_GET_INFO ioctls.  It probably should not be used outside of
 331  *      that context.  The modes supplied are supported by the MII/PHY.
 332  *      Drivers may wish to add modes for MAC internal loopbacks as well.
 333  *      See <sys/netlb.h> for more information.
 334  *
 335  *      Note that the first item in the modes array will always be the
 336  *      mode to disable the MII/PHY loopback, and will have the value
 337  *      MII_LOOPBACK_NONE.
 338  *
 339  * Arguments
 340  *
 341  *      mii             MII handle.
 342  *      modes           Location to receive an array of loopback modes.
 343  *                      Drivers should ensure that enough room is available.
 344  *                      There will never be more than MII_LOOPBACK_MAX modes
 345  *                      returned.  May be NULL, in which case no data will
 346  *                      be returned to the caller.
 347  *
 348  * Returns
 349  *
 350  *      Count of number of modes available, in no case larger than
 351  *      MII_LOOPBACK_MAX.
 352  */
 353 int mii_get_loopmodes(mii_handle_t mii, lb_property_t *modes);
 354
 355 #define MII_LOOPBACK_MAX        16
 356 #define MII_LOOPBACK_NONE       0
 357
 358 /*
 359  * mii_set_loopback
 360  *
 361  *      Sets the loopback mode, intended for use in support of the
 362  *      LB_SET_MODE ioctl.  The mode value will be one of the values
 363  *      returned in the modes array (see mii_get_loopmodes), or the
 364  *      special value MII_LOOPBACK_NONE to return to normal operation.
 365  *
 366  * Arguments
 367  *
 368  *      mii             MII handle.
 369  *      mode            New loopback mode number; MII_LOOPBACK_NONE indicates
 370  *                      a return to normal operation.
 371  *
 372  * Returns
 373  *
 374  *      Zero on success, or EINVAL if the mode is invalid or unsupported.
 375  */
 376 int mii_set_loopback(mii_handle_t mii, uint32_t mode);
 377
 378 /*
 379  * mii_get_loopback
 380  *
 381  *      Queries the loopback mode, intended for use in support of the
 382  *      LB_GET_MODE ioctl, but may be useful in programming device
 383  *      settings that are sensitive to loopback setting.
 384  *
 385  * Returns
 386  *
 387  *      The current mode number (one of the reported by
 388  *      mii_get_loopmodes), or the special value MII_LOOPBACK_NONE
 389  *      indicating that loopback is not in use.
 390  */
 391 uint32_t mii_get_loopback(mii_handle_t mii);
 392
 393 /*
 394  * mii_m_loop_ioctl
 395  *
 396  *      Used to support the driver's mc_ioctl() for loopback ioctls.
 397  *      If the driver is going to use the loopback optons from the
 398  *      PHY, and isn't adding any MAC level loopback, then this function
 399  *      can handle the entire set of ioctls, removing yet more code from
 400  *      the driver.  Ultimately, this is a very reasonable thing to do,
 401  *      since the PHY level loopback should exercise all of the same
 402  *      MAC level circuitry that a MAC internal loopback would do.
 403  *
 404  * Arguments
 405  *
 406  *      mii             MII handle.
 407  *      wq              The write queue supplied to mc_ioctl().
 408  *      msg             The mblk from the mc_ioctl (contains an iocblk).
 409  *
 410  * Returns
 411  *
 412  *      B_TRUE if the ioctl was handled by the driver.
 413  *      B_FALSE if the ioctl was not handled, and may need to be
 414  *      handled by the driver.
 415  */
 416 boolean_t mii_m_loop_ioctl(mii_handle_t mii, queue_t *wq, mblk_t *msg);
 417
 418 /*
 419  * mii_m_getprop
 420  *
 421  *      Used to support the driver's mc_getprop() mac callback,
 422  *      and only to be called from that function (and without any
 423  *      locks held).  This routine will process all of the properties
 424  *      that are relevant to MII on behalf of the driver.
 425  *
 426  * Arguments
 427  *
 428  *      mii             MII handle.
 429  *      name            Property name.
 430  *      id              Property ID.
 431  *      sz              Size of property in bytes.
 432  *      val             Location to receive property value.
 433  *
 434  * Returns
 435  *
 436  *      0 on successful handling of property.
 437  *      EINVAL if invalid arguments (e.g. a bad size) are supplied.
 438  *      ENOTSUP if the prooperty is not supported by MII or the PHY.
 439  */
 440 int mii_m_getprop(mii_handle_t mii, const char *name, mac_prop_id_t id,
 441     uint_t sz, void *val);
 442
 443 /*
 444  * mii_m_setprop
 445  *
 446  *      Used to support the driver's mc_setprop() mac callback,
 447  *      and only to be called from that function (and without any
 448  *      locks held).  This routine will process all of the properties
 449  *      that are relevant to MII on behalf of the driver.  This will
 450  *      often result in the PHY being reset.
 451  *
 452  * Arguments
 453  *
 454  *      mii             MII handle.
 455  *      name            Property name.
 456  *      id              Property ID.
 457  *      sz              Size of property in bytes.
 458  *      val             Location of property value.
 459  *
 460  * Returns
 461  *
 462  *      0 on successful handling of property.
 463  *      EINVAL if invalid arguments (e.g. a bad size) are supplied.
 464  *      ENOTSUP if the prooperty is not supported by MII or the PHY,
 465  *      or if the property is read-only.
 466  */
 467 int mii_m_setprop(mii_handle_t mii, const char *name, mac_prop_id_t id,
 468     uint_t sz, const void *val);
 469
 470 /*
 471  * mii_m_propinfo
 472  *
 473  *      Used to support the driver's mc_setprop() mac callback,
 474  *      and only to be called from that function (and without any
 475  *      locks held).
 476  *
 477  * Arguments
 478  *
 479  *      mii             MII handle.
 480  *      name            Property name.
 481  *      id              Property ID.
 482  *      prh             Property info handle.
 483  *
 484  */
 485 void mii_m_propinfo(mii_handle_t mii, const char *name, mac_prop_id_t id,
 486     mac_prop_info_handle_t prh);
 487
 488
 489 /*
 490  * mii_m_getstat
 491  *
 492  *      Used to support the driver's mc_getstat() mac callback for
 493  *      statistic collection, and only to be called from that function
 494  *      (without any locks held).  This routine will process all of
 495  *      the statistics that are relevant to MII on behalf of the
 496  *      driver.
 497  *
 498  * Arguments
 499  *
 500  *      mii             MII handle.
 501  *      stat            Statistic number.
 502  *      val             Location to receive statistic value.
 503  *
 504  * Returns
 505  *
 506  *      0 on successful handling of statistic.
 507  *      ENOTSUP if the statistic is not supported by MII.
 508  */
 509 int mii_m_getstat(mii_handle_t mii, uint_t stat, uint64_t *val);
 510
 511 #endif  /* _KERNEL */
 512
 513 #ifdef  __cplusplus
 514 }
 515 #endif
 516
 517 #endif /* _SYS_MII_H */