Date: Thu, 18 May 2023 15:53:42 GMT From: Benedict Reuschling <bcr@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: b2f883f5a2 - main - Remove instances of "in order to" to ease readability Message-ID: <202305181553.34IFrg9O002254@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by bcr: URL: https://cgit.FreeBSD.org/doc/commit/?id=b2f883f5a2d9010820ec194ab709549c3303db6e commit b2f883f5a2d9010820ec194ab709549c3303db6e Author: Benedict Reuschling <bcr@FreeBSD.org> AuthorDate: 2023-05-18 15:46:42 +0000 Commit: Benedict Reuschling <bcr@FreeBSD.org> CommitDate: 2023-05-18 15:53:26 +0000 Remove instances of "in order to" to ease readability Chapter 11 of the FreeBSD Documentation Project Primer states that language should be clear, short, and simple. This phrasing rarely helps with that and can be cut to a single "to" in pretty much all instances. --- .../en/articles/committers-guide/_index.adoc | 4 ++-- .../content/en/articles/contributing/_index.adoc | 2 +- .../content/en/articles/contributors/_index.adoc | 4 ++-- documentation/content/en/articles/cups/_index.adoc | 4 ++-- .../content/en/articles/explaining-bsd/_index.adoc | 8 ++++---- .../en/articles/filtering-bridges/_index.adoc | 16 ++++++++-------- .../content/en/articles/freebsd-releng/_index.adoc | 14 +++++++------- .../content/en/articles/ipsec-must/_index.adoc | 2 +- .../content/en/articles/license-guide/_index.adoc | 4 ++-- .../en/articles/linux-emulation/_index.adoc | 18 +++++++++--------- .../content/en/articles/rc-scripting/_index.adoc | 8 ++++---- .../content/en/articles/remote-install/_index.adoc | 10 +++++----- .../content/en/articles/vinum/_index.adoc | 14 +++++++------- .../content/en/articles/vm-design/_index.adoc | 22 +++++++++++----------- 14 files changed, 65 insertions(+), 65 deletions(-) diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc index 47d7060859..744d3e31ed 100644 --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -1876,7 +1876,7 @@ would look at the log for the vendor branch for zlib starting at 1.2.10. === Collaborating with others One of the keys to good software development on a project as large as FreeBSD is the ability to collaborate with others before you push your changes to the tree. -The FreeBSD project's Git repositories do not, yet, allow user-created branches to be pushed to the repository, and therefore if you wish to share your changes with others you must use another mechanism, such as a hosted GitLab or GitHub, in order to share changes in a user-generated branch. +The FreeBSD project's Git repositories do not, yet, allow user-created branches to be pushed to the repository, and therefore if you wish to share your changes with others you must use another mechanism, such as a hosted GitLab or GitHub, to share changes in a user-generated branch. The following instructions show how to set up a user-generated branch, based on the FreeBSD `main` branch, and push it to GitHub. @@ -3698,7 +3698,7 @@ FreeBSD committers can get a free 4-CD or DVD set at conferences from http://www https://gandi.net[Gandi] provides website hosting, cloud computing, domain registration, and X.509 certificate services. Gandi offers an E-rate discount to all FreeBSD developers. -In order to streamline the process of getting the discount first set up a Gandi account, fill in the billing information and select the currency. +To streamline the process of getting the discount first set up a Gandi account, fill in the billing information and select the currency. Then send an mail to mailto:non-profit@gandi.net[non-profit@gandi.net] using your `@freebsd.org` mail address, and indicate your Gandi handle. [[benefits-rsync]] diff --git a/documentation/content/en/articles/contributing/_index.adoc b/documentation/content/en/articles/contributing/_index.adoc index f4d6a9c657..ceefd904e5 100644 --- a/documentation/content/en/articles/contributing/_index.adoc +++ b/documentation/content/en/articles/contributing/_index.adoc @@ -332,7 +332,7 @@ An additional challenge is to keep individual ports working within the Ports Col As a maintainer, you will need to manage the following challenges: -* *New software versions and updates.* New versions and updates of existing ported software become available all the time, and these need to be incorporated into the Ports Collection in order to provide up-to-date software. +* *New software versions and updates.* New versions and updates of existing ported software become available all the time, and these need to be incorporated into the Ports Collection to provide up-to-date software. * *Changes to dependencies.* If significant changes are made to the dependencies of your port, it may need to be updated so that it will continue to work correctly. diff --git a/documentation/content/en/articles/contributors/_index.adoc b/documentation/content/en/articles/contributors/_index.adoc index 55230b53dc..41516b19fc 100644 --- a/documentation/content/en/articles/contributors/_index.adoc +++ b/documentation/content/en/articles/contributors/_index.adoc @@ -198,12 +198,12 @@ The following individuals and businesses have generously contributed hardware fo * TRW Financial Systems, Inc. provided 130 PCs, three 68 GB file servers, twelve Ethernets, two routers and an ATM switch for debugging the diskless code * Dermot McDonnell donated the Toshiba XM3401B CDROM drive currently used in _freefall_. * Chuck Robey <mailto:chuckr@glue.umd.edu[chuckr@glue.umd.edu]> contributed his floppy tape streamer for experimental work. -* Larry Altneu <mailto:larry@alr.com[larry@alr.com],> and {wilko}, provided Wangtek and Archive QIC-02 tape drives in order to improve the [.filename]#wt# driver. +* Larry Altneu <mailto:larry@alr.com[larry@alr.com],> and {wilko}, provided Wangtek and Archive QIC-02 tape drives to improve the [.filename]#wt# driver. * Ernst Winter (http://berklix.org/ewinter/[Deceased]) contributed a 2.88 MB floppy drive to the project. This will hopefully increase the pressure for rewriting the floppy disk driver. * http://www.tekram.com/[Tekram Technologies] sent one each of their DC-390, DC-390U and DC-390F FAST and ULTRA SCSI host adapter cards for regression testing of the NCR and AMD drivers with their cards. They are also to be applauded for making driver sources for free operating systems available from their FTP server link:ftp://ftp.tekram.com/scsi/FreeBSD/[ftp://ftp.tekram.com/scsi/FreeBSD/]. * Larry M. Augustin contributed not only a Symbios Sym8751S SCSI card, but also a set of data books, including one about the forthcoming Sym53c895 chip with Ultra-2 and LVD support, and the latest programming manual with information on how to safely use the advanced features of the latest Symbios SCSI chips. Thanks a lot! * {kuku} donated an FX120 12 speed Mitsumi CDROM drive for IDE CDROM driver development. -* Mike Tancsa <mailto:mike@sentex.ca[mike@sentex.ca]> donated four various ATM PCI cards in order to help increase support of these cards as well as help support the development effort of the netatm ATM stack. +* Mike Tancsa <mailto:mike@sentex.ca[mike@sentex.ca]> donated four various ATM PCI cards to help increase support of these cards as well as help support the development effort of the netatm ATM stack. === Special contributors diff --git a/documentation/content/en/articles/cups/_index.adoc b/documentation/content/en/articles/cups/_index.adoc index 58930951c9..d16f8da5de 100644 --- a/documentation/content/en/articles/cups/_index.adoc +++ b/documentation/content/en/articles/cups/_index.adoc @@ -77,7 +77,7 @@ Once installed, the CUPS configuration files can be found in the directory [.fil [[printing-cups-configuring-server]] == Configuring the CUPS Print Server -After installation, a few files must be edited in order to configure the CUPS server. +After installation, a few files must be edited to configure the CUPS server. First, create or modify, as the case may be, the file [.filename]#/etc/devfs.rules# and add the following information to set the proper permissions on all potential printer devices and to associate printers with the `cups` user group: [.programlisting] @@ -105,7 +105,7 @@ devfs_system_ruleset="system" These two entries will start the CUPS print server on boot and invoke the local devfs rule created above, respectively. -In order to enable CUPS printing under certain Microsoft(R) Windows(R) clients, the line below should be uncommented in [.filename]#/usr/local/etc/cups/mime.types# and [.filename]#/usr/local/etc/cups/mime.convs#: +To enable CUPS printing under certain Microsoft(R) Windows(R) clients, the line below should be uncommented in [.filename]#/usr/local/etc/cups/mime.types# and [.filename]#/usr/local/etc/cups/mime.convs#: [.programlisting] .... diff --git a/documentation/content/en/articles/explaining-bsd/_index.adoc b/documentation/content/en/articles/explaining-bsd/_index.adoc index b188f0a2b0..ca7b1c02e5 100644 --- a/documentation/content/en/articles/explaining-bsd/_index.adoc +++ b/documentation/content/en/articles/explaining-bsd/_index.adoc @@ -145,8 +145,8 @@ Users can obtain a complete copy of any version. A large number of developers worldwide contribute to improvements to BSD. They are divided into three kinds: -* _Contributors_ write code or documentation. They are not permitted to commit (add code) directly to the source tree. In order for their code to be included in the system, it must be reviewed and checked in by a registered developer, known as a __committer__. -* _Committers_ are developers with write access to the source tree. In order to become a committer, an individual must show ability in the area in which they are active. +* _Contributors_ write code or documentation. They are not permitted to commit (add code) directly to the source tree. For their code to be included in the system, it must be reviewed and checked in by a registered developer, known as a __committer__. +* _Committers_ are developers with write access to the source tree. To become a committer, an individual must show ability in the area in which they are active. + It is at the individual committer's discretion whether they should obtain authority before committing changes to the source tree. In general, an experienced committer may make changes which are obviously correct without obtaining consensus. @@ -154,7 +154,7 @@ For example, a documentation project committer may correct typographical or gram On the other hand, developers making far-reaching or complicated changes are expected to submit their changes for review before committing them In extreme cases, a core team member with a function such as Principal Architect may order that changes be removed from the tree, a process known as _backing out_. All committers receive mail describing each individual commit, so it is not possible to commit secretly. -* The _Core team_. FreeBSD and NetBSD each have a core team which manages the project. The core teams developed in the course of the projects, and their role is not always well-defined. It is not necessary to be a developer in order to be a core team member, though it is normal. The rules for the core team vary from one project to the other, but in general they have more say in the direction of the project than non-core team members have. +* The _Core team_. FreeBSD and NetBSD each have a core team which manages the project. The core teams developed in the course of the projects, and their role is not always well-defined. It is not necessary to be a developer to be a core team member, though it is normal. The rules for the core team vary from one project to the other, but in general they have more say in the direction of the project than non-core team members have. This arrangement differs from Linux in a number of ways: @@ -206,7 +206,7 @@ This is particularly attractive for embedded applications. === What else should I know? Since fewer applications are available for BSD than Linux, the BSD developers created a Linux compatibility package, which allows Linux programs to run under BSD. -The package includes both kernel modifications, in order to correctly perform Linux system calls, and Linux compatibility files such as the C library. +The package includes both kernel modifications, to correctly perform Linux system calls, and Linux compatibility files such as the C library. There is no noticeable difference in execution speed between a Linux application running on a Linux machine and a Linux application running on a BSD machine of the same speed. The "all from one supplier" nature of BSD means that upgrades are much easier to handle than is frequently the case with Linux. diff --git a/documentation/content/en/articles/filtering-bridges/_index.adoc b/documentation/content/en/articles/filtering-bridges/_index.adoc index 1d9f76ba83..ae744fb88d 100644 --- a/documentation/content/en/articles/filtering-bridges/_index.adoc +++ b/documentation/content/en/articles/filtering-bridges/_index.adoc @@ -44,7 +44,7 @@ Abstract Often it is useful to divide one physical network (like an Ethernet) into two separate segments without having to create subnets, and use a router to link them together. The device that connects the two networks in this way is called a bridge. -A FreeBSD system with two network interfaces is enough in order to act as a bridge. +A FreeBSD system with two network interfaces is enough to act as a bridge. A bridge works by scanning the addresses of MAC level (Ethernet addresses) of the devices connected to each of its network interfaces and then forwarding the traffic between the two networks only if the source and the destination are on different segments. Under many points of view a bridge is similar to an Ethernet switch with only two ports. @@ -78,7 +78,7 @@ Select the best choice according to your needs and abilities. Before going on, be sure to have at least two Ethernet cards that support the promiscuous mode for both reception and transmission, since they must be able to send Ethernet packets with any address, not just their own. Moreover, to have a good throughput, the cards should be PCI bus mastering cards. The best choices are still the Intel EtherExpress(TM) Pro, followed by the 3Com(R) 3c9xx series. -To simplify the firewall configuration it may be useful to have two cards of different manufacturers (using different drivers) in order to distinguish clearly which interface is connected to the router and which to the inner network. +To simplify the firewall configuration it may be useful to have two cards of different manufacturers (using different drivers) to distinguish clearly which interface is connected to the router and which to the inner network. [[filtering-bridges-kernel]] === Kernel Configuration @@ -114,9 +114,9 @@ It is not required to add a similar row for the [.filename]#ipfw.ko# module, sin [[filtering-bridges-finalprep]] == Final Preparation -Before rebooting in order to load the new kernel or the required modules (according to the previously chosen installation method), you have to make some changes to the [.filename]#/etc/rc.conf# configuration file. +Before rebooting to load the new kernel or the required modules (according to the previously chosen installation method), you have to make some changes to the [.filename]#/etc/rc.conf# configuration file. The default rule of the firewall is to reject all IP packets. -Initially we will set up an `open` firewall, in order to verify its operation without any issue related to packet filtering (in case you are going to execute this procedure remotely, such configuration will avoid you to remain isolated from the network). +Initially we will set up an `open` firewall, to verify its operation without any issue related to packet filtering (in case you are going to execute this procedure remotely, such configuration will avoid you to remain isolated from the network). Put these lines in [.filename]#/etc/rc.conf#: [.programlisting] @@ -138,7 +138,7 @@ Assigning an IP to both the network cards does not make much sense, unless, duri There is another important thing to know. When running IP over Ethernet, there are actually two Ethernet protocols in use: one is IP, the other is ARP. ARP does the conversion of the IP address of a host into its Ethernet address (MAC layer). -In order to allow the communication between two hosts separated by the bridge, it is necessary that the bridge will forward ARP packets. +To allow the communication between two hosts separated by the bridge, it is necessary that the bridge will forward ARP packets. Such protocol is not included in the IP layer, since it exists only with IP over Ethernet. The FreeBSD firewall filters exclusively on the IP layer and therefore all non-IP packets (ARP included) will be forwarded without being filtered, even if the firewall is configured to not permit anything. @@ -161,12 +161,12 @@ At this point, to enable the bridge, you have to execute the following commands The first row specifies which interfaces should be activated by the bridge, the second one will enable the firewall on the bridge and finally the third one will enable the bridge. At this point you should be able to insert the machine between two sets of hosts without compromising any communication abilities between them. -If so, the next step is to add the `net.link.ether.bridge._[blah]_=_[blah]_` portions of these rows to the [.filename]#/etc/sysctl.conf# file, in order to have them execute at startup. +If so, the next step is to add the `net.link.ether.bridge._[blah]_=_[blah]_` portions of these rows to the [.filename]#/etc/sysctl.conf# file, to have them execute at startup. [[filtering-bridges-ipfirewall]] == Configuring The Firewall -Now it is time to create your own file with custom firewall rules, in order to secure the inside network. +Now it is time to create your own file with custom firewall rules, to secure the inside network. There will be some complication in doing this because not all of the firewall functionalities are available on bridged packets. Furthermore, there is a difference between the packets that are in the process of being forwarded and packets that are being received by the local machine. In general, incoming packets are run through the firewall only once, not twice as is normally the case; in fact they are filtered only upon receipt, so rules that use `out` or `xmit` will never match. @@ -267,7 +267,7 @@ But there is a difference: all suspected traffic will be logged. There are two rules for passing SMTP and DNS traffic towards the mail server and the name server, if you have them. Obviously the whole rule set should be flavored to personal taste, this is only a specific example (rule format is described accurately in the man:ipfw[8] man page). -Note that in order for "relay" and "ns" to work, name service lookups must work _before_ the bridge is enabled. +Note that for "relay" and "ns" to work, name service lookups must work _before_ the bridge is enabled. This is an example of making sure that you set the IP on the correct network card. Alternatively it is possible to specify the IP address instead of the host name (required if the machine is IP-less). diff --git a/documentation/content/en/articles/freebsd-releng/_index.adoc b/documentation/content/en/articles/freebsd-releng/_index.adoc index 02452258df..69a43a8d46 100644 --- a/documentation/content/en/articles/freebsd-releng/_index.adoc +++ b/documentation/content/en/articles/freebsd-releng/_index.adoc @@ -221,7 +221,7 @@ For example, a FreeBSD developer may request blanket approvals from the start of [NOTE] ==== -In order to keep track of blanket approvals, the {teamRe} uses an internal repository to keep a running log of such requests, which defines the area upon which a blanket approval was granted, the author(s), when the blanket approval expires, and the reason the approval was granted. +To keep track of blanket approvals, the {teamRe} uses an internal repository to keep a running log of such requests, which defines the area upon which a blanket approval was granted, the author(s), when the blanket approval expires, and the reason the approval was granted. One example of this is granting blanket approval to [.filename]#release/doc/# to all {teamRe} members until the final `RC` to update the release notes and other release-related documentation. ==== @@ -527,7 +527,7 @@ This is enforced by pre-commit hooks in the Subversion repository by editing [.f [NOTE] ==== There are two general exceptions to requiring commit approval during the release cycle. -The first is any change that needs to be committed by the Release Engineer in order to proceed with the day-to-day workflow of the release cycle, the other is security fixes that may occur during the release cycle. +The first is any change that needs to be committed by the Release Engineer to proceed with the day-to-day workflow of the release cycle, the other is security fixes that may occur during the release cycle. ==== Once the code freeze is in effect, the next build from the branch is labeled `BETA1`. @@ -540,7 +540,7 @@ Subsequent `BETA` builds do not require updates to any files other than [.filena === Creating the {branchRelengx} Branch When the first `RC` (Release Candidate) build is ready to begin, the {branchReleng} branch is created. -This is a multi-step process that must be done in a specific order, in order to avoid anomalies such as overlaps with `__FreeBSD_version` values, for example. +This is a multi-step process that must be done in a specific order, to avoid anomalies such as overlaps with `__FreeBSD_version` values, for example. The paths listed below are relative to the repository root. The order of commits and what to change are: @@ -641,7 +641,7 @@ See and [.filename]#src/release/release.conf.sample# for more details and exampl [[releng-build-scripts-multiple]] ==== The [.filename]#thermite.sh# Wrapper Script -In order to make cross building the full set of architectures supported on a given branch faster, easier, and reduce human error factors, a wrapper script around [.filename]#src/release/release.sh# was written to iterate through the various combinations of architectures and invoke [.filename]#src/release/release.sh# using a configuration file specific to that architecture. +To make cross building the full set of architectures supported on a given branch faster, easier, and reduce human error factors, a wrapper script around [.filename]#src/release/release.sh# was written to iterate through the various combinations of architectures and invoke [.filename]#src/release/release.sh# using a configuration file specific to that architecture. The wrapper script is called [.filename]#thermite.sh#, which is available in the FreeBSD Subversion repository at `svn://svn.freebsd.org/base/user/gjb/thermite/`, in addition to configuration files used to build {branchHead} and {branchStablex} development snapshots. @@ -795,14 +795,14 @@ On `ftp-master` in the FreeBSD Project infrastructure, this step requires `root` === Publishing FreeBSD Installation Media Once the images are staged in [.filename]#/archive/tmp/#, they are ready to be made public by putting them in [.filename]#/archive/pub/FreeBSD#. -In order to reduce propagation time, is used to create hard links from [.filename]#/archive/tmp# to [.filename]#/archive/pub/FreeBSD#. +To reduce propagation time, is used to create hard links from [.filename]#/archive/tmp# to [.filename]#/archive/pub/FreeBSD#. [NOTE] ==== -In order for this to be effective, both [.filename]#/archive/tmp# and [.filename]#/archive/pub# must reside on the same logical filesystem. +For this to be effective, both [.filename]#/archive/tmp# and [.filename]#/archive/pub# must reside on the same logical filesystem. ==== -There is a caveat, however, where rsync must be used after in order to correct the symbolic links in [.filename]#pub/FreeBSD/snapshots/ISO-IMAGES# which will replace with a hard link, increasing the propagation time. +There is a caveat, however, where rsync must be used after to correct the symbolic links in [.filename]#pub/FreeBSD/snapshots/ISO-IMAGES# which will replace with a hard link, increasing the propagation time. [NOTE] ==== diff --git a/documentation/content/en/articles/ipsec-must/_index.adoc b/documentation/content/en/articles/ipsec-must/_index.adoc index 361f70406f..d4de24e1a9 100644 --- a/documentation/content/en/articles/ipsec-must/_index.adoc +++ b/documentation/content/en/articles/ipsec-must/_index.adoc @@ -148,7 +148,7 @@ A comprehensive guide on running IPsec on FreeBSD is provided in extref:{handboo [[kernel]] == src/sys/i386/conf/KERNELNAME -This needs to be present in the kernel config file in order to capture network data with man:tcpdump[1]. +This needs to be present in the kernel config file to capture network data with man:tcpdump[1]. Be sure to run man:config[8] after adding this, and rebuild and reinstall. [.programlisting] diff --git a/documentation/content/en/articles/license-guide/_index.adoc b/documentation/content/en/articles/license-guide/_index.adoc index e6d91491dc..44fbb70d00 100644 --- a/documentation/content/en/articles/license-guide/_index.adoc +++ b/documentation/content/en/articles/license-guide/_index.adoc @@ -66,7 +66,7 @@ Any questions or concerns should immediately be brought to the attention of {cor == Software License Policy The following sections outline the project's Software License Policies in detail. -For the most part we expect developers to read, understand and utilize the sections above this one in order to apply appropriate licenses to their contributions. +For the most part we expect developers to read, understand and utilize the sections above this one to apply appropriate licenses to their contributions. The rest of this document details the philosophical background to the policies as well as the policies in great detail. As always, if the text below is confusing or you need help with applying these policies, please reach out to {core-email}. @@ -113,7 +113,7 @@ The Core Team must approve the import of new CDDL licensed components or the cha *** ZFS filesystem, including kernel support and userland utilities * Historically, the phrase 'All Rights Reserved.' was included in all copyright notices. -All the BSD releases had it, in order to comply with the https://en.wikipedia.org/wiki/Buenos_Aires_Convention[Buenos Aires Convention of 1910] in the Americas. +All the BSD releases had it, to comply with the https://en.wikipedia.org/wiki/Buenos_Aires_Convention[Buenos Aires Convention of 1910] in the Americas. With the ratification of the https://en.wikipedia.org/wiki/Berne_Convention[Berne Convention] in 2000 by Nicaragua, the Buenos Aires Convention -- and the phrase -- became obsolete. As such, the FreeBSD project recommends that new code omit the phrase and encourages existing copyright holders to remove it. In 2018, the project updated its templates to remove it. diff --git a/documentation/content/en/articles/linux-emulation/_index.adoc b/documentation/content/en/articles/linux-emulation/_index.adoc index b695d7bc81..7fefba22e0 100644 --- a/documentation/content/en/articles/linux-emulation/_index.adoc +++ b/documentation/content/en/articles/linux-emulation/_index.adoc @@ -510,14 +510,14 @@ numbers are not casual Spin locks let waiters to spin until they cannot acquire the lock. An important matter do deal with is when a thread contests on a spin lock if it is not descheduled. -Since the FreeBSD kernel is preemptive, this exposes spin lock at the risk of deadlocks that can be solved just disabling interrupts while they are acquired. +Since the FreeBSD kernel is preemptive, this exposes spin lock at the risk of deadlocks that can be solved just disabling interrupts while they are acquired. For this and other reasons (like lack of priority propagation support, poorness in load balancing schemes between CPUs, etc.), spin locks are intended to protect very small paths of code, or ideally not to be used at all if not explicitly requested (explained later). [[freebsd-blocking]] ===== Blocking Block locks let waiters to be descheduled and blocked until the lock owner does not drop it and wakes up one or more contenders. -In order to avoid starvation issues, blocking locks do priority propagation from the waiters to the owner. +To avoid starvation issues, blocking locks do priority propagation from the waiters to the owner. Block locks must be implemented through the turnstile interface and are intended to be the most used kind of locks in the kernel, if no particular conditions are met. [[freebsd-sleeping]] @@ -548,7 +548,7 @@ Among these locks only mutexes, sxlocks, rwlocks and lockmgrs are intended to ha [[freebsd-scheduling]] ===== Scheduling barriers -Scheduling barriers are intended to be used in order to drive scheduling of threading. +Scheduling barriers are intended to be used to drive scheduling of threading. They consist mainly of three different stubs: * critical sections (and preemption) @@ -561,11 +561,11 @@ Generally, these should be used only in a particular context and even if they ca ===== Critical sections The FreeBSD kernel has been made preemptive basically to deal with interrupt threads. -In fact, in order to avoid high interrupt latency, time-sharing priority threads can be preempted by interrupt threads (in this way, they do not need to wait to be scheduled as the normal path previews). +In fact, to avoid high interrupt latency, time-sharing priority threads can be preempted by interrupt threads (in this way, they do not need to wait to be scheduled as the normal path previews). Preemption, however, introduces new racing points that need to be handled, as well. -Often, in order to deal with preemption, the simplest thing to do is to completely disable it. +Often, to deal with preemption, the simplest thing to do is to completely disable it. A critical section defines a piece of code (borderlined by the pair of functions man:critical_enter[9] and man:critical_exit[9], where preemption is guaranteed to not happen (until the protected code is fully executed). -This can often replace a lock effectively but should be used carefully in order to not lose the whole advantage that preemption brings. +This can often replace a lock effectively but should be used carefully to not lose the whole advantage that preemption brings. [[freebsd-schedpin]] ===== sched_pin/sched_unpin @@ -578,7 +578,7 @@ The latter condition will determine a critical section as a too strong condition [[freebsd-schedbind]] ===== sched_bind/sched_unbind -`sched_bind` is an API used in order to bind a thread to a particular CPU for all the time it executes the code, until a `sched_unbind` function call does not unbind it. +`sched_bind` is an API used to bind a thread to a particular CPU for all the time it executes the code, until a `sched_unbind` function call does not unbind it. This feature has a key role in situations where you cannot trust the current state of CPUs (for example, at very early stages of boot), as you want to avoid your thread to migrate on inactive CPUs. Since `sched_bind` and `sched_unbind` manipulate internal scheduler structures, they need to be enclosed in `sched_lock` acquisition/releasing when used. @@ -741,7 +741,7 @@ On the other hand `close` is just an alias for real FreeBSD man:close[2] so it h The Linux(R) emulation layer is not complete, as some syscalls are not implemented properly and some are not implemented at all. The emulation layer employs a facility to mark unimplemented syscalls with the `DUMMY` macro. These dummy definitions reside in [.filename]#linux_dummy.c# in a form of `DUMMY(syscall);`, which is then translated to various syscall auxiliary files and the implementation consists of printing a message saying that this syscall is not implemented. -The `UNIMPL` prototype is not used because we want to be able to identify the name of the syscall that was called in order to know what syscalls are more important to implement. +The `UNIMPL` prototype is not used because we want to be able to identify the name of the syscall that was called to know what syscalls are more important to implement. [[signal-handling]] === Signal handling @@ -775,7 +775,7 @@ It also unmasks the signal in process signal mask. [[ptrace]] === Ptrace -Many UNIX(R) derivates implement the man:ptrace[2] syscall in order to allow various tracking and debugging features. +Many UNIX(R) derivates implement the man:ptrace[2] syscall to allow various tracking and debugging features. This facility enables the tracing process to obtain various information about the traced process, like register dumps, any memory from the process address space, etc. and also to trace the process like in stepping an instruction or between system entries (syscalls and traps). man:ptrace[2] also lets you set various information in the traced process (registers etc.). man:ptrace[2] is a UNIX(R)-wide standard implemented in most UNIX(R)es around the world. diff --git a/documentation/content/en/articles/rc-scripting/_index.adoc b/documentation/content/en/articles/rc-scripting/_index.adoc index ae68c31c28..cdfa656e53 100644 --- a/documentation/content/en/articles/rc-scripting/_index.adoc +++ b/documentation/content/en/articles/rc-scripting/_index.adoc @@ -92,7 +92,7 @@ Finally, an important part of the [.filename]#rc.d# framework is man:rcorder[8], It can help [.filename]#/etc/rc.shutdown#, too, because the proper order for the shutdown sequence is opposite to that of startup. The BSD [.filename]#rc.d# design is described in <<lukem, the original article by Luke Mewburn>>, and the [.filename]#rc.d# components are documented in great detail in <<manpages, the respective manual pages>>. -However, it might not appear obvious to an [.filename]#rc.d# newbie how to tie the numerous bits and pieces together in order to create a well-styled script for a particular task. +However, it might not appear obvious to an [.filename]#rc.d# newbie how to tie the numerous bits and pieces together to create a well-styled script for a particular task. Therefore this article will try a different approach to describe [.filename]#rc.d#. It will show which features should be used in a number of typical cases, and why. Note that this is not a how-to document because our aim is not at giving ready-made recipes, but at showing a few easy entrances into the [.filename]#rc.d# realm. @@ -100,7 +100,7 @@ Neither is this article a replacement for the relevant manual pages. Do not hesitate to refer to them for more formal and complete documentation while reading this article. There are prerequisites to understanding this article. -First of all, you should be familiar with the man:sh[1] scripting language in order to master [.filename]#rc.d#. +First of all, you should be familiar with the man:sh[1] scripting language to master [.filename]#rc.d#. In addition, you should know how the system performs userland startup and shutdown tasks, which is described in man:rc[8]. This article focuses on the FreeBSD branch of [.filename]#rc.d#. @@ -110,7 +110,7 @@ Nevertheless, it may be useful to NetBSD developers, too, because the two branch == Outlining the task A little consideration before starting `$EDITOR` will not hurt. -In order to write a well-tempered [.filename]#rc.d# script for a system service, we should be able to answer the following questions first: +To write a well-tempered [.filename]#rc.d# script for a system service, we should be able to answer the following questions first: * Is the service mandatory or optional? * Will the script serve a single program, e.g., a daemon, or perform more complex actions? @@ -157,7 +157,7 @@ For example, a system admin can run our script manually, from the command line: [NOTE] ==== -In order to be properly managed by the [.filename]#rc.d# framework, its scripts need to be written in the man:sh[1] language. +To be properly managed by the [.filename]#rc.d# framework, its scripts need to be written in the man:sh[1] language. If you have a service or port that uses a binary control utility or a startup routine written in another language, install that element in [.filename]#/usr/sbin# (for the system) or [.filename]#/usr/local/sbin# (for ports) and call it from a man:sh[1] script in the appropriate [.filename]#rc.d# directory. ==== diff --git a/documentation/content/en/articles/remote-install/_index.adoc b/documentation/content/en/articles/remote-install/_index.adoc index f1bd16bb37..9efc5e4165 100644 --- a/documentation/content/en/articles/remote-install/_index.adoc +++ b/documentation/content/en/articles/remote-install/_index.adoc @@ -70,7 +70,7 @@ The instructions included in this article will benefit those using services prov [.procedure] ==== -. As we have mentioned in the <<background>> section, many of the reputable server hosting companies provide some kind of rescue system, which is booted from their LAN and accessible over SSH. They usually provide this support in order to help their customers fix broken operating systems. As this article will explain, it is possible to install FreeBSD with the help of these rescue systems. +. As we have mentioned in the <<background>> section, many of the reputable server hosting companies provide some kind of rescue system, which is booted from their LAN and accessible over SSH. They usually provide this support to help their customers fix broken operating systems. As this article will explain, it is possible to install FreeBSD with the help of these rescue systems. + . The next section of this article will describe how to configure, and build minimalistic FreeBSD on the local machine. That version will eventually be running on the remote machine from a ramdisk, which will allow us to install a complete FreeBSD operating system from an FTP mirror using the sysinstall utility. . The rest of this article will describe the installation procedure itself, as well as the configuration of the ZFS file system. @@ -261,7 +261,7 @@ The following example will describe how to create slices and labels, initialize <.> Write a standard label for each disk including the bootstrap code. -<.> Now, manually edit the label of the given disk. Refer to the man:bsdlabel[8] manual page in order to find out how to create partitions. Create partitions `a` for [.filename]#/# (root) file system, `b` for swap, `d` for [.filename]#/var#, `e` for [.filename]#/usr# and finally `f` which will later be used for ZFS. +<.> Now, manually edit the label of the given disk. Refer to the man:bsdlabel[8] manual page to find out how to create partitions. Create partitions `a` for [.filename]#/# (root) file system, `b` for swap, `d` for [.filename]#/var#, `e` for [.filename]#/usr# and finally `f` which will later be used for ZFS. <.> Import the recently created label for the second hard drive, so both hard drives will be labeled in the same way. @@ -297,7 +297,7 @@ Note that this step is very important and if skipped, `sysinstall` will be unabl ==== Go to the [.guimenuitem]#Distributions# menu, move the cursor with the arrow keys to `Minimal`, and check it by pressing kbd:[Space]. -This article uses the Minimal distribution in order to save network traffic, because the system itself will be installed over ftp. +This article uses the Minimal distribution to save network traffic, because the system itself will be installed over ftp. Exit this menu by choosing `Exit`. [NOTE] @@ -315,9 +315,9 @@ Exit `sysinstall` when it finishes the installation. === Post Installation Steps The FreeBSD operating system should be installed now; however, the process is not finished yet. -It is necessary to perform some post installation steps in order to allow FreeBSD to boot in the future and to be able to log in to the system. +It is necessary to perform some post installation steps to allow FreeBSD to boot in the future and to be able to log in to the system. -You must now man:chroot[8] into the freshly installed system in order to finish the installation. +You must now man:chroot[8] into the freshly installed system to finish the installation. Use the following command: [source,shell] diff --git a/documentation/content/en/articles/vinum/_index.adoc b/documentation/content/en/articles/vinum/_index.adoc index f6b0baea11..0583ae94a7 100644 --- a/documentation/content/en/articles/vinum/_index.adoc +++ b/documentation/content/en/articles/vinum/_index.adoc @@ -68,7 +68,7 @@ This chapter provides an overview of potential problems with traditional disk st [NOTE] ==== -Starting with FreeBSD 5, [.filename]#vinum# has been rewritten in order to fit into the extref:{handbook}[GEOM architecture, geom], while retaining the original ideas, terminology, and on-disk metadata. +Starting with FreeBSD 5, [.filename]#vinum# has been rewritten to fit into the extref:{handbook}[GEOM architecture, geom], while retaining the original ideas, terminology, and on-disk metadata. This rewrite is called _gvinum_ (for _GEOM vinum_). While this chapter uses the term [.filename]#vinum#, any command invocations should be performed with `gvinum`. The name of the kernel module has changed from the original [.filename]#vinum.ko# to [.filename]#geom_vinum.ko#, and all device nodes reside under [.filename]#/dev/gvinum# instead of [.filename]#/dev/vinum#. @@ -158,7 +158,7 @@ If one drive fails, the array can continue to operate in degraded mode where a r [[vinum-objects]] == [.filename]#vinum# Objects -In order to address these problems, [.filename]#vinum# implements a four-level hierarchy of objects: +To address these problems, [.filename]#vinum# implements a four-level hierarchy of objects: * The most visible object is the virtual disk, called a _volume_. Volumes have essentially the same properties as a UNIX(R) disk drive, though there are some minor differences. For one, they have no size limitations. * Volumes are composed of _plexes_, each of which represent the total address space of a volume. This level in the hierarchy provides redundancy. Think of plexes as individual disks in a mirrored array, each containing the same data. @@ -186,7 +186,7 @@ As long as at least one plex can provide the data for the complete address range [.filename]#vinum# implements both concatenation and striping at the plex level: * A _concatenated plex_ uses the address space of each subdisk in turn. Concatenated plexes are the most flexible as they can contain any number of subdisks, and the subdisks may be of different length. The plex may be extended by adding additional subdisks. They require less CPU time than striped plexes, though the difference in CPU overhead is not measurable. On the other hand, they are most susceptible to hot spots, where one disk is very active and others are idle. -* A _striped plex_ stripes the data across each subdisk. The subdisks must all be the same size and there must be at least two subdisks in order to distinguish it from a concatenated plex. The greatest advantage of striped plexes is that they reduce hot spots. By choosing an optimum sized stripe, about 256 kB, the load can be evened out on the component drives. Extending a plex by adding new subdisks is so complicated that [.filename]#vinum# does not implement it. +* A _striped plex_ stripes the data across each subdisk. The subdisks must all be the same size and there must be at least two subdisks to distinguish it from a concatenated plex. The greatest advantage of striped plexes is that they reduce hot spots. By choosing an optimum sized stripe, about 256 kB, the load can be evened out on the component drives. Extending a plex by adding new subdisks is so complicated that [.filename]#vinum# does not implement it. <<vinum-comparison, [.filename]#vinum# Plex Organizations>> summarizes the advantages and disadvantages of each plex organization. @@ -484,7 +484,7 @@ For example, a disk drive may have a name like [.filename]#/dev/ad0a# or [.filen These names represent the first partition ([.filename]#a#) on the first (0) IDE disk ([.filename]#ad#) and the eighth partition ([.filename]#h#) on the third (2) SCSI disk ([.filename]#da#) respectively. By contrast, a [.filename]#vinum# volume might be called [.filename]#/dev/gvinum/concat#, which has no relationship with a partition name. -In order to create a file system on this volume, use man:newfs[8]: +To create a file system on this volume, use man:newfs[8]: [source,shell] .... @@ -582,7 +582,7 @@ Each single subdisk within these plexes needs its own `a` partition illusion, fo It is not strictly needed that each of these faked `a` partitions is located at the same offset within its device, compared with other devices containing plexes of the root volume. However, it is probably a good idea to create the [.filename]#vinum# volumes that way so the resulting mirrored devices are symmetric, to avoid confusion. -In order to set up these `a` partitions for each device containing part of the root volume, the following is required: +To set up these `a` partitions for each device containing part of the root volume, the following is required: [.procedure] ==== @@ -594,7 +594,7 @@ In order to set up these `a` partitions for each device containing part of the r .... + [.filename]#vinum# offsets and sizes are measured in bytes. -They must be divided by 512 in order to obtain the block numbers that are to be used by `bsdlabel`. +They must be divided by 512 to obtain the block numbers that are to be used by `bsdlabel`. . Run this command for each device that participates in the root volume: + [source,shell] @@ -713,4 +713,4 @@ So if a [.filename]#vinum# partition was started at offset 0 within a slice or d Similarly, if the above situation has been recovered, by booting from a "Fixit" media, and the bootstrap has been re-installed using `bsdlabel -B` as described in extref:{handbook}[stage two, boot-boot1], the bootstrap will trash the [.filename]#vinum# header, and [.filename]#vinum# will no longer find its disk(s). Though no actual [.filename]#vinum# configuration data or data in [.filename]#vinum# volumes will be trashed, and it would be possible to recover all the data by entering exactly the same [.filename]#vinum# configuration data again, the situation is hard to fix. -It is necessary to move the entire [.filename]#vinum# partition by at least 4 KB, in order to have the [.filename]#vinum# header and the system bootstrap no longer collide. +It is necessary to move the entire [.filename]#vinum# partition by at least 4 KB, to have the [.filename]#vinum# header and the system bootstrap no longer collide. diff --git a/documentation/content/en/articles/vm-design/_index.adoc b/documentation/content/en/articles/vm-design/_index.adoc index 7499c1e362..1a6431a489 100644 --- a/documentation/content/en/articles/vm-design/_index.adoc +++ b/documentation/content/en/articles/vm-design/_index.adoc @@ -76,7 +76,7 @@ These issues are not due to bad algorithmic design but instead rise from environ In any direct comparison between platforms, these issues become most apparent when system resources begin to get stressed. As I describe FreeBSD's VM/Swap subsystem the reader should always keep two points in mind: -. The most important aspect of performance design is what is known as "Optimizing the Critical Path". It is often the case that performance optimizations add a little bloat to the code in order to make the critical path perform better. +. The most important aspect of performance design is what is known as "Optimizing the Critical Path". It is often the case that performance optimizations add a little bloat to the code to make the critical path perform better. . A solid, generalized design outperforms a heavily-optimized design over the long run. While a generalized design may end up being slower than an heavily-optimized design when they are first implemented, the generalized design tends to be easier to adapt to changing conditions and the heavily-optimized design winds up having to be thrown away. Any codebase that will survive and be maintainable for years must therefore be designed properly from the beginning even if it costs some performance. @@ -185,7 +185,7 @@ FreeBSD allocates the swap management structure for a VM Object only when it is However, the swap management structure has had problems historically: * Under FreeBSD 3.X the swap management structure preallocates an array that encompasses the entire object requiring swap backing store-even if only a few pages of that object are swap-backed. This creates a kernel memory fragmentation problem when large objects are mapped, or processes with large runsizes (RSS) fork. -* Also, in order to keep track of swap space, a "list of holes" is kept in kernel memory, and this tends to get severely fragmented as well. Since the "list of holes" is a linear list, the swap allocation and freeing performance is a non-optimal O(n)-per-page. +* Also, to keep track of swap space, a "list of holes" is kept in kernel memory, and this tends to get severely fragmented as well. Since the "list of holes" is a linear list, the swap allocation and freeing performance is a non-optimal O(n)-per-page. * It requires kernel memory allocations to take place during the swap freeing process, and that creates low memory deadlock problems. * The problem is further exacerbated by holes created due to the interleaving algorithm. * Also, the swap block map can become fragmented fairly easily resulting in non-contiguous allocations. @@ -196,10 +196,10 @@ For FreeBSD 4.X, I completely rewrote the swap subsystem: * Swap management structures are allocated through a hash table rather than a linear array giving them a fixed allocation size and much finer granularity. * Rather then using a linearly linked list to keep track of swap space reservations, it now uses a bitmap of swap blocks arranged in a radix tree structure with free-space hinting in the radix node structures. This effectively makes swap allocation and freeing an O(1) operation. -* The entire radix tree bitmap is also preallocated in order to avoid having to allocate kernel memory during critical low memory swapping operations. After all, the system tends to swap when it is low on memory so we should avoid allocating kernel memory at such times in order to avoid potential deadlocks. +* The entire radix tree bitmap is also preallocated to avoid having to allocate kernel memory during critical low memory swapping operations. After all, the system tends to swap when it is low on memory so we should avoid allocating kernel memory at such times to avoid potential deadlocks. * To reduce fragmentation the radix tree is capable of allocating large contiguous chunks at once, skipping over smaller fragmented chunks. -I did not take the final step of having an "allocating hint pointer" that would trundle through a portion of swap as allocations were made in order to further guarantee contiguous allocations or at least locality of reference, but I ensured that such an addition could be made. +I did not take the final step of having an "allocating hint pointer" that would trundle through a portion of swap as allocations were made to further guarantee contiguous allocations or at least locality of reference, but I ensured that such an addition could be made. [[freeing-pages]] == When to free a page @@ -208,7 +208,7 @@ Since the VM system uses all available memory for disk caching, there are usuall The VM system depends on being able to properly choose pages which are not in use to reuse for new allocations. Selecting the optimal pages to free is possibly the single-most important function any VM system can perform because if it makes a poor selection, the VM system may be forced to unnecessarily retrieve pages from disk, seriously degrading system performance. -How much overhead are we willing to suffer in the critical path to avoid freeing the wrong page? Each wrong choice we make will cost us hundreds of thousands of CPU cycles and a noticeable stall of the affected processes, so we are willing to endure a significant amount of overhead in order to be sure that the right page is chosen. +How much overhead are we willing to suffer in the critical path to avoid freeing the wrong page? Each wrong choice we make will cost us hundreds of thousands of CPU cycles and a noticeable stall of the affected processes, so we are willing to endure a significant amount of overhead to be sure that the right page is chosen. This is why FreeBSD tends to outperform other systems when memory resources become stressed. The free page determination algorithm is built upon a history of the use of memory pages. @@ -240,7 +240,7 @@ This is why you will see some systems with very low cache queue counts and high As the VM system becomes more stressed, it makes a greater effort to maintain the various page queues at the levels determined to be the most effective. An urban myth has circulated for years that Linux did a better job avoiding swapouts than FreeBSD, but this in fact is not true. -What was actually occurring was that FreeBSD was proactively paging out unused pages in order to make room for more disk cache while Linux was keeping unused pages in core and leaving less memory available for cache and process pages. +What was actually occurring was that FreeBSD was proactively paging out unused pages to make room for more disk cache while Linux was keeping unused pages in core and leaving less memory available for cache and process pages. I do not know whether this is still true today. [[prefault-optimizations]] @@ -261,8 +261,8 @@ These occur when a process accesses pages in its BSS area. The BSS area is expected to be initially zero but the VM system does not bother to allocate any memory at all until the process actually accesses it. When a fault occurs the VM system must not only allocate a new page, it must zero it as well. To optimize the zeroing operation the VM system has the ability to pre-zero pages and mark them as such, and to request pre-zeroed pages when zero-fill faults occur. -The pre-zeroing occurs whenever the CPU is idle but the number of pages the system pre-zeros is limited in order to avoid blowing away the memory caches. -This is an excellent example of adding complexity to the VM system in order to optimize the critical path. +The pre-zeroing occurs whenever the CPU is idle but the number of pages the system pre-zeros is limited to avoid blowing away the memory caches. +This is an excellent example of adding complexity to the VM system to optimize the critical path. [[page-table-optimizations]] == Page Table Optimizations @@ -360,16 +360,16 @@ A `vm_page` represents an (object,index#) tuple. A `pv_entry` represents a hardw If you have five processes sharing the same physical page, and three of those processes's page tables actually map the page, that page will be represented by a single `vm_page` structure and three `pv_entry` structures. `pv_entry` structures only represent pages mapped by the MMU (one `pv_entry` represents one pte). -This means that when we need to remove all hardware references to a `vm_page` (in order to reuse the page for something else, page it out, clear it, dirty it, and so forth) we can simply scan the linked list of pv_entry's associated with that vm_page to remove or modify the pte's from their page tables. +This means that when we need to remove all hardware references to a `vm_page` (to reuse the page for something else, page it out, clear it, dirty it, and so forth) we can simply scan the linked list of pv_entry's associated with that vm_page to remove or modify the pte's from their page tables. Under Linux there is no such linked list. -In order to remove all the hardware page table mappings for a `vm_page` linux must index into every VM object that _might_ have mapped the page. +To remove all the hardware page table mappings for a `vm_page` linux must index into every VM object that _might_ have mapped the page. For example, if you have 50 processes all mapping the same shared library and want to get rid of page X in that library, you need to index into the page table for each of those 50 processes even if only 10 of them have actually mapped the page. So Linux is trading off the simplicity of its design against performance. Many VM algorithms which are O(1) or (small N) under FreeBSD wind up being O(N), O(N^2), or worse under Linux. Since the pte's representing a particular page in an object tend to be at the same offset in all the page tables they are mapped in, reducing the number of accesses into the page tables at the same pte offset will often avoid blowing away the L1 cache line for that offset, which can lead to better performance. -FreeBSD has added complexity (the `pv_entry` scheme) in order to increase performance (to limit page table accesses to _only_ those pte's that need to be modified). +FreeBSD has added complexity (the `pv_entry` scheme) to increase performance (to limit page table accesses to _only_ those pte's that need to be modified). But FreeBSD has a scaling problem that Linux does not in that there are a limited number of `pv_entry` structures and this causes problems when you have massive sharing of data. In this case you may run out of `pv_entry` structures even though there is plenty of free memory available.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202305181553.34IFrg9O002254>