libsel4utils/include/sel4utils/process.h

/*
 * Copyright 2014, NICTA
 *
 * This software may be distributed and modified according to the terms of
 * the BSD 2-Clause license. Note that NO WARRANTY is provided.
 * See "LICENSE_BSD2.txt" for details.
 *
 * @TAG(NICTA_BSD)
 */
#ifndef SEL4UTILS_PROCESS_H
#define SEL4UTILS_PROCESS_H

#include <autoconf.h>

#if (defined CONFIG_LIB_SEL4_VSPACE && defined CONFIG_LIB_SEL4_VKA)

#include <vka/vka.h>
#include <vspace/vspace.h>

#include <sel4utils/thread.h>
#include <sel4utils/vspace.h>
#include <sel4utils/elf.h>

#define WORD_STRING_SIZE ((CONFIG_WORD_SIZE / 3) + 1)

typedef struct object_node object_node_t;

struct object_node {
    vka_object_t object;
    object_node_t *next;
};

typedef struct {
    vka_object_t pd;
    vspace_t vspace;
    sel4utils_alloc_data_t data;
    vka_object_t cspace;
    uint32_t cspace_size;
    uint32_t cspace_next_free;
    sel4utils_thread_t thread;
    vka_object_t fault_endpoint;
    void *entry_point;
    uintptr_t sysinfo;
    object_node_t *allocated_object_list_head;
    /* if the elf wasn't loaded into the address space, this describes the regions.
     * this permits lazy loading / copy on write / page sharing / whatever crazy thing
     * you want to implement */
    int num_elf_regions;
    sel4utils_elf_region_t *elf_regions;
    bool own_vspace;
    bool own_cspace;
} sel4utils_process_t;

/* sel4utils processes start with some caps in their cspace.
 * These are the caps
 */
enum sel4utils_cspace_layout {
    /* no cap in NULL */
    SEL4UTILS_NULL_SLOT = 0,
    /*
     * The root cnode (with appropriate guard)
     */
    SEL4UTILS_CNODE_SLOT = 1,
    /* The slot on the cspace that fault_endpoint is put if
     * sel4utils_configure_process is used.
     */
    SEL4UTILS_ENDPOINT_SLOT = 2,
    
    /* The page directory slot */
    SEL4UTILS_PD_SLOT = 3,
 
    /* the slot for the asid pool that this thread is in and can create threads
     * in. 0 if this kernel does not support asid pools */
    SEL4UTILS_ASID_POOL_SLOT = 4,

    /* the slot for this processes tcb */
    SEL4UTILS_TCB_SLOT = 5,

    /* First free slot in the cspace configured by sel4utils */
    SEL4UTILS_FIRST_FREE = 6
};

typedef struct {
    /* should we handle elf logic at all? */
    bool is_elf;
    /* if so what is the image name? */
    char *image_name;
    /* Do you want the elf image preloaded? */
    bool do_elf_load;

    /* otherwise what is the entry point and sysinfo? */
    void *entry_point;
    uintptr_t sysinfo;

    /* should we create a default single level cspace? */
    bool create_cspace;
    /* if so how big ? */
    int one_level_cspace_size_bits;

    /* otherwise what is the root cnode ?*/
    /* Note if you use a custom cspace then
     * sel4utils_copy_cap_to_process etc will not work */
    vka_object_t cnode;

    /* do you want us to create a vspace for you? */
    bool create_vspace;
    /* if not what is the page dir, and what is the vspace */
    vspace_t *vspace;
    vka_object_t page_dir;

    /* if so, is there a regions you want left clear?*/
    sel4utils_elf_region_t *reservations;
    int num_reservations;

    /* do you want a fault endpoint created? */
    bool create_fault_endpoint;
    /* otherwise what is it */
    vka_object_t fault_endpoint;

    int priority;
#ifndef CONFIG_KERNEL_STABLE
    seL4_CPtr asid_pool;
#endif
} sel4utils_process_config_t;

/**
 * Start a process, and copy arguments into the processes address space.
 *
 * This is intended to use when loading applications of the format:
 *
 * int main(int argc, char **argv) { };
 *
 * The third argument (in r2 for arm, on stack for ia32) will be the address of the ipc buffer.
 * This is intended to be loaded by the crt into the data word of the ipc buffer,
 * or you can just add it to your function prototype.
 *
 * Add the following to your crt to use it this way:
 *
 * arm: str r2, [r2, #484]
 * ia32: popl %ebp
 *       movl %ebp, 484(%ebp)
 *
 * @param process initialised sel4utils process struct.
 * @param vka     vka interface to use for allocation of frames.
 * @param vspace  the current vspace.
 * @param argc    the number of arguments.
 * @param argv    a pointer to an array of strings in the current vspace.
 * @param resume  1 to start the process, 0 to leave suspended.
 *
 * @return -1 on error, 0 on success.
 *
 */
int sel4utils_spawn_process(sel4utils_process_t *process, vka_t *vka, vspace_t *vspace,
                            int argc, char *argv[], int resume);

