Date: Fri, 17 Aug 2018 12:37:22 +0000 (UTC) From: Benedict Reuschling <bcr@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r52145 - in head/en_US.ISO8859-1/books/developers-handbook: policies x86 Message-ID: <201808171237.w7HCbMCg001422@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201808171237.w7HCbMCg001422>