Prior to IRIX 6.4, the minor device number served as an argument to help the device driver distinguish one device from another. Many devices can have the same major number and be serviced by the same driver. Using the minor number, the driver could distinguish the particular device being serviced.

Some device drivers treated the minor device number as a logical unit number, while other drivers used it to contain multiple, encoded bit fields. For example:

With STREAMS drivers, the minor device number can be chosen arbitrarily during a CLONE open—see “Support for CLONE Drivers” in Chapter 22.

Beginning with IRIX 6.4, the minor device number has little importance because the driver has a direct way to distinguish each device and its special needs, through the hardware graph (see “Hardware Graph”.)

The minor number in device special files in /hw is an arbitrary integer with no relation to the device itself. The device special files in /hw are created dynamically, by the device drivers, as the devices are attached. The device driver stores any information it needs to distinguish one device from another, directly in the device special file itself. When a process opens a device special file in /hw (or a name in /dev that is a symbolic link to /hw), the driver can retrieve the information directly, without needing to decode the minor number.

Conventions for the format of device special filenames are spelled out in the following reference pages: intro(7) , dks(7) , dsreq(7) , and tps(7) . For example, the components of a disk device name in /dev/dsk include

Programs throughout the system rely on the conventions for these device names. In addition, by convention the associated major and minor numbers agree with the names. For example, the logical unit and partition numbers that appear in a disk name are also encoded into the minor number.

Beginning with IRIX 6.4, these highly-compressed conventional names are unpacked into longer pathnames in the /hw filesystem. However, the older, encoded names in /dev are retained for compatibility and portability.

The conventions for all the IRIX device special names are written into the script /dev/MAKEDEV. This is a make file, but unlike most make files, it is not used to compile executable programs. It contains the logic to prepare device special names and their associated major and minor numbers and file permissions.

The MAKEDEV script is executed during IRIX startup from a script in /etc/rc2.d. It is executed after all device drivers have been initialized, so it can use the output of the hinv command to construct device names to suit the actual configuration.

The system administrator can invoke MAKEDEV to construct device special files. Administrator use of MAKEDEV is described in IRIX Admin: System Configuration and Operation.

You or a system administrator can create device special files explicitly using the commands mknod or install. Either command can be used in a make file such as you might create as part of the installation script for a product.

For details of these commands, see the install(1) and mknod(1M) reference pages, and IRIX Admin: System Configuration and Operation. The following is a hypothetical example of install:

# install -m 644 -u root -g sys -root /dev -chr 62,0 

The -chr option specifies a character device, and 62,0 are the major and minor device numbers, respectively.

---

Tip: The mknod command is portable, being used in most UNIX systems. The install command is unique to IRIX, and has a number of features and uses beyond those of mknod. Examples of both can be found by reading /dev/MAKEDEV.

---

“In-memory” means that the hwgraph is contained in kernel memory. It is reconstructed dynamically in memory each time the system boots up, and is kept current in memory as the hardware configuration changes.

“Graph-structured” means that the hwgraph is topologically a directed graph, consisting of a set of “vertexes” (points) that represent devices, and “edges” (lines) that connect the vertexes. Each edge is a one-way linkage from a source vertex to a target vertex (this is the definition of a directed graph). Each edge has a label, a character string that names the edge. A small part of a typical hwgraph is depicted in Figure 2-1.

Figure 2-1. Part of a Typical Hwgraph

Figure 2-1 shows the part of the graph that represents block-mode and character-mode access to the whole-volume partition of a disk. The more familiar path notation for the same graph would be as follows:

/hw/module/1/io/pci/slot/0/scsi_ctlr/0/target/1/lun/0/disk/volume/char
/hw/module/1/io/pci/slot/0/scsi_ctlr/0/target/1/lun/0/disk/volume/block
/hw/module/1/io/dks0d0vol/block
/hw/module/1/io/dks0d0vol/char

Figure 2-1 is color-coded to show when the parts of graph are built:

An edge in the hwgraph originates in one vertex (the source vertex) and points to another vertex (the target vertex). The only property of an edge is its label.

A vertex in the hwgraph stores information about an addressable unit of hardware in the system. A vertex can contain the following kinds of information:

Not all vertexes have all this information.

The basic hwgraph—as constructed by the kernel and by built-in drivers such as the PCI bus adapter—is highly detailed and explicit, and is generally tree-structured. However, kernel-level drivers are free to add edges between any two vertexes. A driver can add extra edges in order to provide short-circuit paths for convenient access to vertexes deep in the hwgraph.

Many device drivers distributed with IRIX create convenience vertexes and edges; and device drivers provided by OEMs are welcome to do so as well. One problem is that often a driver needs to label a convenience edge with a unique number—a controller number, a port number, or a line number of some kind. At the time a driver is initializing and creating vertexes, the total hardware complement is not known and it is impossible to decide which number of this kind to use. This problem is alleviated by a program like ioconfig; see “Using ioconfig for Global Controller Numbers”.

