===================================================================================== = = = Linux x86 Assembly Software Development Helper Kit = = = = Last updated on 16/03/07 = = = ===================================================================================== 1. Introduction 2. Installation Instructions 3. Information 3.1 System Calls Reference 3.2 Include Files 3.3 Sample Applications 3.4 Tools & Utilities 4. License Agreement 5. Authors/Contributors ===================================================================================== 1. Introduction ===================================================================================== This project aims to provide a functional and solid foundation for anyone interested in programming with x86 Assembly Language (using FASM) for Linux. At the current stage it includes a system calls reference for Linux kernel 2.6 and higher branches, a set of FASM include files with structure and symbolic constants definitions, a number of small example applications demonstrating variety of Linux programming principles from AL point of view, and some helper utilities. Visit the LSCR Project's website at: http://sourceforge.net/projects/lscr Contact address: rovsey@gmail.com ===================================================================================== 2. Installation Instructions ===================================================================================== In order to build the example applications and supplied utilities following applications and libraries are required: - FASM (www.flatassembler.net) - libX11, libXt, libXaw, libXpm (xorg.freedesktop.org) - libncurses (www.gnu.org/software/ncurses/) *) `cd' to the directory where the archive was extracted and run `make'. This will compile utilities and sample applications. *) Running `make install' will copy include files to /usr/include/fasm and setup needed environment variables. *) If you want to remove all the generated object files and program binaries run `make clean'. ===================================================================================== 3. Information ===================================================================================== ------------------------------------------------------------------------------------- 3.1 System Calls Reference ------------------------------------------------------------------------------------- The reference documents only the system calls provided by Linux kernel 2.6 and higher branches. Thus some things may or may not apply to previous versions of the kernel. While referring to appropriate 'Compatibility' fields you will usually see "n/a" or for example "Available since 2.6.16". "n/a" means that the given system call is known to be available for Linux 2.6.0 and later versions. Since this reference focuses solely on Linux 2.6+, compatibility of previous kernel versions is omitted. So please note that even if some system call was available in previous Linux versions it may significantly differ in implementation. Under grayish 'Unimplemented' menu a list of unimplemented system calls is located. Those system calls are either deprecated or not yet implemented but have an entry in unistd.h. ------------------------------------------------------------------------------------- 3.2 Include Files ------------------------------------------------------------------------------------- Following is the set of currently available FASM include files: symbols.inc - Kernel symbolic constants definitions structs.inc - Kernel structure definitions* x.inc - Xlib/Xt/Xaw symbols & extrns definitions x_structs.inc - Xlib/Xt/Xaw structure definitions* x_res.inc - Xt/Xaw resource strings ncurses.inc - NCURSES symbolic constants & extrns definitions 'include' directory contains more files than listed here. Namely, there is additional *structs_v.inc files that contain offset definitions for structures. Those files are included from within *structs.inc and shouldn't be included directly from the source file. ------------------------------------------------------------------------------------- 3.3 Sample Applications ------------------------------------------------------------------------------------- gui/ ncurses/ chatwin.asm - chat like window menu.asm - simple menu xlib/ shapes.asm - shapes drawing xbm.asm - X BitMap drawing example xt/ xaw/ button.asm - button dialog.asm - dialog box dropdown.asm - button with a dropdown menu ioctl/ devinfo.asm - retrieves size of a block device leds.asm - switches on the keyboard LEDs and generates a tone vtinfo.asm - retrieves currently active and first available VTs ipc/ posix_msg.asm - POSIX IPC using Message Queues sysv_msg.asm - System V IPC using Message Queues sysv_semaphore.asm - System V IPC using Semaphores sysv_shmem.asm - System V IPC using Shared Memory Segments lkm/ lkm.asm - loadable kernel module example misc.syscalls/ execve.asm - sys_execve usage demonstration filecreate.asm - sys_open, sys_brk, & sys_lseek usage demonstration fork.asm - sys_fork usage demonstration getdir.asm - sys_getdents usage demonstration ports.asm - sys_ioperm usage demonstration ptrace.asm - sys_ptrace and sys_kill usage demonstration sigaction.asm - sys_sigaction usage demonstration sysctl.asm - sys_sysctl usage demonstration waitpid.asm - sys_waitpid and sys_pause usage demonstration so/ libsotest.asm - shared object test_static.asm - static usage of a shared library socket/ icmp.asm - sys_socketcall demonstration ------------------------------------------------------------------------------------- 3.4 Tools & Utilities ------------------------------------------------------------------------------------- fasm2gas.pl - FASM to GAS source code converter fasm2nasm.pl - FASM to NASM source code converter gas2fasm.pl - GAS to FASM source code converter nasm2fasm.pl - NASM to FASM source code converter know-fasm.pl - Converts C header files to FASM-compatible header files make4fasm.pl - Makefile generator for FASM source code files koupd - kernel modules symversion and modinfo information generator/updater ===================================================================================== 4. License Agreement ===================================================================================== This software package is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. In no event shall the initial developers or copyright holders be liable for any damages whatsoever, including - but not restricted to - lost revenue or profits or other direct, indirect, special, incidental or consequential damages, even if they have been advised of the possibility of such damages, except to the extent invariable law, if any, provides otherwise. If this package to be distributed we would appreciate if it's distributed in unmodified form with all files intact. We also would appreciate if 'include' files intended for usage in other projects retain the original header mentioning the name of 'LSCR Project'. Some parts of this package are covered by other licenses, thus additional terms and conditions should apply where appropriate. See file`s headers for more information. (c) LSCR Project. ===================================================================================== 5. Authors/Contributors ===================================================================================== Roman Ovseytsev - rovsey@gmail.com Jonathan Pleski - jpleski@walla.com Bogdan Drozdowski - bogdandr@op.pl, bogdro@rudy.mif.pg.gda.pl