net/ieee_oui.h: clarify how `OUI_FREEBSD_BASE` is managed

[ngie]

Summary

Note that the FreeBSD Foundation manages the current value
associated with OUI_FREEBSD_BASE.

Trim trailing whitespace in comments in the change while here.

MFC after: 1 week

[kevans]

share/man/man9/ether_gen_addr.9

71 ↗

(On Diff #183710)

This was supposed to serve as a pointer to find more details- the Foundation is infact the arbiter of and entity behind the OUI that we use for this

[ngie]

share/man/man9/ether_gen_addr.9

71 ↗

(On Diff #183710)

This seems like a better spot to document that requirement. Adding this policy detail to a random manpage doesn't help since all manpages would need to do similar to ensure parity:

% git diff sys/net/ieee_oui.h
diff --git a/sys/net/ieee_oui.h b/sys/net/ieee_oui.h
index b5dd9fccefe1..b8cba10d1135 100644
--- a/sys/net/ieee_oui.h
+++ b/sys/net/ieee_oui.h
@@ -30,7 +30,11 @@
  *
  */
 
-/* Organizationally Unique Identifier assigned by IEEE 14 Nov 2013 */
+/**
+ * Organizationally Unique Identifier assigned by IEEE 14 Nov 2013.
+ *
+ * This OUI is managed by the FreeBSD Foundation.
+ */
 #define OUI_FREEBSD_BASE 0x589cfc000000
 #define OUI_FREEBSD(nic) (OUI_FREEBSD_BASE | (nic))

I would be game for referring to OUI_FREEBSD_BASE in this manpage instead of the explicit OUI prefix.

[kevans]

share/man/man9/ether_gen_addr.9

71 ↗

(On Diff #183710)

No objection to that, but this isn't a random manpage- it's the only function that hands MAC addresses out of this OUI, so I'm not sure what you mean by needing to add it to all. It seems incredibly relevant when trying to decide what this KPI is going to generate for you, since we've had a mix of LAA generation things in the past.

[ngie]

share/man/man9/ether_gen_addr.9

71 ↗

(On Diff #183710)

No objection to that, but this isn't a random manpage- it's the only function that hands MAC addresses out of this OUI, so I'm not sure what you mean by needing to add it to all. It seems incredibly relevant when trying to decide what this KPI is going to generate for you, since we've had a mix of LAA generation things in the past.

I see.

Let me step back and give you an idea of how this change "came about".

Running make manlint identities potential issues with mandoc text in manpages. One class of issues that's frequently cited is replacing .Fx with FreeBSD, .Nx with NetBSD, etc. "FreeBSD Foundation" is a complaint for this target because FreeBSD is into the organization string.

My first reaction when I did this was to make the string more generic by removing "FreeBSD" from the manpage entirely, leveraging .Fx alone, since the original description didn't seem accurate to me with my earlier context and it didn't seem to match the constant in the consumed code.

My gut feeling about this is (really) given that this is a specific entity name ("FreeBSD Foundation") that should remain as-is, the issue should be ignored. Moreover, the ability to ignore the issue should be handled within the mandoc linter logic and this should be added to the allowlist.

Suggested next steps: I can make comment edit to just the header, drop the manpage change, and file another issue so that strings like "FreeBSD Foundation" no longer get flagged by make manlint. Does that sound good?

[kevans]

share/man/man9/ether_gen_addr.9

71 ↗

(On Diff #183710)

I think that sounds perfect, thank you!

[ngie]

• Remove manpage portion of the diff.
• Expand on the fact that the FF setup OUI_FREEBSD_BASE in the header, like mentioned earlier.

[ziaee]

This is good information. Can you do something like "OUI_FREEBSD_BASE: Note Foundation management" so that the commit message is still in our easy to scan format?

sys/net/ieee_oui.h

33–36

Why put a second * here? Also why add a blank line?

[ngie]

sys/net/ieee_oui.h

33–36

Why put a second * here?

style(9) says that multi-line C quotes should be written this way.

Also why add a blank line?

I can remove the blank line.

[ngie]

Tweak comment wording

[ziaee]

sys/net/ieee_oui.h

33–36

In my style(9) in HEAD there is only one *:

/*
 * Multi-line comments look like this.  Make them real sentences.  Fill
 * them so they look like real paragraphs.
 */

[ngie]

sys/net/ieee_oui.h

33–36

In my style(9) in HEAD there is only one *:

/*
 * Multi-line comments look like this.  Make them real sentences.  Fill
 * them so they look like real paragraphs.
 */

style(9) changed. I'll update the comment to be consistent with the others/the new guidance.

[ngie]

Normalize multiline comment header

[ngie]

share/man/man9/ether_gen_addr.9

71 ↗

(On Diff #183710)

I think that sounds perfect, thank you!

Tracking in https://github.com/ngie-eign/freebsd-src.project-tracking/issues/3 .