| # Protocols in drivers | |
| Caution: This page may contain information that is specific to the legacy | |
| version of the driver framework (DFv1). | |
| ## What is a protocol? | |
| A protocol is a strict interface definition. | |
| The ethernet driver published an interface that conforms to `ZX_PROTOCOL_ETHERNET_IMPL`. | |
| This means that it must provide a set of functions defined in a data structure | |
| (in this case, `ethernet_impl_protocol_ops_t`). | |
| These functions are common to all devices implementing the protocol — for example, | |
| all ethernet devices must provide a function that queries the MAC address of the | |
| interface. | |
| Other protocols will of course have different requirements for the functions they | |
| must provide. | |
| For example, a block device serves the | |
| [`fuchsia.hardware.block.volume.Service`](/sdk/fidl/fuchsia.hardware.block.volume/volume.fidl) | |
| FIDL service, whose `volume` protocol | |
| ([`fuchsia.storage.block.Block`](/sdk/fidl/fuchsia.storage.block/block.fidl)) | |
| includes methods that return the size of the device in blocks and open sessions | |
| for I/O. | |
| In many cases a Protocol is used to allow drivers to be simpler by taking | |
| advantage of a common implementation of an Interface. For example, the | |
| "ethernet" driver implements the Ethernet Interface and binds to devices | |
| implementing the Ethermac Protocol. Some protocols make use of shared memory and | |
| non-rpc signaling for more efficient, lower latency, and higher throughput than | |
| could be achieved otherwise. | |
| Classes represent a promise that a device implements an Interface or Protocol. | |
| Devices exist in the Device Filesystem under a topological path, like | |
| `/sys/platform/pci/00:02:00/e1000`. If they are a specific class, they also appear | |
| as an alias under `/dev/class/CLASSNAME/...`. The `e1000` driver implements | |
| the Ethermac interface, so it also shows up at `/dev/class/ethermac/000`. The names | |
| within class directories are unique but not meaningful, and are assigned on demand. | |
| Note: Currently names in class directories are 3 digit decimal numbers, but they | |
| are likely to change form in the future. Clients should not assume there is any | |
| specific meaning to a class alias name. | |
| Example protocols: | |
| * the PCI root protocol (`ZX_PROTOCOL_PCIROOT`), | |
| * the PCI device protocol (`ZX_PROTOCOL_PCI`), and | |
| * the ethernet implementation protocol (`ZX_PROTOCOL_ETHERNET_IMPL`). | |
| The names in brackets are the C language constants corresponding to the protocols, for reference. | |
| ## Platform dependent vs platform independent | |
| Above, we mentioned that `ZX_PROTOCOL_ETHERNET_IMPL` was "close to" the functions used | |
| by the client, but one step removed. | |
| That's because there's one more protocol, `ZX_PROTOCOL_ETHERNET`, that sits between | |
| the client and the driver. | |
| This additional protocol is in place to handle functionality common to all ethernet | |
| drivers (in order to avoid code duplication). | |
| Such functionality includes buffer management, status reporting, and administrative | |
| functions. | |
| This is effectively a "platform dependent" vs "platform independent" decoupling; | |
| common code exists in the platform independent part (once), and driver-specific code | |
| is implemented in the platform dependent part. | |
| This architecture is repeated in multiple places, such as with display controllers, | |
| I<sup>2</sup>C bus, and serial drivers. | |
| <!--- More content? --> | |
| ## Process / protocol mapping | |
| In order to keep the discussions above simple, we didn't talk about process separation | |
| as it relates to the drivers. | |
| To understand the issues, let's see how other operating systems deal with them, | |
| and compare that to the Fuchsia approach. | |
| In a monolithic kernel, such as Linux, many drivers are implemented within the kernel. | |
| This means that they share the same address space, and effectively live in the same | |
| "process." | |
| The major problem with this approach is fault isolation / exploitation. | |
| A bad driver can take out the entire kernel, because it lives in the same address | |
| space and thus has privileged access to all kernel memory and resources. | |
| A compromised driver can present a security threat for the same reason. | |
| The other extreme, that is, putting each and every driver service into its own | |
| process, is used by some microkernel operating systems. | |
| Its major drawback is that if one driver relies on the services of another driver, | |
| the kernel must effect at least a context switch operation (if not a data transfer | |
| as well) between the two driver processes. | |
| While microkernel operating systems are usually designed to be fast at these | |
| kinds of operations, performing them at high frequency is undesirable. | |
| The approach taken by Fuchsia is based on the concept of a driver host. | |
| A driver host is a process that contains a protocol stack — that is, one or | |
| more protocols that work together. | |
| The driver host loads drivers from ELF shared libraries (called Dynamic Shared Objects, | |
| or **DSO**s). | |
| The protocol stack effectively allows the creation of a complete "driver" for | |
| a device, consisting of platform dependent and platform independent components, | |
| in a self-contained process container. | |
| For the advanced reader, take a look at the `driver dump` command available from | |
| the Fuchsia command line. It displays a tree of devices, and shows you the | |
| process ID, DSO name, and other useful information. | |
| Here's a highly-edited version showing just the PCI ethernet driver parts: | |
| ``` | |
| 1. [root] | |
| 2. [sys] | |
| 3. <sys> pid=1416 /boot/driver/bus-acpi.so | |
| 4. [acpi] pid=1416 /boot/driver/bus-acpi.so | |
| 5. [pci] pid=1416 /boot/driver/bus-acpi.so | |
| ... | |
| 6. [00:02:00] pid=1416 /boot/driver/bus-pci.so | |
| 7. <00:02:00> pid=2052 /boot/driver/bus-pci.proxy.so | |
| 8. [e1000] pid=2052 /boot/driver/e1000.so | |
| 9. [ethernet] pid=2052 /boot/driver/ethernet.so | |
| ``` | |
| From the above, you can see that process ID `1416` (lines 3 through 6) | |
| is the Advanced Configuration and Power Interface (**ACPI**) driver, implemented | |
| by the DSO `bus-acpi.so`. | |
| During primary enumeration, the ACPI DSO detected a PCI bus. | |
| This caused the publication of a parent with `ZX_PROTOCOL_PCI_ROOT` (line 5, | |
| causing the appearance of the `[pci]` entry), | |
| which then caused the driver host to load the `bus-pci.so` DSO and bind to it. | |
| That DSO is the "base PCI driver" to which we've been referring throughout the | |
| discussions above. | |
| During its binding, the base PCI driver enumerated the PCI bus, and found an ethernet | |
| card (line 6 detects bus 0, device 2, function 0, shown as `[00:02:00]`). | |
| (Of course, many other devices were found as well, but we've removed them from | |
| the above listing for simplicity). | |
| The detection of this device then caused the base PCI driver to publish a new parent | |
| with `ZX_PROTOCOL_PCI` and the device's VID and DID. | |
| Additionally, a new driver host (process ID `2052`) was created and loaded with the | |
| `bus-pci.proxy.so` DSO (line 7). | |
| This proxy serves as the interface from the new driver host (pid `2052`) to the base PCI | |
| driver (pid `1416`). | |
| > This is where the decision was made to "sever" the device driver into its own | |
| > process — the new driver host and the base PCI driver now live in two | |
| > different processes. | |
| The new driver host `2052` then finds a matching child (the `e1000.so` | |
| DSO on line 8; it's considered a match because it has `ZX_PROTOCOL_PCI` and the correct | |
| VID and DID). | |
| That DSO publishes a `ZX_PROTOCOL_ETHERNET_IMPL`, which binds to a matching | |
| child (the `ethernet.so` DSO on line 9; it's considered a match because it has a | |
| `ZX_PROTOCOL_ETHERNET_IMPL` protocol). | |
| What's not shown by this chain is that the final DSO (`ethernet.so`) publishes | |
| a `ZX_PROTOCOL_ETHERNET` — that's the piece that clients can use, so of | |
| course there's no further "device" binding involved. | |
| ### Driver Framework Version 2 (DFv2) | |
| If driver framework version 2 is enabled, `driver dump` will show a slightly | |
| different tree. | |
| ```sh | |
| $ driver dump | |
| [root] pid=4766 fuchsia-boot:///#meta/platform-bus.cm | |
| [sys] pid=4766 | |
| [platform] pid=4766 | |
| [pt] pid=4766 fuchsia-boot:///#meta/platform-bus-x86.cm | |
| [acpi] pid=4766 | |
| [acpi-pwrbtn] pid=4766 fuchsia-boot:///#meta/hid.cm | |
| ... | |
| [PCI0] pid=4766 fuchsia-boot:///#meta/bus-pci.cm | |
| [bus] pid=4766 | |
| ... | |
| [00_04_0] pid=4766 fuchsia-boot:///#meta/virtio_ethernet.cm | |
| [virtio-net] pid=4766 fuchsia-boot:///#meta/netdevice-migration.cm | |
| [netdevice-migration] pid=4766 fuchsia-boot:///#meta/network-device.cm | |
| [network-device] pid=4766 | |
| ... | |
| ``` | |
| It is important to point out that nodes (devices are referred to as nodes in | |
| DFv2) do not have an `.so` file associated with them. Instead, there is a URL of | |
| the component manifest of the driver that is attached to a given node. |