/** * @file tasks.dox * @page tasks Creating your own tasks in MetalSVM * * * @section toc Table of Contents * - @ref initd * - @ref kerneltasks * - @ref usertasks * * @section initd Where MetalSVM starts tasks after boot * * The last step after booting is starting the \c initd process: * * \c kernel/main.c: * \code ... create_kernel_task (&id, initd, NULL, NORMAL_PRIO); ...\endcode * * \c Initd starts all the other processes and then exits. * The list of processes to start is defined in \c apps/tests.c * within \c test_init(): * * \code int test_init(void) { /* This is how the ARGV parameter list is defined */ char* argv[] = {"/bin/tests", NULL}; char* server_argv[] = {"/bin/server", "6789", NULL}; char* client_argv[] = {"/bin/client", "192.168.0.1", "6789", NULL}; ... /* Starting kernel- and user space tasks */ create_kernel_task(NULL, foo, "Hello from foo1", NORMAL_PRIO); create_kernel_task(NULL, join_test, NULL, NORMAL_PRIO); create_user_task(NULL, "/bin/tests", argv); return 0; }\endcode * * @section kerneltasks Creating kernel tasks * * To create your own kernel task, you will need to write a task first. * This can look like the following example task in \c kernel/tests.c: * * \code static int foo(void* arg) { int i; if (!arg) return 0; for(i=0; i<5; i++) { kprintf("%s\n", (char*) arg); sleep(1); } return 42; }\endcode * * A kernel task is just a procedure within the scope of init_test(). * Its signature should match the following pattern: * \code int my_task(void* my_args)\endcode * * To make \c initd start your task after booting the system, you will need to * write a \c create_kernel_task() call within \c test_init() which looks like * the \c foo example from the section above: * \code create_kernel_task(NULL, foo, "Hello from foo1", NORMAL_PRIO); \endcode * * The \c create_kernel_task procedure has the following signature: * \code int create_kernel_task(tid_t* id, entry_point_t ep, void* args, uint8_t prio)\endcode * Its parameters are the following: * - \c id: Provide the address of a \c tid_t variable here, if you need the new * task's ID. * - \c ep: The entry point of your task is just its function/procedure symbol. * - \c args: The address of the parameter structure your task expects. * - \c prio: The priority your task shall be executed with. Priority levels are * defined in \c include/metalsvm/tasks_types.h: * \code #define MAX_PRIO 31 #define REALTIME_PRIO 31 #define HIGH_PRIO 16 #define NORMAL_PRIO 8 #define LOW_PRIO 1 #define IDLE_PRIO 0\endcode * * @section usertasks Creating user space tasks * * User space tasks are usually not defined within the kernel code, * therefore they are launched differently. * * To write your own user space application, place your *.c source code within * \c newlib/examples/ and add a target in the Makefile (\c newlib/examples/Makefile) * to ensure that your application is built when you type \c "make" in the * MetalSVM directory. * * If your code does not consist of just some *.c and *.h files and you rather want * keep your own project folder: The only important thing for later is that your * executables and other runtime-needed files lay in the \c newlib/examples/ directory * during build of the initial ramdisk. * * The scripts which build MetalSVM's initial ramdisk are launched when the kernel * itself is built. \c metalsvm.elf and \c tools/initrd.img together * compose a bootable system which is rebuilt (if necessary) everytimes you run * \c make in the project directory. * * The initrd building scripts include every file within the \c newlib/examples/ * directory which is marked as \b executable. Do not forget this if you use your * own build scripts! * * After providing your own executable for the system within the initial ramdisk, * it still needs to be executed after boot. This is done very similarly to * launching kernel threads. * * Place your application launching \c create_user_task() call within \c test_init(): * \code create_user_task(NULL, "/bin/tests", argv);\endcode * * In this case the executable \c tests is launched with the parameter array \c argv. * Note that at build-time the executable is located at \c newlib/examples/tests. * The \c argv array is constructed like in the example at the top of this page. * * \c create_user_task()'s signature looks like this: * \code int create_user_task(tid_t* id, const char* fname, char** argv)\endcode * Its parameters are the following: * - \c id: Provide the address of a \c tid_t variable if you need the ID of your * started process. * - \c fname: This string denotes the path of your executable within the file system. * Every executable which comes from \c newlib/examples/ will be located within * \c /bin in MetalSVM's file system after boot. * - \c argv: This is the ARGV-structure the task will be equipped with after launch. * * */