Include usage notes in the rest of the endian.h files for consistancy.

1 files changed, 7 insertions, 0 deletions

diff --git a/sys/arch/pmax/include/endian.h b/sys/arch/pmax/include/endian.h
index c2957e659fc..60cac2a0a72 100644
--- a/sys/arch/pmax/include/endian.h
+++ b/sys/arch/pmax/include/endian.h
@@ -75,6 +75,13 @@ __END_DECLS
 
 /*
  * Macros for network/external number representation conversion.
+ *
+ * The way this works is that HTONS(x) modifies x and *can't* be used as
+ * and rvalue i.e.  foo=HTONS(bar) is wrong.  Likewise x=htons(x) should
+ * never be used where HTONS(x) will serve i.e. foo=htons(foo) is wrong.
+ * Failing to observe these rule will result in code that appears to work
+ * and probably does work, but generates gcc warnings on architectures
+ * where the macros are used to optimize away an unneeded conversion.
  */
 #if BYTE_ORDER == BIG_ENDIAN && !defined(lint)
 #define	ntohl(x)	(x)