svn commit: r52145 - in head/en_US.ISO8859-1/books/developers-handbook: policies x86
Benedict Reuschling <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.cvs.doc |
|---|---|
| Message-ID | <[email protected]> |
Author: bcr
Date: Fri Aug 17 12:37:22 2018
New Revision: 52145
URL: https://svnweb.freebsd.org/changeset/doc/52145
Log:
Rewrapping, putting commas after i.e., minor fixes that textproc/igor was
emitting.
Modified:
head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml
head/en_US.ISO8859-1/books/developers-handbook/x86/chapter.xml
Modified: head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml Fri Aug 17 09:16:31 2018 (r52144)
+++ head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml Fri Aug 17 12:37:22 2018 (r52145)
@@ -4,17 +4,29 @@
$FreeBSD$
-->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="policies">
- <info><title>Source Tree Guidelines and Policies</title>
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="policies">
+ <info>
+ <title>Source Tree Guidelines and Policies</title>
+
<authorgroup>
- <author><personname><firstname>Poul-Henning</firstname><surname>Kamp</surname></personname><contrib>Contributed by </contrib></author>
- <author><personname><firstname>Giorgos</firstname><surname>Keramidas</surname></personname></author>
+ <author>
+ <personname>
+ <firstname>Poul-Henning</firstname>
+ <surname>Kamp</surname>
+ </personname>
+ <contrib>Contributed by </contrib>
+ </author>
+ <author>
+ <personname>
+ <firstname>Giorgos</firstname>
+ <surname>Keramidas</surname>
+ </personname>
+ </author>
</authorgroup>
-
</info>
-
-
<para>This chapter documents various guidelines and policies in
force for the FreeBSD source tree.</para>
@@ -37,11 +49,11 @@
<para>If a particular portion of the &os;
<filename>src/</filename> distribution is being maintained by a
person or group of persons, this is communicated through an
- entry in the <filename>src/MAINTAINERS</filename> file.
- Maintainers of ports within the Ports Collection express their
- maintainership to the world by adding a
- <varname>MAINTAINER</varname> line to the
- <filename>Makefile</filename> of the port in question:</para>
+ entry in <filename>src/MAINTAINERS</filename>. Maintainers of
+ ports within the Ports Collection express their maintainership
+ to the world by adding a <varname>MAINTAINER</varname> line to
+ the <filename>Makefile</filename> of the port in
+ question:</para>
<programlisting><varname>MAINTAINER</varname>= <replaceable>email-addresses</replaceable></programlisting>
@@ -90,17 +102,32 @@
</sect1>
<sect1 xml:id="policies-contributed">
- <info><title>Contributed Software</title>
+ <info>
+ <title>Contributed Software</title>
+
<authorgroup>
- <author><personname><firstname>Poul-Henning</firstname><surname>Kamp</surname></personname><contrib>Contributed by </contrib></author>
- <author><personname><firstname>David</firstname><surname>O'Brien</surname></personname></author>
- <author><personname><firstname>Gavin</firstname><surname>Atkinson</surname></personname></author>
+ <author>
+ <personname>
+ <firstname>Poul-Henning</firstname>
+ <surname>Kamp</surname>
+ </personname>
+ <contrib>Contributed by </contrib>
+ </author>
+ <author>
+ <personname>
+ <firstname>David</firstname>
+ <surname>O'Brien</surname>
+ </personname>
+ </author>
+ <author>
+ <personname>
+ <firstname>Gavin</firstname>
+ <surname>Atkinson</surname>
+ </personname>
+ </author>
</authorgroup>
-
</info>
-
-
<indexterm><primary>contributed software</primary></indexterm>
<para>Some parts of the FreeBSD distribution consist of software
@@ -144,12 +171,19 @@
</note>
<sect2 xml:id="vendor-import-svn">
- <info><title>Vendor Imports with SVN</title>
+ <info>
+ <title>Vendor Imports with SVN</title>
+
<authorgroup>
- <author><personname><firstname>Dag-Erling</firstname><surname>Smørgrav</surname></personname><contrib>Contributed by </contrib></author>
+ <author>
+ <personname>
+ <firstname>Dag-Erling</firstname>
+ <surname>Smørgrav</surname>
+ </personname>
+ <contrib>Contributed by </contrib>
+ </author>
</authorgroup>
</info>
-
<para>This section describes the vendor import procedure with
<application>Subversion</application> in details.</para>
@@ -212,7 +246,7 @@
&prompt.user; <userinput>svn commit</userinput></screen>
<para>where <replaceable>svn_base</replaceable> is the base
- directory of your <acronym>SVN</acronym> repository, e.g.
+ directory of your <acronym>SVN</acronym> repository, e.g.,
<literal>svn+ssh://svn.FreeBSD.org/base</literal>.</para>
</step>
@@ -237,7 +271,7 @@
&prompt.user; <userinput>find . -type f | cut -c 3- | sort > ../<replaceable>new</replaceable></userinput></screen>
<para>With these two files, the following command will list
- list removed files (files only in
+ removed files (files only in
<filename><replaceable>old</replaceable></filename>):</para>
<screen>&prompt.user; <userinput>comm -23 ../<replaceable>old</replaceable> ../<replaceable>new</replaceable></userinput></screen>
@@ -248,7 +282,7 @@
<screen>&prompt.user; <userinput>comm -13 ../<replaceable>old</replaceable> ../<replaceable>new</replaceable></userinput></screen>
- <para>Let's put this together:</para>
+ <para>Let us put this together:</para>
<screen>&prompt.user; <userinput>cd vendor/<replaceable>foo</replaceable>/<replaceable>foo-9.9</replaceable></userinput>
&prompt.user; <userinput>tar cf - . | tar xf - -C ../dist</userinput>
@@ -337,7 +371,7 @@
<screen>&prompt.user; <userinput>svn diff --no-diff-deleted --old=<replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist --new=.</userinput></screen>
- <para>The <option>--no-diff-deleted</option> option tells
+ <para><option>--no-diff-deleted</option> tells
<acronym>SVN</acronym> not to check files that are in the
vendor tree but not in the main tree.</para>
@@ -401,7 +435,8 @@
<listitem>
<para>Any encumbered file requires specific approval from the
- <link xlink:href="&url.base;/administration.html#t-core">Core
+ <link
+ xlink:href="&url.base;/administration.html#t-core">Core
Team</link> before it is added to the repository.</para>
</listitem>
@@ -433,9 +468,11 @@
<listitem>
<para>Should always be in <filename>LINT</filename>, but
- the <link xlink:href="&url.base;/administration.html#t-core">Core
- Team</link> decides per case if it should be
- commented out or not. The <link xlink:href="&url.base;/administration.html#t-core">Core
+ the <link
+ xlink:href="&url.base;/administration.html#t-core">Core
+ Team</link> decides per case if it should be commented
+ out or not. The <link
+ xlink:href="&url.base;/administration.html#t-core">Core
Team</link> can, of course, change their minds later
on.</para>
</listitem>
@@ -452,18 +489,19 @@
<orderedlist>
<listitem>
- <para>The <link xlink:href="&url.base;/administration.html#t-core">Core
+ <para>The <link
+ xlink:href="&url.base;/administration.html#t-core">Core
team</link><indexterm><primary>core
- team</primary></indexterm> decides if
- the code should be part of
- <command>make world</command>.</para>
+ team</primary></indexterm> decides if the code
+ should be part of <command>make world</command>.</para>
</listitem>
<listitem>
- <para>The <link xlink:href="&url.base;/administration.html#t-re">Release
+ <para>The <link
+ xlink:href="&url.base;/administration.html#t-re">Release
Engineering</link><indexterm><primary>release
- engineering</primary></indexterm>
- decides if it goes into the release.</para>
+ engineering</primary></indexterm> decides if it goes
+ into the release.</para>
</listitem>
</orderedlist>
</listitem>
@@ -471,17 +509,32 @@
</sect1>
<sect1 xml:id="policies-shlib">
- <info><title>Shared Libraries</title>
+ <info>
+ <title>Shared Libraries</title>
+
<authorgroup>
- <author><personname><firstname>Satoshi</firstname><surname>Asami</surname></personname><contrib>Contributed by </contrib></author>
- <author><personname><firstname>Peter</firstname><surname>Wemm</surname></personname></author>
- <author><personname><firstname>David</firstname><surname>O'Brien</surname></personname></author>
+ <author>
+ <personname>
+ <firstname>Satoshi</firstname>
+ <surname>Asami</surname>
+ </personname>
+ <contrib>Contributed by </contrib>
+ </author>
+ <author>
+ <personname>
+ <firstname>Peter</firstname>
+ <surname>Wemm</surname>
+ </personname>
+ </author>
+ <author>
+ <personname>
+ <firstname>David</firstname>
+ <surname>O'Brien</surname>
+ </personname>
+ </author>
</authorgroup>
-
</info>
-
-
<para>If you are adding shared library support to a port or other
piece of software that does not have one, the version numbers
should follow these rules. Generally, the resulting numbers
@@ -518,7 +571,7 @@
form
<replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
well. Any version number after the <replaceable>y</replaceable>
- (i.e. the third digit) is totally ignored when comparing shared
+ (i.e., the third digit) is totally ignored when comparing shared
lib version numbers to decide which library to link with. Given
two shared libraries that differ only in the
<quote>micro</quote> revision, <command>ld.so</command> will
@@ -547,7 +600,7 @@
<para>For non-port libraries, it is also our policy to change the
shared library version number only once between releases. In
addition, it is our policy to change the major shared library
- version number only once between major OS releases (i.e. from
+ version number only once between major OS releases (i.e., from
6.0 to 7.0). When you make a change to a system library that
requires the version number to be bumped, check the
<filename>Makefile</filename>'s commit logs. It is the
Modified: head/en_US.ISO8859-1/books/developers-handbook/x86/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/developers-handbook/x86/chapter.xml Fri Aug 17 09:16:31 2018 (r52144)
+++ head/en_US.ISO8859-1/books/developers-handbook/x86/chapter.xml Fri Aug 17 12:37:22 2018 (r52145)
@@ -18,150 +18,118 @@
$FreeBSD$
-->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="x86">
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="x86">
-<title>x86 Assembly Language Programming</title>
-<para>
-<emphasis>
-This chapter was written by &a.stanislav.email;.
-</emphasis></para>
+ <title>x86 Assembly Language Programming</title>
+ <para><emphasis>This chapter was written by
+ &a.stanislav.email;.</emphasis></para>
+ <sect1 xml:id="x86-intro">
+ <title>Synopsis</title>
-<sect1 xml:id="x86-intro">
-<title>Synopsis</title>
+ <para>Assembly language programming under &unix; is highly
+ undocumented. It is generally assumed that no one would ever
+ want to use it because various &unix; systems run on different
+ microprocessors, so everything should be written in C for
+ portability.</para>
-<para>
-Assembly language programming under &unix; is highly undocumented. It
-is generally assumed that no one would ever want to use it because
-various &unix; systems run on different microprocessors, so everything
-should be written in C for portability.
-</para>
+ <para>In reality, C portability is quite a myth. Even C programs
+ need to be modified when ported from one &unix; to another,
+ regardless of what processor each runs on. Typically, such a
+ program is full of conditional statements depending on the
+ system it is compiled for.</para>
-<para>
-In reality, C portability is quite a myth. Even C programs need
-to be modified when ported from one &unix; to another, regardless of
-what processor each runs on. Typically, such a program is full
-of conditional statements depending on the system it is
-compiled for.
-</para>
+ <para>Even if we believe that all of &unix; software should be
+ written in C, or some other high-level language, we still need
+ assembly language programmers: Who else would write the section
+ of C library that accesses the kernel?</para>
-<para>
-Even if we believe that all of &unix; software should be written in C,
-or some other high-level language, we still need assembly language
-programmers: Who else would write the section of C library
-that accesses the kernel?
-</para>
+ <para>In this chapter I will attempt to show you how you can use
+ assembly language writing &unix; programs, specifically under
+ FreeBSD.</para>
-<para>
-In this chapter I will attempt to show you
-how you can use assembly language writing
-&unix; programs, specifically under FreeBSD.
-</para>
+ <para>This chapter does not explain the basics of assembly
+ language. There are enough resources about that (for a complete
+ online course in assembly language, see Randall Hyde's <link
+ xlink:href="http://webster.cs.ucr.edu/">Art of Assembly
+ Language</link>; or if you prefer a printed book, take a look
+ at Jeff Duntemann's Assembly Language Step-by-Step (ISBN:
+ 0471375233). However, once the chapter is finished, any
+ assembly language programmer will be able to write programs for
+ FreeBSD quickly and efficiently.</para>
-<para>
-This chapter does not explain the basics of assembly language.
-There are enough resources about that (for a complete
-online course in assembly language, see Randall Hyde's
-<link xlink:href="http://webster.cs.ucr.edu/">Art
-of Assembly Language</link>; or if you prefer
-a printed book, take a look at Jeff Duntemann's
-Assembly
-Language Step-by-Step (ISBN: 0471375233). However,
-once the chapter is finished, any assembly language programmer
-will be able to write programs for FreeBSD
-quickly and efficiently.
-</para>
+ <para>Copyright © 2000-2001 G. Adam Stanislav. All rights
+ reserved.</para>
+ </sect1>
-<para>
-Copyright © 2000-2001 G. Adam Stanislav. All rights reserved.
-</para>
+ <sect1 xml:id="x86-the-tools">
+ <title>The Tools</title>
-</sect1>
+ <sect2 xml:id="x86-the-assembler">
+ <title>The Assembler</title>
-<sect1 xml:id="x86-the-tools">
-<title>The Tools</title>
+ <para>The most important tool for assembly language programming
+ is the assembler, the software that converts assembly language
+ code into machine language.</para>
-<sect2 xml:id="x86-the-assembler">
-<title>The Assembler</title>
+ <para>Two very different assemblers are available for FreeBSD.
+ One is
+ <citerefentry><refentrytitle>as</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ which uses the traditional &unix; assembly language syntax.
+ It comes with the system.</para>
-<para>
-The most important tool for assembly language programming is the
-assembler, the software that converts assembly language code
-into machine language.
-</para>
+ <para>The other is
+ <application>/usr/ports/devel/nasm</application>. It uses the
+ Intel syntax. Its main advantage is that it can assemble code
+ for many operating systems. It needs to be installed
+ separately, but is completely free.</para>
-<para>
-Two very different assemblers are available for FreeBSD. One is
-<citerefentry><refentrytitle>as</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-which uses the traditional &unix; assembly language syntax. It
-comes with the system.
-</para>
+ <para>This chapter uses <application>nasm</application> syntax
+ because most assembly language programmers coming to FreeBSD
+ from other operating systems will find it easier to
+ understand. And, because, quite frankly, that is what I am
+ used to.</para>
+ </sect2>
-<para>
-The other is <application>/usr/ports/devel/nasm</application>.
-It uses the Intel syntax. Its main advantage is that it
-can assemble code for many operating systems. It needs
-to be installed separately, but is completely free.
-</para>
+ <sect2 xml:id="x86-the-linker">
+ <title>The Linker</title>
-<para>
-This chapter uses <application>nasm</application>
-syntax because most assembly language programmers
-coming to FreeBSD from other operating systems
-will find it easier to understand. And, because,
-quite frankly, that is what I am used to.
-</para>
+ <para>The output of the assembler, like that of any compiler,
+ needs to be linked to form an executable file.</para>
-</sect2>
+ <para>The standard
+ <citerefentry><refentrytitle>ld</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ linker comes with FreeBSD. It works with the code assembled
+ with either assembler.</para>
+ </sect2>
+ </sect1>
-<sect2 xml:id="x86-the-linker">
-<title>The Linker</title>
+ <sect1 xml:id="x86-system-calls">
+ <title>System Calls</title>
-<para>
-The output of the assembler, like that of any
-compiler, needs to be linked to form an executable file.
-</para>
+ <sect2 xml:id="x86-default-calling-convention">
+ <title>Default Calling Convention</title>
-<para>
-The standard
-<citerefentry><refentrytitle>ld</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-linker comes with FreeBSD. It works with the
-code assembled with either assembler.
-</para>
+ <para>By default, the FreeBSD kernel uses the C calling
+ convention. Further, although the kernel is accessed using
+ <function role="opcode">int 80h</function>, it is assumed the
+ program will call a function that issues <function
+ role="opcode">int 80h</function>, rather than issuing
+ <function role="opcode">int 80h</function> directly.</para>
-</sect2>
-</sect1>
+ <para>This convention is very convenient, and quite superior to
+ the µsoft; convention used by
+ <acronym>&ms-dos;</acronym>. Why? Because the &unix;
+ convention allows any program written in any language to
+ access the kernel.</para>
-<sect1 xml:id="x86-system-calls">
-<title>System Calls</title>
+ <para>An assembly language program can do that as well. For
+ example, we could open a file:</para>
-<sect2 xml:id="x86-default-calling-convention">
-<title>Default Calling Convention</title>
-
-<para>
-By default, the FreeBSD kernel uses the C calling
-convention. Further, although the kernel is accessed
-using <function role="opcode">int 80h</function>,
-it is assumed the program will call a function that
-issues <function role="opcode">int 80h</function>, rather than
-issuing <function role="opcode">int 80h</function> directly.
-</para>
-
-<para>
-This convention is very convenient, and quite superior to the
-µsoft; convention used by <acronym>&ms-dos;</acronym>.
-Why? Because the &unix; convention allows any program written in
-any language to access the kernel.
-</para>
-
-<para>
-An assembly language program can do that as well.
-For example, we could open a file:
-</para>
-
-<programlisting>
-kernel:
+ <programlisting>kernel:
int 80h ; Call kernel
ret
@@ -172,364 +140,286 @@ open:
mov eax, 5
call kernel
add esp, byte 12
- ret
-</programlisting>
+ ret</programlisting>
-<para>
-This is a very clean and portable way of coding. If you need to
-port the code to a &unix; system which uses a different interrupt,
-or a different way of passing parameters, all you need to change
-is the kernel procedure.
-</para>
+ <para>This is a very clean and portable way of coding. If you
+ need to port the code to a &unix; system which uses a
+ different interrupt, or a different way of passing parameters,
+ all you need to change is the kernel procedure.</para>
-<para>
-But assembly language programmers like to shave off cycles. The above example
-requires a <function role="opcode">call/ret</function> combination.
-We can eliminate it by
-<function role="opcode">push</function>ing an extra dword:
-</para>
+ <para>But assembly language programmers like to shave off
+ cycles. The above example requires a <function
+ role="opcode">call/ret</function> combination. We can
+ eliminate it by <function role="opcode">push</function>ing an
+ extra dword:</para>
-<programlisting>
-open:
+ <programlisting>open:
push dword mode
push dword flags
push dword path
mov eax, 5
push eax ; Or any other dword
int 80h
- add esp, byte 16
-</programlisting>
+ add esp, byte 16</programlisting>
-<para>
-The <constant>5</constant> that we have placed in
-<varname role="register">EAX</varname> identifies
-the kernel function, in this case <function role="syscall">open</function>.
-</para>
+ <para>The <constant>5</constant> that we have placed in <varname
+ role="register">EAX</varname> identifies the kernel
+ function, in this case <function
+ role="syscall">open</function>.</para>
+ </sect2>
-</sect2>
-<sect2 xml:id="x86-alternate-calling-convention">
-<title>Alternate Calling Convention</title>
-<para>
-FreeBSD is an extremely flexible system. It offers other ways of
-calling the kernel. For it to work, however, the system must
-have Linux emulation installed.
-</para>
+ <sect2 xml:id="x86-alternate-calling-convention">
+ <title>Alternate Calling Convention</title>
-<para>
-Linux is a &unix; like system. However, its kernel uses the same
-system-call convention of passing parameters in registers
-<acronym>&ms-dos;</acronym> does. As with the &unix; convention,
-the function number is placed in <varname role="register">EAX</varname>.
-The parameters, however, are not passed on the stack but in
-<varname role="register">EBX, ECX, EDX, ESI, EDI, EBP</varname>:
-</para>
+ <para>FreeBSD is an extremely flexible system. It offers other
+ ways of calling the kernel. For it to work, however, the
+ system must have Linux emulation installed.</para>
-<programlisting>
-open:
+ <para>Linux is a &unix; like system. However, its kernel uses
+ the same system-call convention of passing parameters in
+ registers <acronym>&ms-dos;</acronym> does. As with the
+ &unix; convention, the function number is placed in <varname
+ role="register">EAX</varname>. The parameters, however, are
+ not passed on the stack but in <varname role="register">EBX,
+ ECX, EDX, ESI, EDI, EBP</varname>:</para>
+
+ <programlisting>open:
mov eax, 5
mov ebx, path
mov ecx, flags
mov edx, mode
- int 80h
-</programlisting>
+ int 80h</programlisting>
-<para>
-This convention has a great disadvantage over
-the &unix; way, at least as far as assembly language programming
-is concerned: Every time you make a kernel call
-you must <function role="opcode">push</function> the registers, then
-<function role="opcode">pop</function> them later. This makes your code
-bulkier and slower. Nevertheless, FreeBSD gives
-you a choice.
-</para>
+ <para>This convention has a great disadvantage over the &unix;
+ way, at least as far as assembly language programming is
+ concerned: Every time you make a kernel call you must
+ <function role="opcode">push</function> the registers, then
+ <function role="opcode">pop</function> them later. This makes
+ your code bulkier and slower. Nevertheless, FreeBSD gives you
+ a choice.</para>
-<para>
-If you do choose the Linux convention, you must let
-the system know about it. After your program is assembled and
-linked, you need to brand the executable:
-</para>
+ <para>If you do choose the Linux convention, you must let the
+ system know about it. After your program is assembled and
+ linked, you need to brand the executable:</para>
-<screen>&prompt.user; <userinput>brandelf -t Linux <replaceable>filename</replaceable></userinput></screen>
+ <screen>&prompt.user; <userinput>brandelf -t Linux <replaceable>filename</replaceable></userinput></screen>
+ </sect2>
-</sect2>
+ <sect2 xml:id="x86-use-geneva">
+ <title>Which Convention Should You Use?</title>
-<sect2 xml:id="x86-use-geneva">
-<title>Which Convention Should You Use?</title>
+ <para>If you are coding specifically for FreeBSD, you should
+ always use the &unix; convention: It is faster, you can store
+ global variables in registers, you do not have to brand the
+ executable, and you do not impose the installation of the
+ Linux emulation package on the target system.</para>
-<para>
-If you are coding specifically for FreeBSD, you should always
-use the &unix; convention: It is faster, you can store global
-variables in registers, you do not have to brand
-the executable, and you do not impose the installation of
-the Linux emulation package on the target system.
-</para>
+ <para>If you want to create portable code that can also run on
+ Linux, you will probably still want to give the FreeBSD users
+ as efficient a code as possible. I will show you how you can
+ accomplish that after I have explained the basics.</para>
+ </sect2>
-<para>
-If you want to create portable code that can also run
-on Linux, you will probably still want to give the FreeBSD
-users as efficient a code as possible. I will show you
-how you can accomplish that after I have explained the basics.
-</para>
+ <sect2 xml:id="x86-call-numbers">
+ <title>Call Numbers</title>
-</sect2>
+ <para>To tell the kernel which system service you are calling,
+ place its number in <varname role="register">EAX</varname>.
+ Of course, you need to know what the number is.</para>
-<sect2 xml:id="x86-call-numbers">
-<title>Call Numbers</title>
+ <sect3 xml:id="x86-the-syscalls-file">
+ <title>The <filename>syscalls</filename> File</title>
-<para>
-To tell the kernel which system service you are calling,
-place its number in <varname role="register">EAX</varname>. Of course, you need
-to know what the number is.
-</para>
+ <para>The numbers are listed in <filename>syscalls</filename>.
+ <command>locate syscalls</command> finds this file in
+ several different formats, all produced automatically from
+ <filename>syscalls.master</filename>.</para>
-<sect3 xml:id="x86-the-syscalls-file">
-<title>The <filename>syscalls</filename> File</title>
+ <para>You can find the master file for the default &unix;
+ calling convention in
+ <filename>/usr/src/sys/kern/syscalls.master</filename>. If
+ you need to use the other convention implemented in the
+ Linux emulation mode, read
+ <filename>/usr/src/sys/i386/linux/syscalls.master</filename>.</para>
-<para>
-The numbers are listed in <filename>syscalls</filename>.
-<command>locate syscalls</command> finds this file
-in several different formats, all produced automatically
-from <filename>syscalls.master</filename>.
-</para>
+ <note>
+ <para>Not only do FreeBSD and Linux use different calling
+ conventions, they sometimes use different numbers for the
+ same functions.</para>
+ </note>
-<para>
-You can find the master file for the default &unix; calling
-convention in
-<filename>/usr/src/sys/kern/syscalls.master</filename>.
-If you need to use the other convention implemented
-in the Linux emulation mode, read
-<filename>/usr/src/sys/i386/linux/syscalls.master</filename>.
-</para>
+ <para><filename>syscalls.master</filename> describes how the
+ call is to be made:</para>
-<note>
-<para>
-Not only do FreeBSD and Linux use different calling
-conventions, they sometimes use different numbers for
-the same functions.
-</para>
-</note>
-
-<para>
-<filename>syscalls.master</filename> describes how
-the call is to be made:
-</para>
-
-<programlisting>
-0 STD NOHIDE { int nosys(void); } syscall nosys_args int
+ <programlisting>0 STD NOHIDE { int nosys(void); } syscall nosys_args int
1 STD NOHIDE { void exit(int rval); } exit rexit_args void
2 STD POSIX { int fork(void); }
3 STD POSIX { ssize_t read(int fd, void *buf, size_t nbyte); }
4 STD POSIX { ssize_t write(int fd, const void *buf, size_t nbyte); }
5 STD POSIX { int open(char *path, int flags, int mode); }
6 STD POSIX { int close(int fd); }
-etc...
-</programlisting>
-<para>
-It is the leftmost column that tells us the number to place in
-<varname role="register">EAX</varname>.
-</para>
+etc...</programlisting>
-<para>
-The rightmost column tells us what parameters to
-<function role="opcode">push</function>. They are <function role="opcode">push</function>ed
-<emphasis>from right to left</emphasis>.
-</para>
+ <para>It is the leftmost column that tells us the number to
+ place in <varname role="register">EAX</varname>.</para>
-<informalexample>
-<para>
-For example, to <function>open</function> a file, we need
-to <function role="opcode">push</function> the <varname>mode</varname> first,
-then <varname>flags</varname>, then the address at which
-the <varname>path</varname> is stored.
-</para>
-</informalexample>
+ <para>The rightmost column tells us what parameters to <function
+ role="opcode">push</function>. They are <function
+ role="opcode">push</function>ed <emphasis>from right to
+ left</emphasis>.</para>
-</sect3>
-
-</sect2>
-
+ <informalexample>
+ <para>For example, to <function>open</function> a file, we
+ need to <function role="opcode">push</function> the
+ <varname>mode</varname> first, then
+ <varname>flags</varname>, then the address at which the
+ <varname>path</varname> is stored.</para>
+ </informalexample>
+ </sect3>
+ </sect2>
</sect1>
<sect1 xml:id="x86-return-values">
-<title>Return Values</title>
+ <title>Return Values</title>
-<para>
-A system call would not be useful most of the time
-if it did not return some kind of a value: The file
-descriptor of an open file, the number of bytes read
-to a buffer, the system time, etc.
-</para>
+ <para>A system call would not be useful most of the time if it did
+ not return some kind of a value: The file descriptor of an open
+ file, the number of bytes read to a buffer, the system time,
+ etc.</para>
-<para>
-Additionally, the system needs to inform us if an error
-occurs: A file does not exist, system resources are exhausted,
-we passed an invalid parameter, etc.
-</para>
+ <para>Additionally, the system needs to inform us if an error
+ occurs: A file does not exist, system resources are exhausted, we
+ passed an invalid parameter, etc.</para>
-<sect2 xml:id="x86-man-pages">
-<title>Man Pages</title>
+ <sect2 xml:id="x86-man-pages">
+ <title>Man Pages</title>
-<para>
-The traditional place to look for information about various
-system calls under &unix; systems are the manual pages.
-FreeBSD describes its system calls in section 2, sometimes
-in section 3.
-</para>
+ <para>The traditional place to look for information about various
+ system calls under &unix; systems are the manual pages. FreeBSD
+ describes its system calls in section 2, sometimes in section
+ 3.</para>
-<para>
-For example, <citerefentry><refentrytitle>open</refentrytitle><manvolnum>2</manvolnum></citerefentry> says:
-</para>
+ <para>For example,
+ <citerefentry><refentrytitle>open</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ says:</para>
-<blockquote>
-<para>
-If successful, <function>open()</function> returns a non-negative
-integer, termed a file descriptor. It returns <varname>-1</varname> on failure,
-and sets <varname>errno</varname> to indicate the error.
-</para>
+ <blockquote>
+ <para>If successful, <function>open()</function> returns a
+ non-negative integer, termed a file descriptor. It returns
+ <varname>-1</varname> on failure, and sets
+ <varname>errno</varname> to indicate the error.</para>
+ </blockquote>
-</blockquote>
-<para>
-The assembly language programmer new to &unix; and FreeBSD will
-immediately ask the puzzling question: Where is
-<varname>errno</varname> and how do I get to it?
-</para>
+ <para>The assembly language programmer new to &unix; and FreeBSD
+ will immediately ask the puzzling question: Where is
+ <varname>errno</varname> and how do I get to it?</para>
-<note>
-<para>
-The information presented in the manual pages applies
-to C programs. The assembly language programmer needs additional
-information.
-</para>
-</note>
+ <note>
+ <para>The information presented in the manual pages applies to C
+ programs. The assembly language programmer needs additional
+ information.</para>
+ </note>
+ </sect2>
-</sect2>
+ <sect2 xml:id="x86-where-return-values">
+ <title>Where Are the Return Values?</title>
-<sect2 xml:id="x86-where-return-values">
-<title>Where Are the Return Values?</title>
+ <para>Unfortunately, it depends... For most system calls it is in
+ <varname role="register">EAX</varname>, but not for all. A good
+ rule of thumb, when working with a system call for the first
+ time, is to look for the return value in <varname
+ role="register">EAX</varname>. If it is not there, you need
+ further research.</para>
-<para>
-Unfortunately, it depends... For most system calls it is
-in <varname role="register">EAX</varname>, but not for all.
-A good rule of thumb,
-when working with a system call for
-the first time, is to look for
-the return value in <varname role="register">EAX</varname>.
-If it is not there, you
-need further research.
-</para>
+ <note>
+ <para>I am aware of one system call that returns the value in
+ <varname role="register">EDX</varname>: <function
+ role="syscall">SYS_fork</function>. All others I have
+ worked with use <varname role="register">EAX</varname>. But I
+ have not worked with them all yet.</para>
+ </note>
-<note>
-<para>
-I am aware of one system call that returns the value in
-<varname role="register">EDX</varname>: <function role="syscall">SYS_fork</function>. All others
-I have worked with use <varname role="register">EAX</varname>.
-But I have not worked with them all yet.
-</para>
-</note>
+ <tip>
+ <para>If you cannot find the answer here or anywhere else, study
+ <application>libc</application> source code and see how it
+ interfaces with the kernel.</para>
+ </tip>
+ </sect2>
-<tip>
-<para>
-If you cannot find the answer here or anywhere else,
-study <application>libc</application> source code and see how it
-interfaces with the kernel.
-</para>
-</tip>
+ <sect2 xml:id="x86-where-errno">
+ <title>Where Is <varname>errno</varname>?</title>
-</sect2>
-<sect2 xml:id="x86-where-errno">
-<title>Where Is <varname>errno</varname>?</title>
+ <para>Actually, nowhere...</para>
-<para>
-Actually, nowhere...
-</para>
+ <para><varname>errno</varname> is part of the C language, not the
+ &unix; kernel. When accessing kernel services directly, the
+ error code is returned in <varname
+ role="register">EAX</varname>, the same register the proper
+ return value generally ends up in.</para>
-<para>
-<varname>errno</varname> is part of the C language, not the
-&unix; kernel. When accessing kernel services directly, the
-error code is returned in <varname role="register">EAX</varname>,
-the same register the proper
-return value generally ends up in.
-</para>
+ <para>This makes perfect sense. If there is no error, there is no
+ error code. If there is an error, there is no return value.
+ One register can contain either.</para>
+ </sect2>
-<para>
-This makes perfect sense. If there is no error, there is
-no error code. If there is an error, there is no return
-value. One register can contain either.
-</para>
+ <sect2 xml:id="x86-how-to-know-error">
+ <title>Determining an Error Occurred</title>
-</sect2>
+ <para>When using the standard FreeBSD calling convention, the
+ <varname role="register">carry flag</varname> is cleared upon
+ success, set upon failure.</para>
-<sect2 xml:id="x86-how-to-know-error">
-<title>Determining an Error Occurred</title>
-
-<para>
-When using the standard FreeBSD calling convention,
-the <varname role="register">carry flag</varname> is cleared upon success,
-set upon failure.
-</para>
-
-<para>
-When using the Linux emulation mode, the signed
-value in <varname role="register">EAX</varname> is non-negative upon success,
-and contains the return value. In case of an error, the value
-is negative, i.e., <varname>-errno</varname>.
-</para>
-
-</sect2>
-
+ <para>When using the Linux emulation mode, the signed value in
+ <varname role="register">EAX</varname> is non-negative upon
+ success, and contains the return value. In case of an error,
+ the value is negative, i.e., <varname>-errno</varname>.</para>
+ </sect2>
</sect1>
<sect1 xml:id="x86-portable-code">
-<title>Creating Portable Code</title>
+ <title>Creating Portable Code</title>
-<para>
-Portability is generally not one of the strengths of assembly language.
-Yet, writing assembly language programs for different platforms is
-possible, especially with <application>nasm</application>. I have written
-assembly language libraries that can be assembled for such different
-operating systems as &windows; and FreeBSD.
-</para>
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
_______________________________________________
[email protected] mailing list
https://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "[email protected]"