Every vertex has one implicit edge with the label “..” which leads back to a parent vertex. Every vertex has one implicit edge with the label “.” which leads to the vertex itself. This is deliberately the same convention used in a filesystem, where every directory contains “..” and “.” entries. No other edges are required.

A vertex that has only the implicit edges is a leaf vertex. A leaf vertex can stand for a device, so that a user process can name a leaf vertex in an open() call in order to open the device. A user process cannot open a non-leaf vertex, just as a process cannot open a directory as a file.

Using database terminology, the hardware inventory consists of a single table with the following columns:

Of these values,

The hinv command formats all or selected rows of the inventory table for display (see the hinv(1) reference page), translating the numbers to readable form. The user or system administrator can use command options to select a class of entries or certain specific device types by name. The class or type can be qualified with a unit number and a controller number. For example, the following command displays information about disk 4 on controller 1:

hinv -c disk -b 1 -u 4 

You can use hinv to check the result of installing new hardware. The new hardware should show up in the report after the system is booted following installation, provided that the associated device driver was called and was written correctly.

A full inventory report (hinv -mv) is almost mandatory documentation for a software problem report, either submitted by your user to you, or by you to Silicon Graphics.

Within a shell script, you can test the output of hinv most conveniently in the command exit status. The command sets exit status of 0 when it finds or reports any items. It sets status of 1 when it finds no items. The code in Example 2-1 could be used in a shell script to test the existence of a disk controller.

if hinv -s -c disk -b 1;
   then ;
   else echo No second disk controller;
fi ;

You can access the inventory table in a C program using the functions documented in the getinvent(3) reference page. The only access method supported is a sequential scan over the table, viewing all entries. Three functions permit access:

These functions use static variables and should only be used by a single process within an address space. Reentrant forms of the same functions, which can safely be used in a multithreaded process, are also available (see getinvent(3) ). Example 2-2 demonstrates the use of these functions.

The format of one inventory table row is declared as type inventory_t in the sys/invent.h header file. This header file also supplies symbolic names for all the class and type numbers that can appear in the table, as well as containing commentary explaining the meanings of some of the numbers.

#include <stddef.h> /* for NULL */
#include <invent.h> /* includes sys/invent.h */
int getIPtypeCode()
{
   inv_state_t * pstate = NULL;
   inventory_t * work;
   int ret = 0;
   setinvent_r(&pstate);
   do {
      work = getinvent_r(pstate);
      if ( (INV_PROCESSOR == work->inv_class)
      &&   (INV_CPUBOARD == work->inv_type) )
         ret = work->inv_state;
   } while (!ret);
   endinvent_r(pstate); /* releases pstate-> */
   return ret;
}

As discussed under “IRIX Conventional Device Names”, a conventional name for a disk device in the /dev/dsk directory is dksCdulnsp. The number C is the “controller” number, which in previous systems represented a fixed, well-known numbering of SCSI bus adapters. No such fixed numbering is inherent in the Origin2000 architecture. Controller cards can be added to and removed from modules, and entire modules can be added to and removed from the system.

Users of network interface cards, serial ports, bus adapters, and other devices need a predictable, static naming scheme for devices. The name /dev/ttyf2 should represent the same serial port tomorrow that it does today. A related problem is that some device drivers want to place extra, short-circuit vertexes under /hw to allow simpler access to their devices (see “Additional Edges”). Typically such short-circuit names ought to be distinguished by a predictable number.

However, it is impossible to assign stable, repeatable controller numbers dynamically at boot time, while the system is discovering the I/O complement. All the CPUs in the system boot at the same time. Bus controllers and device drivers are initialized in parallel on the nodes to which the hardware is connected. The sequence in which this happens is unpredictable; and in any case the hardware connections can change from boot to boot. A driver cannot know, when it is called to attach a device, what controller number it ought to specify in the hardware inventory.

In order to solve these problems, the ioconfig command is invoked automatically, after device drivers have been initialized and the hwgraph has been initialized, but before user processes are started.

Operating in parallel for speed, ioconfig traverses the entire hwgraph, inspecting the hardware inventory data at each vertex. At a vertex where the hardware inventory Class value indicates a controller that should be numbered, ioconfig assigns a number, and updates the hardware inventory Controller value to reflect the assigned number. Then the program opens the device and optionally causes an ioctl() function. This results in an entry to the open() entry point, and optionally the ioctl() entry point., of the device driver (for an overview of this interaction, see “Overview of Device Open” in Chapter 3 and “Overview of Device Control” in Chapter 3).

In these entry points, the device driver can recognize that its device now has an assigned Controller number. The driver can use this information to create extra hwgraph vertexes and edges if it wishes. (For an overview of how the distributed SCSI drivers use this facility, see “SCSI Devices in the hwgraph” in Chapter 16.)

