diff --git a/en_US.ISO8859-1/books/arch-handbook/newbus/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/newbus/chapter.sgml index e33a5cc9e9..4fda867ee6 100644 --- a/en_US.ISO8859-1/books/arch-handbook/newbus/chapter.sgml +++ b/en_US.ISO8859-1/books/arch-handbook/newbus/chapter.sgml @@ -1,360 +1,360 @@ Jeroen Ruigrok van der Werven (asmodai)
asmodai@FreeBSD.org
 Written by Hiten Pandya
hiten@uk.FreeBSD.org
 Newbus - Special thanks to Mathew N. Dodd, Warner Losh, Bill Paul. - Daug Rabson, Mike Smith, Peter Wemm and Scott Long. + Special thanks to Matthew N. Dodd, Warner Losh, Bill Paul, + Doug Rabson, Mike Smith, Peter Wemm and Scott Long. This chapter explains the Newbus device framework in detail. Device Drivers Purpose of a Device Driver 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. Types of Device Drivers There used to be days in &unix;, and thus FreeBSD, in which there were four types of devices defined: block device drivers character device drivers network device drivers pseudo-device drivers Block devices performed in way that used fixed size blocks [of data]. This type of driver depended on the so called buffer cache, which had the purpose to cache accessed blocks of data in a dedicated part of the 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. Character devices However, in the versions of FreeBSD 4.0 and onward the distinction between block and character devices became non-existent. Overview of Newbus 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. Its main features include amongst others: dynamic attaching easy modularization of drivers 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 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 and for Alpha, various different different models of Alpha have different top-level devices corresponding to the different hardware chipsets, including lca, apecs, cia and tsunami. 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-to-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 top-level 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 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. 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). 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). 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 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. 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. 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 named foo_if.m). Newbus Methods # Foo subsystem/driver (a comment...) INTERFACE foo METHOD int doit { device_t dev; }; # DEFAULT is the method that will be used, if a method was not # provided via: DEVMETHOD() METHOD void doit_to_child { device_t dev; driver_t child; } DEFAULT doit_generic_to_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_CHILD(device_t dev, device_t child); A source file, 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. 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. 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 &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). 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 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. Newbus API 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. Important locations in the source hierarchy src/sys/[arch]/[arch] - Kernel code for a specific machine architecture resides in this directory. for example, the i386 architecture, or the SPARC64 architecture. src/sys/dev/[bus] - device support for a specific [bus] resides in this directory. src/sys/dev/pci - PCI bus support code resides in this directory. 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. Important structures and type definitions devclass_t - This is a type definition of a pointer to a struct devclass. device_method_t - This is same as kobj_method_t (see src/sys/kobj.h). 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 src/sys/sys/bus_private.h for implementation details. 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 for the driver.
<emphasis>driver_t</emphasis> implementation struct driver { KOBJ_CLASS_FIELDS; void *priv; /* driver private data */ };
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.
Device states<emphasis>device_state_t</emphasis> /* * src/sys/sys/bus.h */ typedef enum device_state { DS_NOTPRESENT, /* not probed or probe failed */ DS_ALIVE, /* probe succeeded */ DS_ATTACHED, /* attach method called */ DS_BUSY /* device is open */ } device_state_t;
diff --git a/en_US.ISO8859-1/books/developers-handbook/newbus/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/newbus/chapter.sgml index e33a5cc9e9..4fda867ee6 100644 --- a/en_US.ISO8859-1/books/developers-handbook/newbus/chapter.sgml +++ b/en_US.ISO8859-1/books/developers-handbook/newbus/chapter.sgml @@ -1,360 +1,360 @@ Jeroen Ruigrok van der Werven (asmodai)
asmodai@FreeBSD.org
 Written by Hiten Pandya
