File:  [NetBSD Developer Wiki] / wikisrc / users / mlelstv / device-naming.mdwn
Revision 1.11: download - view: text, annotated - select for diffs
Tue Sep 23 11:23:42 2014 UTC (5 years, 5 months ago) by mlelstv
Branches: MAIN
CVS tags: HEAD

# Rationale

## Talk about device names used in /etc/fstab

/etc/fstab is a simple text file describing targets of a mount operation. Each line consists
of six fields:

> fs_spec fs_file fs_vfstype fs_mntops fs_freq fs_passno

The manual describes the fs_spec field as

> The first field, (fs_spec), describes the block special device or remote
> file system to be mounted.  For file systems of type ffs, the special
> file name is the block special file name, and not the character special
> file name.  If a program needs the character special file name, the
> program must create it by appending a ``r'' after the last ``/'' in the
> special file name.

The block special file names are built by convention from the name of the
device driver, a unit number and a partition suffix. E.g.

> /dev/sd3f


- sd = SCSI disk driver name
- 3  = Unit 3
- f  = Partition 6 (count starts with 'a')

## Autoconf: devices are named driver+unit, unit is just the next unused unit number

During autoconfiguration the kernel attaches disk drivers, the drivers then assign free
unit numbers to detected hardware. Unit numbers are counted per driver.

The disk driver name is something strongly connected to the hardware, there is hardly
any hard disk that can attach to both the IDE driver and the SCSI driver. Even when you
think about hybrid SAS/SATA controllers or multiport USB/Firewire/SATA enclosures,
there is no confusion, because it requires an intentional change to the hardware.

The unit numbers however are very volatile. They are assigned in the order a particular
disk is detected. Concurrent autoconfiguration might even generate unpredictable unit numbers
without any intervention.

## Partitions on device names are just private counts (a,b,c,...) per device

Partition suffixes are just indexes into a table that describes slices of a disk.
There is always a specific slice (RAW_PART) that covers that whole disk. It is
usually not used for filesystems, but for meta information like the disk label

On some disks, the partition table is computed from disk parameters instead of
read from persistent storage. But this is supposed to be a stable mapping.

Partition suffixes however are not portable because they are based
on labels that depend on the machine or even individual drivers.

## Wedges are partitions that look like units of a single driver

A wedge is a pseudo disk that accesses the RAW_PART of a real disk. This effectively
bypasses the driver based partitioning and is used to provide a driver independent
partitioning system, in particular to support foreign disk labels.

Since wedges are subject to the same autoconf naming scheme, we now have a
disk driver name that is always 'dk' and has no connection to the accessed
hardware. There is a, this time, global unit number for all disks and
of course no partition suffix.

You must predict the order of wedge attachments to be able to access a
particular disk.

# Wedge names

## Wedges are a unified interface to partitions

In a wedge enabled system, each disk partition is referenced by a wedge. This is
a very simple view on a range of disk blocks. In particular there is no meta
information except for the simple geometry describing the size of a block
and the total number of blocks.

Wedges reflect all the data and meta-data that is required to provide
storage used by a filesystem.

## Wedges can have a name which defaults to a UUID

Wedges are units of the 'dk' driver and can be identified by a name. The name
is a string that uniquely identifies the unit and must be given to the unit
when it is attached. The attachment will fail, when the name already exists.

When a wedge is created manually, the name is given by the operator to the
dkctl command.

When a wedge is created by the autodetect code, the names are taken or computed
from the detected label. In particular:

- MBR partitions generate the wedge name from driver, unit, partition suffix
  of the underlying disk where the suffixes start with 'e' to avoid conflicts.
  This looks like a conventional partition name, e.g. sd3f.

- BSD disklabel partitions do something similar but also check for the volume
  name in the disklabel.
  - If there is a volume name and it is not the default string 'fictitious'
    then the wedge name is built from volume and partition suffix separated
    by a '/', e.g. system/f for partition 6 of the volume named 'system'.
  - Otherwise it is built from driver, unit and partition suffix. This again
    looks like a conventional partition name, e.g. sd3f.

- GPT partitions may have names themselves, but they always have assigned
  a UUID when created. The wedge takes the name of the partition if set,
  otherwise it defaults to the UUID.

A wedge has exactly one name, so it is currently not possible to have multiple
aliases like 'by-name', 'by-uuid', 'by-label'.

## Names can be looked up in userland

The command 'dkctl diskdev listwedges' shows all wedges attached to a particular
disk and their names.

The command 'dkctl wedgedev getwedgeinfo' shows data about a wedge device including
its name.

There is no command to map a name back to the device special file of the wedge.

## util function getfsspecname()

Programs using /etc/fstab can use wedge names instead of device paths. That's
because the fs_spec component isn't necessarily a device path but can be
interpreted by the specific commands.

The getfsspecname() function currently implements the interpretation of a string

> NAME=name

and returns the device path of the wedge that has the particular name. Other
strings are just passed through to retain the conventional behaviour.

## Patches for userland tools (mount,umount,swapctl,fsck,quotaon,quotacheck,edquota,dumpfs,tunefs,dump)

Several commands have been augmented to utilize the getfsspecname() function so that
they will understand fs_spec strings. The commands use this for data fetched from
/etc/fstab but also for command line arguments.

This is a pure userland function, the commands will still use conventional device paths
when talking to the kernel, and anything the kernel reports (e.g. syslog messages)
will identify a device by driver name and unit number.

Userland code also lacks support for reverse mapping. E.g. the df command will also
report usage values for devices 'dk0','dk1' and so on instead of wedge names that
might have been used in /etc/fstab for mounting the filesystems.

CVSweb for NetBSD wikisrc <> software: FreeBSD-CVSweb