Manual Pages  — GEOM

• SYNOPSIS
• DESCRIPTION
• TERMINOLOGY AND TOPOLOGY
• SPECIAL TOPOLOGICAL MANEUVERS
• DIAGNOSTICS
• OBSOLETE OPTIONS
• SEE ALSO
• HISTORY
• AUTHORS

A new class will be offered to all existing providers in turn and a new provider will be offered to all classes in turn.

Exactly what a class does to recognize if it should accept the offered provider is not defined by GEOM, but the sensible set of options are:

• Examine specific data structures on the disk.
• Examine properties like "sectorsize" or "mediasize" for the provider.
• Examine the rank number of the provider's geom.
• Examine the method name of the provider's geom.

When a geom orphans a provider, all future I/O requests will "bounce" on the provider with an error code set by the geom. Any consumers attached to the provider will receive notification about the orphanization when the event loop gets around to it, and they can take appropriate action at that time.

A geom which came into being as a result of a normal taste operation should self-destruct unless it has a way to keep functioning whilst lacking the orphaned provider. Geoms like disk slicers should therefore self-destruct whereas RAID5 or mirror geoms will be able to continue as long as they do not lose quorum.

When a provider is orphaned, this does not necessarily result in any immediate change in the topology: any attached consumers are still attached, any opened paths are still open, any outstanding I/O requests are still outstanding.

The typical scenario is:

• A device driver detects a disk has departed and orphans the provider for it.
• The geoms on top of the disk receive the orphanization event and orphan all their providers in turn. Providers which are not attached to will typically self-destruct right away. This process continues in a quasi-recursive fashion until all relevant pieces of the tree have heard the bad news.
• Eventually the buck stops when it reaches geom_dev at the top of the stack.
• Geom_dev will call destroy_dev(9) to stop any more requests from coming in. It will sleep until any and all outstanding I/O requests have been returned. It will explicitly close (i.e.: zero the access counts), a change which will propagate all the way down through the mesh. It will then detach and destroy its geom.
• The geom whose provider is now detached will destroy the provider, detach and destroy its consumer and destroy its geom.
• This process percolates all the way down through the mesh, until the cleanup is complete.

While this approach seems byzantine, it does provide the maximum flexibility and robustness in handling disappearing devices.

The one absolutely crucial detail to be aware of is that if the device driver does not return all I/O requests, the tree will not unravel.

Imagine a disk, da0, on top of which an MBR geom provides da0s1 and da0s2, and on top of da0s1 a BSD geom provides da0s1a through da0s1e, and that both the MBR and BSD geoms have autoconfigured based on data structures on the disk media. Now imagine the case where da0 is opened for writing and those data structures are modified or overwritten: now the geoms would be operating on stale metadata unless some notification system can inform them otherwise.

To avoid this situation, when the open of da0 for write happens, all attached consumers are told about this and geoms like MBR and BSD will self-destruct as a result. When da0 is closed, it will be offered for tasting again and, if the data structures for MBR and BSD are still there, new geoms will instantiate themselves anew.

Now for the fine print:

If any of the paths through the MBR or BSD module were open, they would have opened downwards with an exclusive bit thus rendering it impossible to open da0 for writing in that case. Conversely, the requested exclusive bit would render it impossible to open a path through the MBR geom while da0 is open for writing.

From this it also follows that changing the size of open geoms can only be done with their cooperation.

Finally: the spoiling only happens when the write count goes from zero to non-zero and the retasting happens only when the write count goes from non-zero to zero.

Finally, I/O is the reason we even do this: it concerns itself with sending I/O requests through the graph.

In total, four different I/O requests exist in GEOM: read, write, delete, and "get attribute".

Read and write are self explanatory.

Delete indicates that a certain range of data is no longer used and that it can be erased or freed as the underlying technology supports. Technologies like flash adaptation layers can arrange to erase the relevant blocks before they will become reassigned and cryptographic devices may want to fill random bits into the range to reduce the amount of data available for attack.

It is important to recognize that a delete indication is not a request and consequently there is no guarantee that the data actually will be erased or made unavailable unless guaranteed by specific geoms in the graph. If "secure delete" semantics are required, a geom should be pushed which converts delete indications into (a sequence of) write requests.

"Get attribute" supports inspection and manipulation of out-of-band attributes on a particular provider or path. Attributes are named by ASCII strings and they will be discussed in a separate section below.