hwgraph(4) hwgraph(4) NAME hwgraph, hwgfs, hw - hardware graph and hardware graph file system Internal Hardware Graph Internally, Irix system software maintains a directed graph called the "hardware graph". The hwgraph represents the collection of all significant hardware connected to a system. It represents each piece of hardware -- modules, CPUs, memories, disk controllers, disk drives, disk partitions, serial ports, Ethernet ports, some system integrated circuits, etc. -- as a distinct vertex in the graph. There are some additional vertices that represent collections of hardware (e.g. "the disks") or more abstract architectural concepts (e.g. "a node"). The contents of the hardware graph are obviously system-dependent; but there are many common elements that cross system types. Labeled edges are used to connect graph vertexes in a way that shows some relationship between the underlying hardware. For instance, an edge labeled "3" originates at a vertex that represents the collection of all partitions on a drive. It points to a vertex that represents the third partition on that drive. Another example: An edge labeled "memory" hanging off a vertex that represents a system node points to a vertex that represents the memory on that node. The internal hwgraph also supports arbitrarily-labeled information associated with each vertex. This allows device drivers to associate useful data structures and other information with a particular device. The hardware graph is maintained by system software with the cooperation of device drivers using new device driver interfaces as described in the Device Driver Programmer's Guide. Hardware graph filesystem (hwgfs) The internal hardware graph is exported to user-level through a pseudo- file system (similar to /proc(4)). The hwgfs file system represents the collection of all interesting hardware and pseudo-devices as a file system tree of special files and directories. It is mounted at /hw by the kernel during system boot, and can be re-mounted using /etc/mnthwgfs. In order to represent the directed graph as a Unix file system tree, hwgfs imposes an artificial hierarchy on the hardware graph, and it uses hard links and symlinks to represent graph edges that are outside that hierarchy. Note that it is usually the case that the hwgfs file system contains symlinks that point back "up" to higher-level directories. The implication is that there will be some symlinks under /hw that form cycles which "ls -R" and other commands that recursively descend from a directory have trouble dealing with. Note, however, that the "find" command handles symlinks very well and works as desired: find /hw -print | xargs ls -ld hwgfs does not allow users to create or remove files or symlinks under /hw. Rather, this section of the file system hierarchy is controlled exclusively by device drivers and other system software. In other words, /hw should be viewed purely as a reflection of the contents of the internal hardware graph. The contents of the graph and the links within it may change across releases, and should not be depended upon. They may also change when new hardware releases. The internal hardware graph is updated dynamically when hardware is added and removed, and the file system reflection of that graph is updated accordingly. For instance, when the fx(1m) utility is used to repartition a disk drive, the special files used for the old partitioning automatically disappear and new special files that represent the new partitioning automatically appear. Since hwgfs is a pseudo-filesystem whose files don't actually use any disk space, there is no persistent information associated with files under /hw. In particular, file attributes (mode, owner, group) are not stored across reboots under hwgfs. Rather, reasonable default are used for all hwgfs special files. These defaults can be changed in the normal ways (i.e. with chmod(1), chown(1), chgrp(1)), but the changes only last until the next time the system is rebooted. In order to supply the appearance of special file attributes that are persistent across reboots, hwgfs uses the ioconfig(1m) utility, controlled by the contents of the file /etc/ioperms. The /dev directory is the root of the recommended path for all device file usage, even though many of the files and directories under /dev are now symlinks into /hw. For example, device names under /hw should not be used when mounting filesystems, or configuring the root filesystem for the kernel. Only a few administrative programs need to use the hardware graph pathnames under /hw to obtain additional info directly from the hardware graph. System software (i.e. device drivers) may associate "labeled information" with a hwgraph vertex. In particular, lboot(1m) provides the ability to associate administrative information with an instance of a device using DEVICE_ADMIN directives. Such information is interpreted by the appropriate device driver. Additionally, system software (i.e. device drivers) may choose to "export" such labeled information to user mode. When this is done, the information is available as an extended user-level attribute on the hwgfs file that represents that vertex; so it can be obtained with an attr_get(2) call. Major/Minor Numbers As in earlier releases, the system uses a 32-bit identifier known as a dev_t to identify a particular instance of a device (or special file). In previous releases, a dev_t consisted of a "major number" -- which told the system which driver to use -- and a "minor number" which was a magic cookie interpreted by that driver. Frequently a minor number was sliced into various bit-fields, including a "unit number" which the device driver used to index into an array of per-unit data structures. For backwards compatibility, the Irix kernel continues to support this model for pseudo-drivers. For hwgraph-aware drivers, things are a bit different: A 32-bit dev_t still uniquely identifies a device; but the major number is always 0 (regardless of which driver owns the special file) and the minor number is a system-wide unique "vertex handle". From the vertex handle, system software uses system-level hwgraph interfaces to determine exactly which instance of a device is referenced. The impact at user level is that there is no way for user code to interpret minor numbers of a hwgraph- aware device driver. The driver writer may provide a library (DSO) with appropriate formal interfaces for user-level operations, or the driver writer can export useful information which the user can retrieve with attr_get(2). Note that the dev_t (major/minor) for a particular device may change across reboots. In general, user code should not attempt to interpret the bits in a dev_t, nor is there a valid reason to store a dev_t on persistent storage for use across reboots. Internal hwgraph Interfaces There is an extensive set of interfaces that allow device drivers and other system software to manipulate the hardware graph. Basic operations on vertices include: create, destroy, clone, and get_next. Basic operations on edges include: add, remove, and get_next. Basic operations on labeled vertex information include: add, remove, replace, get, get_next, export, and unexport. There are many other operations, too. These are all defined in the Device Driver Programmer's Guide. User-level Interfaces At user-level, users continue to see special files which represent hardware devices. Users can create symlinks from normal file systems that point into the hwgfs file system. The usual device driver operations (open, close, read, write, ioctl, etc.) and the usual file operations (stat, attr_get, etc.) work as expected, with the exception that stat always returns the current time for st_mtime on non-streams devices. As mentioned earlier, chmod, chown, and chgrp work, but only until the next reboot. For persistent changes to hwgfs special files, the user must use ioconfig(1m). (This may change in a future release of Irix.) The ls(1) command includes an 'S' option that can be used to display the canonical device name for a specified hwgfs file or directory. A canonical device name is a path starting with /hw that unambiguously identifies a device or collection of devices. SEE ALSO attr_get(2), fx(1m), ioconfig(1m), lboot(1m), ls(1), MAKEDEV(1m), setdevperms(1m), linkstat(1), nstats(1), sn(1), xbstat(1m). Page 4