Differences

This shows you the differences between two versions of the page.

--- summerofcode2014:lualoader [2014/07/26 01:05] – PedroSouza
+++ summerofcode2014:lualoader [2014/09/25 01:05] (current) – PedroSouza
@@ Line 5: / Line 5: @@
 ===== Project description =====
-This project aims to make the Loader script interpreter modular so that the user can choose which scripting language to use at compile time. After that, it will be implemented a Lua scripting module and incrementally add the functionalities present in the Forth scripts.
+The project aims to design and implement a modular interface for the loader script \\
+interpreter decoupling the interpreter from the loader.
+Thus one can divide the project in two tasks:
+  * Design a modular interface to interpreters and adapt the already existing\\
+interpreters (**//Simple//** and **//Forth//**) to this interface.
+  * Implement a Lua interpreter with all the functionalities present in the Forth\\
+scripts.
+With this approach one want to provide a easy way to choose (at compile time) which\\
+interpreter the loader will use, and also provide a skeleton for adding others scripting\\
+languages.
 ===== Approach to solving the problem =====
-Based on the interface defined for scripting modules:
+==== Interface design ====
-  * The already present Forth interpreter will be updated to match the defined interface
+//src/sys/boot/common/interp.h//
-  * Implement the basics of the Lua interpreter
-  * Incrementally add functionalities present in the Forth interpreter to the Lua interpreter
+<code>
-  * Handle .conf and .rc file parsing with the Lua interpreter
+typedef void	interp_init_t(void *ctx);
+typedef int	interp_run_t(void *ctx, const char *input);
+typedef int	interp_incl_t(void *ctx, const char *filename);
+typedef int	interp_load_def_t(void *ctx);
+struct interp {
+	interp_init_t	*init;
+	interp_run_t	*run;
+	interp_incl_t	*incl;
+	interp_load_def_t *load_configs;
+	void		*context;
+};
+</code>
+The above C code shows the interpreter interface which contains:
+  * **init** Initializes the interpreter. Should be called before using any other interpreter function.
+  * **run** Interpretes and runs the passed string.
+  * **incl** Reads the file contents to a string and run it.
+  * **load_configs** Loads the default boot configuration file. (loader.rc for Forth, loader.lua for Lua).
+  * **context** Pointer to interpreter/vm context data.
+==== Lua interp implementation ====
+The lua interpreter is written in C and it uses some standard C functions. To embedded\\
+Lua into to loader the missing standard C functions (not present in libstand) where added\\
+in //src/sys/lua/src/lstd.h// and //src/sys/lua/src/lstd.c//.
+With the Lua embedded into the loader the **interp** interface was implemented in \\
+//src/sys/boot/common/interp_lua.c//.
+==== Lua scripts ====
+The scripts where implemented to match all the features present in the Forth scripts\\
+except for the PNP script (//src/sys/boot/forth/pnp.4th//) which I could not find any reference\\
+to its functions and I treated it as deprecated.
+The scripts are located at //src/sys/boot/lua// together with //lutils.h// and //lutils.c//\\
+which implements the following builtin lua functions:
+  * **loader.perform(string)** Perform a loader command.
+  * **loader.delay(time)** Delay function, time is passed in microsencods (1/1000 miliseconds).
+  * **loader.time()** Wrapper for C time function.
+  * **loader.include(filename)** Includes a lua script. Notice that it does not prevent multiple inclusion of the same file.
+  * **loader.getenv(name)** Returns the value of the given environment variable as string or nil if it does not exists.
+  * **io.getchar()** Wrapper for C getchar function.
+  * **io.ischar()** Wrapper for ischar C function.
+  * **io.gets()** Wrapper for gets C function.
+  * **io.open(filename)** Opens the given file. Returns a file (Lua user_data) variable or nil in case of failure.
+  * **io.close(file)** Closes the given file.
+  * **io.read(file, [size])** Returns S, R where S is a string containing the file data and R the number of bytes read.\\
+If size parameter is nil the function reads the whole file.
+Besides these builtin functions all functions from Lua baselib and stringlib are provided.
+List of lua scripts:
+  * **config.lua**: functions to load configuration files, parse and execute it.
+  * **core.lua**: functions to set verbose, ACPI, single user mode, safe mode, autoboot.
+  * **loader.lua**: script loaded in the boot startup.
+  * **menu.lua**: boot menu related functions.
+  * **password.lua**: boot password check functions.
+  * **screen.lua**: screen utility functions.
 ===== Deliverables =====
@@ Line 19: / Line 96: @@
   * Lua interpreter module
   * Lua scripts providing advanced boot options
-  * Lua parser for .conf and .rc files
+  * Lua parser for .conf files
 ===== Milestones =====
-  * 2 weeks - Decouple Forth interpreter and ensure that it's working properly.
+| Interpreter interface definition | **//DONE//** ||
-  * 2 weeks - Port Lua interpreter and ensure that it's working properly.
+| Adapt existing interpretes to the interface | **//DONE//** ||
-  * 1 week - Implement the loader function bindings.
+| Lua interpreter working with the loader | **//DONE//** ||
-  * 5 weeks - Incrementally add Lua script functionalities and ensure that they're working properly.
+| Lua loader builtin functions ||
-  * 1 week - Implement the .conf and .rc parser.
+| loader.%%**%%%%**%% functions | **//DONE//** ||
-  * 1 week - Write the documentation.
+| Lua file io functions | **//DONE//** ||
+| Lua base library | **//DONE//** ||
+| Lua string library | **//DONE//** ||
+| Kernel loading functions | **//DONE//** ||
+|  ||
+| Config file parsing and module loading | **//DONE//** ||
+| Boot menu | **//DONE//** ||
+| <del>%%PnP%% config & setup</del> | **//DEPRECATED//** ||
+==== New milestones ====
+| Fix //drawer.isColorEnabled()// | **//DONE//** ||
+| Fix //menu.run()// proper environment variable checks | **//DONE//** ||
+| Merge //menu.options.alias// with //menu.options// | **//TODO//** ||
+| Fix //kernels// menu option logic | **//DONE//** ||
+| Add dynamic menu options ordering (boot simple/multi) | **//TODO//** ||
+| Fix ANSI vs non-ANSI coloring | **//NEED TEST//** ||
+===== Testing =====
+Checkout the code:
+<code>
+$svn co https://socsvn.freebsd.org/socsvn/soc2014/pedrosouza/lua_loader/
+</code>
+By default the Lua interpreter is enabled, to revert to the Forth interpreter
+edit ///etc/src.conf// and add the following lines:
+<code>
+WITH_FORTH="yes"
+WITHOUT_LUA="yes"
+</code>
+or if you want to disable both Lua and Forth and use the simple interpreter:
+<code>
+WITHOUT_FORTH="yes"
+WITHOUT_LUA="yes"
+</code>
-===== Test Plan =====
+Then build and install the boot loader:
-List of features integrated and tested:
-| Lua interpreter working with the loader | DONE ||
+<code>
-| Lua loader functions (perform, set/get environment var, etc) | DONE ||
+$cd head/sys/boot
-| Lua file handling and include functions | DONE ||
+$make
-| Lua string library | DONE ||
+$su
-| Kernel loading functions | DONE ||
+$make install
-| Config file parsing and mudule loading | DONE ||
+</code>
-| Boot menu | BASIC ||
-| %%PnP%% config & setup | TODO ||
 ===== The Code =====