/**
 * Start a process, and copy arguments into the processes address space.
 *
 * This is intended for use when loading applications that have a System V ABI compliant
 * entry point. This means that the entry point should *not* be a 'main' that is expecting
 * argc and argv in the form as passed here, but should be an _start routine that will
 * take a stack frame with the arguments on it and construct an appropriate invocation
 * to a main function. The stack frame passed to the entry point will have an auxv, envp
 * and argv
 *
 * @param process initialised sel4utils process struct.
 * @param vka     vka interface to use for allocation of frames.
 * @param vspace  the current vspace.
 * @param argc    the number of arguments.
 * @param argv    a pointer to an array of strings in the current vspace.
 * @param resume  1 to start the process, 0 to leave suspended.
 *
 * @return -1 on error, 0 on success.
 *
 */
int sel4utils_spawn_process_v(sel4utils_process_t *process, vka_t *vka, vspace_t *vspace,
                              int argc, char *argv[], int resume);

/**
 * This is the function to use if you just want to set up a process as fast as possible.
 * It creates a simple cspace and vspace for you, allocates a fault endpoint and puts
 * it into the new cspace.
 *
 * It loads the elf file into the new vspace, parses the elf file and stores the entry point
 * into process->entry_point.
 *
 * It uses the same vka for both allocations - the new process will not have an allocator.
 *
 * The process will have just one thread.
 *
 * Otherwise, use it as a model for loading processes and use the elf_load.
 *
 * WARNING: when launching processes on ia32 please ensure your calling convention
 * matches that documented in sel4utils_start_thread. Otherwise your arguments
 * won't come through correctly.
 *
 * @param process      uninitialised process struct.
 * @param vka          allocator to use to allocate objects.
 * @param vspace vspace allocator for the current vspace.
 * @param priority     priority to configure the process to run as.
 * @param image_name   name of the elf image to load from the cpio archive.
 *
 * @return 0 on success, -1 on error.
 */
int sel4utils_configure_process(sel4utils_process_t *process, vka_t *vka, vspace_t *vspace,
                                uint8_t priority, char *image_name);

/**
 * Configure a process with more customisations (Create your own vspace, customise cspace size).
 *
 * @param process               uninitialised process struct
 * @param vka                   allocator to use to allocate objects.
 * @param spawner_vspace        vspace to use to allocate virtual memory in the current address space.
 * @param config process config.
 *
 * @return 0 on success, -1 on error.
 */
int sel4utils_configure_process_custom(sel4utils_process_t *process, vka_t *target_vka,
                                       vspace_t *spawner_vspace, sel4utils_process_config_t config);

/**
 * Copy a cap into a process' cspace.
 *
 * This will only work if you configured the process using one of the above functions, or
 * have mimicked their functionality.
 *
 * @param process process to copy the cap to
 * @param src     path in the current cspace to copy the cap from
 *
 * @return 0 on failure, otherwise the slot in the processes cspace.
 */
seL4_CPtr sel4utils_copy_cap_to_process(sel4utils_process_t *process, cspacepath_t src);


/**
 * Move a cap into a process' cspace.
 *
 * This will only work if you configured the process using one of the above functions, or
 * have mimicked their functionality.
 *
 * @param process process to move the cap to
 * @param src     path in the current cspace to move the cap from
 * @param vka     the allocator that owns the cslot the cap is currently in, so it may be freed after the move.
 *
 * @return 0 on failure, otherwise the slot in the processes cspace.
 */
seL4_CPtr sel4utils_move_cap_to_process(sel4utils_process_t *process, cspacepath_t src, vka_t *from_vka);

/**
 *
 * Mint a cap into a process' cspace.
 *
 * As above, except mint the cap with rights and data.
 *
 * @return 0 on failure, otherwise the slot in the cspace where the new cap is.
 */
seL4_CPtr sel4utils_mint_cap_to_process(sel4utils_process_t *process, cspacepath_t src, seL4_CapRights rights, seL4_CapData_t data);

/**
 * Destroy a process.
 *
 * This will free everything possible associated with a process and teardown the vspace.
 *
 * @param process process to destroy
 * @param vka allocator used to allocate objects for this process
 */
void sel4utils_destroy_process(sel4utils_process_t *process, vka_t *vka);


/*
 * sel4utils default allocated object function for vspaces.
 *
 * Stores a list of allocated objects in the process struct and frees them
 * when sel4utils_destroy_process is called.
 */
void sel4utils_allocated_object(void *cookie, vka_object_t object);

/*
 * Create c-formatted argument list to pass to a process from arbitrarily long amount of words.
 *
 * @param strings empty 2d array of chars to populate with word strings.
 * @param argv empty 1d array of char pointers which will be set up with pointers to
 *             strings in strings.
 * @param argc number of words
 * @param ... list of words to create arguments from.
 *
 */
void sel4utils_create_word_args(char strings[][WORD_STRING_SIZE], char *argv[], int argc, ...);

#endif /* (defined CONFIG_LIB_SEL4_VSPACE && defined CONFIG_LIB_SEL4_VKA) */
#endif /* SEL4UTILS_PROCESS_H */