Commits

Anonymous committed a9a6fc1

#16: mainlining; merged from 65:66 branches/issue_0016_dwhall_create_pm_init

Comments (0)

Files changed (7)

docs/src/HowToUsePyMite.txt

+=================
+How to Use PyMite
+=================
+
+:Author:    Dean Hall
+:Id:        $Id$
+
+Purpose
+-------
+
+This document describes how to use the high-level PyMite API
+to run a user module.  In doing so, it helps the developer
+write system tests and the user write a PyMite application.
+
+Overview
+--------
+
+PyMite shall provide a high-level API that makes it easy to use the
+virtual machine (VM).  In most cases, one must write the application
+in Python and a small ``main()`` in C that uses the high-level API.
+After the sources are written, the Python application is converted
+to an image using ``pmImgCreator`` and the image is compiled with the
+user's C code and linked to the PyMite VM library, ``libpmvm.a``.
+The build process is explained in greater detail in `BuildSystem`_.
+
+.. _`BuildSystem`: BuildSystem.html
+
+PyMite Example
+--------------
+
+This section demonstrates how a trivial program is written to run
+in the PyMite VM.  A more detailed example can be found in the PyMite
+source tree in ``src/sample``.
+
+First write the Python application, ``trivial.py`` that will run in the VM::
+
+    def funcname(n):
+        return n-42
+
+    funcname(6*7)
+
+Notice that an application in PyMite does not use the
+``if __name__ == "__main__":`` convention that Python does;
+also note that the program written above will run on a desktop Python VM.
+
+The next step is to create a C file that will run this program in the PyMite VM.
+The following C program will do exactly that::
+
+    #include "py.h"
+
+    extern unsigned char usrlib_img[];
+
+    int main(void)
+    {
+        PyReturn_t retval;
+
+        retval = pm_init(MEMSPACE_FLASH, usrlib_img);
+        PY_RETURN_IF_ERROR(retval);
+
+        retval = pm_run((P_U8)"trivial");
+        return (int)retval;
+    }
+
+Since not all Python programmers are familiar with C, I will explain the program
+above line by line.  The ``include`` statement brings many PyMite definitions
+such as ``pm_init()``, ``pm_run()``, and ``MEMSPACE_FLASH`` into the namespace
+of this file.  The ``extern`` line tells the compiler that the variable
+``usrlib_img[]`` is defined in another file.  Next the ``main()`` function
+means this program will run as the primary executable on the target.
+
+Inside ``main()`` the ``retval`` variable is declared.  It is used to catch
+any error codes that might come from the PyMite API functions.
+Next, the call to ``pm_init()`` initializes the VM and tells it where to find
+the images of the user application.  In our case, the ``trivial.py`` Python 
+program was turned into ``trivial_img.c`` and ``trivial_nat.c``
+by the tool ``pmImgCreator``.
+Inside ``trivial_img.c`` is where one finds the variable ``usrlib_img[]``
+which contains the `image` of our application (the equivalent of a ``.pyc``
+file).  Our application does not have any native code, but ``trivial_nat.c``
+is still needed because it defines an empty function table that needs to be
+linked to the VM.  The macro ``PY_RETURN_IF_ERROR()`` does what its name
+suggests.
+
+The next PyMite API, ``pm_run()`` tries to execute the module with the same
+name as the string you give to the function.  Here we tell the VM to find
+the module ``trivial`` in the global list of modules and run it.
+Behind the scenes, the module is loaded from its image into a structure in RAM
+and bytecodes are executed until program completion or an unhandled exception
+occurs.
+
+.. :mode=rest:
 
 #include "py.h"
 
-extern unsigned char stdlib_img[];
+
 extern unsigned char usrlib_img[];
 
 
 int main(void)
 {
-    /* ptr to code imgs */
-    P_U8 pimg;
-    pPyObj_t pstring = C_NULL;
-    /* ptr to module obj */
-    pPyFunc_t pmod;
-    /* name of module to run */
-    P_U8 modstr = (P_U8)"t002";
-    PyReturn_t retval = PY_RET_OK;
+    PyReturn_t retval;
 
-    heap_init();
-    retval = global_init();
+    retval = pm_init(MEMSPACE_FLASH, usrlib_img);
     PY_RETURN_IF_ERROR(retval);
 
-    /* load std image info */
-    pimg = (P_U8)&stdlib_img;
-    retval = img_findInMem(MEMSPACE_FLASH, &pimg);
-    PY_RETURN_IF_ERROR(retval);
-
-    /* load usr image info */
-    pimg = (P_U8)&usrlib_img;
-    retval = img_findInMem(MEMSPACE_FLASH, &pimg);
-    PY_RETURN_IF_ERROR(retval);
-
-    /* import module from global struct */
-    retval = string_new(&modstr, &pstring);
-    PY_RETURN_IF_ERROR(retval);
-    retval = mod_import(pstring, &pmod);
-    PY_RETURN_IF_ERROR(retval);
-
-    /* load builtins into root module */
-    retval = global_loadBuiltins(pmod);
-    PY_RETURN_IF_ERROR(retval);
-
-    /* XXX set "__name__" == "__main__" in mod's attrs here? */
-
-    /* interpret the module's bcode */
-    retval = interpret(pmod);
-
-    return retval;
+    retval = pm_run((P_U8)"t002");
+    return (int)retval;
 }