hiten@uk.FreeBSD.org
 Newbus - Special thanks to Mathew N. Dodd, Warner Losh, Bill Paul. - Daug Rabson, Mike Smith, Peter Wemm and Scott Long. + Special thanks to Matthew N. Dodd, Warner Losh, Bill Paul, + Doug Rabson, Mike Smith, Peter Wemm and Scott Long. This chapter explains the Newbus device framework in detail. Device Drivers Purpose of a Device Driver 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. Types of Device Drivers There used to be days in &unix;, and thus FreeBSD, in which there were four types of devices defined: block device drivers character device drivers network device drivers pseudo-device drivers Block devices performed in way that used fixed size blocks [of data]. This type of driver depended on the so called buffer cache, which had the purpose to cache accessed blocks of data in a dedicated part of the 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. Character devices However, in the versions of FreeBSD 4.0 and onward the distinction between block and character devices became non-existent. Overview of Newbus 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. Its main features include amongst others: dynamic attaching easy modularization of drivers 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 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 and for Alpha, various different different models of Alpha have different top-level devices corresponding to the different hardware chipsets, including lca, apecs, cia and tsunami. 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-to-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 top-level 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 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. 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). 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). 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 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. 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. 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 named foo_if.m). Newbus Methods # Foo subsystem/driver (a comment...) INTERFACE foo METHOD int doit { device_t dev; }; # DEFAULT is the method that will be used, if a method was not # provided via: DEVMETHOD() METHOD void doit_to_child { device_t dev; driver_t child; } DEFAULT doit_generic_to_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_CHILD(device_t dev, device_t child); A source file, 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. 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. 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 &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). 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 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. Newbus API 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. Important locations in the source hierarchy src/sys/[arch]/[arch] - Kernel code for a specific machine architecture resides in this directory. for example, the i386 architecture, or the SPARC64 architecture. src/sys/dev/[bus] - device support for a specific [bus] resides in this directory. src/sys/dev/pci - PCI bus support code resides in this directory. 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. Important structures and type definitions devclass_t - This is a type definition of a pointer to a struct devclass. device_method_t - This is same as kobj_method_t (see src/sys/kobj.h). 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 src/sys/sys/bus_private.h for implementation details. 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 for the driver.