The ioconfig program uses three disk files. The first, /etc/ioconfig.conf, in which it records the controller numbers it has assigned and the related /hw pathnames. When it needs to assign a number, ioconfig first looks up the current hwgraph path in /etc/ioconfig.conf. If the path appears, ioconfig assigns the same controller number that it used last time. If the path does not appear, ioconfig assigns the lowest number that has never been assigned in this device Class, and adds the path and its number to /etc/ioconfig.conf.

This procedure ensures that a given device always receives the same controller number, even if the device is removed and later replaced. Users can inspect /etc/ioconfig.conf at any time to discover the numbering, and so can infer the relationship of a controller number in /dev/dsk (for example) to a vertex in the hwgraph. Alternatively, the system administrator can cause all numbers to be reassigned simply by removing the file /etc/ioconfig.conf.

The ioconfig command also can be used to set ownership and permissions on the device special files. This enables the administrator to specify ownership and permissions for device names that are created dynamically, each time the system boots.

Assignment of permissions is driven by the file /etc/ioperms. Its format (as described in ioconfig(1M) ) has four fields:

There is no requirement that /etc/ioperms describe only existing devices; it can describe devices that are not currently in the system. Also it can describe devices defined by third parties other than Silicon Graphics.

The ioconfig command has built-in knowledge of Silicon Graphics network and disk controllers and other devices. However, you can cause ioconfig to assign a controller number to an OEM device, and to call your driver when it does so. You do this by placing a file in the directory /var/sysgen/ioconfig.

All files in that directory are processed by ioconfig. A noncomment line in any of these files has the following seven fields (not 8 fields, as some editions of the ioconfig(1M) reference page show):

By placing a file in /var/sysgen/ioconfig, you can cause ioconfig to assign a controller number to devices that you support, and to open each device and optionally execute an ioctl call against each device, so the device driver can take note of the assigned number.

The contents of the files direct lboot in loading components that are described by files in /var/sysgen/master.d, and in probing for devices to see if they exist. (For details of the operation of lboot, see the lboot(1M) and autoconfig(1M) reference pages.)

The VECTOR statement in a kernel configuration file directs lboot to probe for the existence of hardware at a stated address, and to include a device driver only when the hardware existed. Starting with IRIX 6.3, the kernel automatically probes the PCI bus and other attachments in which the hardware devices can identify themselves dynamically. The VECTOR statement is used only for VME and EISA devices (in systems that support them) because these cannot identify themselves automatically.

The system administrator can place statements in any file in /var/sysgen/system. These statements cause labelled attributes to be placed in the hardware graph, where device drivers can retrieve them (see “Driver Interface to Hwgraph” and the system(4) reference page).

The DEVICE_ADMIN statement is used to attach an attribute giving information about a particular device. The attribute is attached to a specific device special file in the hwgraph. Its syntax is as follows:

DEVICE_ADMIN : /hw/path label = value [, label = value]... 

The colon (:) is required; do not overlook it. The values you supply are:

The path is terminated by white space. The label is terminated by the “=” or by white space. The value is terminated by a comma or by the end of the line, so the value can contain white space and special characters other than the comma. As one example of the use of DEVICE_ADMIN, you can find the following in /var/sysgen/system/irix.sm:

DEVICE_ADMIN: /hw/module/1/slot/io1/baseio/pci/0/scsi_ctlr/0
                                          ql_request_queue_depth=1024

The path specifies a particular SCSI controller. The label is “ql_request_queue_depth,” and the value is 1024.

The DRIVER_ADMIN statement is used to pass a value directly to a device driver. Its syntax is as follows:

DRIVER_ADMIN : prefix label = value [, label = value]... 

The values you supply are:

The prefix is terminated by white space. The label is terminated by the “=” or by white space. The value is terminated by a comma or by the end of the line, so the value can contain white space and special characters other than the comma.

These two statements can be placed in any file in /var/sysgen/system, but typically appear in the irix.sm file. The device driver must expect to receive labeled values, and must request them using the interface described under “Retrieving Administrator Attributes” in Chapter 8.

The DEVICE_ADMIN statement is used to perform general administration of device interrupts. These uses are documented with examples in /var/sysgen/system/irix.sm:

The DEVICE_ADMIN statement is also used to administer 32-bit direct mapping.

---

Note: The following information does not apply to O2 or Octane systems.

---

When a PCI driver uses 32-bit direct mapping (with the pciio_dmatrans_addr() and pciio_dmatrans_list() functions), the memory space that is being mapped must be on one specific node. The default is node zero. You can use the DEVICE_ADMIN statement to change the mapping node for a specific PCI bus.

---

Caution: This change occurs at the PCI bus level, not the device level. This means that each device on that PCI bus will be affected by the change.

---

These uses are documented with examples in /var/sysgen/system/irix.sm: