=====================================================================================
=                                                                                   =
=               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
