Changes

231 bytes added ,  18:05, 22 September 2016
reorganizing things a bit, rephrasing, English fixes
Line 1: Line 1: −
Compel temporary GIT repo is at http://github.com/xemul/compel.
+
'''Compel''' is a utility to execute arbitrary code in a context of a foreign process. Compel is part of CRIU, and its sources are available from [https://github.com/xemul/criu/tree/criu-dev/compel the criu-dev branch of CRIU repo, subdirectory compel].
Now compel sits in the main criu repo at https://github.com/xemul/criu/tree/criu-dev/compel.
     −
== Compel ==
+
The code to be executed is called '''parasite code'''. Once compiled with compel flags and packed, it can be executed in other task's context. Note the code is run in environment without glibc, thus it can not call the usual stdio/stdlib/etc. functions.
   −
An utility to execute code in foreign process address space. The code should be compiled with compel flags and packed, then it can be executed in other task's context. The parasite code executes in an environment w/o glibc, thus you cannot call the usual stdio/stdlib/etc. functions. Compel provides a set of plugins for your convenience. Plugins get linked to parasite binary on the pack stage (see below).
+
A set of [[compel plugins]] are provided for your convenience. Plugins get linked to the parasite binary during the pack stage.
   −
== How we want it to look like ==
+
== Writing parasite code ==
    
Execution of the parasite code starts with the function
 
Execution of the parasite code starts with the function
Line 16: Line 15:  
that should be present in your code. The <code>arg_p</code> and <code>arg_s</code> is the binary argument that will get delivered to parasite code by complel <code>_start()</code> call (see below). Sometimes this binary argument can be treated as CLI arguments argc/argv.
 
that should be present in your code. The <code>arg_p</code> and <code>arg_s</code> is the binary argument that will get delivered to parasite code by complel <code>_start()</code> call (see below). Sometimes this binary argument can be treated as CLI arguments argc/argv.
   −
=== Compile the sources and pack the binary ===
+
=== Compiling and packing ===
   −
Take a program on C and compile it with compel flags
+
Take the program and compile it with compel flags:
    
<pre>
 
<pre>
$ gcc -c foo.c -o foo.o $(compel cflags)
+
$ gcc -c foo1.c -o foo1.o $(compel cflags)
 
</pre>
 
</pre>
   −
To combine the foo.o out of many sources, they should all be linked with compel flags as well
+
To combine the foo.o out of many sources, they should all be linked with compel linker flags:
    
<pre>
 
<pre>
$ ld foo_1.o foo_2.o -o foo.o $(compel ldflags)
+
$ ld foo1.o foo2.o -o foo.o $(compel ldflags)
 
</pre>
 
</pre>
   −
Pack the binary. Packing would link the object file with compel plugins (see below)
+
Pack the binary. Packing would link the object file with [[compel plugins]].
    
<pre>
 
<pre>
Line 36: Line 35:  
</pre>
 
</pre>
   −
The <code>-l</code> option specifies plugins to be added to the packed binary. Plugin <code>std</code> is added all the time w/o any options.
+
The <code>-l</code> option specifies plugins to be added to the packed binary. The <code>std</code> plugin is added by default, i.e. it does not require any flags.
   −
The foo.compel.o is ready for remote execution (foo.o was not).
+
Now, the <code>foo.compel.o</code> is ready for remote execution (note that <code>foo.o</code> was not).
   −
=== Execute the code remotely ===
+
=== Execute the code ===
   −
Using CLI like this
+
Using CLI, the compiled and packed parasite code can be executed like this:
    
<pre>
 
<pre>
$ compel run -f foo.compel.o -p $pid [args]
+
$ compel run -f foo.compel.o -p ''pid'' [args ...]
 
</pre>
 
</pre>
   −
Or, you can link with libcompel.so and use
+
Alternatively, you can link it with the <code>libcompel.so</code> and use the following calls:
    
<source lang="C">
 
<source lang="C">
Line 56: Line 55:  
</source>
 
</source>
   −
calls.
+
These library calls require binary argument that is copied into the parasite context and is available from it via arg_p/arg_s pair. When run from CLI, the arguments are packed in the usual way (argc/argv).
   −
The library calls require binary argument that will get copied into parasite context and passed to it via arg_p/arg_s pair. When run from CLI the arguments are packed in argc/argv manner.
+
=== Communicate to parasite code ===
 
  −
=== How to communicate to parasite code ===
      
There are several ways for doing this.
 
There are several ways for doing this.
   −
If you run the parasite binary from CLI, the tail command line arguments are passed into the parasite main() function.
+
If you run the parasite binary from CLI, the command line arguments after <code>--</code> are passed into the parasite's <code>main()</code> function.
    
<pre>
 
<pre>
Line 70: Line 67:  
</pre>
 
</pre>
   −
In the main() common argc and argv are accessed using the
+
In <code>main()</code>, common argc and argv can be accessed using the following code:
    
<source lang="C">
 
<source lang="C">
Line 77: Line 74:  
</source>
 
</source>
   −
calls available in <code>argv</code> [[Compel/Plugins|plugin]]. Then use argc and argv as you would use them in normal C program run from shell.
+
These calls are available in <code>argv</code> [[compel plugins|plugin]]. Now, argc and argv can be handled as usual.
    
== See also ==
 
== See also ==
 
* [[Compel/Usage_scenarios]]
 
* [[Compel/Usage_scenarios]]
* [[Compel/Plugins]]
+
* [[Compel plugins]]
    
[[Category:Compel]]
 
[[Category:Compel]]