Date: Thu, 1 Apr 2021 18:54:50 GMT From: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: 11cd6edd39 - main - Split the developers handbook Message-ID: <202104011854.131Iso4c058093@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by carlavilla: URL: https://cgit.FreeBSD.org/doc/commit/?id=11cd6edd391a42845859da65cb804980dc59221d commit 11cd6edd391a42845859da65cb804980dc59221d Author: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> AuthorDate: 2021-04-01 18:54:26 +0000 Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> CommitDate: 2021-04-01 18:54:26 +0000 Split the developers handbook --- .../en/books/developers-handbook/_index.adoc | 61 +---- .../bibliography/{chapter.adoc => _index.adoc} | 0 .../content/en/books/developers-handbook/book.adoc | 99 ++++++++ .../books/developers-handbook/chapters-order.adoc | 29 ++- .../introduction/{chapter.adoc => _index.adoc} | 2 +- .../ipv6/{chapter.adoc => _index.adoc} | 16 +- .../kernelbuild/{chapter.adoc => _index.adoc} | 8 +- .../kerneldebug/{chapter.adoc => _index.adoc} | 92 +++---- .../l10n/{chapter.adoc => _index.adoc} | 2 +- .../en/books/developers-handbook/parti.adoc | 10 + .../en/books/developers-handbook/partii.adoc | 10 + .../en/books/developers-handbook/partiii.adoc | 10 + .../en/books/developers-handbook/partiv.adoc | 11 + .../en/books/developers-handbook/partv.adoc | 10 + .../books/developers-handbook/policies/_index.adoc | 271 +++++++++++++++++++++ .../developers-handbook/policies/chapter.adoc | 139 ----------- .../secure/{chapter.adoc => _index.adoc} | 6 +- .../sockets/{chapter.adoc => _index.adoc} | 16 +- .../testing/{chapter.adoc => _index.adoc} | 0 .../tools/{chapter.adoc => _index.adoc} | 100 ++++---- .../x86/{chapter.adoc => _index.adoc} | 58 ++--- 21 files changed, 593 insertions(+), 357 deletions(-) diff --git a/documentation/content/en/books/developers-handbook/_index.adoc b/documentation/content/en/books/developers-handbook/_index.adoc index 08a9490c92..3082156c0f 100644 --- a/documentation/content/en/books/developers-handbook/_index.adoc +++ b/documentation/content/en/books/developers-handbook/_index.adoc @@ -3,28 +3,20 @@ title: FreeBSD Developers' Handbook authors: - author: The FreeBSD Documentation Project copyright: 1995-2020 The FreeBSD Documentation Project -releaseinfo: "$FreeBSD$" -trademarks: ["freebsd", "apple", "ibm", "ieee", "intel", "linux", "microsoft", "opengroup", "sun", "general"] +releaseinfo: "$FreeBSD: head/en_US.ISO8859-1/books/developers-handbook/book.xml 54255 2020-06-15 08:13:08Z bcr $" +trademarks: ["freebsd", "apple", "ibm", "ieee", "intel", "linux", "microsoft", "opengroup", "sun", "general"] +next: books/developers-handbook/parti --- = FreeBSD Developers' Handbook :doctype: book :toc: macro -:toclevels: 2 +:toclevels: 1 :icons: font -:xrefstyle: basic -:relfileprefix: ../ -:outfilesuffix: :sectnums: :sectnumlevels: 6 -:partnums: -:chapter-signifier: Chapter -:part-signifier: Part :source-highlighter: rouge :experimental: -:skip-front-matter: -:book: true -:pdf: false ifeval::["{backend}" == "html5"] include::shared/mirrors.adoc[] @@ -33,8 +25,6 @@ include::shared/releases.adoc[] include::shared/en/mailing-lists.adoc[] include::shared/en/teams.adoc[] include::shared/en/urls.adoc[] -:imagesdir: ../../../../images/books/developers-handbook/ -:chapters-path: content/en/books/developers-handbook/ endif::[] ifeval::["{backend}" == "pdf"] @@ -44,8 +34,6 @@ include::../../../../shared/releases.adoc[] include::../../../../shared/en/mailing-lists.adoc[] include::../../../../shared/en/teams.adoc[] include::../../../../shared/en/urls.adoc[] -:imagesdir: ../../../static/images/books/developers-handbook/ -:chapters-path: endif::[] ifeval::["{backend}" == "epub3"] @@ -55,8 +43,6 @@ include::../../../../shared/releases.adoc[] include::../../../../shared/en/mailing-lists.adoc[] include::../../../../shared/en/teams.adoc[] include::../../../../shared/en/urls.adoc[] -:imagesdir: ../../../static/images/books/developers-handbook/ -:chapters-path: endif::[] [.abstract-title] @@ -69,41 +55,4 @@ The latest version of this document is always available from the link:https://ww ''' -toc::[] - -// Section one -[[basics]] -= Basics - -include::{chapters-path}introduction/chapter.adoc[leveloffset=+1, lines=10..24;35..-1] -include::{chapters-path}tools/chapter.adoc[leveloffset=+1, lines=10..26;37..-1] -include::{chapters-path}secure/chapter.adoc[leveloffset=+1, lines=9..23;34..-1] -include::{chapters-path}l10n/chapter.adoc[leveloffset=+1, lines=8..22;33..-1] -include::{chapters-path}policies/chapter.adoc[leveloffset=+1, lines=10..24;35..-1] -include::{chapters-path}testing/chapter.adoc[leveloffset=+1, lines=8..22;33..-1] - -// Section two -[[ipc]] -= Interprocess Communication - -include::{chapters-path}sockets/chapter.adoc[leveloffset=+1, lines=9..23;35..-1] -include::{chapters-path}ipv6/chapter.adoc[leveloffset=+1, lines=9..23;34..-1] - -// Section three -[[kernel]] -= Kernel - -include::{chapters-path}kernelbuild/chapter.adoc[leveloffset=+1, lines=8..22;33..-1] -include::{chapters-path}kerneldebug/chapter.adoc[leveloffset=+1, lines=11..25;36..-1] - -// Section four -[[architectures]] -= Architectures - -include::{chapters-path}x86/chapter.adoc[leveloffset=+1, lines=8..22;33..-1] - -// Appendices -[[appendices]] -= Appendices - -include::{chapters-path}bibliography/chapter.adoc[leveloffset=+1, lines=6..20;29..-1] +include::content/en/books/developers-handbook/toc.adoc[] diff --git a/documentation/content/en/books/developers-handbook/bibliography/chapter.adoc b/documentation/content/en/books/developers-handbook/bibliography/_index.adoc similarity index 100% rename from documentation/content/en/books/developers-handbook/bibliography/chapter.adoc rename to documentation/content/en/books/developers-handbook/bibliography/_index.adoc diff --git a/documentation/content/en/books/developers-handbook/book.adoc b/documentation/content/en/books/developers-handbook/book.adoc new file mode 100644 index 0000000000..c59bda0a3d --- /dev/null +++ b/documentation/content/en/books/developers-handbook/book.adoc @@ -0,0 +1,99 @@ +--- +title: FreeBSD Developers' Handbook +authors: + - author: The FreeBSD Documentation Project +copyright: 1995-2020 The FreeBSD Documentation Project +releaseinfo: "$FreeBSD: head/en_US.ISO8859-1/books/developers-handbook/book.xml 54255 2020-06-15 08:13:08Z bcr $" +trademarks: ["freebsd", "apple", "ibm", "ieee", "intel", "linux", "microsoft", "opengroup", "sun", "general"] +--- + += FreeBSD Developers' Handbook +:doctype: book +:toc: macro +:toclevels: 2 +:icons: font +:xrefstyle: basic +:relfileprefix: ../ +:outfilesuffix: +:sectnums: +:sectnumlevels: 6 +:partnums: +:chapter-signifier: Chapter +:part-signifier: Part +:source-highlighter: rouge +:experimental: +:skip-front-matter: +:book: true +:pdf: false + +ifeval::["{backend}" == "html5"] +include::shared/mirrors.adoc[] +include::shared/authors.adoc[] +include::shared/releases.adoc[] +include::shared/en/mailing-lists.adoc[] +include::shared/en/teams.adoc[] +include::shared/en/urls.adoc[] +:imagesdir: ../../../../images/books/developers-handbook/ +:chapters-path: content/en/books/developers-handbook/ +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/mirrors.adoc[] +include::../../../../shared/authors.adoc[] +include::../../../../shared/releases.adoc[] +include::../../../../shared/en/mailing-lists.adoc[] +include::../../../../shared/en/teams.adoc[] +include::../../../../shared/en/urls.adoc[] +:imagesdir: ../../../static/images/books/developers-handbook/ +:chapters-path: +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/mirrors.adoc[] +include::../../../../shared/authors.adoc[] +include::../../../../shared/releases.adoc[] +include::../../../../shared/en/mailing-lists.adoc[] +include::../../../../shared/en/teams.adoc[] +include::../../../../shared/en/urls.adoc[] +:imagesdir: ../../../static/images/books/developers-handbook/ +:chapters-path: +endif::[] + +[.abstract-title] +[abstract] +Abstract + +Welcome to the Developers' Handbook. This manual is a _work in progress_ and is the work of many individuals. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to the {freebsd-doc}. + +The latest version of this document is always available from the link:https://www.FreeBSD.org[FreeBSD World Wide Web server]. It may also be downloaded in a variety of formats and compression options from the link:https://download.freebsd.org/ftp/doc/[FreeBSD FTP server] or one of the numerous link:{handbook}#mirrors-ftp/[mirror sites]. + +''' + +toc::[] + +// Section one +include::{chapters-path}parti.adoc[lines=7..8] +include::{chapters-path}introduction/_index.adoc[leveloffset=+1, lines=10..24;35..-1] +include::{chapters-path}tools/_index.adoc[leveloffset=+1, lines=10..26;37..-1] +include::{chapters-path}secure/_index.adoc[leveloffset=+1, lines=9..23;34..-1] +include::{chapters-path}l10n/_index.adoc[leveloffset=+1, lines=8..22;33..-1] +include::{chapters-path}policies/_index.adoc[leveloffset=+1, lines=10..24;35..-1] +include::{chapters-path}testing/_index.adoc[leveloffset=+1, lines=8..22;33..-1] + +// Section two +include::{chapters-path}partii.adoc[lines=7..8] +include::{chapters-path}sockets/_index.adoc[leveloffset=+1, lines=9..23;35..-1] +include::{chapters-path}ipv6/_index.adoc[leveloffset=+1, lines=9..23;34..-1] + +// Section three +include::{chapters-path}partiii.adoc[lines=7..8] +include::{chapters-path}kernelbuild/_index.adoc[leveloffset=+1, lines=8..22;33..-1] +include::{chapters-path}kerneldebug/_index.adoc[leveloffset=+1, lines=11..25;36..-1] + +// Section four +include::{chapters-path}partiv.adoc[lines=7..8] +include::{chapters-path}x86/_index.adoc[leveloffset=+1, lines=8..22;33..-1] + +// Appendices +include::{chapters-path}partv.adoc[lines=7..8] +include::{chapters-path}bibliography/_index.adoc[leveloffset=+1, lines=6..20;29..-1] diff --git a/documentation/content/en/books/developers-handbook/chapters-order.adoc b/documentation/content/en/books/developers-handbook/chapters-order.adoc index 90183764d6..ef978f645c 100644 --- a/documentation/content/en/books/developers-handbook/chapters-order.adoc +++ b/documentation/content/en/books/developers-handbook/chapters-order.adoc @@ -1,12 +1,17 @@ -introduction/chapter.adoc -tools/chapter.adoc -secure/chapter.adoc -l10n/chapter.adoc -policies/chapter.adoc -testing/chapter.adoc -sockets/chapter.adoc -ipv6/chapter.adoc -kernelbuild/chapter.adoc -kerneldebug/chapter.adoc -x86/chapter.adoc -bibliography/chapter.adoc +parti.adoc +introduction/_index.adoc +tools/_index.adoc +secure/_index.adoc +l10n/_index.adoc +policies/_index.adoc +testing/_index.adoc +partii.adoc +sockets/_index.adoc +ipv6/_index.adoc +partiii.adoc +kernelbuild/_index.adoc +kerneldebug/_index.adoc +partiv.adoc +x86/_index.adoc +partv.adoc +bibliography/_index.adoc diff --git a/documentation/content/en/books/developers-handbook/introduction/chapter.adoc b/documentation/content/en/books/developers-handbook/introduction/_index.adoc similarity index 99% rename from documentation/content/en/books/developers-handbook/introduction/chapter.adoc rename to documentation/content/en/books/developers-handbook/introduction/_index.adoc index 4aff6e3847..019f80f577 100644 --- a/documentation/content/en/books/developers-handbook/introduction/chapter.adoc +++ b/documentation/content/en/books/developers-handbook/introduction/_index.adoc @@ -60,7 +60,7 @@ Our ideology can be described by the following guidelines From Scheifler & Gettys: "X Window System" [[introduction-layout]] -== The Layout of [.filename]#/usr/src# +== The Layout of /usr/src The complete source code to FreeBSD is available from our public repository. The source code is normally installed in [.filename]#/usr/src# which contains the following subdirectories: diff --git a/documentation/content/en/books/developers-handbook/ipv6/chapter.adoc b/documentation/content/en/books/developers-handbook/ipv6/_index.adoc similarity index 99% rename from documentation/content/en/books/developers-handbook/ipv6/chapter.adoc rename to documentation/content/en/books/developers-handbook/ipv6/_index.adoc index 50379e6d09..1d86a91fe4 100644 --- a/documentation/content/en/books/developers-handbook/ipv6/chapter.adoc +++ b/documentation/content/en/books/developers-handbook/ipv6/_index.adoc @@ -164,7 +164,7 @@ Ordinary userland applications should use advanced API (RFC2292) to specify scop In the kernel, an interface index for link-local scoped address is embedded into 2nd 16bit-word (3rd and 4th byte) in IPv6 address. For example, you may see something like: -[source,shell] +[source,bash] .... fe80:1::200:f8ff:fe01:6317 .... @@ -190,7 +190,7 @@ IPv6 link-local address is generated from IEEE802 address (Ethernet MAC address) Here is an output of netstat command: -[source,shell] +[source,bash] .... Internet6: Destination Gateway Flags Netif Expire @@ -221,7 +221,7 @@ Therefore, this is unwise to enable net.inet6.ip6.accept_rtadv on routers, or mu To summarize the sysctl knob: -[source,shell] +[source,bash] .... accept_rtadv forwarding role of the node --- --- --- @@ -288,7 +288,7 @@ and recompile the new kernel. Then you can test jumbo payloads by the man:ping6[8] command with -b and -s options. The -b option must be specified to enlarge the size of the socket buffer and the -s option specifies the length of the packet, which should be more than 65,535. For example, type as follows: -[source,shell] +[source,bash] .... % ping6 -b 70000 -s 68000 ::1 .... @@ -297,7 +297,7 @@ The IPv6 specification requires that the Jumbo Payload option must not be used i When an IPv6 packet is received, the frame length is checked and compared to the length specified in the payload length field of the IPv6 header or in the value of the Jumbo Payload option, if any. If the former is shorter than the latter, the packet is discarded and statistics are incremented. You can see the statistics as output of man:netstat[8] command with `-s -p ip6' option: -[source,shell] +[source,bash] .... % netstat -s -p ip6 ip6: @@ -345,7 +345,7 @@ To process IP6 header, extension headers and transport headers easily, network d `netstat -s -p ip6` tells you whether or not your driver conforms such requirement. In the following example, "cce0" violates the requirement. (For more information, refer to Section 2.) -[source,shell] +[source,bash] .... Mbuf statistics: 317 one mbuf @@ -374,7 +374,7 @@ You can perform wildcard bind on both of the address families, on the same port. The following table show the behavior of FreeBSD 4.x. -[source,shell] +[source,bash] .... listening side initiating side (AF_INET6 wildcard (connection to ::ffff:10.1.1.1) @@ -627,7 +627,7 @@ Note that the behavior is configurable in per-node manner, not per-SA manner (dr The behavior is summarized as follows (see source code for more detail): -[source,shell] +[source,bash] .... encapsulate decapsulate --- --- diff --git a/documentation/content/en/books/developers-handbook/kernelbuild/chapter.adoc b/documentation/content/en/books/developers-handbook/kernelbuild/_index.adoc similarity index 97% rename from documentation/content/en/books/developers-handbook/kernelbuild/chapter.adoc rename to documentation/content/en/books/developers-handbook/kernelbuild/_index.adoc index 906ce32357..7322b4cab3 100644 --- a/documentation/content/en/books/developers-handbook/kernelbuild/chapter.adoc +++ b/documentation/content/en/books/developers-handbook/kernelbuild/_index.adoc @@ -47,21 +47,21 @@ Building the kernel this way may be useful when working on the kernel code and i [.procedure] . Run man:config[8] to generate the kernel source code: + -[source,shell] +[source,bash] .... # /usr/sbin/config MYKERNEL .... . Change into the build directory. man:config[8] will print the name of this directory after being run as above. + -[source,shell] +[source,bash] .... # cd ../compile/MYKERNEL .... . Compile the kernel: + -[source,shell] +[source,bash] .... # make depend # make @@ -69,7 +69,7 @@ Building the kernel this way may be useful when working on the kernel code and i . Install the new kernel: + -[source,shell] +[source,bash] .... # make install .... diff --git a/documentation/content/en/books/developers-handbook/kerneldebug/chapter.adoc b/documentation/content/en/books/developers-handbook/kerneldebug/_index.adoc similarity index 98% rename from documentation/content/en/books/developers-handbook/kerneldebug/chapter.adoc rename to documentation/content/en/books/developers-handbook/kerneldebug/_index.adoc index f0d83de480..930d941c3f 100644 --- a/documentation/content/en/books/developers-handbook/kerneldebug/chapter.adoc +++ b/documentation/content/en/books/developers-handbook/kerneldebug/_index.adoc @@ -73,7 +73,7 @@ Check [.filename]#/etc/fstab# or man:swapinfo[8] for a list of swap devices. ==== Make sure the `dumpdir` specified in man:rc.conf[5] exists before a kernel crash! -[source,shell] +[source,bash] .... # mkdir /var/crash # chmod 700 /var/crash @@ -96,7 +96,7 @@ The man:crashinfo[8] utility generates a text file containing a summary of infor If you are testing a new kernel but need to boot a different one in order to get your system up and running again, boot it only into single user mode using the `-s` flag at the boot prompt, and then perform the following steps: -[source,shell] +[source,bash] .... # fsck -p # mount -a -t ufs # make sure /var/crash is writable @@ -111,7 +111,7 @@ This instructs man:savecore[8] to extract a kernel dump from [.filename]#/dev/ad The kernel includes a man:sysctl[8] node that requests a kernel panic. This can be used to verify that your system is properly configured to save kernel crash dumps. You may wish to remount existing file systems as read-only in single user mode before triggering the crash to avoid data loss. -[source,shell] +[source,bash] .... # shutdown now ... @@ -134,21 +134,21 @@ This section covers man:kgdb[1]. The latest version is included in the package:d To enter into the debugger and begin getting information from the dump, start kgdb: -[source,shell] +[source,bash] .... # kgdb -n N .... Where _N_ is the suffix of the [.filename]#vmcore.N# to examine. To open the most recent dump use: -[source,shell] +[source,bash] .... # kgdb -n last .... Normally, man:kgdb[1] should be able to locate the kernel running at the time the dump was generated. If it is not able to locate the correct kernel, pass the pathname of the kernel and dump as two arguments to kgdb: -[source,shell] +[source,bash] .... # kgdb /boot/kernel/kernel /var/crash/vmcore.0 .... @@ -157,7 +157,7 @@ You can debug the crash dump using the kernel sources just like you can for any This dump is from a 5.2-BETA kernel and the crash comes from deep within the kernel. The output below has been modified to include line numbers on the left. This first trace inspects the instruction pointer and obtains a back trace. The address that is used on line 41 for the `list` command is the instruction pointer and can be found on line 17. Most developers will request having at least this information sent to them if you are unable to debug the problem yourself. If, however, you do solve the problem, make sure that your patch winds its way into the source tree via a problem report, mailing lists, or by being able to commit it! -[source,shell] +[source,bash] .... 1:# cd /usr/obj/usr/src/sys/KERNCONF 2:# kgdb kernel.debug /var/crash/vmcore.0 @@ -281,7 +281,7 @@ Once your DDB kernel is running, there are several ways to enter DDB. The first, The second scenario is to drop to the debugger once the system has booted. There are two simple ways to accomplish this. If you would like to break to the debugger from the command prompt, simply type the command: -[source,shell] +[source,bash] .... # sysctl debug.kdb.enter=1 .... @@ -301,7 +301,7 @@ to the kernel configuration file and rebuild/reinstall. The DDB commands roughly resemble some `gdb` commands. The first thing you probably need to do is to set a breakpoint: -[source,shell] +[source,bash] .... break function-name address .... @@ -310,14 +310,14 @@ Numbers are taken hexadecimal by default, but to make them distinct from symbol To exit the debugger and continue execution, type: -[source,shell] +[source,bash] .... continue .... To get a stack trace of the current thread, use: -[source,shell] +[source,bash] .... trace .... @@ -326,7 +326,7 @@ To get a stack trace of an arbitrary thread, specify a process ID or thread ID a If you want to remove a breakpoint, use -[source,shell] +[source,bash] .... del del address-expression @@ -334,28 +334,28 @@ If you want to remove a breakpoint, use The first form will be accepted immediately after a breakpoint hit, and deletes the current breakpoint. The second form can remove any breakpoint, but you need to specify the exact address; this can be obtained from: -[source,shell] +[source,bash] .... show b .... or: -[source,shell] +[source,bash] .... show break .... To single-step the kernel, try: -[source,shell] +[source,bash] .... s .... This will step into functions, but you can make DDB trace them until the matching return statement is reached by: -[source,shell] +[source,bash] .... n .... @@ -367,7 +367,7 @@ This is different from ``gdb``'s `next` statement; it is like ``gdb``'s `finish` To examine data from memory, use (for example): -[source,shell] +[source,bash] .... x/wx 0xf0133fe0,40 x/hd db_symtab_space @@ -377,14 +377,14 @@ To examine data from memory, use (for example): for word/halfword/byte access, and hexadecimal/decimal/character/ string display. The number after the comma is the object count. To display the next 0x10 items, simply use: -[source,shell] +[source,bash] .... x ,10 .... Similarly, use -[source,shell] +[source,bash] .... x/ia foofunc,10 .... @@ -393,7 +393,7 @@ to disassemble the first 0x10 instructions of `foofunc`, and display them along To modify memory, use the write command: -[source,shell] +[source,bash] .... w/b termbuf 0xa 0xb 0 w/w 0xf0010030 0 0 @@ -403,28 +403,28 @@ The command modifier (`b`/`h`/`w`) specifies the size of the data to be written, If you need to know the current registers, use: -[source,shell] +[source,bash] .... show reg .... Alternatively, you can display a single register value by e.g. -[source,shell] +[source,bash] .... p $eax .... and modify it by: -[source,shell] +[source,bash] .... set $eax new-value .... Should you need to call some kernel functions from DDB, simply say: -[source,shell] +[source,bash] .... call func(arg1, arg2, ...) .... @@ -433,28 +433,28 @@ The return value will be printed. For a man:ps[1] style summary of all running processes, use: -[source,shell] +[source,bash] .... ps .... Now you have examined why your kernel failed, and you wish to reboot. Remember that, depending on the severity of previous malfunctioning, not all parts of the kernel might still be working as expected. Perform one of the following actions to shut down and reboot your system: -[source,shell] +[source,bash] .... panic .... This will cause your kernel to dump core and reboot, so you can later analyze the core on a higher level with man:kgdb[1]. -[source,shell] +[source,bash] .... call boot(0) .... Might be a good way to cleanly shut down the running system, `sync()` all disks, and finally, in some cases, reboot. As long as the disk and filesystem interfaces of the kernel are not damaged, this could be a good way for an almost clean shutdown. -[source,shell] +[source,bash] .... reset .... @@ -463,7 +463,7 @@ This is the final way out of disaster and almost the same as hitting the Big Red If you need a short command summary, simply type: -[source,shell] +[source,bash] .... help .... @@ -479,7 +479,7 @@ GDB has already supported _remote debugging_ for a long time. This is done using You should configure the kernel in question with `config -g` if building the "traditional" way. If building the "new" way, make sure that `makeoptions DEBUG=-g` is in the configuration. In both cases, include `DDB` in the configuration, and compile it as usual. This gives a large binary, due to the debugging information. Copy this kernel to the target machine, strip the debugging symbols off with `strip -x`, and boot it using the `-d` boot option. Connect the serial line of the target machine that has "flags 080" set on its uart device to any serial line of the debugging host. See man:uart[4] for information on how to set the flags on an uart device. Now, on the debugging machine, go to the compile directory of the target kernel, and start `gdb`: -[source,shell] +[source,bash] .... % kgdb kernel GDB is free software and you are welcome to distribute copies of it @@ -492,14 +492,14 @@ Copyright 1996 Free Software Foundation, Inc... Initialize the remote debugging session (assuming the first serial port is being used) by: -[source,shell] +[source,bash] .... (kgdb) target remote /dev/cuau0 .... Now, on the target host (the one that entered DDB right before even starting the device probe), type: -[source,shell] +[source,bash] .... Debugger("Boot flags requested debugger") Stopped at Debugger+0x35: movb $0, edata+0x51bc @@ -508,14 +508,14 @@ db> gdb DDB will respond with: -[source,shell] +[source,bash] .... Next trap will enter GDB remote protocol mode .... Every time you type `gdb`, the mode will be toggled between remote GDB and local DDB. In order to force a next trap immediately, simply type `s` (step). Your hosting GDB will now gain control over the target kernel: -[source,shell] +[source,bash] .... Remote debugging using /dev/cuau0 Debugger (msg=0xf01b0383 "Boot flags requested debugger") @@ -579,7 +579,7 @@ To enable FireWire(R) and Dcons support in man:loader[8] on i386 or amd64: Add `LOADER_FIREWIRE_SUPPORT=YES` in [.filename]#/etc/make.conf# and rebuild man:loader[8]: -[source,shell] +[source,bash] .... # cd /sys/boot/i386 && make clean && make && make install .... @@ -588,7 +588,7 @@ To enable man:dcons[4] as an active low-level console, add `boot_multicons="YES" Here are a few configuration examples. A sample kernel configuration file would contain: -[source,shell] +[source,bash] .... device dcons device dcons_crom @@ -600,7 +600,7 @@ options ALT_BREAK_TO_DEBUGGER And a sample [.filename]#/boot/loader.conf# would contain: -[source,shell] +[source,bash] .... dcons_crom_load="YES" dcons_gdb=1 @@ -613,7 +613,7 @@ hw.firewire.dcons_crom.force_console=1 To enable FireWire(R) support in the kernel on the _host machine_: -[source,shell] +[source,bash] .... # kldload firewire .... @@ -622,7 +622,7 @@ Find out the EUI64 (the unique 64 bit identifier) of the FireWire(R) host contro Run man:dconschat[8], with: -[source,shell] +[source,bash] .... # dconschat -e \# -br -G 12345 -t 00-11-22-33-44-55-66-77 .... @@ -648,7 +648,7 @@ The following key combinations can be used once man:dconschat[8] is running: Attach remote GDB by starting man:kgdb[1] with a remote debugging session: -[source,shell] +[source,bash] .... kgdb -r :12345 kernel .... @@ -659,7 +659,7 @@ Here are some general tips: To take full advantage of the speed of FireWire(R), disable other slow console drivers: -[source,shell] +[source,bash] .... # conscontrol delete ttyd0 # serial console # conscontrol delete consolectl # video/keyboard @@ -667,7 +667,7 @@ To take full advantage of the speed of FireWire(R), disable other slow console d There exists a GDB mode for man:emacs[1]; this is what you will need to add to your [.filename]#.emacs#: -[source,shell] +[source,bash] .... (setq gud-gdba-command-name "kgdb -a -a -a -r :12345") (setq gdb-many-windows t) @@ -677,7 +677,7 @@ M-x gdba And for DDD ([.filename]#devel/ddd#): -[source,shell] +[source,bash] .... # remote serial protocol LANG=C ddd --debugger kgdb -r :12345 kernel @@ -695,21 +695,21 @@ To use man:dcons[4] with KVM: Dump a man:dcons[4] buffer of a live system: -[source,shell] +[source,bash] .... # dconschat -1 .... Dump a man:dcons[4] buffer of a crash dump: -[source,shell] +[source,bash] .... # dconschat -1 -M vmcore.XX .... Live core debugging can be done via: -[source,shell] +[source,bash] .... # fwcontrol -m target_eui64 # kgdb kernel /dev/fwmem0.2 diff --git a/documentation/content/en/books/developers-handbook/l10n/chapter.adoc b/documentation/content/en/books/developers-handbook/l10n/_index.adoc similarity index 97% rename from documentation/content/en/books/developers-handbook/l10n/chapter.adoc rename to documentation/content/en/books/developers-handbook/l10n/_index.adoc index 3903ed3d75..4966af0aa2 100644 --- a/documentation/content/en/books/developers-handbook/l10n/chapter.adoc +++ b/documentation/content/en/books/developers-handbook/l10n/_index.adoc @@ -78,7 +78,7 @@ The language catalog files have to be compiled into a binary form before they ca [[nls-using]] === Using the Catalog Files from the Source Code -Using the catalog files is simple. To use the related functions, [.filename]#nl_types.h# must be included. Before using a catalog, it has to be opened with man:catopen[3]. The function takes two arguments. The first parameter is the name of the installed and compiled catalog. Usually, the name of the program is used, such as grep. This name will be used when looking for the compiled catalog file. The man:catopen[3] call looks for this file in [.filename]#/usr/share/nls/locale/catname# and in [.filename]#/usr/local/shared/nls/locale/catname#, where `locale` is the locale set and `catname` is the catalog name being discussed. The second parameter is a constant, which can have two values: +Using the catalog files is simple. To use the related functions, [.filename]#nl_types.h# must be included. Before using a catalog, it has to be opened with man:catopen[3]. The function takes two arguments. The first parameter is the name of the installed and compiled catalog. Usually, the name of the program is used, such as grep. This name will be used when looking for the compiled catalog file. The man:catopen[3] call looks for this file in [.filename]#/usr/shared/nls/locale/catname# and in [.filename]#/usr/local/shared/nls/locale/catname#, where `locale` is the locale set and `catname` is the catalog name being discussed. The second parameter is a constant, which can have two values: * `NL_CAT_LOCALE`, which means that the used catalog file will be based on `LC_MESSAGES`. * `0`, which means that `LANG` has to be used to open the proper catalog. diff --git a/documentation/content/en/books/developers-handbook/parti.adoc b/documentation/content/en/books/developers-handbook/parti.adoc new file mode 100644 index 0000000000..28dc649a3e --- /dev/null +++ b/documentation/content/en/books/developers-handbook/parti.adoc @@ -0,0 +1,10 @@ +--- +title: Part I. Basics +prev: books/developers-handbook/preface +next: books/developers-handbook/introduction +--- + +[[basics]] += Basics + +include::content/en/books/developers-handbook/toc-1.adoc[] diff --git a/documentation/content/en/books/developers-handbook/partii.adoc b/documentation/content/en/books/developers-handbook/partii.adoc new file mode 100644 index 0000000000..0216af6687 --- /dev/null +++ b/documentation/content/en/books/developers-handbook/partii.adoc @@ -0,0 +1,10 @@ +--- +title: Part II. Interprocess Communication +prev: books/developers-handbook/testing +next: books/developers-handbook/sockets +--- + +[[ipc]] += Interprocess Communication + +include::content/en/books/developers-handbook/toc-2.adoc[] diff --git a/documentation/content/en/books/developers-handbook/partiii.adoc b/documentation/content/en/books/developers-handbook/partiii.adoc new file mode 100644 index 0000000000..7357b79867 --- /dev/null +++ b/documentation/content/en/books/developers-handbook/partiii.adoc @@ -0,0 +1,10 @@ +--- +title: Part III. Kernel +prev: books/developers-handbook/ipv6 +next: books/developers-handbook/kernelbuild +--- + +[[kernel]] += Kernel + +include::content/en/books/developers-handbook/toc-3.adoc[] diff --git a/documentation/content/en/books/developers-handbook/partiv.adoc b/documentation/content/en/books/developers-handbook/partiv.adoc new file mode 100644 index 0000000000..bed213b989 --- /dev/null +++ b/documentation/content/en/books/developers-handbook/partiv.adoc @@ -0,0 +1,11 @@ +--- +title: Part IV. Architectures +prev: books/developers-handbook/kerneldebug +next: books/developers-handbook/x86 +--- + +[[architectures]] += Architectures + +include::content/en/books/developers-handbook/toc-4.adoc[] + diff --git a/documentation/content/en/books/developers-handbook/partv.adoc b/documentation/content/en/books/developers-handbook/partv.adoc new file mode 100644 index 0000000000..305926ca2e --- /dev/null +++ b/documentation/content/en/books/developers-handbook/partv.adoc @@ -0,0 +1,10 @@ +--- +title: Part V. Appendices +prev: books/developers-handbook/x86 +next: books/developers-handbook/bibliography +--- + +[[appendices]] += Appendices + +include::content/en/books/developers-handbook/toc-5.adoc[] diff --git a/documentation/content/en/books/developers-handbook/policies/_index.adoc b/documentation/content/en/books/developers-handbook/policies/_index.adoc new file mode 100644 index 0000000000..0f437fd48c --- /dev/null +++ b/documentation/content/en/books/developers-handbook/policies/_index.adoc @@ -0,0 +1,271 @@ +--- +title: Chapter 5. Source Tree Guidelines and Policies +authors: + - author: Poul-Henning Kamp + - author: Giorgos Keramidas +prev: books/developers-handbook/l10n +next: books/developers-handbook/testing +--- + +[[policies]] += Source Tree Guidelines and Policies +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:source-highlighter: rouge +:experimental: +:skip-front-matter: +:xrefstyle: basic +:relfileprefix: ../ +:outfilesuffix: +:sectnumoffset: 5 + +include::shared/mirrors.adoc[] +include::shared/authors.adoc[] +include::shared/releases.adoc[] +include::shared/en/mailing-lists.adoc[] +include::shared/en/teams.adoc[] +include::shared/en/urls.adoc[] + +toc::[] + +This chapter documents various guidelines and policies in force for the FreeBSD source tree. + +[[policies-style]] +== Style Guidelines + +Consistent coding style is extremely important, particularly with large projects like FreeBSD. Code should follow the FreeBSD coding styles described in man:style[9] and man:style.Makefile[5]. + +[[policies-maintainer]] +== `MAINTAINER` on Makefiles + +If a particular portion of the FreeBSD [.filename]#src/# distribution is being maintained by a person or group of persons, this is communicated through an entry in [.filename]#src/MAINTAINERS#. Maintainers of ports within the Ports Collection express their maintainership to the world by adding a `MAINTAINER` line to the [.filename]#Makefile# of the port in question: + +[.programlisting] +.... +MAINTAINER= email-addresses +.... + +[TIP] +==== + +For other parts of the repository, or for sections not listed as having a maintainer, or when you are unsure who the active maintainer is, try looking at the recent commit history of the relevant parts of the source tree. It is quite often the case that a maintainer is not explicitly named, but the people who are actively working in a part of the source tree for, say, the last couple of years are interested in reviewing changes. Even if this is not specifically mentioned in the documentation or the source itself, asking for a review as a form of courtesy is a very reasonable thing to do. +==== + +The role of the maintainer is as follows: + *** 1175 LINES SKIPPED ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202104011854.131Iso4c058093>