bus: Document special ranges of IVARs

Some IVAR indices are special in that they have global meaning across
multiple buses where as other IVARs are always private to the local bus.
Try to document this a bit and add constants for the various ranges to
avoid future conflicts.

This is a no-op, but IVAR indices are now generally defined as enums
as that makes it easier to define them in terms of ranges.

Reviewed by:	imp, royger, andrew
Differential Revision:	https://reviews.freebsd.org/D54159

sys/arm/arm/gic_common.h

@@ -35,10 +35,12 @@ struct arm_gic_range {
 	uint64_t size;
 };
 
-#define	GIC_IVAR_HW_REV		500
-#define	GIC_IVAR_BUS		501
-#define	GIC_IVAR_VGIC		502
-#define	GIC_IVAR_SUPPORT_LPIS	503
+enum {
+	GIC_IVAR_HW_REV = BUS_IVARS_GIC,
+	GIC_IVAR_BUS,
+	GIC_IVAR_VGIC,
+	GIC_IVAR_SUPPORT_LPIS
+};
 
 /* GIC_IVAR_BUS values */
 #define	GIC_BUS_UNKNOWN		0

sys/arm64/arm64/gic_v3_var.h

@@ -109,10 +109,12 @@ struct gic_v3_devinfo {
 MALLOC_DECLARE(M_GIC_V3);
 
 /* ivars */
-#define	GICV3_IVAR_NIRQS	1000
-/* 1001 was GICV3_IVAR_REDIST_VADDR */
-#define	GICV3_IVAR_REDIST	1002
-#define	GICV3_IVAR_FLAGS	1003
+enum {
+	GICV3_IVAR_NIRQS = BUS_IVARS_GICV3,
+	_GICV3_IVAR_REDIST_VADDR,	/* unused */
+	GICV3_IVAR_REDIST,
+	GICV3_IVAR_FLAGS,
+};
 
 __BUS_ACCESSOR(gicv3, nirqs, GICV3, NIRQS, u_int);
 __BUS_ACCESSOR(gicv3, redist, GICV3, REDIST, void *);

sys/dev/acpica/acpivar.h

@@ -277,11 +277,13 @@ extern int	acpi_override_isa_irq_polarity;
  * interface compatibility with ISA drivers which can also
  * attach to ACPI.
  */
-#define ACPI_IVAR_HANDLE	0x100
-#define ACPI_IVAR_UNUSED	0x101	/* Unused/reserved. */
-#define ACPI_IVAR_PRIVATE	0x102
-#define ACPI_IVAR_FLAGS		0x103
-#define	ACPI_IVAR_DOMAIN	0x104
+enum {
+	ACPI_IVAR_HANDLE = BUS_IVARS_ACPI,
+	ACPI_IVAR_UNUSED,		/* Unused/reserved. */
+	ACPI_IVAR_PRIVATE,
+	ACPI_IVAR_FLAGS,
+	ACPI_IVAR_DOMAIN
+};
 
 /*
  * ad_domain NUMA domain special value.

sys/dev/atkbdc/atkbdcreg.h

@@ -215,7 +215,7 @@ typedef struct atkbdc_softc {
 } atkbdc_softc_t; 
 
 enum kbdc_device_ivar {
-	KBDC_IVAR_VENDORID,
+	KBDC_IVAR_VENDORID = BUS_IVARS_PRIVATE,
 	KBDC_IVAR_SERIAL,
 	KBDC_IVAR_LOGICALID,
 	KBDC_IVAR_COMPATID, 

sys/dev/bhnd/bhnd.h

@@ -60,7 +60,7 @@
  * bhnd child instance variables
  */
 enum bhnd_device_vars {
-	BHND_IVAR_VENDOR,	/**< Designer's JEP-106 manufacturer ID. */
+	BHND_IVAR_VENDOR = BUS_IVARS_PRIVATE,	/**< Designer's JEP-106 manufacturer ID. */
 	BHND_IVAR_DEVICE,	/**< Part number */
 	BHND_IVAR_HWREV,	/**< Core revision */
 	BHND_IVAR_DEVICE_CLASS,	/**< Core class (@sa bhnd_devclass_t) */

sys/dev/fdc/fdcvar.h

@@ -69,7 +69,7 @@ struct fdc_data {
 };
 
 enum fdc_device_ivars {
-	FDC_IVAR_FDUNIT,
+	FDC_IVAR_FDUNIT = BUS_IVARS_PRIVATE,
 	FDC_IVAR_FDTYPE,
 };
 

sys/dev/gpio/gpiobusvar.h

@@ -109,7 +109,7 @@ struct gpiobus_ivar
 };
 
 enum gpiobus_ivars {
-	GPIOBUS_IVAR_NPINS	= 10500,
+	GPIOBUS_IVAR_NPINS	= BUS_IVARS_GPIOBUS,
 	GPIOBUS_IVAR_PINS,
 };
 

sys/dev/hid/hidbus.h

@@ -27,7 +27,7 @@
 #define _HID_HIDBUS_H_
 
 enum {
-	HIDBUS_IVAR_USAGE,
+	HIDBUS_IVAR_USAGE = BUS_IVARS_PRIVATE,
 	HIDBUS_IVAR_INDEX,
 	HIDBUS_IVAR_FLAGS,
 #define	HIDBUS_FLAG_AUTOCHILD	(0<<1)	/* Child is autodiscovered */

sys/dev/iicbus/iicbus.h

@@ -57,7 +57,7 @@ struct iicbus_ivar
 
 /* Value of 0x100 is reserved for ACPI_IVAR_HANDLE used by acpi_iicbus */
 enum {
-	IICBUS_IVAR_ADDR		/* Address or base address */
+	IICBUS_IVAR_ADDR = BUS_IVARS_PRIVATE	/* Address or base address */
 };
 
 #define IICBUS_ACCESSOR(A, B, T)					\

sys/dev/mii/miivar.h

@@ -250,7 +250,7 @@ struct mii_phydesc {
 	(*(p)->mii_funcs->pf_reset)(p)
 
 enum miibus_device_ivars {
-	MIIBUS_IVAR_FLAGS
+	MIIBUS_IVAR_FLAGS = BUS_IVARS_PRIVATE
 };
 
 /*

sys/dev/mmc/mmcbrvar.h

@@ -60,7 +60,7 @@
 #include "mmcbr_if.h"
 
 enum mmcbr_device_ivars {
-    MMCBR_IVAR_BUS_TYPE,
+    MMCBR_IVAR_BUS_TYPE = BUS_IVARS_PRIVATE,
     MMCBR_IVAR_BUS_MODE,
     MMCBR_IVAR_BUS_WIDTH,
     MMCBR_IVAR_CHIP_SELECT,

sys/dev/mmc/mmcvar.h

@@ -56,7 +56,7 @@
 #define DEV_MMC_MMCVAR_H
 
 enum mmc_device_ivars {
-    MMC_IVAR_SPEC_VERS,
+    MMC_IVAR_SPEC_VERS = BUS_IVARS_PRIVATE,
     MMC_IVAR_DSR_IMP,
     MMC_IVAR_MEDIA_SIZE,
     MMC_IVAR_RCA,

sys/dev/nvdimm/nvdimm_var.h

@@ -79,7 +79,7 @@ _Static_assert(sizeof(struct nvdimm_label) == 256, "Incorrect layout");
 typedef uint32_t nfit_handle_t;
 
 enum nvdimm_acpi_ivar {
-	NVDIMM_ROOT_IVAR_ACPI_HANDLE,
+	NVDIMM_ROOT_IVAR_ACPI_HANDLE = BUS_IVARS_PRIVATE,
 	NVDIMM_ROOT_IVAR_DEVICE_HANDLE,
 	NVDIMM_ROOT_IVAR_MAX,
 };

sys/dev/ow/ow.h

@@ -27,7 +27,7 @@
 #define DEV_OW_OW_H 1
 
 enum ow_device_ivars {
-	OW_IVAR_FAMILY,
+	OW_IVAR_FAMILY = BUS_IVARS_PRIVATE,
 	OW_IVAR_ROMID
 };
 

sys/dev/pccard/pccardvar.h

@@ -191,7 +191,7 @@ int pccard_select_cfe(device_t dev, int entry);
 
 /* ivar interface */
 enum {
-	PCCARD_IVAR_ETHADDR,	/* read ethernet address from CIS tupple */
+	PCCARD_IVAR_ETHADDR = BUS_IVARS_PRIVATE, /* read ethernet address from CIS tupple */
 	PCCARD_IVAR_VENDOR,
 	PCCARD_IVAR_PRODUCT,
 	PCCARD_IVAR_PRODEXT,

sys/dev/pci/pcivar.h

@@ -340,7 +340,7 @@ struct pci_devinfo {
 #include "pci_if.h"
 
 enum pci_device_ivars {
-    PCI_IVAR_SUBVENDOR,
+    PCI_IVAR_SUBVENDOR = BUS_IVARS_PRIVATE,
     PCI_IVAR_SUBDEVICE,
     PCI_IVAR_VENDOR,
     PCI_IVAR_DEVICE,
@@ -414,7 +414,7 @@ pci_write_config(device_t dev, int reg, uint32_t val, int width)
 
 /*typedef enum pci_device_ivars pcib_device_ivars;*/
 enum pcib_device_ivars {
-	PCIB_IVAR_DOMAIN,
+	PCIB_IVAR_DOMAIN = BUS_IVARS_PRIVATE,
 	PCIB_IVAR_BUS
 };
 

sys/dev/ppbus/ppbconf.h

@@ -178,7 +178,9 @@ struct ppb_context {
 /*
  * List of IVARS available to ppb device drivers
  */
-#define PPBUS_IVAR_MODE 0
+enum {
+	PPBUS_IVAR_MODE = BUS_IVARS_PRIVATE
+};
 
 /* other fields are reserved to the ppbus internals */
 
@@ -208,9 +210,11 @@ struct ppb_device {
 #define EPP_1_7		0x1
 
 /* Parallel Port Chipset IVARS */		/* elsewhere XXX */
-#define PPC_IVAR_EPP_PROTO	0
-#define PPC_IVAR_LOCK		1
-#define PPC_IVAR_INTR_HANDLER	2
+enum {
+	PPC_IVAR_EPP_PROTO = BUS_IVARS_PRIVATE,
+	PPC_IVAR_LOCK,
+	PPC_IVAR_INTR_HANDLER
+};
 
 /*
  * Maximum size of the PnP info string

sys/dev/puc/puc_bus.h

@@ -32,8 +32,10 @@
 #include <sys/serial.h>
 #include <serdev_if.h>
 
-#define	PUC_IVAR_CLOCK		0
-#define	PUC_IVAR_TYPE		1
+enum {
+	PUC_IVAR_CLOCK = BUS_IVARS_PRIVATE,
+	PUC_IVAR_TYPE
+};
 
 /* Port types. */
 #define	PUC_TYPE_SERIAL		1

sys/dev/pwm/pwmbus.h

@@ -38,7 +38,7 @@ struct pwmbus_ivars {
 };
 
 enum {
-	PWMBUS_IVAR_CHANNEL,	/* Channel used by child dev */
+	PWMBUS_IVAR_CHANNEL = BUS_IVARS_PRIVATE, /* Channel used by child dev */
 };
 
 #define PWMBUS_ACCESSOR(A, B, T)					\

sys/dev/quicc/quicc_bus.h

@@ -29,9 +29,11 @@
 #ifndef _DEV_QUICC_BUS_H_
 #define	_DEV_QUICC_BUS_H_
 
-#define	QUICC_IVAR_CLOCK	1	/* The CPM clock. */
-#define	QUICC_IVAR_BRGCLK	2	/* The BRG clock affected by SCCR. */
-#define	QUICC_IVAR_DEVTYPE	3
+enum {
+	QUICC_IVAR_CLOCK = BUS_IVARS_PRIVATE + 1,	/* The CPM clock. */
+	QUICC_IVAR_BRGCLK,		/* The BRG clock affected by SCCR. */
+	QUICC_IVAR_DEVTYPE
+};
 
 /* Device types. */
 #define	QUICC_DEVTYPE_SCC	1

sys/dev/scc/scc_bus.h

@@ -32,12 +32,14 @@
 #include <sys/serial.h>
 #include <serdev_if.h>
 
-#define	SCC_IVAR_CHANNEL	0
-#define	SCC_IVAR_CLASS		1
-#define	SCC_IVAR_CLOCK		2
-#define	SCC_IVAR_MODE		3
-#define	SCC_IVAR_REGSHFT	4
-#define	SCC_IVAR_HWMTX		5
+enum {
+	SCC_IVAR_CHANNEL = BUS_IVARS_PRIVATE,
+	SCC_IVAR_CLASS,
+	SCC_IVAR_CLOCK,
+	SCC_IVAR_MODE,
+	SCC_IVAR_REGSHFT,
+	SCC_IVAR_HWMTX
+};
 
 /* Hardware class -- the SCC type. */
 #define	SCC_CLASS_UNUSED	0

sys/dev/sdio/sdiob.h

@@ -64,7 +64,7 @@
 #ifdef _SYS_BUS_H_
 /* Ivars for sdiob. */
 enum sdiob_dev_enum {
-	SDIOB_IVAR_SUPPORT_MULTIBLK,
+	SDIOB_IVAR_SUPPORT_MULTIBLK = BUS_IVARS_PRIVATE,
 	SDIOB_IVAR_FUNCTION,
 	SDIOB_IVAR_FUNCNUM,
 	SDIOB_IVAR_CLASS,

sys/dev/smbus/smbconf.h

@@ -75,7 +75,7 @@
  * ivars codes
  */
 enum smbus_ivars {
-    SMBUS_IVAR_ADDR,	/* slave address of the device */
+	SMBUS_IVAR_ADDR = BUS_IVARS_PRIVATE, /* slave address of the device */
 };
 
 int	smbus_request_bus(device_t, device_t, int);

sys/dev/sound/pci/hda/hdac.h

@@ -982,7 +982,7 @@ typedef int nid_t;
  ****************************************************************************/
 
 enum hdac_device_ivars {
-    HDA_IVAR_CODEC_ID,
+    HDA_IVAR_CODEC_ID = BUS_IVARS_PRIVATE,
     HDA_IVAR_NODE_ID,
     HDA_IVAR_VENDOR_ID,
     HDA_IVAR_DEVICE_ID,

sys/dev/spibus/spibusvar.h

@@ -48,7 +48,7 @@ struct spibus_ivar
 #define	SPIBUS_CS_HIGH	(1U << 31)
 
 enum {
-	SPIBUS_IVAR_CS,		/* chip select that we're on */
+	SPIBUS_IVAR_CS = BUS_IVARS_PRIVATE,	/* chip select that we're on */
 	SPIBUS_IVAR_MODE,	/* SPI mode (0-3) */
 	SPIBUS_IVAR_CLOCK,	/* maximum clock freq for device */
 	SPIBUS_IVAR_CS_DELAY,	/* delay in microseconds after toggling chip select */

sys/dev/superio/superio.h

@@ -60,7 +60,7 @@ device_t superio_find_dev(device_t superio, superio_dev_type_t type,
     int ldn);
 
 enum superio_ivars {
-	SUPERIO_IVAR_LDN =	10600,
+	SUPERIO_IVAR_LDN =	BUS_IVARS_SUPERIO,
 	SUPERIO_IVAR_TYPE,
 	SUPERIO_IVAR_IOBASE,
 	SUPERIO_IVAR_IOBASE2,

sys/dev/virtio/virtio.h

@@ -53,13 +53,15 @@ struct vq_alloc_info;
 /*
  * VirtIO instance variables indices.
  */
-#define VIRTIO_IVAR_DEVTYPE		1
-#define VIRTIO_IVAR_FEATURE_DESC	2
-#define VIRTIO_IVAR_VENDOR		3
-#define VIRTIO_IVAR_DEVICE		4
-#define VIRTIO_IVAR_SUBVENDOR		5
-#define VIRTIO_IVAR_SUBDEVICE		6
-#define VIRTIO_IVAR_MODERN		7
+enum {
+	VIRTIO_IVAR_DEVTYPE = BUS_IVARS_PRIVATE + 1,
+	VIRTIO_IVAR_FEATURE_DESC,
+	VIRTIO_IVAR_VENDOR,
+	VIRTIO_IVAR_DEVICE,
+	VIRTIO_IVAR_SUBVENDOR,
+	VIRTIO_IVAR_SUBDEVICE,
+	VIRTIO_IVAR_MODERN
+};
 
 struct virtio_feature_desc {
 	uint64_t	 vfd_val;

sys/isa/isavar.h

@@ -103,7 +103,7 @@ struct isa_pnp_id {
 };
 
 enum isa_device_ivars {
-	ISA_IVAR_PORT,
+	ISA_IVAR_PORT = BUS_IVARS_PRIVATE,
 	ISA_IVAR_PORT_0 = ISA_IVAR_PORT,
 	ISA_IVAR_PORT_1,
 	ISA_IVAR_PORTSIZE,

sys/powerpc/ps3/ps3bus.h

@@ -29,7 +29,7 @@
 #define _POWERPC_PS3_PS3BUS_H
 
 enum {
-	PS3BUS_IVAR_BUS,
+	PS3BUS_IVAR_BUS = BUS_IVARS_PRIVATE,
 	PS3BUS_IVAR_DEVICE,
 	PS3BUS_IVAR_BUSTYPE,
 	PS3BUS_IVAR_DEVTYPE,

sys/powerpc/psim/iobusvar.h

@@ -35,7 +35,7 @@
  */
 
 enum iobus_ivars {
-        IOBUS_IVAR_NODE,
+        IOBUS_IVAR_NODE = BUS_IVARS_PRIVATE,
         IOBUS_IVAR_NAME,
 	IOBUS_IVAR_NREGS,
 	IOBUS_IVAR_REGS,

sys/sys/bus.h

@@ -297,6 +297,22 @@ enum intr_polarity {
 	INTR_POLARITY_LOW = 2
 };
 
+/**
+ * Bus drivers may maintain a set of bus-specific instance variables
+ * for each child device.  The BUS_READ_IVAR/BUS_WRITE_IVAR API can be
+ * used to access these variables using an index value.  Some index
+ * values are private to a single bus and should be defined in the
+ * private range.  Other index values are shared by multiple busses
+ * and must have the same meaning in all bus drivers.
+ */
+
+#define	BUS_IVARS_PRIVATE	0x0	/* private variables */
+#define	BUS_IVARS_ACPI		0x100
+#define	BUS_IVARS_GIC		500
+#define	BUS_IVARS_GICV3		1000
+#define	BUS_IVARS_GPIOBUS	10500
+#define	BUS_IVARS_SUPERIO	10600
+
 /**
  * CPU sets supported by bus_get_cpus().  Note that not all sets may be
  * supported for a given device.  If a request is not supported by a

sys/sys/cpu.h

@@ -35,10 +35,12 @@
  * CPU device support.
  */
 
-#define CPU_IVAR_PCPU		1
-#define CPU_IVAR_NOMINAL_MHZ	2
-#define CPU_IVAR_CPUID_SIZE	3
-#define CPU_IVAR_CPUID		4
+enum {
+	CPU_IVAR_PCPU = BUS_IVARS_PRIVATE + 1,
+	CPU_IVAR_NOMINAL_MHZ,
+	CPU_IVAR_CPUID_SIZE,
+	CPU_IVAR_CPUID
+};
 
 static __inline struct pcpu *
 cpu_get_pcpu(device_t dev)

sys/x86/include/legacyvar.h

@@ -30,7 +30,7 @@
 #define	_X86_LEGACYVAR_H_
 
 enum legacy_device_ivars {
-	LEGACY_IVAR_PCIDOMAIN,
+	LEGACY_IVAR_PCIDOMAIN = BUS_IVARS_PRIVATE,
 	LEGACY_IVAR_PCIBUS,
 	LEGACY_IVAR_PCISLOT,
 	LEGACY_IVAR_PCIFUNC

sys/xen/xenbus/xenbusvar.h

@@ -55,7 +55,7 @@ enum {
 	/**
 	 * Path of this device node.
 	 */
-	XENBUS_IVAR_NODE,
+	XENBUS_IVAR_NODE = BUS_IVARS_PRIVATE,
 
 	/**
 	 * The device type (e.g. vif, vbd).