Date: Wed, 17 Feb 1999 11:59:19 -0800 (PST) From: Paul Thomas Subject: Item #457: USB Binding: support for recursive probing P1275 Openboot Working Group Proposal -- Proposal #:457 Ver 1 Title: Add find-fcode to USB binding Author: Paul Thomas Date: February 17, 1999 Ed/Tech: Technical Synopsis: define find-fcode to support recursive probing of USB Doc & Version: Universal Serial Bus, version 1 Problem: When it is desired to create a full tree of device nodes for the Universal Serial Bus, a problem arises because of three conditions: 1. USB physical devices do not carry their own FCode, 2. USB physical devices are not addressable in the address space of the host system, and 3. USB hub devices must be actively managed in order to probe further down the bus. Other bus structures may arise that share similar conditions. This proposal presents a general technique for such situations. Suppose the USB device tree is being created. Some of the devices are now present, together with their properties and whatever FCode is appropriate. In other words, we are now half-way down the bus, having magically created the parent device nodes of interest, together with their methods. We are now at a hub, and want to activate its ports to find more USB devices attached to the hub. Suppose the hub has its FCode magically supplied to it, so the methods are available to run the ports. The basic probing loop is roughly: For each port, is something attached? If so, power the port, get the downstream descriptors, construct a partial device tree node, and byte-load the FCode module that corresponds to that USB device to finish the device tree node -- together with any child devices that USB device has. (For USB, we have a depth-first device tree creation scheme.) In the probing loop, a critical piece is managing the FCode modules needed by the down-stream child devices. There is no information available before probing as to what those devices are, so the modules must be available on demand. Since the probing is recursive, the modules cannot be embedded in a master module (unless the master module is available on demand; in which case they might as well be available individually). Since the addressing scheme for the USB devices is not the same as that of the host system, the FCode modules cannot access a special place in the host system. In the situation above, when at some random hub down in the tree, the hub FCode doesn't know how to get at the FCode prom image on a PCI plug-in card, for instance, since it doesn't know it is ultimately attached to such a host controller, and doesn't know what to do with that kind of address anyway. If the host controller is built onto the motherboard, the FCode for it may not be in a PCI prom anyway, but rather in the main cpu bootprom image. Note that this situation is different from that of PCI-PCI bridges. There the subsidiary devices are all still in the same address space, so the very same FCode can be used over and over recursively, and no new technique is needed to find the FCode module needed. This proposal recognizes that the host controller device node has knowledge of host system addressing, to some degree. In particular, it knows whether it is on a plug-in card, and if so, how to access the full prom image. Or, it knows that it is on a motherboard, and can get access to the main cpu bootprom image through an agreement with the rest of the Open Firmware. (See a little more on this agreement below.) We take advantage of the host controller's knowledge by having it do the caretaking for the various FCode modules useful to USB probing. The host controller makes available to USB descendants a method that the descendants can use to get a particular FCode module when needed. The descendant provides the name of the module desired, the host controller finds it in some library of modules, and returns it to the descendant. The descendant knows what module it needs, and only needs a mechanism to activate the look-up by the host controller. The host controller publishes its look-up mechanism. The descendant inherits the mechanism via get-inherited-property, provides the name, and executes the mechanism. Voila! This process relies on an agreed-upon, reserved property in the host controller node, so that the descendant nodes can rely on inheriting the proper method. A little more on the agreement with the rest of Open Firmware: Currently, our implementation takes advantage of /packages to hold the various FCode modules used when the host controller is built onto the motherboard. In this particular case, descendant devices could go directly to /packages and get modules on their own, without going through the host controller. However, that technique doesn't work well when the USB host controller is on a plug-in card. If the descendant devices go through the host controller in all cases, the knowledge as to specific locations is kept to one device. The descendant devices have a much greater chance of using FCode that is independent of the specific host controller, and hence the same FCode can be used in many situations. In addition, if a plug-in USB has differences from a built-in USB, the FCode modules for descendant devices can come from the plug-in card in preference to ones from /packages of the host system. There are a couple of alternatives to this proposal that should be mentioned, as they may prove more applicable to some other situation. For various reasons, they are not as appropriate in this particular one: 1. The addresses of the FCode modules could be published as properties to be inherited by descendants. This idea involves standardization of several more properties in the host controller than the current proposal does. In addition, it essentially requires the permanent allocation of the memory needed to hold the images. It is cumbersome to extend this approach to new FCode modules when they are needed, as the properties are public. They should be viewed as potential amendments to the USB document, with all of the process entailed. 2. A virtual library could be created. For instance, the root hub, which is a virtual USB device anyway (i.e., implemented completely in software with transactions to it intercepted by the host controller software), could have an additional interface which is used to respond to USB transactions that essentially ask for particular FCode modules. This idea involves a fair amount of overhead managing the USB descriptors and transactions. It also may run afoul of the USB committee process, with the attendant approval procedures, when extensions to new modules are needed. 3. The request for a particular FCode module could be done via a $call-parent method which is passed up the chain of USB devices to the host controller. This notion is similar to the actual implementation of many of the methods used to run the various USB transactions on behalf of a USB device. It carries with it the requirement that many USB devices must implement the $call-parent method, instead of just the host adaptor publishing a method one time. 4. The addresses of the FCode modules or of the execution tokens of the look-up method(s) could be passed to each new device as it is created, so the new device could either access the images directly, or run a method to perform the look-up. Depending on the details, this could be cumbersome to extend to new FCode modules. It could use memory permanently that really isn't needed after probe time. It seems to spread around more knowledge about the FCode images themselves than is really needed. Proposal: Replace the contents of section 3.1.1.2. Bus-specific Properties for Host Controller Nodes with: "find-fcode" prop-name to indicate a function that provides a specific Fcode module. prop-encoded-array: one execution token, encoded as with encode-int. This property, if present, indicates an execution token which has the following stack diagram: ( addr1 len1 -- addr2 len2 true | false ) addr1 len1 are a string that names an Fcode module. Return addr2 len2 the location and length of the corresponding FCode module, together with true, if the module can be found. If the corresponding FCode module cannot be found, return false. [ P1275 Item #457 -- Received: Wed Feb 17 11:59:49 PST 1999 ]