From owner-freebsd-new-bus Sun Feb 27 6: 9:48 2000 Delivered-To: freebsd-new-bus@freebsd.org Received: from anchor-post-31.mail.demon.net (anchor-post-31.mail.demon.net [194.217.242.89]) by hub.freebsd.org (Postfix) with ESMTP id 5745237B57E for ; Sun, 27 Feb 2000 06:09:33 -0800 (PST) (envelope-from dfr@nlsystems.com) Received: from nlsys.demon.co.uk ([158.152.125.33] helo=herring.nlsystems.com) by anchor-post-31.mail.demon.net with esmtp (Exim 2.12 #1) id 12P4O2-0009Ak-0V; Sun, 27 Feb 2000 14:09:30 +0000 Received: from salmon.nlsystems.com (salmon.nlsystems.com [10.0.0.3]) by herring.nlsystems.com (8.9.3/8.8.8) with ESMTP id OAA44652; Sun, 27 Feb 2000 14:13:22 GMT (envelope-from dfr@nlsystems.com) Date: Sun, 27 Feb 2000 14:12:30 +0000 (GMT) From: Doug Rabson To: Jeroen Ruigrok/Asmodai Cc: new-bus@freebsd.org Subject: Re: New version of the newbus draft In-Reply-To: <20000226113136.S79013@daemon.ninth-circle.org> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-freebsd-new-bus@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG On Sat, 26 Feb 2000, Jeroen Ruigrok/Asmodai wrote: > http://people.freebsd.org/~asmodai/newbus-draft.txt > > Added some blurb about interface methods, macro/function wrapping. > > 590 words/version 1.3. Here is my marked-up version of the text. | Newbus and busspace, an explanation of the possibilities | -------------------------------------------------------------------------------- | Newbus is the implementation of a new bus architecture based on abstraction | layers which saw its introduction in FreeBSD 4.0. Its goals are to provide a FreeBSD 3.0 [I used new bus to manage the moderately complex device hierarchy of the alpha port which was first released publicly in FreeBSD 3.0. The major busses (ISA and PCI) were not converted at this time and the x86 port didn't depend on new-bus at all.] | more object oriented means of interconnecting the various busses and devices | which a host system provides to the Operating System. | Its main features include amongst others: | | o dynamic attaching | o easy modularisation of drivers | o pseudo-busses. | | One of the most prominent changes is the migration from the flat and ad-hoc | system to a device tree lay-out. | | At the top level resides the ``nexus'' bus which is the parent to hang all | other busses on. This includes host-to-pci bridges, npx, and apm. | Under the host-to-pci bridge we have the pci bus(ses), pci-to-pci bridges, | pci devices, and pci-to-isa bridges. The nexus only exists on IA-32 platforms | and is not available on, for example, the Alpha platform. At the top level is the ``root'' device. This is the parent to hang all other devices on. For each architecture, there is typically a single child of ``root'' which has such things as host-pci bridges, etc. attached to it. For x86, this is the ``nexus'' device and for alpha, various different different models of alpha have different toplevel devices corresponding to the different hardware chipsets, including lca, apecs, cia and tsunami. | | A device in the newbus context can be a bus, a device, or a bridge. This is | kind of ambiguous. A device in the newbus context, more accurately, refers to | the total of its methods. A device in the newbus context represents a single hardware entity in the system. For instance each PCI device is represented by a newbus device. Any device in the system can have children; a device which has children is often called a ``bus''. Examples of common busses in the system are isa and pci which manage lists of devices attached to ISA and PCI busses respectively. Often, a connection between different kinds of bus is represented by a ``bridge'' device which normally has one child for the attached bus. An example of this is a pci-pci bridge which is represented by a device pcibN on the parent PCI bus and has a child pciN for the attached bus. This layout simplifies the implementation of the PCI bus tree, allowing common code to be used for both toplevel and bridged busses. | | Each device in the newbus architecture asks its parent to map its resources. | The parent then asks its own parent until the nexus is reached. So, basically | the nexus is the only part of the newbus system which knows about all resources. | An example: an isa device might want to map its IO port at 0x23c, so it asks its | parent, in this case the isa bus. The isa bus hands it over to the pci-to-isa | bridge which in its turn asks the pci bus, which reaches the host-to-pci bridge | and finally the nexus. | The beauty of this transition upwards is that there is room to translate the | requests. For example, the 0x23c IO port request might become memorymapped | at 0xc000023c on a MIPS box by the pci bridge. | | Resource allocation is, in the newbus case, something which can be controlled | anywhere in the device tree. On the Alpha the isa bus has its own set of | interrupts that isa devices allocate. The code on the IA-32 platform is kind | of hackish. In the IA-32 case the IRQs get allocated on the nexus. Also the IO | space and the memory get allocated on the nexus. Resource allocation can be controlled at any place in the device tree. For instance on many alpha platforms, ISA interrupts are managed separately from PCI interrupts and resource allocations for ISA interrupts are managed by the alpha's isa bus device. On IA-32, ISA and PCI interrupts are both managed by the toplevel nexus device. For both ports, memory and port address space is managed by a single entity - nexus for IA-32 and the relavent chipset driver on alpha (e.g. cia or tsunami). | | Newbus provides the driver with a bustag (bus_space_tag_t) and bushandle | (bus_space_handle_t) with which it can, for example, simply ask for its second | I/O-range and which will be provided to it. In order to regularise access to memory and port mapped resources, newbus integrates the bus_space apis from NetBSD. These provide a single api to replace inb/outb and direct memory reads/writes. The advantage of this is that a single driver can easily use either memory-mapped registers or port-mapped registers (some hardware supports both). This support is integrated into the resource allocation mechanism. When a resource is allocated, a driver can retrieve the associated bus_space_tag_t and bus_space_handle_t from the resource. | | Newbus also allows for definitions of interface methods in files dedicated to | this purpose. These are the .m files that are found under the src/sys | hierarchy. | | The .m files define an interface and its methods, and it could also define a | default for this method. For example (src/sys/pci/pci_if.m): | | INTERFACE pci; | | METHOD u_int32_t read_config { | device_t dev; | device_t child; | int reg; | int width; | }; | | METHOD void write_config { | device_t dev; | device_t child; | int reg; | u_int32_t val; | int width; | }; | | This will define and create macros and configuration structures for the | interface to be used at runtime compilation. | | In the above case we have defined PCI_READ_CONFIG() and PCI_WRITE_CONFIG(). We | take the INTERFACE and append _METHOD to create the macros. | | The configuration structures make the macros comply to the METHODs due to their | calling arguments: PCI_READ_CONFIG(device_t, device_t, int, int). | | Most of these macros get wrapped up inside functions. In our above example we | defined PCI_READ_CONFIG() and PCI_WRITE_CONFIG. If we know take a look at | src/sys/pci/pcivar.h we can see how the wrapping takes place: | | static __inline u_int32_t | pci_read_config(device_t dev, int reg, int width) | { | return PCI_READ_CONFIG(device_get_parent(dev), dev, reg, width); | } | | static __inline void | pci_write_config(device_t dev, int reg, u_int32_t val, int width) | { | PCI_WRITE_CONFIG(device_get_parent(dev), dev, reg, val, width); | } Strike this whole section. I'll write something new here. -- Doug Rabson Mail: dfr@nlsystems.com Nonlinear Systems Ltd. Phone: +44 181 442 9037 To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-new-bus" in the body of the message From owner-freebsd-new-bus Sun Feb 27 7: 2:47 2000 Delivered-To: freebsd-new-bus@freebsd.org Received: from finch-post-10.mail.demon.net (finch-post-10.mail.demon.net [194.217.242.38]) by hub.freebsd.org (Postfix) with ESMTP id 9AF9A37B568 for ; Sun, 27 Feb 2000 07:02:38 -0800 (PST) (envelope-from dfr@nlsystems.com) Received: from nlsys.demon.co.uk ([158.152.125.33] helo=herring.nlsystems.com) by finch-post-10.mail.demon.net with esmtp (Exim 2.12 #1) id 12P5DQ-0003An-0A; Sun, 27 Feb 2000 15:02:37 +0000 Received: from salmon.nlsystems.com (salmon.nlsystems.com [10.0.0.3]) by herring.nlsystems.com (8.9.3/8.8.8) with ESMTP id PAA46142; Sun, 27 Feb 2000 15:06:29 GMT (envelope-from dfr@nlsystems.com) Date: Sun, 27 Feb 2000 15:05:37 +0000 (GMT) From: Doug Rabson To: Jeroen Ruigrok/Asmodai Cc: new-bus@freebsd.org Subject: Re: New version of the newbus draft In-Reply-To: Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-freebsd-new-bus@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG Here is a first draft of a document on the new-bus method system. The New-bus Object System ======================== The core of the new-bus system is an extensible object-based programming model. Each device in the system has a table of methods which it supports. The system and other devices uses those methods to control the device and request services. The different methods supported by a device are defined by a number of ``interfaces''. An ``interface'' is simply a group of related methods which can be implemented by a device. In the new-bus system, the methods for a device are provided by the various device drivers in the system. When a device is attached to a driver during auto-configuration, it uses the method table declared by the driver. A device can later detach from its driver and re-attach to a new driver with a new method table. This allows dynamic replacement of drivers which can be useful for driver development. The interfaces are described by an interface definition language similar to the language used to define vnode operations for file systems. A simple example interface (which would normally be in a file named foo_if.m) might look like this: INTERFACE FOO METHOD int doit { device_t dev; }; METHOD int doit_to_child { device_t dev; device_t child; }; When this interface is compiled, it generates a header file ``foo_if.h'' which contains function declarations: int FOO_DOIT(device_t dev); int FOO_DOIT_TO_SOMEONE(device_t dev, device_t child); and also a source file ``foo_if.c'' which contains implementations of those functions which look up the location of the relevant functions in the object's method table and call that function. The system defines two main interfaces. The first fundamental interface is called ``device'' and includes methods which are relevant to all devices. Methods in the ``device'' interface include ``probe'', ``attach'' and ``detach'' to control detection of hardware and ``shutdown'', ``suspend'' and ``resume'' for critical even notification. The second, more complex interface is ``bus''. This interface contains methods suitable for devices which have children, including methods to access bus-specific per-device information (read_ivar and write_ivar), event notification (child_detached, driver_added) and resource management (alloc_resource, activate_resource, deactivate_resource, release_resource). Many methods in the ``bus'' interface are performing services for some child of the bus device. These methods would normally use the first two arguments to specify the bus providing the service and the child device which is requesting the service. To simplify driver code, many of these methods have accessor functions which lookup the parent and call a method on the parent. For instance the method BUS_TEARDOWN_INTR(device_t dev, device_t child, ...) can be called using the function bus_teardown_intr(device_t child, ...). Some types of bus in the system define additional interfaces to provide access to bus-specific functionality. For instance, the pci bus driver defines the ``pci'' interface which has two methods ``read_config'' and ``write_config'' for accessing the configuration registers of a pci device. -- Doug Rabson Mail: dfr@nlsystems.com Nonlinear Systems Ltd. Phone: +44 181 442 9037 To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-new-bus" in the body of the message