Installation

Pyasm currently requires python 2.6.

Linux Install:

• Download and extract pyasm-0.3.tar.gz
• python setup.py install

Windows Install:

• Download and run pyasm-0.3.win32-py2.6.exe
• A source distribution pyasm-0.3.zip is available, but you'll need VS7.0 to compile the excmem module.

Hello World!

A simple Windows version of a hello_world.py program is as follows:

#
# Hello World in assembly:  pyasm/examples/hello_World.py
#
#

from pyasm import pyasm

pyasm(globals(),r"""
   !PROC hello_world PYTHON
   !ARG  self
   !ARG  args
        !CALL PySys_WriteStdout "Hello, World!\n\0"
        ADD ESP, 0x4
        MOV EAX,PyNone
        ADD [EAX],1
   !ENDPROC
   """)

hello_world()

A brief description of what is happening durring the pyasm call:

1. the globals() statement tells pyasm where to bind newly created python functions

2. The !CHARS directive creates a string constant.

3. The !PROC and !ARG directives create a procedure that matches the standard CPythonFunction signature [PyObject* hello_world(PyObject* self, PyObject* args) and create procedure initialization code.

4. The procedure calls python's PySys_WriteStdout function. Since python functions use CDECL calling conventions, we:

   1. PUSH the paramters onto the stack from right to left
   2. CALL the function
   3. Cleanup the stack ourselves

5. PyCFunctions must return some sort of python object, so we:

   1. Load PyNone into the EAX register, which will become the return value.
   2. Add one to the reference count

6. The !ENDPROC directive ends the procedure and creates function cleanup code. This creates a procedure called hello_world that would have the C signature of PyObject* hello_world(PyObject* self, PyObject* args). The procedure loads hello_str onto the stack, calls the python interpreters PySys_WriteStdout function,

1. Calling hello_world() executes the newly created function.

Assembler Syntax

Like most assemblers, the command-line assembler contains a very simple parser. There two basic statements that can be used. An instruction statement and an assembler directive. Assembler directives contain information that makes your assembly a little easier to read than raw assembly code, such as the begining and ending of function; declaration of parameters, variables, constants and data; and other stuff. Instruction Statements consist of real assembly instructions such as MOV [EAX+4],value

Additional notes specific to this assembler are as follows:

• Numbers use python's formatting scheme, so hex is represented as 0xFF and not FFh.
• Instructions and Registers must be in all caps. mov eax,0x0 is invalid.

Typical Usage

Typically, usage is as simple as the hello world example listed above. Import the pyasm function from the pyasm package and call it. globals blah blah blah.

Assembly via the API

calling pyasm is fine if you're just trying to inline some assembly functions, but if you're trying to dynamically generate assembly (such as writing a python compiler) you're better off accessing the api directly. This involves a few steps:

1. import the assembler class from x86 asm and instantiate.
2. Add instructions either as strings that need to be preprocessed or via the api.
3. generate an intermediate 'codepackage' by calling the .Compile() method
4. transform the codePackage to runtime memory via CpToMemory.

Command-line assembler

NOT IMPLEMENTED YET

If you really want to, a command-line asembler is available for usage. Usage is straightforward:

python pyassemble.py asmfile.asm

This will generate an object file asmfile.o that can be used by your linker.

Linux Debuggers

On Linux, you obviously have gdb.

Windows debuggers

Contrary to popular belief, there is a buildin command-line debugger on Windows NT/2000/XP called ntsd.exe that can be used in a bind. If you're doing any serious work though, do yourself a favor and download the 18MB "Debugging Tools for Windows." It includes an updated version of ntsd.exe and a version with a simple Windows interface called WinDBG. You'll really want to download this if you're getting serious about assembly debugging. Actual usage is beyond the scope of this document, but read up on setting up a symbol server.

And yes, there is the Visual Studio .NET debugger. This is a great debugger when you're debugging C or VB code in an existing project. But it is designed to work as part of an IDE. It gets a little wierd when debugging raw assembly or compiled code without the source floating around. As ugly as WinDBG's gui looks like by todays standards, it is a lot more convienent in these cases.

Source output - *not implemented yet

I plan to provide a hook via the logging module so you can obtain disassembly of the source at runtime.

Adding x86 instructions

I haven't added all of the x86 instructions yet. Most of it involves cutting and pasting from the IA32 Intel Software Architecture Manual Volumes 2 and 3. For standard instructions, you should just be able to add the appropriate text to x86inst.py and creating a test in test_instructions.py. SIMD and FPU operations will probably require some additional hacking.

ELF serialization/deserialization

There is currently code that converts windows COFF objects to a python-based object model and vice versa. This allows you to create standard object files for traditional linking. An equivilent for ELF files would allow you to do the same thing in Linux. Refer to the coff*.py files to see how this format was implemented.