GLDv2->GLDv3 conversion notes

I was recently asked to provide some notes about GLDv2 to GLDv3 conversion for NIC drivers. Here's a rough draft of them. (This is cut-n-paste from mail I sent to an intern at Sun... I'm posting them here so the knowledge isn't lost.)

It is really helpful if you don't try to implement 100% of the features of GLDv3 in the first pass. (Some of the existing GLDv3 drivers, such as rge, nge, have incorrectly provided stubs for some functions, so don't use those as references.) Specifically I would not attempt to implement mac_resource allocation (MC_RESOURCES, etc.) or multiaddress support.

You really do need to implement VLAN full frame sizes for MTU if your hardware can do it. Almost all NICs can do this. Sometimes the code to do it isn't in any Solaris driver. My preferred reference for alternate code sources is the NetBSD tree, which has an OpenGrok server for their code at http://opengrok.netbsd.org/ Ask me if you have any question about VLANs. It helps if you have a switch where you can test VLAN frames.

With GLDv3, there is no reset function, so you have to figure out how to put that in attach (for both DDI_ATTACH and DDI_RESUME!), or in the mac_start() function.

With GLDv3 the stats are quite different. Pay attention, and look at the headers to figure it out.

Many GLDv2 drivers don't do the mac_link_update() call. You should add those for NWAM, IPMP, and correct kstat reporting.

You should rip out any attempt to log to the console on link up, down, or carrier errors. See PSARC 2007/298 for details.

GLDv3 wants to operate on mblk_t's that are chained by b_next. Often you can use the old functions from a new function that just walks down, or builds up the list (depending on whether its receive or transmit.)

Pay careful attention to locking. Try not to call GLDv3 functions with locks held. (I have been pressing to allow mac_tx_update and mac_link_update be called with driver locks held. Right now its safe, but I can't seem to get a promise from the Nemo group yet.)

You see all those cyclics in some drivers? Try not to use 'em if you don't have to. What I usually do is cheat and use the on-chip timer if I need some kind of time driven functionality.

GLDv3 never explicitly initializes the physical addresses on the NIC. GLDv2 used to always call gldm_set_mac_addr()... so some drivers expect this. You may need to do that yourself in the mac_start() routine.

Anyway, maybe those notes will save someone somewhere else some effort. Or inspire someone to pick up another driver and convert it.