/* riscos/usb/sys/ccall.h
 *
 * (c) 2002 Simtec Electronics
 *
 * Ben Dooks
 *
 * Header file for ccall library function
 *
 * $Id: ccall.h,v 1.5 2003/08/07 22:16:25 ben Exp $
 *
 * This Library file is part of the Simtec Electronics USB stack development
 *   suite.
 * Specific licence is granted to use this file by third parties for the
 *   development of USB device drivers.
 *
 */

#ifndef __USB_SYS_CCALL_H
#define __USB_SYS_CCALL_H "$Id: ccall.h,v 1.5 2003/08/07 22:16:25 ben Exp $"

/** Inter C module calling wrapper.</para>

 <para>ccall_create makes a small piece of code so that one module's C code
 can call another, or an external caller can enter the C code with the
 correct workspace setup.</para>

 <para>There are a number of limitations:

  - variable argument functions are not supported
  - you can only pass 4 registers worth of arguments through
  - the calling mode must be SVC
</para>

 <para>the space for the code-segment is currently allocated out of the RMA, and as
 such, should be freed after the user has done with it.</para>

 <para>An example piece of code, where my_example_routine needs to be
 called by another piece of C...

<programlisting>
 void *example_entry;
 void *my_pw;
 int my_example_routine(args);

 void init_entry(void)
 {
   ccall_create(&example_entry, my_example_routine, my_pw)
 }

 void fini_entry(void)
 {
   ccall_free(&example_entry);
 }
</programlisting>


 @memo Inter C module calling wrapper.
 @param dest Pointer to a void* to place the result.
 @param call Function to be called through this.
 @param pw   The private word to get the proper workspace for the call.

*/
extern int ccall_create(void **dest, void *call, void *pw);

/** Free ccall structure created by ccall_create().
 @memo Free inter C module calling wrapper.
 @param entry Entry pointer from create.
*/
extern int ccall_free(void **entry);

#endif /* __USB_SYS_CCALL_H */
