svn commit: r321920 - head/sys/sys

[Konstantin Belousov]

On Thu, Aug 03, 2017 at 01:21:56PM +1000, Bruce Evans wrote:
> It would be better to remove the comments.
> 
> makedev() actually has a man page (a FreeBSD addition makedev(3)).
> This could have been better, and is now out of date.  The largest error
> is that major() is still documented to return a value between 0 and
> 255.  This reduction prevented makedev() being the inverse of
> major()+minor() on arbitrary args.  The man page doesn't claim that
> it is, and barely gives a hint that makedev() can be used to synthesize
> a dev_t from (x, y) provided 0 <= x <= 255.

See below.

diff --git a/share/man/man3/makedev.3 b/share/man/man3/makedev.3
index 87ca953dc79..a54d0590bc5 100644
--- a/share/man/man3/makedev.3
+++ b/share/man/man3/makedev.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd September 28, 2008
+.Dd August 3, 2017
 .Dt MAKEDEV 3
 .Os
 .Sh NAME
@@ -54,11 +54,18 @@ and
 .Fn minor
 macros can be used to obtain the original numbers from the device number
 .Fa dev .
+In other words, for a value
+.Va dev
+of the type
+.Vt dev_t ,
+the assertion
+.Dl dev == makedev(major(dev), minor(dev))
+is valid.
 .Pp
 In previous implementations of
 .Fx
 all block and character devices were uniquely identified by a pair of
-major and minor numbers.
+stable major and minor numbers.
 The major number referred to a certain device class (e.g. disks, TTYs)
 while the minor number identified an instance within the device class.
 Later versions of
@@ -66,7 +73,8 @@ Later versions of
 automatically generate a unique device number for each character device
 visible in
 .Pa /dev/ .
-These numbers are not divided in device classes.
+These numbers are not divided in device classes and are not guaranteed
+to be stable upon reboot or driver reload.
 .Pp
 On
 .Fx
@@ -78,11 +86,9 @@ conventional way.
 .Sh RETURN VALUES
 The
 .Fn major
-macro returns a device major number that has a value between 0 and 255.
-The
+and
 .Fn minor
-macro returns a device minor number whose value can span the complete
-range of an
+macros return numbers whose value can span the complete range of an
 .Vt int .
 .Sh SEE ALSO
 .Xr mknod 2 ,
diff --git a/sys/sys/types.h b/sys/sys/types.h
index 30a08724443..8ea6e146e08 100644
--- a/sys/sys/types.h
+++ b/sys/sys/types.h
@@ -364,9 +364,9 @@ __bitcount64(__uint64_t _x)
 
 #include <sys/select.h>
 
-#define	major(x)	((int)((dev_t)(x) >> 32))	/* major number */
-#define	minor(x)	((int)((x) & 0xffffffff))	/* minor number */
-#define	makedev(x, y)	(((dev_t)(x) << 32) | (unsigned)(y)) /* create dev_t */
+#define	major(x)	((int)((dev_t)(x) >> 32))
+#define	minor(x)	((int)((x) & 0xffffffff))
+#define	makedev(x, y)	(((dev_t)(x) << 32) | (unsigned)(y))
 
 /*
  * These declarations belong elsewhere, but are repeated here and in