1: # Rationale
3: ## Talk about device names used in /etc/fstab
5: /etc/fstab is a simple text file describing targets of a mount operation. Each line consists
6: of six fields:
8: > fs_spec fs_file fs_vfstype fs_mntops fs_freq fs_passno
10: The manual describes the fs_spec field as
12: > The first field, (fs_spec), describes the block special device or remote
13: > file system to be mounted. For file systems of type ffs, the special
14: > file name is the block special file name, and not the character special
15: > file name. If a program needs the character special file name, the
16: > program must create it by appending a ``r'' after the last ``/'' in the
17: > special file name.
19: The block special file names are built by convention from the name of the
20: device driver, a unit number and a partition suffix. E.g.
22: > /dev/sd3f
26: - sd = SCSI disk driver name
27: - 3 = Unit 3
28: - f = Partition 6 (count starts with 'a')
30: ## Autoconf: devices are named driver+unit, unit is just the next unused unit number
32: During autoconfiguration the kernel attaches disk drivers, the drivers then assign free
33: unit numbers to detected hardware. Unit numbers are counted per driver.
35: The disk driver name is something strongly connected to the hardware, there is hardly
36: any hard disk that can attach to both the IDE driver and the SCSI driver. Even when you
37: think about hybrid SAS/SATA controllers or multiport USB/Firewire/SATA enclosures,
38: there is no confusion, because it requires an intentional change to the hardware.
40: The unit numbers however are very volatile. They are assigned in the order a particular
41: disk is detected. Concurrent autoconfiguration might even generate unpredictable unit numbers
42: without any intervention.
44: ## Partitions on device names are just private counts (a,b,c,...) per device
46: Partition suffixes are just indexes into a table that describes slices of a disk.
47: There is always a specific slice (RAW_PART) that covers that whole disk. It is
48: usually not used for filesystems, but for meta information like the disk label
51: On some disks, the partition table is computed from disk parameters instead of
52: read from persistent storage. But this is supposed to be a stable mapping.
54: Partition suffixes however are not portable because they are based
55: on labels that depend on the machine or even individual drivers.
57: ## Wedges are partitions that look like units of a single driver
59: A wedge is a pseudo disk that accesses the RAW_PART of a real disk. This effectively
60: bypasses the driver based partitioning and is used to provide a driver independent
61: partitioning system, in particular to support foreign disk labels.
63: Since wedges are subject to the same autoconf naming scheme, we now have a
64: disk driver name that is always 'dk' and has no connection to the accessed
65: hardware. There is a, this time, global unit number for all disks and
66: of course no partition suffix.
68: You must predict the order of wedge attachments to be able to access a
69: particular disk.
72: # Wedge names
74: ## Wedges are a unified interface to partitions
76: In a wedge enabled system, each disk partition is referenced by a wedge. This is
77: a very simple view on a range of disk blocks. In particular there is no meta
78: information except for the simple geometry describing the size of a block
79: and the total number of blocks.
81: Wedges reflect all the data and meta-data that is required to provide
82: storage used by a filesystem.
84: ## Wedges can have a name which defaults to a UUID
86: Wedges are units of the 'dk' driver and can be identified by a name. The name
87: is a string that uniquely identifies the unit and must be given to the unit
88: when it is attached. The attachment will fail, when the name already exists.
90: When a wedge is created manually, the name is given by the operator to the
91: dkctl command.
93: When a wedge is created by the autodetect code, the names are taken or computed
94: from the detected label. In particular:
96: - MBR partitions generate the wedge name from driver, unit, partition suffix
97: of the underlying disk where the suffixes start with 'e' to avoid conflicts.
98: This looks like a conventional partition name, e.g. sd3f.
100: - BSD disklabel partitions do something similar but also check for the volume
101: name in the disklabel.
102: - If there is a volume name and it is not the default string 'fictitious'
103: then the wedge name is built from volume and partition suffix separated
104: by a '/', e.g. system/f for partition 6 of the volume named 'system'.
105: - Otherwise it is built from driver, unit and partition suffix. This again
106: looks like a conventional partition name, e.g. sd3f.
108: - GPT partitions may have names themselves, but they always have assigned
109: a UUID when created. The wedge takes the name of the partition if set,
110: otherwise it defaults to the UUID.
112: A wedge has exactly one name, so it is currently not possible to have multiple
113: aliases like 'by-name', 'by-uuid', 'by-label'.
115: ## Names can be looked up in userland
117: The command 'dkctl diskdev listwedges' shows all wedges attached to a particular
118: disk and their names.
120: The command 'dkctl wedgedev getwedgeinfo' shows data about a wedge device including
121: its name.
123: There is no command to map a name back to the device special file of the wedge.
125: ## util function getfsspecname()
127: Programs using /etc/fstab can use wedge names instead of device paths. That's
128: because the fs_spec component isn't necessarily a device path but can be
129: interpreted by the specific commands.
131: The getfsspecname() function currently implements the interpretation of a string
134: > NAME=name
136: and returns the device path of the wedge that has the particular name. Other
137: strings are just passed through to retain the conventional behaviour.
139: ## Patches for userland tools (mount,umount,swapctl,fsck,quotaon,quotacheck,edquota,dumpfs,tunefs,dump)
141: Several commands have been augmented to utilize the getfsspecname() function so that
142: they will understand fs_spec strings. The commands use this for data fetched from
143: /etc/fstab but also for command line arguments.
145: This is a pure userland function, the commands will still use conventional device paths
146: when talking to the kernel, and anything the kernel reports (e.g. syslog messages)
147: will identify a device by driver name and unit number.
149: Userland code also lacks support for reverse mapping. E.g. the df command will also
150: report usage values for devices 'dk0','dk1' and so on instead of wedge names that
151: might have been used in /etc/fstab for mounting the filesystems.
CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb