Outdated egg!

This is an egg for CHICKEN 3, the unsupported old release. You're almost certainly looking for the CHICKEN 4 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

lightning
  1. Outdated egg!
  2. lightning
    1. Description
    2. Author
    3. Requirements
    4. Download
    5. Documentation
      1. jit:make-buffer
      2. jit:set-ip!
      3. jit:ip
      4. jit:flush
      5. jit:bytes
      6. jit:release
      7. jit:compile
      8. define-jit-macro
      9. jit:insn
    6. Example
    7. Changelog
    8. License

Description

An interface to the GNU Lightning library for dynamic code generation.

Some knowledge about GNU Lightning is required to use this extension effectively.

Author

felix winkelmann

Requirements

Download

lightning.egg

Documentation

jit:make-buffer

[procedure] (jit:make-buffer SIZE)

Allocates space for SIZE abstract JIT instructions and returns a machine-pointer to the start of the allocated area. The exact meaning of SIZE depends on the architecture; in general, defining an array of 1024 machine-instructions allows one to write 100 to 400 GNU lightning instructions (depending on the architecture and exact instructions).

jit:set-ip!

[procedure] (jit:set-ip! POINTER)

Sets the current instruction pointer to POINTER. Subsequently compiled code will be written to that location.

jit:ip

[procedure] (jit:ip)

Returns the current instruction pointer (a pointer to the next compiled instruction in the current code buffer).

jit:flush

[procedure] (jit:flush START [END])

Flushes the generated code area out of the processor's instruction cache, starting at the addresses given by the machine-pointer START end ending at END, which defaults to the value of (jit:ip). END may also be an offset, counted from START.

Returns a pointer to the start of the compiled code.

jit:bytes

[procedure] (jit:bytes START [END])

Returns the number of bytes needed for compiled code, counting from START (a pointer). END designates a pointer to the end of the compiled code and defaults to the value of (jit:ip).

jit:release

[procedure] (jit:release POINTER)

Frees the allocated buffer designated by POINTER. This is just a wrapper for free().

jit:compile

[syntax] (jit:compile ((TYPE VARIABLE VALUE) ...) INSTRUCTION ...)

Compiles the JIT instructions given by INSTRUCTION ... into the current buffer (which should have been set up with jit:set-buffer!). The first argument to this macro defines local variables which are passed into the code-generation process. TYPE should be foreign type specifier (as described in the CHICKEN manual) and VALUE should be the initial value VARIABLE should have.

The instructions should follow this grammar:

 <instruction> = (<operation> <argument> ...)
               | (<instruction>)
               | (begin <instruction> ...)
 	      | (delay <instruction1> <instruction2>)
               | ([TYPE] VARIABLE = . <instruction>)
 
    <argument> = <number>
               | <string>
               | <char>
 	      | <register>
               | forward
               | <variable>
 
    <register> = R0 | R1 | R2 | V0 | V1 | V2 | RET | SP | FPR0 | FPR1 | FPR2 | FPR3 | FPR4 | FPR5
 
    <variable> = <symbol>

The form ([TYPE] VARIABLE = <instruction>) defines a variable with a given type (which defaults to int) and assigns the result of <instruction> to that variable. VARIABLE may also be a variable declared in the declaration list given as the first argument to jit:compile. TYPE may be any C type, or one of the symbols insn, integer, unsigned-int, unsigned-integer, unsigned-short, unsigned-long or unsigned-char.

jit:compile expands into a foreign-lambda* form and can only be used in compiled code.

For more information see the GNU Lightning manual.

define-jit-macro

[syntax] (define-jit-macro (NAME . LAMBDA-LIST) BODY ...)

Defines a JIT macro. A form (NAME ARGUMENT ...) may appear in place of an instruction inside a jit:compile form and will be replaced by the result of evaluating BODY ... (and recursively processed).

jit:insn

[constant] jit:insn

An alias for (pointer "jit_insn").

Example

Here the "incr" example from the GNU Lightning documentation:

(include "lightning")

#>!
static int call_incr(int (*proc)(int), int n)
{
  return proc(n);
}
<#

(define-jit-macro (addc d s #!optional (n 1)) ; somewhat silly, just for demonstration.
  `(addi_i ,d ,s ,n) )

(define buf (jit:make-buffer 1000))

(jit:set-ip! buf)

(jit:compile ()
  (leaf 1)
  (in = arg_i)
  (getarg_i R0 in)
  (addc RET R0)
  (ret) )

(jit:flush buf)

(pp (call_incr buf 42)) ; => 43

And the nfibs example, from the same source:

(include "lightning")

#>!
static int call_nfibs(int (*proc)(int), int n)
{
  return proc(n);
}
<#

(define buf (jit:make-buffer 1000))

(jit:set-ip! buf)

(jit:compile 
 ((jit:insn nfibs buf))
 (prolog 1)
 (in =  arg_ui)
 (getarg_ui V0 in);              /* V0 = n */
 (insn ref = blti_ui forward V0 2);
 (subi_ui V1 V0 1);       /* V1 = n-1 */
 (subi_ui V2 V0 2);       /* V2 = n-2 */
 (prepare 1);
 (pusharg_ui V1);
 (finish nfibs);
 (retval V1);                     /* V1 = nfibs(n-1) */
 (prepare 1);
 (pusharg_ui V2);
 (finish nfibs);
 (retval V2);                     /* V2 = nfibs(n-2) */
 (addr_ui RET V1 V2);   /* RET = V1 + V2 */
 (ret);
 (patch ref);                               /* patch jump */
 (movi_i RET 1);                 /* RET = 1 */
 (ret) )

(jit:flush buf)
(pp (call_nfibs buf 30))

Changelog

License

 
 Copyright (c) 2005, Felix L. Winkelmann
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
 conditions are met:
 
   Redistributions of source code must retain the above copyright notice, this list of conditions and the following
     disclaimer. 
   Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
     disclaimer in the documentation and/or other materials provided with the distribution. 
   Neither the name of the author nor the names of its contributors may be used to endorse or promote
     products derived from this software without specific prior written permission. 
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGE.