Path: blob/main/documentation/content/en/books/arch-handbook/newbus/_index.po
18099 views
# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2025-05-01 19:56-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <[email protected]>\n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: Title = #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:1 #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:19 #, no-wrap msgid "Newbus" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:1 #, no-wrap msgid "Chapter 14. Newbus" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:57 msgid "" "_Special thanks to Matthew N. Dodd, Warner Losh, Bill Paul, Doug Rabson, " "Mike Smith, Peter Wemm and Scott Long_." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:59 msgid "This chapter explains the Newbus device framework in detail." msgstr "" #. type: Title == #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:61 #, no-wrap msgid "Device Drivers" msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:63 #, no-wrap msgid "Purpose of a Device Driver" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:66 msgid "" "A device driver is a software component which provides the interface between " "the kernel's generic view of a peripheral (e.g., disk, network adapter) and " "the actual implementation of the peripheral. The _device driver interface " "(DDI)_ is the defined interface between the kernel and the device driver " "component." msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:67 #, no-wrap msgid "Types of Device Drivers" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:70 msgid "" "There used to be days in UNIX(R), and thus FreeBSD, in which there were four " "types of devices defined:" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:72 msgid "block device drivers" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:73 msgid "character device drivers" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:74 msgid "network device drivers" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:75 msgid "pseudo-device drivers" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:77 msgid "" "_Block devices_ performed in a way that used fixed size blocks [of data]. " "This type of driver depended on the so-called _buffer cache_, which had " "cached accessed blocks of data in a dedicated part of memory. Often this " "buffer cache was based on write-behind, which meant that when data was " "modified in memory it got synced to disk whenever the system did its " "periodical disk flushing, thus optimizing writes." msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:78 #, no-wrap msgid "Character Devices" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:81 msgid "" "However, in the versions of FreeBSD 4.0 and onward the distinction between " "block and character devices became non-existent." msgstr "" #. type: Title == #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:83 #, no-wrap msgid "Overview of Newbus" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:86 msgid "" "_Newbus_ is the implementation of a new bus architecture based on " "abstraction layers which saw its introduction in FreeBSD 3.0 when the Alpha " "port was imported into the source tree. It was not until 4.0 before it " "became the default system to use for device drivers. Its goals are to " "provide a more object-oriented means of interconnecting the various busses " "and devices which a host system provides to the _Operating System_." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:88 msgid "Its main features include amongst others:" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:90 msgid "dynamic attaching" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:91 msgid "easy modularization of drivers" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:92 msgid "pseudo-busses" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:94 msgid "" "One of the most prominent changes is the migration from the flat and ad-hoc " "system to a device tree layout." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:96 msgid "" "At the top level resides the _\"root\"_ device which 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-to-PCI bridges_, etc. " "attached to it. For x86, this \"root\" device is the _\"nexus\"_ device. For " "Alpha, various different models of Alpha have different top-level devices " "corresponding to the different hardware chipsets, including _lca_, _apecs_, " "_cia_ and _tsunami_." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:98 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:100 msgid "" "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-to-PCI bridge_ which is represented by a device " "_[.filename]#pcibN#_ on the parent PCI bus and has a child " "_[.filename]#pciN#_ for the attached bus. This layout simplifies the " "implementation of the PCI bus tree, allowing common code to be used for both " "top-level and bridged busses." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:102 msgid "" "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." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:106 msgid "" "An ISA device might want to map its IO port at `0x230`, 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 `0x230` IO port " "request might become memory-mapped at `0xb0000230` on a MIPS box by the PCI " "bridge." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:109 msgid "" "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 top-level nexus device. For both ports, memory and port " "address space is managed by a single entity - nexus for IA-32 and the " "relevant chipset driver on Alpha (e.g., CIA or tsunami)." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:111 msgid "" "In order to normalize 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)." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:113 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:115 msgid "" "Newbus also allows for definitions of interface methods in files dedicated " "to this purpose. These are the [.filename]#.m# files that are found under " "the [.filename]#src/sys# hierarchy." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:117 msgid "" "The core of the Newbus 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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:119 msgid "" "In the Newbus 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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:121 msgid "" "The interfaces are described by an interface definition language similar to " "the language used to define vnode operations for file systems. The interface " "would be stored in a methods file (which would normally be named " "[.filename]#foo_if.m#)." msgstr "" #. type: Block title #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:122 #, no-wrap msgid "Newbus Methods" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:128 #, no-wrap msgid " # Foo subsystem/driver (a comment...)\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:130 #, no-wrap msgid "\t INTERFACE foo\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:134 #, no-wrap msgid "" "\tMETHOD int doit {\n" "\t\tdevice_t dev;\n" "\t};\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:137 #, no-wrap msgid "" "\t# DEFAULT is the method that will be used, if a method was not\n" "\t# provided via: DEVMETHOD()\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:142 #, no-wrap msgid "" "\tMETHOD void doit_to_child {\n" "\t\tdevice_t dev;\n" "\t\tdriver_t child;\n" "\t} DEFAULT doit_generic_to_child;\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:146 msgid "" "When this interface is compiled, it generates a header file " "\"[.filename]#foo_if.h#\" which contains function declarations:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:151 #, no-wrap msgid "" " int FOO_DOIT(device_t dev);\n" " int FOO_DOIT_TO_CHILD(device_t dev, device_t child);\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:154 msgid "" "A source file, \"[.filename]#foo_if.c#\" is also created to accompany the " "automatically generated header file; it contains implementations of those " "functions which look up the location of the relevant functions in the " "object's method table and call that function." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:156 msgid "" "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 event notification." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:158 msgid "" "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 footnote:" "[man:bus_generic_read_ivar[9] and man:bus_generic_write_ivar[9]], event " "notification (`_child_detached_`, `_driver_added_`) and resource management " "(`_alloc_resource_`, `_activate_resource_`, `_deactivate_resource_`, " "`_release_resource_`)." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:160 msgid "" "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, ...)`." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:162 msgid "" "Some bus types 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." msgstr "" #. type: Title == #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:164 #, no-wrap msgid "Newbus API" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:167 msgid "" "As the Newbus API is huge, this section makes some effort at documenting it. " "More information to come in the next revision of this document." msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:168 #, no-wrap msgid "Important Locations in the Source Hierarchy" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:171 msgid "" "[.filename]#src/sys/[arch]/[arch]# - Kernel code for a specific machine " "architecture resides in this directory. For example, the `i386` " "architecture, or the `SPARC64` architecture." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:173 msgid "" "[.filename]#src/sys/dev/[bus]# - device support for a specific `[bus]` " "resides in this directory." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:175 msgid "" "[.filename]#src/sys/dev/pci# - PCI bus support code resides in this " "directory." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:177 msgid "" "[.filename]#src/sys/[isa|pci]# - PCI/ISA device drivers reside in this " "directory. The PCI/ISA bus support code used to exist in this directory in " "FreeBSD version `4.0`." msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:178 #, no-wrap msgid "Important Structures and Type Definitions" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:181 msgid "" "`devclass_t` - This is a type definition of a pointer to a `struct devclass`." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:183 msgid "" "`device_method_t` - This is the same as `kobj_method_t` (see [.filename]#src/" "sys/kobj.h#)." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:185 msgid "" "`device_t` - This is a type definition of a pointer to a `struct device`. " "`device_t` represents a device in the system. It is a kernel object. See " "[.filename]#src/sys/sys/bus_private.h# for implementation details." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:187 msgid "" "`driver_t` - This is a type definition which references `struct driver`. The " "`driver` struct is a class of the `device` kernel object; it also holds data " "private to the driver." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:189 #, no-wrap msgid "*_driver_t_ Implementation*\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:195 #, no-wrap msgid "" "\t struct driver {\n" "\t\tKOBJ_CLASS_FIELDS;\n" "\t\tvoid\t*priv;\t\t\t/* driver private data */\n" "\t };\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:198 msgid "" "A `device_state_t` type, which is an enumeration, `device_state`. It " "contains the possible states of a Newbus device before and after the " "autoconfiguration process." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:200 #, no-wrap msgid "*Device States _device_state_t*\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/newbus/_index.adoc:211 #, no-wrap msgid "" "\t /*\n" "\t * src/sys/sys/bus.h\n" "\t */\n" "\t typedef enum device_state {\n" "\t\tDS_NOTPRESENT,\t/* not probed or probe failed */\n" "\t\tDS_ALIVE,\t\t/* probe succeeded */\n" "\t\tDS_ATTACHED,\t/* attach method called */\n" "\t\tDS_BUSY\t\t\t/* device is open */\n" "\t } device_state_t;\n" msgstr ""