-
  * 2002/05/18   First.
  */
 
-/***************************************************************
- * Includes
- **************************************************************/
+#include "py.h"
 
 
- #include "py.h"
-
-
-/***************************************************************
- * Constants
- **************************************************************/
-
-/***************************************************************
- * Macros
- **************************************************************/
-
-/***************************************************************
- * Types
- **************************************************************/
-
-/***************************************************************
- * Globals
- **************************************************************/
-
-extern unsigned char stdlib_img[];
 extern unsigned char usrlib_img[];
 
-/***************************************************************
- * Main
- **************************************************************/
 
 int main(void)
 {
-    /* ptr to code imgs */
-    P_U8 pimg;
-    pPyObj_t pstring = C_NULL;
-    /* ptr to module obj */
-    pPyFunc_t pmod;
-    /* name of module to run */
-    P_U8 modstr = (P_U8)"t003";
-    PyReturn_t retval = PY_RET_OK;
+    PyReturn_t retval;
 
-    heap_init();
-    retval = global_init();
+    retval = pm_init(MEMSPACE_FLASH, usrlib_img);
     PY_RETURN_IF_ERROR(retval);
 
-    /* load std image info */
-    pimg = (P_U8)&stdlib_img;
-    retval = img_findInMem(MEMSPACE_FLASH, &pimg);
-    PY_RETURN_IF_ERROR(retval);
-
-    /* load usr image info */
-    pimg = (P_U8)&usrlib_img;
-    retval = img_findInMem(MEMSPACE_FLASH, &pimg);
-    PY_RETURN_IF_ERROR(retval);
-
-    /* import module from global struct */
-    retval = string_new(&modstr, &pstring);
-    PY_RETURN_IF_ERROR(retval);
-    retval = mod_import(pstring, &pmod);
-    PY_RETURN_IF_ERROR(retval);
-
-    /* load builtins into root module */
-    retval = global_loadBuiltins(pmod);
-    PY_RETURN_IF_ERROR(retval);
-
-    /* XXX set "__name__" == "__main__" in mod's attrs here? */
-
-    /* interpret the module's bcode */
-    retval = interpret(pmod);
-
-    return retval;
+    retval = pm_run((P_U8)"t003");
+    return (int)retval;
 }
-
 
 #include "py.h"
 
-extern unsigned char stdlib_img[];
+
 extern unsigned char usrlib_img[];
 
 
 int main(void)
 {
-    /* ptr to code imgs */
-    P_U8 pimg;
-    pPyObj_t pstring = C_NULL;
-    /* ptr to module obj */
-    pPyFunc_t pmod;
-    /* name of module to run */
-    P_U8 modstr = (P_U8)"t009";
-    PyReturn_t retval = PY_RET_OK;
+    PyReturn_t retval;
 
-    heap_init();
-    retval = global_init();
+    retval = pm_init(MEMSPACE_FLASH, usrlib_img);
     PY_RETURN_IF_ERROR(retval);
 
-    /* load std image info */
-    pimg = (P_U8)&stdlib_img;
-    retval = img_findInMem(MEMSPACE_FLASH, &pimg);
-    PY_RETURN_IF_ERROR(retval);
-
-    /* load usr image info */
-    pimg = (P_U8)&usrlib_img;
-    retval = img_findInMem(MEMSPACE_FLASH, &pimg);
-    PY_RETURN_IF_ERROR(retval);
-
-    /* import module from global struct */
-    retval = string_new(&modstr, &pstring);
-    PY_RETURN_IF_ERROR(retval);
-    retval = mod_import(pstring, &pmod);
-    PY_RETURN_IF_ERROR(retval);
-
-    /* load builtins into root module */
-    retval = global_loadBuiltins(pmod);
-    PY_RETURN_IF_ERROR(retval);
-
-    /* XXX set "__name__" == "__main__" in mod's attrs here? */
-
-    /* interpret the module's bcode */
-    retval = interpret(pmod);
-
-    return retval;
+    retval = pm_run((P_U8)"t009");
+    return (int)retval;
 }
-
 
 #include "py.h"
 