<emphasis>driver_t</emphasis> implementation struct driver { KOBJ_CLASS_FIELDS; void *priv; /* driver private data */ };
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.
Device states<emphasis>device_state_t</emphasis> /* * src/sys/sys/bus.h */ typedef enum device_state { DS_NOTPRESENT, /* not probed or probe failed */ DS_ALIVE, /* probe succeeded */ DS_ATTACHED, /* attach method called */ DS_BUSY /* device is open */ } device_state_t;
diff --git a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml index 6d56dcef9a..bde00866fa 100644 --- a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml +++ b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml @@ -1,399 +1,399 @@ Source Tree Guidelines and Policies Contributed by &a.phk;. This chapter documents various guidelines and policies in force for the FreeBSD source tree. <makevar>MAINTAINER</makevar> on Makefiles ports maintainer June 1996. If a particular portion of the FreeBSD distribution is being maintained by a person or group of persons, they can communicate this fact to the world by adding a MAINTAINER= email-addresses line to the Makefiles covering this portion of the source tree. The semantics of this are as follows: The maintainer owns and is responsible for that code. This means that he is responsible for fixing bugs and answering problem reports pertaining to that piece of the code, and in the case of contributed software, for tracking new versions, as appropriate. Changes to directories which have a maintainer defined shall be sent to the maintainer for review before being committed. Only if the maintainer does not respond for an unacceptable period of time, to several emails, will it be acceptable to commit changes without review by the maintainer. However, it is suggested that you try to have the changes reviewed by someone else if at all possible. It is of course not acceptable to add a person or group as maintainer unless they agree to assume this duty. On the other hand it does not have to be a committer and it can easily be a group of people. Contributed Software contributed software Contributed by &a.phk; and &a.obrien;. June 1996. Some parts of the FreeBSD distribution consist of software that is actively being maintained outside the FreeBSD project. For historical reasons, we call this contributed software. Some - examples are perl, gcc and patch. + examples are sendmail, gcc and patch. Over the last couple of years, various methods have been used in dealing with this type of software and all have some number of advantages and drawbacks. No clear winner has emerged. Since this is the case, after some debate one of these methods has been selected as the official method and will be required for future imports of software of this kind. Furthermore, it is strongly suggested that existing contributed software converge on this model over time, as it has significant advantages over the old method, including the ability to easily obtain diffs relative to the official versions of the source by everyone (even without cvs access). This will make it significantly easier to return changes to the primary developers of the contributed software. Ultimately, however, it comes down to the people actually doing the work. If using this model is particularly unsuited to the package being dealt with, exceptions to these rules may be granted only with the approval of the core team and with the general consensus of the other developers. The ability to maintain the package in the future will be a key issue in the decisions. Because of some unfortunate design limitations with the RCS file format and CVS's use of vendor branches, minor, trivial and/or cosmetic changes are strongly discouraged on files that are still tracking the vendor branch. Spelling fixes are explicitly included here under the cosmetic category and are to be avoided for files with revision 1.1.x.x. The repository bloat impact from a single character change can be rather dramatic. The Tcl embedded programming language will be used as example of how this model works: src/contrib/tcl contains the source as distributed by the maintainers of this package. Parts that are entirely not applicable for FreeBSD can be removed. In the case of Tcl, the mac, win and compat subdirectories were eliminated before the import. src/lib/libtcl contains only a "bmake style" Makefile that uses the standard bsd.lib.mk makefile rules to produce the library and install the documentation. src/usr.bin/tclsh contains only a bmake style Makefile which will produce and install the tclsh program and its associated man-pages using the standard bsd.prog.mk rules. src/tools/tools/tcl_bmake contains a couple of shell-scripts that can be of help when the tcl software needs updating. These are not part of the built or installed software. The important thing here is that the src/contrib/tcl directory is created according to the rules: it is supposed to contain the sources as distributed (on a proper CVS vendor-branch and without RCS keyword expansion) with as few FreeBSD-specific changes as possible. The 'easy-import' tool on freefall will assist in doing the import, but if there are any doubts on how to go about it, it is imperative that you ask first and not blunder ahead and hope it works out. CVS is not forgiving of import accidents and a fair amount of effort is required to back out major mistakes. Because of the previously mentioned design limitations with CVS's vendor branches, it is required that official patches from the vendor be applied to the original distributed sources and the result re-imported onto the vendor branch again. Official patches should never be patched into the FreeBSD checked out version and committed, as this destroys the vendor branch coherency and makes importing future versions rather difficult as there will be conflicts. Since many packages contain files that are meant for compatibility with other architectures and environments that FreeBSD, it is permissible to remove parts of the distribution tree that are of no interest to FreeBSD in order to save space. Files containing copyright notices and release-note kind of information applicable to the remaining files shall not be removed. If it seems easier, the bmake Makefiles can be produced from the dist tree automatically by some utility, something which would hopefully make it even easier to upgrade to a new version. If this is done, be sure to check in such utilities (as necessary) in the src/tools directory along with the port itself so that it is available to future maintainers. In the src/contrib/tcl level directory, a file called FREEBSD-upgrade should be added and it should state things like: Which files have been left out. Where the original distribution was obtained from and/or the official master site. Where to send patches back to the original authors. Perhaps an overview of the FreeBSD-specific changes that have been made. However, please do not import FREEBSD-upgrade with the contributed source. Rather you should cvs add FREEBSD-upgrade ; cvs ci after the initial import. Example wording from src/contrib/cpio is below: This directory contains virgin sources of the original distribution files on a "vendor" branch. Do not, under any circumstances, attempt to upgrade the files in this directory via patches and a cvs commit. New versions or official-patch versions must be imported. Please remember to import with "-ko" to prevent CVS from corrupting any vendor RCS Ids. For the import of GNU cpio 2.4.2, the following files were removed: INSTALL cpio.info mkdir.c Makefile.in cpio.texi mkinstalldirs To upgrade to a newer version of cpio, when it is available: 1. Unpack the new version into an empty directory. [Do not make ANY changes to the files.] 2. Remove the files listed above and any others that don't apply to FreeBSD. 3. Use the command: cvs import -ko -m 'Virgin import of GNU cpio v<version>' \ src/contrib/cpio GNU cpio_<version> For example, to do the import of version 2.4.2, I typed: cvs import -ko -m 'Virgin import of GNU v2.4.2' \ src/contrib/cpio GNU cpio_2_4_2 4. Follow the instructions printed out in step 3 to resolve any conflicts between local FreeBSD changes and the newer version. Do not, under any circumstances, deviate from this procedure. To make local changes to cpio, simply patch and commit to the main branch (aka HEAD). Never make local changes on the GNU branch. All local changes should be submitted to "cpio@gnu.ai.mit.edu" for inclusion in the next vendor release. obrien@FreeBSD.org - 30 March 1997 Encumbered Files It might occasionally be necessary to include an encumbered file in the FreeBSD source tree. For example, if a device requires a small piece of binary code to be loaded to it before the device will operate, and we do not have the source to that code, then the binary file is said to be encumbered. The following policies apply to including encumbered files in the FreeBSD source tree. Any file which is interpreted or executed by the system CPU(s) and not in source format is encumbered. Any file with a license more restrictive than BSD or GNU is encumbered. A file which contains downloadable binary data for use by the hardware is not encumbered, unless (1) or (2) apply to it. It must be stored in an architecture neutral ASCII format (file2c or uuencoding is recommended). Any encumbered file requires specific approval from the Core team before it is added to the CVS repository. Encumbered files go in src/contrib or src/sys/contrib. The entire module should be kept together. There is no point in splitting it, unless there is code-sharing with non-encumbered code. Object files are named arch/filename.o.uu>. Kernel files: Should always be referenced in conf/files.* (for build simplicity). Should always be in LINT, but the Core team decides per case if it should be commented out or not. The Core team can, of course, change their minds later on. The Release Engineer decides whether or not it goes into the release. User-land files: core team The Core team decides if the code should be part of make world. release engineer The Release Engineer decides if it goes into the release. Shared Libraries Contributed by &a.asami;, &a.peter;, and &a.obrien; 9 December 1996. If you are adding shared library support to a port or other piece of software that does not have one, the version numbers should follow these rules. Generally, the resulting numbers will have nothing to do with the release version of the software. The three principles of shared library building are: Start from 1.0 If there is a change that is backwards compatible, bump minor number (note that ELF systems ignore the minor number) If there is an incompatible change, bump major number For instance, added functions and bugfixes result in the minor version number being bumped, while deleted functions, changed function call syntax, etc. will force the major version number to change. Stick to version numbers of the form major.minor (x.y). Our a.out dynamic linker does not handle version numbers of the form x.y.z well. Any version number after the y (i.e. the third digit) is totally ignored when comparing shared lib version numbers to decide which library to link with. Given two shared libraries that differ only in the micro revision, ld.so will link with the higher one. That is, if you link with libfoo.so.3.3.3, the linker only records 3.3 in the headers, and will link with anything starting with libfoo.so.3.(anything >= 3).(highest available). ld.so will always use the highest minor revision. For instance, it will use libc.so.2.2 in preference to libc.so.2.0, even if the program was initially linked with libc.so.2.0. In addition, our ELF dynamic linker does not handle minor version numbers at all. However, one should still specify a major and minor version number as our Makefiles do the right thing based on the type of system. For non-port libraries, it is also our policy to change the shared library version number only once between releases. In addition, it is our policy to change the major shared library version number only once between major OS releases (i.e. from 3.0 to 4.0). When you make a change to a system library that requires the version number to be bumped, check the Makefile's commit logs. It is the responsibility of the committer to ensure that the first such change since the release will result in the shared library version number in the Makefile to be updated, and any subsequent changes will not.