diff --git a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml index 2df22d03ff..aa3bb17b29 100644 --- a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml @@ -4,16 +4,28 @@ $FreeBSD$ --> - - Source Tree Guidelines and Policies - - Poul-HenningKampContributed by - GiorgosKeramidas - - - + + + Source Tree Guidelines and Policies - + + + + Poul-Henning + Kamp + + Contributed by + + + + Giorgos + Keramidas + + + + This chapter documents various guidelines and policies in force for the FreeBSD source tree. @@ -37,11 +49,11 @@ If a particular portion of the &os; src/ distribution is being maintained by a person or group of persons, this is communicated through an - entry in the src/MAINTAINERS file. - Maintainers of ports within the Ports Collection express their - maintainership to the world by adding a - MAINTAINER line to the - Makefile of the port in question: + entry in src/MAINTAINERS. Maintainers of + ports within the Ports Collection express their maintainership + to the world by adding a MAINTAINER line to + the Makefile of the port in + question: MAINTAINER= email-addresses @@ -90,16 +102,31 @@ - Contributed Software - - Poul-HenningKampContributed by - DavidO'Brien - GavinAtkinson - - - + + Contributed Software - + + + + Poul-Henning + Kamp + + Contributed by + + + + David + O'Brien + + + + + Gavin + Atkinson + + + + contributed software @@ -144,12 +171,19 @@ - Vendor Imports with SVN + + Vendor Imports with SVN + - Dag-ErlingSmørgravContributed by + + + Dag-Erling + Smørgrav + + Contributed by + - This section describes the vendor import procedure with Subversion in details. @@ -212,7 +246,7 @@ &prompt.user; svn commit where svn_base is the base - directory of your SVN repository, e.g. + directory of your SVN repository, e.g., svn+ssh://svn.FreeBSD.org/base. @@ -237,7 +271,7 @@ &prompt.user; find . -type f | cut -c 3- | sort > ../new With these two files, the following command will list - list removed files (files only in + removed files (files only in old): &prompt.user; comm -23 ../old ../new @@ -248,7 +282,7 @@ &prompt.user; comm -13 ../old ../new - Let's put this together: + Let us put this together: &prompt.user; cd vendor/foo/foo-9.9 &prompt.user; tar cf - . | tar xf - -C ../dist @@ -337,7 +371,7 @@ &prompt.user; svn diff --no-diff-deleted --old=svn_base/vendor/foo/dist --new=. - The option tells + tells SVN not to check files that are in the vendor tree but not in the main tree. @@ -401,7 +435,8 @@ Any encumbered file requires specific approval from the - Core + Core Team before it is added to the repository. @@ -433,9 +468,11 @@ Should always be in LINT, but - the Core - Team decides per case if it should be - commented out or not. The Core + the Core + Team decides per case if it should be commented + out or not. The Core Team can, of course, change their minds later on. @@ -452,18 +489,19 @@ - The Core + The Core teamcore - team decides if - the code should be part of - make world. + team decides if the code + should be part of make world. - The Release + The Release Engineeringrelease - engineering - decides if it goes into the release. + engineering decides if it goes + into the release. @@ -471,16 +509,31 @@ - Shared Libraries - - SatoshiAsamiContributed by - PeterWemm - DavidO'Brien - - - + + Shared Libraries - + + + + Satoshi + Asami + + Contributed by + + + + Peter + Wemm + + + + + David + O'Brien + + + + If you are adding shared library support to a port or other piece of software that does not have one, the version numbers @@ -518,7 +571,7 @@ form x.y.z well. Any version number after the y - (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 micro revision, ld.so will @@ -547,7 +600,7 @@ 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 Makefile's commit logs. It is the diff --git a/en_US.ISO8859-1/books/developers-handbook/x86/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/x86/chapter.xml index d119f9d495..ba4b9faca0 100644 --- a/en_US.ISO8859-1/books/developers-handbook/x86/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/x86/chapter.xml @@ -18,150 +18,118 @@ $FreeBSD$ --> - + -x86 Assembly Language Programming - - -This chapter was written by &a.stanislav.email;. - + x86 Assembly Language Programming + This chapter was written by + &a.stanislav.email;. + + Synopsis - -Synopsis + 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. - -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. - + 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. - -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. - + 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? - -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? - + In this chapter I will attempt to show you how you can use + assembly language writing &unix; programs, specifically under + FreeBSD. - -In this chapter I will attempt to show you -how you can use assembly language writing -&unix; programs, specifically under FreeBSD. - + 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 Art of Assembly + Language; 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. - -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 -Art -of Assembly Language; 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. - + Copyright © 2000-2001 G. Adam Stanislav. All rights + reserved. + - -Copyright © 2000-2001 G. Adam Stanislav. All rights reserved. - + + The Tools - + + The Assembler - -The Tools + The most important tool for assembly language programming + is the assembler, the software that converts assembly language + code into machine language. - -The Assembler + Two very different assemblers are available for FreeBSD. + One is + as1, + which uses the traditional &unix; assembly language syntax. + It comes with the system. - -The most important tool for assembly language programming is the -assembler, the software that converts assembly language code -into machine language. - + The other is + /usr/ports/devel/nasm. 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. - -Two very different assemblers are available for FreeBSD. One is -as1, -which uses the traditional &unix; assembly language syntax. It -comes with the system. - + This chapter uses nasm 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. + - -The other is /usr/ports/devel/nasm. -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. - + + The Linker - -This chapter uses nasm -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. - + The output of the assembler, like that of any compiler, + needs to be linked to form an executable file. - + The standard + ld1 + linker comes with FreeBSD. It works with the code assembled + with either assembler. + + - -The Linker + + System Calls - -The output of the assembler, like that of any -compiler, needs to be linked to form an executable file. - + + Default Calling Convention - -The standard -ld1 -linker comes with FreeBSD. It works with the -code assembled with either assembler. - + By default, the FreeBSD kernel uses the C calling + convention. Further, although the kernel is accessed using + int 80h, it is assumed the + program will call a function that issues int 80h, rather than issuing + int 80h directly. - - + This convention is very convenient, and quite superior to + the µsoft; convention used by + &ms-dos;. Why? Because the &unix; + convention allows any program written in any language to + access the kernel. - -System Calls + An assembly language program can do that as well. For + example, we could open a file: - -Default Calling Convention - - -By default, the FreeBSD kernel uses the C calling -convention. Further, although the kernel is accessed -using int 80h, -it is assumed the program will call a function that -issues int 80h, rather than -issuing int 80h directly. - - - -This convention is very convenient, and quite superior to the -µsoft; convention used by &ms-dos;. -Why? Because the &unix; convention allows any program written in -any language to access the kernel. - - - -An assembly language program can do that as well. -For example, we could open a file: - - - -kernel: + kernel: int 80h ; Call kernel ret @@ -172,363 +140,285 @@ open: mov eax, 5 call kernel add esp, byte 12 - ret - + ret - -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. - + 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. - -But assembly language programmers like to shave off cycles. The above example -requires a call/ret combination. -We can eliminate it by -pushing an extra dword: - + But assembly language programmers like to shave off + cycles. The above example requires a call/ret combination. We can + eliminate it by pushing an + extra dword: - -open: + 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 - + add esp, byte 16 - -The 5 that we have placed in -EAX identifies -the kernel function, in this case open. - + The 5 that we have placed in EAX identifies the kernel + function, in this case open. + - - -Alternate Calling Convention - -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. - + + Alternate Calling Convention - -Linux is a &unix; like system. However, its kernel uses the same -system-call convention of passing parameters in registers -&ms-dos; does. As with the &unix; convention, -the function number is placed in EAX. -The parameters, however, are not passed on the stack but in -EBX, ECX, EDX, ESI, EDI, EBP: - + 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. - -open: + Linux is a &unix; like system. However, its kernel uses + the same system-call convention of passing parameters in + registers &ms-dos; does. As with the + &unix; convention, the function number is placed in EAX. The parameters, however, are + not passed on the stack but in EBX, + ECX, EDX, ESI, EDI, EBP: + + open: mov eax, 5 mov ebx, path mov ecx, flags mov edx, mode - int 80h - + int 80h - -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 push the registers, then -pop them later. This makes your code -bulkier and slower. Nevertheless, FreeBSD gives -you a choice. - + 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 + push the registers, then + pop them later. This makes + your code bulkier and slower. Nevertheless, FreeBSD gives you + a choice. - -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: - + 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: -&prompt.user; brandelf -t Linux filename + &prompt.user; brandelf -t Linux filename + - + + Which Convention Should You Use? - -Which Convention Should You Use? + 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. - -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. - + 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. + - -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. - + + Call Numbers - + To tell the kernel which system service you are calling, + place its number in EAX. + Of course, you need to know what the number is. - -Call Numbers + + The <filename>syscalls</filename> File - -To tell the kernel which system service you are calling, -place its number in EAX. Of course, you need -to know what the number is. - + The numbers are listed in syscalls. + locate syscalls finds this file in + several different formats, all produced automatically from + syscalls.master. - -The <filename>syscalls</filename> File + You can find the master file for the default &unix; + calling convention in + /usr/src/sys/kern/syscalls.master. If + you need to use the other convention implemented in the + Linux emulation mode, read + /usr/src/sys/i386/linux/syscalls.master. - -The numbers are listed in syscalls. -locate syscalls finds this file -in several different formats, all produced automatically -from syscalls.master. - + + Not only do FreeBSD and Linux use different calling + conventions, they sometimes use different numbers for the + same functions. + - -You can find the master file for the default &unix; calling -convention in -/usr/src/sys/kern/syscalls.master. -If you need to use the other convention implemented -in the Linux emulation mode, read -/usr/src/sys/i386/linux/syscalls.master. - + syscalls.master describes how the + call is to be made: - - -Not only do FreeBSD and Linux use different calling -conventions, they sometimes use different numbers for -the same functions. - - - - -syscalls.master describes how -the call is to be made: - - - -0 STD NOHIDE { int nosys(void); } syscall nosys_args int + 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... - - -It is the leftmost column that tells us the number to place in -EAX. - +etc... - -The rightmost column tells us what parameters to -push. They are pushed -from right to left. - + It is the leftmost column that tells us the number to + place in EAX. - - -For example, to open a file, we need -to push the mode first, -then flags, then the address at which -the path is stored. - - - - - - + The rightmost column tells us what parameters to push. They are pushed from right to + left. + + For example, to open a file, we + need to push the + mode first, then + flags, then the address at which the + path is stored. + + + -Return Values + Return Values - -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. - + 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. - -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. - + 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. - -Man Pages + + Man Pages - -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. - + 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. - -For example, open2 says: - + For example, + open2 + says: -
- -If successful, open() returns a non-negative -integer, termed a file descriptor. It returns -1 on failure, -and sets errno to indicate the error. - +
+ If successful, open() returns a + non-negative integer, termed a file descriptor. It returns + -1 on failure, and sets + errno to indicate the error. +
-
- -The assembly language programmer new to &unix; and FreeBSD will -immediately ask the puzzling question: Where is -errno and how do I get to it? - + The assembly language programmer new to &unix; and FreeBSD + will immediately ask the puzzling question: Where is + errno and how do I get to it? - - -The information presented in the manual pages applies -to C programs. The assembly language programmer needs additional -information. - - + + The information presented in the manual pages applies to C + programs. The assembly language programmer needs additional + information. + + - + + Where Are the Return Values? - -Where Are the Return Values? + Unfortunately, it depends... For most system calls it is in + EAX, 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 EAX. If it is not there, you need + further research. - -Unfortunately, it depends... For most system calls it is -in EAX, 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 EAX. -If it is not there, you -need further research. - + + I am aware of one system call that returns the value in + EDX: SYS_fork. All others I have + worked with use EAX. But I + have not worked with them all yet. + - - -I am aware of one system call that returns the value in -EDX: SYS_fork. All others -I have worked with use EAX. -But I have not worked with them all yet. - - + + If you cannot find the answer here or anywhere else, study + libc source code and see how it + interfaces with the kernel. + + - - -If you cannot find the answer here or anywhere else, -study libc source code and see how it -interfaces with the kernel. - - + + Where Is <varname>errno</varname>? - - -Where Is <varname>errno</varname>? + Actually, nowhere... - -Actually, nowhere... - + errno is part of the C language, not the + &unix; kernel. When accessing kernel services directly, the + error code is returned in EAX, the same register the proper + return value generally ends up in. - -errno is part of the C language, not the -&unix; kernel. When accessing kernel services directly, the -error code is returned in EAX, -the same register the proper -return value generally ends up in. - + 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. + - -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. - + + Determining an Error Occurred - - - -Determining an Error Occurred - - -When using the standard FreeBSD calling convention, -the carry flag is cleared upon success, -set upon failure. - - - -When using the Linux emulation mode, the signed -value in EAX is non-negative upon success, -and contains the return value. In case of an error, the value -is negative, i.e., -errno. - - - + When using the standard FreeBSD calling convention, the + carry flag is cleared upon + success, set upon failure. + When using the Linux emulation mode, the signed value in + EAX is non-negative upon + success, and contains the return value. In case of an error, + the value is negative, i.e., -errno. + -Creating Portable Code + Creating Portable Code - -Portability is generally not one of the strengths of assembly language. -Yet, writing assembly language programs for different platforms is -possible, especially with nasm. I have written -assembly language libraries that can be assembled for such different -operating systems as &windows; and FreeBSD. - + Portability is generally not one of the strengths of assembly + language. Yet, writing assembly language programs for different + platforms is possible, especially with + nasm. I have written assembly language + libraries that can be assembled for such different operating + systems as &windows; and FreeBSD. - -It is all the more possible when you want your code to run -on two platforms which, while different, are based on -similar architectures. - + It is all the more possible when you want your code to run on + two platforms which, while different, are based on similar + architectures. - -For example, FreeBSD is &unix;, Linux is &unix; like. I only -mentioned three differences between them (from an assembly language -programmer's perspective): The calling convention, the -function numbers, and the way of returning values. - + For example, FreeBSD is &unix;, Linux is &unix; like. I only + mentioned three differences between them (from an assembly + language programmer's perspective): The calling convention, the + function numbers, and the way of returning values. -Dealing with Function Numbers + + Dealing with Function Numbers - -In many cases the function numbers are the same. However, -even when they are not, the problem is easy to deal with: -Instead of using numbers in your code, use constants which -you have declared differently depending on the target -architecture: - + In many cases the function numbers are the same. However, + even when they are not, the problem is easy to deal with: + Instead of using numbers in your code, use constants which you + have declared differently depending on the target + architecture: - -%ifdef LINUX + %ifdef LINUX %define SYS_execve 11 %else %define SYS_execve 59 -%endif - - -Dealing with Conventions - -Both, the calling convention, and the return value (the -errno problem) can be resolved with macros: - +%endif + - -%ifdef LINUX + + Dealing with Conventions + + Both, the calling convention, and the return value (the + errno problem) can be resolved with + macros: + + %ifdef LINUX %macro system 0 call kernel @@ -573,64 +463,51 @@ kernel: int 80h %endmacro -%endif - +%endif + - + + Dealing with Other Portability Issues -Dealing with Other Portability Issues + The above solutions can handle most cases of writing code + portable between FreeBSD and Linux. Nevertheless, with some + kernel services the differences are deeper. - -The above solutions can handle most cases of writing code -portable between FreeBSD and Linux. Nevertheless, with some -kernel services the differences are deeper. - + In that case, you need to write two different handlers for + those particular system calls, and use conditional assembly. + Luckily, most of your code does something other than calling the + kernel, so usually you will only need a few such conditional + sections in your code. + - -In that case, you need to write two different handlers -for those particular system calls, and use conditional -assembly. Luckily, most of your code does something other -than calling the kernel, so usually you will only need -a few such conditional sections in your code. - + + Using a Library - + You can avoid portability issues in your main code + altogether by writing a library of system calls. Create a + separate library for FreeBSD, a different one for Linux, and yet + other libraries for more operating systems. -Using a Library + In your library, write a separate function (or procedure, if + you prefer the traditional assembly language terminology) for + each system call. Use the C calling convention of passing + parameters. But still use EAX to pass the call number in. In + that case, your FreeBSD library can be very simple, as many + seemingly different functions can be just labels to the same + code: - -You can avoid portability issues in your main code altogether -by writing a library of system calls. Create a separate library -for FreeBSD, a different one for Linux, and yet other libraries -for more operating systems. - - - -In your library, write a separate function (or procedure, if -you prefer the traditional assembly language terminology) for each system -call. Use the C calling convention of passing parameters. -But still use EAX to pass the call number in. -In that case, your FreeBSD library can be very simple, as -many seemingly different functions can be just labels to -the same code: - - - -sys.open: + sys.open: sys.close: [etc...] int 80h - ret - + ret - -Your Linux library will require more different functions. -But even here you can group system calls using the same -number of parameters: - + Your Linux library will require more different functions. + But even here you can group system calls using the same number + of parameters: - -sys.exit: + sys.exit: sys.close: [etc... one-parameter functions] push ebx @@ -650,111 +527,79 @@ sys.return: sys.err: neg eax stc - ret - + ret - -The library approach may seem inconvenient at first because -it requires you to produce a separate file your code depends -on. But it has many advantages: For one, you only need to -write it once and can use it for all your programs. You can -even let other assembly language programmers use it, or perhaps use -one written by someone else. But perhaps the greatest -advantage of the library is that your code can be ported -to other systems, even by other programmers, by simply -writing a new library without any changes to your code. - + The library approach may seem inconvenient at first because + it requires you to produce a separate file your code depends on. + But it has many advantages: For one, you only need to write it + once and can use it for all your programs. You can even let + other assembly language programmers use it, or perhaps use one + written by someone else. But perhaps the greatest advantage of + the library is that your code can be ported to other systems, + even by other programmers, by simply writing a new library + without any changes to your code. - -If you do not like the idea of having a library, you can -at least place all your system calls in a separate assembly language file -and link it with your main program. Here, again, all porters -have to do is create a new object file to link with your -main program. - + If you do not like the idea of having a library, you can at + least place all your system calls in a separate assembly + language file and link it with your main program. Here, again, + all porters have to do is create a new object file to link with + your main program. + - + + Using an Include File - -Using an Include File + If you are releasing your software as (or with) source code, + you can use macros and place them in a separate file, which you + include in your code. - -If you are releasing your software as (or with) -source code, you can use macros and place them -in a separate file, which you include in your -code. - + Porters of your software will simply write a new include + file. No library or external object file is necessary, yet your + code is portable without any need to edit the code. - -Porters of your software will simply write a new -include file. No library or external object file -is necessary, yet your code is portable without any -need to edit the code. - + + This is the approach we will use throughout this chapter. + We will name our include file system.inc, + and add to it whenever we deal with a new system call. + - - -This is the approach we will use throughout this chapter. -We will name our include file system.inc, and -add to it whenever we deal with a new system call. - - + We can start our system.inc by + declaring the standard file descriptors: - -We can start our system.inc by declaring the -standard file descriptors: - - - -%define stdin 0 + %define stdin 0 %define stdout 1 -%define stderr 2 - +%define stderr 2 - -Next, we create a symbolic name for each system call: - + Next, we create a symbolic name for each system call: - -%define SYS_nosys 0 + %define SYS_nosys 0 %define SYS_exit 1 %define SYS_fork 2 %define SYS_read 3 %define SYS_write 4 -; [etc...] - +; [etc...] - -We add a short, non-global procedure with a long name, -so we do not accidentally reuse the name in our code: - + We add a short, non-global procedure with a long name, so we + do not accidentally reuse the name in our code: - -section .text + section .text align 4 access.the.bsd.kernel: int 80h - ret - + ret - -We create a macro which takes one argument, the syscall number: - + We create a macro which takes one argument, the syscall + number: - -%macro system 1 + %macro system 1 mov eax, %1 call access.the.bsd.kernel -%endmacro - +%endmacro - -Finally, we create macros for each syscall. These macros take -no arguments. - + Finally, we create macros for each syscall. These macros + take no arguments. - -%macro sys.exit 0 + %macro sys.exit 0 system SYS_exit %endmacro @@ -770,29 +615,21 @@ no arguments. system SYS_write %endmacro -; [etc...] - - - -Go ahead, enter it into your editor and save it as -system.inc. We will add more to it as we -discuss more syscalls. - - - +; [etc...] + Go ahead, enter it into your editor and save it as + system.inc. We will add more to it as we + discuss more syscalls. + -Our First Program + Our First Program - -We are now ready for our first program, the mandatory -Hello, World! - + We are now ready for our first program, the mandatory + Hello, World! - - 1: %include 'system.inc' + 1: %include 'system.inc' 2: 3: section .data 4: hello db 'Hello, World!', 0Ah @@ -807,67 +644,54 @@ We are now ready for our first program, the mandatory 13: sys.write 14: 15: push dword 0 -16: sys.exit - +16: sys.exit - -Here is what it does: Line 1 includes the defines, the macros, -and the code from system.inc. - + Here is what it does: Line 1 includes the defines, the macros, + and the code from system.inc. - -Lines 3-5 are the data: Line 3 starts the data section/segment. -Line 4 contains the string "Hello, World!" followed by a new -line (0Ah). Line 5 creates a constant that contains -the length of the string from line 4 in bytes. - + Lines 3-5 are the data: Line 3 starts the data + section/segment. Line 4 contains the string "Hello, World!" + followed by a new line (0Ah). Line 5 creates + a constant that contains the length of the string from line 4 in + bytes. - -Lines 7-16 contain the code. Note that FreeBSD uses the elf -file format for its executables, which requires every -program to start at the point labeled _start (or, more -precisely, the linker expects that). This label has to be -global. - + Lines 7-16 contain the code. Note that FreeBSD uses the + elf file format for its executables, which + requires every program to start at the point labeled + _start (or, more precisely, the linker expects + that). This label has to be global. - -Lines 10-13 ask the system to write hbytes bytes -of the hello string to stdout. - + Lines 10-13 ask the system to write hbytes + bytes of the hello string to + stdout. - -Lines 15-16 ask the system to end the program with the return -value of 0. The SYS_exit syscall never -returns, so the code ends there. - + Lines 15-16 ask the system to end the program with the return + value of 0. The SYS_exit syscall never returns, so the + code ends there. - - -If you have come to &unix; from &ms-dos; -assembly language background, you may be used to writing directly -to the video hardware. You will never have to worry about -this in FreeBSD, or any other flavor of &unix;. As far as -you are concerned, you are writing to a file known as -stdout. This can be the video screen, or -a telnet terminal, or an actual file, -or even the input of another program. Which one it is, -is for the system to figure out. - - + + If you have come to &unix; from &ms-dos; + assembly language background, you may be used to writing + directly to the video hardware. You will never have to worry + about this in FreeBSD, or any other flavor of &unix;. As far as + you are concerned, you are writing to a file known as + stdout. This can be the video screen, or a + telnet terminal, or an actual file, + or even the input of another program. Which one it is, is for + the system to figure out. + -Assembling the Code + Assembling the Code - -Type the code (except the line numbers) in an editor, and save -it in a file named hello.asm. You need -nasm to assemble it. - + Type the code (except the line numbers) in an editor, and save + it in a file named hello.asm. You need + nasm to assemble it. -Installing <application>nasm</application> + Installing <application>nasm</application> - -If you do not have nasm, type: - + If you do not have nasm, + type: &prompt.user; su Password:your root password