-extern unsigned char stdlib_img[];
+
 extern unsigned char usrlib_img[];
 
 
 int main(void)
 {
-    /* ptr to code imgs */
-    P_U8 pimg;
-    pPyObj_t pstring = C_NULL;
-    /* ptr to module obj */
-    pPyFunc_t pmod;
-    /* name of module to run */
-    P_U8 modstr = (P_U8)"t020";
-    PyReturn_t retval = PY_RET_OK;
+    PyReturn_t retval;
 
-    heap_init();
-    retval = global_init();
+    retval = pm_init(MEMSPACE_FLASH, usrlib_img);
     PY_RETURN_IF_ERROR(retval);
 
-    /* load std image info */
-    pimg = (P_U8)&stdlib_img;
-    retval = img_findInMem(MEMSPACE_FLASH, &pimg);
-    PY_RETURN_IF_ERROR(retval);
-
-    /* load usr image info */
-    pimg = (P_U8)&usrlib_img;
-    retval = img_findInMem(MEMSPACE_FLASH, &pimg);
-    PY_RETURN_IF_ERROR(retval);
-
-    /* import module from global struct */
-    retval = string_new(&modstr, &pstring);
-    PY_RETURN_IF_ERROR(retval);
-    retval = mod_import(pstring, &pmod);
-    PY_RETURN_IF_ERROR(retval);
-
-    /* load builtins into root module */
-    retval = global_loadBuiltins(pmod);
-    PY_RETURN_IF_ERROR(retval);
-
-    /* XXX set "__name__" == "__main__" in mod's attrs here? */
-
-    /* interpret the module's bcode */
-    retval = interpret(pmod);
-
-    return retval;
+    retval = pm_run((P_U8)"t020");
+    return (int)retval;
 }
-
+/**
+ * PyMite User API
+ *
+ * High-level functions to initialize and run PyMite
+ *
+ * @author      Dean Hall
+ * @copyright   Copyright 2006 Dean Hall.  All rights reserved.
+ *
+ * Log
+ * ---
+ *
+ * 2006/09/16   #16: Create pm_init() that does the initial housekeeping
+ */
+
+#include "py.h"
+
+
+extern unsigned char stdlib_img[];
+
+
+PyReturn_t pm_init(PyMemSpace_t memspace, P_U8 pusrimg)
+{
+    PyReturn_t retval;
+    P_U8 pimg;
+
+    /* Initialize the heap and the globals */
+    heap_init();
+    retval = global_init();
+    PY_RETURN_IF_ERROR(retval);
+
+    /* Load std image info */
+    pimg = (P_U8)&stdlib_img;
+    retval = img_findInMem(MEMSPACE_FLASH, &pimg);
+    PY_RETURN_IF_ERROR(retval);
+
+    /* Load usr image info if given */
+    if (pusrimg != C_NULL)
+    {
+        pimg = pusrimg;
+        retval = img_findInMem(memspace, &pimg);
+    }
+
+    return retval;
+}
+
+
+PyReturn_t pm_run(P_U8 modstr)
+{
+    PyReturn_t retval;
+    pPyFunc_t pmod;
+    pPyObj_t pstring;
+    P_U8 pmodstr = modstr;
+
+    /* Import module from global struct */
+    retval = string_new(&pmodstr, &pstring);
+    PY_RETURN_IF_ERROR(retval);
+    retval = mod_import(pstring, &pmod);
+    PY_RETURN_IF_ERROR(retval);
+
+    /* Load builtins into root module */
+    retval = global_loadBuiltins(pmod);
+    PY_RETURN_IF_ERROR(retval);
+
+    /* Interpret the module's bcode */
+    retval = interpret(pmod);
+
+    return retval;
+}
  * Log
  * ---
  *
+ * 2006/09/16   #16: Create pm_init() that does the initial housekeeping
  * 2006/08/31   #9: Fix BINARY_SUBSCR for case stringobj[intobj]
  * 2006/08/30   #6: Have pmImgCreator append a null terminator to image list
  * 2002/05/04   Merged most of contents to respective files.
  **************************************************************/
 
 /***************************************************************
- * Function Protos
- **************************************************************/
-
-/***************************************************************
  * Includes (order is critical)
  **************************************************************/
 
 #include "global.h"
 #include "misc.h"
 
+/***************************************************************
+ * Function Protos
+ **************************************************************/
+
+/**
+ * Initializes the PyMite virtual machine and  indexes the user's application 
+ * image.  The VM heap and globals are reset.  The argument, pusrimg, may be
+ * null for interactive sessions.
+ *
+ * @param memspace      Memory space in which the user image is located
+ * @param pusrimg       Address of the user image in the memory space
+ * @return Return status
+ */
+PyReturn_t pm_init(PyMemSpace_t memspace, P_U8 pusrimg);
+
+/**
+ * Executes the named module
+ *
+ * @param modstr        Name of module to run
+ * @return Return status
+ */
+PyReturn_t pm_run(P_U8 modstr);
+
+
 #endif /* __PY_H__ */