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 2009 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 * flags Property flags (MAC_PROP_DEFAULT). 432 * sz Size of property in bytes. 433 * val Location to receive property value. 434 * perm Location to receive property permissions (either 435 * MAC_PROP_PERM_READ or MAC_PROP_PERM_RW). 436 * 437 * Returns 438 * 439 * 0 on successful handling of property. 440 * EINVAL if invalid arguments (e.g. a bad size) are supplied. 441 * ENOTSUP if the prooperty is not supported by MII or the PHY. 442 */ 443 int mii_m_getprop(mii_handle_t mii, const char *name, mac_prop_id_t id, 444 uint_t flags, uint_t sz, void *val, uint_t *perm); 445 446 /* 447 * mii_m_setprop 448 * 449 * Used to support the driver's mc_setprop() mac callback, 450 * and only to be called from that function (and without any 451 * locks held). This routine will process all of the properties 452 * that are relevant to MII on behalf of the driver. This will 453 * often result in the PHY being reset. 454 * 455 * Arguments 456 * 457 * mii MII handle. 458 * name Property name. 459 * id Property ID. 460 * sz Size of property in bytes. 461 * val Location of property value. 462 * 463 * Returns 464 * 465 * 0 on successful handling of property. 466 * EINVAL if invalid arguments (e.g. a bad size) are supplied. 467 * ENOTSUP if the prooperty is not supported by MII or the PHY, 468 * or if the property is read-only. 469 */ 470 int mii_m_setprop(mii_handle_t mii, const char *name, mac_prop_id_t id, 471 uint_t sz, const void *val); 472 473 /* 474 * mii_m_getstat 475 * 476 * Used to support the driver's mc_getstat() mac callback for 477 * statistic collection, and only to be called from that function 478 * (without any locks held). This routine will process all of 479 * the statistics that are relevant to MII on behalf of the 480 * driver. 481 * 482 * Arguments 483 * 484 * mii MII handle. 485 * stat Statistic number. 486 * val Location to receive statistic value. 487 * 488 * Returns 489 * 490 * 0 on successful handling of statistic. 491 * ENOTSUP if the statistic is not supported by MII. 492 */ 493 int mii_m_getstat(mii_handle_t mii, uint_t stat, uint64_t *val); 494 495 #endif /* _KERNEL */ 496 497 #ifdef __cplusplus 498 } 499 #endif 500 501 #endif /* _SYS_MII_H */ 502