docs/39214: No my(4) man page

[Tom Rhodes]

On Fri, 16 May 2003 10:53:20 -0700
"Bruce A. Mah" <bmah at freebsd.org> wrote:

> If memory serves me right, Tom Rhodes wrote:
> > On Fri, 16 May 2003 04:27:00 -0700 (PDT)
> > Hiten Pandya <hmp at freebsd.org> wrote:
> > 
> > > Synopsis: No my(4) man page
> > > 
> > > Responsible-Changed-From-To: freebsd-doc->hmp
> > > Responsible-Changed-By: hmp
> > > Responsible-Changed-When: Fri May 16 04:24:42 PDT 2003
> > > Responsible-Changed-Why: 
> > > I have this man page in the works.  It is simple, and not trendy
> > > like other NIC man pages, but it fills the gap:
> > > 
> > > 	http://people.FreeBSD.ORG/~hmp/my.4.txt
> > > 
> > 
> > Need more review?  Note, mii(4) does not exist, its miibus(4), which
> > I wrote and added to the tree a couple of months ago.
> 
> I'll jump in with a few nitpicks.  :-p
> 
> The correspondence between "DEC Tulip NIC chipset" and the dc(4)
> driver in the cross-references is not clear.
> 
> The supported models are not sentences, and therefore should not end
> with full-stops.
> 
> In the HISTORY section, you should say that the my driver *first*
> appeared in FreeBSD 4.6.
> 
> The AUTHORS section could probably be better worded as "The my driver
> was written by Myson Technologies."  If you (hmp) want to give
> yourself credit for the manpage, that's acceptable here.
> 
> I'd also try to turn the BUGS section into a complete sentence.
> 
> Bruce.
> 
> PS.  Yes, I always sign my name in email as though it were a sentence.
> So sue me.  :-)
> 

Oh, we're doing *real* nitpicks?  Well then, I might as well chime in
here then!  Below I've listed several comments.


- My(4) at the top.  This should be MY like many (if not all) of our
driver manual pages (e.g: dc, fxp, miibus, smapi, etc.).

- Can we rephrase under NAME?  Perhaps PCI Ethernet Driver?  It sounds
better when read aloud.

- Something must not have parsed correctly under DESCRIPTION:
The driver provides ...
Could you double check that please?  I would rather it say something
like The .Nm driver provides ... (with applicable spaces of course).

- Under AUTHORS you have 'Myson Technology.' but in NAME you have 'Myson
Technologies', and I'm going to assume that the 'Technologies' is the
correct one.

- Under DESCRIPTION you could put something like:

The
.Nm
driver will probe for a Myson chip, check the PCI vendor and device IDs
against our list of supported devices, and return a device name if we find a match.
If a device is located
.Nm
will attach the interface, allocate softc structures, do ifmedia setup, and
finally complete the Ethernet /
.Xr BPF 4
attach.
During
.Xr BPF 4
attachments, the
.Nm
driver will permit the
.Xr BPF 4
user to see the packet, but will not pass it up to the
.Fn ether_input
layer unless it's a broadcast packet, multicast packet, matches our current
Ethernet address, or the interface is in promiscuous mode.
.Pp
During the main transmit routine, the
.Nm
driver will put pointer to the
.Xr mbuf 9
data regions directly in the transmit lists, thus we avoid
.Xr mbuf 9
copies.
The
.Nm
driver will also save a copy of the pointers because the transmit list fragment
pointers are physical addresses.

This will give a clearer description of at least whats going on in
the background.

- Another thing you could do, to expand on the page a
little bit is add a .Sh FILES section and list the two files:

.Pa /usr/src/sys/dev/my/if_my.c
and
.Pa /usr/src/sys/dev/my/if_myreg.h

and add a small description of them.

- ifmedia (used in the above list) could use a manual page, I've got a
WIP for this.  Actually, I have many WIPs, but I need time to get them
reviewed before the patches are applied.

- This email was not ment to be so long...

--
Tom Rhodes