| /* |
| * Copyright 2017, Data61 |
| * Commonwealth Scientific and Industrial Research Organisation (CSIRO) |
| * ABN 41 687 119 230. |
| * |
| * 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(DATA61_BSD) |
| */ |
| |
| /** |
| * @file bootstrap.h |
| * |
| * @brief Helpers for bootstrapping an allocman on freshly running system |
| * |
| * Bootstrapping a system is hard. These helpers attempt to make it easy to start |
| * a system with a 'common' configuration. Systems that are not common should also |
| * be possible, but the code here will be able to help you less. |
| * |
| * In general to bootstrap a system you need to do the following |
| * 1. Describe the current cspace |
| * 2. Describe where resources (untypeds, slots etc) can be found |
| * 3. (maybe) create and switch to a new cspace |
| * These bootstrapping functions attempt to hide the requirements of these steps as |
| * much as possible, allowing you to substitute 'bootinfo' if you have it, otherweise |
| * requiring some minimal description. However enough internals are provided that |
| * each of these steps can be broken into if you need to describe some particularly |
| * interesting system. |
| * |
| * The allocman that gets created as a result of bootstrapping is constructed using |
| * some default 'sensible' allocators. Unfortunately if you want different allocators |
| * then there is currently no way to control that. |
| * |
| * Bootstrapping here requires some initial 'pool' of memory. This is memory that |
| * must NEVER be freed after you have bootstrapped an allocator. Be very careful |
| * you do not put this on a stack (and then free it) or have it as a global and use |
| * it multiple times. Unfortunately this pool is the 'magic' that allows the allocators |
| * to kick themselves going, and cannot be provided for you. The actual size of the pool |
| * is something you will need to work out with trial and error. |
| * |
| * With all of these methods, once they return failure you are basically 100% fucked |
| * since they make no effort to clean up after themselves if they detect failure. The |
| * ONLY sane thing you can do is log an error and terminate. |
| * |
| * See example_bootstrap.c for sample code that shows how to bootstrap in various ways |
| * |
| */ |
| |
| #pragma once |
| |
| #include <sel4/sel4.h> |
| #include <string.h> |
| #include <allocman/allocman.h> |
| #include <allocman/cspace/simple1level.h> |
| #include <allocman/cspace/two_level.h> |
| #include <allocman/mspace/fixed_pool.h> |
| #include <allocman/mspace/virtual_pool.h> |
| #include <allocman/utspace/twinkle.h> |
| #include <vspace/vspace.h> |
| #include <simple/simple.h> |
| #include <sel4platsupport/pmem.h> |
| /** |
| * Internal data structure for storing bootstrapping information. If you need to break |
| * open the boot strapping process, then you will be given a pointer to one of these |
| * that you will interract with to finish the boot strapping |
| */ |
| typedef struct bootstrap_info bootstrap_info_t; |
| |
| /** |
| * Every allocation manager created by these bootstrapping functions has a dual_pool |
| * as its memory manager. For the purposes of bootstrapping only the fixed pool (as |
| * passed to the boot strapping functions) is used. If you want to use a virtual pool |
| * (you almost certainly do so you don't run out of memory or have a stupidly large |
| * static pool) then this function will initial the virtual pool after the fact. The |
| * reason for this ordering is that it is expected that the creation of a vspace manager |
| * might expect an allocator, which you won't have yet if you are boot strapping. |
| * |
| * Note that there is no protection against calling this function multiple times or |
| * from trying to call it on an allocman that does not have a dual_pool as its underlying |
| * memory manager. DO NOT FUCK IT UP |
| * |
| * @param alloc Allocman whose memory manager to configure |
| * @param vstart Start of a virtual address range that will be allocated from. |
| * @param vsize Size of the virtual address range |
| * @param pd Page directory to invoke when mapping frames/page tables |
| */ |
| void bootstrap_configure_virtual_pool(allocman_t *alloc, void *vstart, size_t vsize, |
| seL4_CPtr pd); |
| |
| /** |
| * Simplest bootstrapping method that uses all the information in seL4_BootInfo |
| * assumes you are the rootserver. This keeps using whatever cspace you are currently in. |
| * |
| * @param bi BootInfo as passed to the rootserver |
| * @param pool_size Size of the initial pool. See file comments for details |
| * @param pool Initial pool. See file comments for details |
| * |
| * @return returns NULL on error |
| */ |
| allocman_t *bootstrap_use_bootinfo(seL4_BootInfo *bi, size_t pool_size, void *pool); |
| |
| /** |
| * Bootstraps using all the information in bootinfo, but switches to a new single |
| * level cspace. All untypeds specified in bootinfo will be moved to the new cspace, |
| * any other capabilities will be left in the old cspace. If you wish to refer to the |
| * boot cspace (most likely since it probably has capabilities you still want), then |
| * a cspace description of the old cspace can also be returned. |
| * |
| * @param bi BootInfo as passed to the rootserver |
| * @param cnode_size Number of slot bits (cnode_slots = 2^cnode_size) for the new cnode |
| * @param pool_size Size of the initial pool. See file comments for details |
| * @param pool Initial pool. See file comments for details |
| * @param old_cspace Optional location to store a description of the original cspace. You |
| * can free this memory back to the allocman when are done with it |
| * |
| * @return returns NULL on error |
| */ |
| allocman_t *bootstrap_new_1level_bootinfo(seL4_BootInfo *bi, size_t cnode_size, size_t pool_size, void *pool, cspace_simple1level_t **old_cspace); |
| |
| /** |
| * Bootstraps using all the information in bootinfo, but switches to a new two |
| * level cspace. All untypeds specified in bootinfo will be moved to the new cspace, |
| * any other capabilities will be left in the old cspace. If you wish to refer to the |
| * boot cspace (most likely since it probably has capabilities you still want), then |
| * a cspace description of the old cspace can also be returned. |
| * |
| * @param bi BootInfo as passed to the rootserver |
| * @param l1size Number of slot bits (l1_slots = 2^l1size) for the level 1 cnode |
| * @param l2size Number of slot bits (l2_slots = 2^l2size) for the level 2 cnode |
| * @param pool_size Size of the initial pool. See file comments for details |
| * @param pool Initial pool. See file comments for details |
| * @param old_cspace Optional location to store a description of the original cspace. You |
| * can free this memory back to the allocman when are done with it |
| * |
| * @return returns NULL on error |
| */ |
| allocman_t *bootstrap_new_2level_bootinfo(seL4_BootInfo *bi, size_t l1size, size_t l2size, size_t pool_size, void *pool, cspace_simple1level_t **old_cspace); |
| |
| /** |
| * Give an allocator all the untyped memory that simple knows about. |
| * |
| * This assumes that all the untyped caps are currently as simple thinks they are. |
| * If there have been any cspace reshuffles simple will not give allocman useable information |
| * |
| * Allocman will also try and use sel4platsupport_get_pmem_region_list to find PMEM_TYPE_RAM |
| * regions that are device untyped objects. |
| */ |
| int allocman_add_simple_untypeds(allocman_t *alloc, simple_t *simple); |
| |
| /** |
| * Give an allocator all the untyped memory that simple knows about. |
| * |
| * This assumes that all the untyped caps are currently as simple thinks they are. |
| * If there have been any cspace reshuffles simple will not give allocman useable information |
| * |
| * If num_regions is set to 0 or region_list is NULL, Allocman will also try and use |
| * sel4platsupport_get_pmem_region_list to find PMEM_TYPE_RAM regions that are device untyped objects. |
| * Otherwise any device untyped objects that overlap with regions that are type PMEM_TYPE_RAM will be marked as ALLOCMAN_UT_DEV_MEM. |
| */ |
| int allocman_add_simple_untypeds_with_regions(allocman_t *alloc, simple_t *simple, int num_regions, pmem_region_t *region_list); |
| |
| /** |
| * Bootstraps using all the information provided by simple, but switches to a new two |
| * level cspace. All capabilities specified by simple will be moved to the new cspace. All untypeds specified by simple are given to the allocator |
| * |
| * @param simple simple pointer to the struct |
| * @param l1size Number of slot bits (l1_slots = 2^l1size) for the level 1 cnode |
| * @param l2size Number of slot bits (l2_slots = 2^l2size) for the level 2 cnode |
| * @param pool_size Size of the initial pool. See file comments for details |
| * @param pool Initial pool. See file comments for details |
| * |
| * @return returns NULL on error |
| */ |
| allocman_t *bootstrap_new_2level_simple(simple_t *simple, size_t l1size, size_t l2size, size_t pool_size, void *pool); |
| |
| /* As above, but 1 level */ |
| allocman_t *bootstrap_new_1level_simple(simple_t *simple, size_t l1size, size_t pool_size, void *pool); |
| |
| /** |
| * Bootstraps into the current environment as defined by simple. This will continue |
| * to use the cspace described by simple, as well as all the untypeds it knows about |
| * |
| * @param simple Pointer to simple interface, will not be retained |
| * @param pool_size Size of the initial pool. See file comments for details |
| * @param pool Initial pool. See file comments for details |
| * |
| * @return returns NULL on error |
| */ |
| allocman_t *bootstrap_use_current_simple(simple_t *simple, size_t pool_size, void *pool); |
| |
| /** |
| * Bootstraps an allocator that will reuse the current single level cspace (which |
| * you must describe to it). While bootstrapping should succeed, you will need to |
| * add untypeds manually to the returned allocman to make it useful. |
| * |
| * @param root_cnode Location of the cnode that is the current cspace |
| * @param cnode_size Size in slot_bits of the current cnode |
| * @param start_slot First free slot in the current cspace |
| * @param end_slot Last free slot + 1 in the current cspace |
| * @param pool_size Size of the initial pool. See file comments for details |
| * @param pool Initial pool. See file comments for details |
| * |
| * @return returns NULL on error |
| */ |
| allocman_t *bootstrap_use_current_1level(seL4_CPtr root_cnode, size_t cnode_size, seL4_CPtr start_slot, seL4_CPtr end_slot, size_t pool_size, void *pool); |
| |
| /** |
| * Provides a description of the boot cspace if you are doing a customized |
| * bootstrapping. This MUST be set before using boostrap_new_[1|2]level |
| * |
| * @param bs Internal bootstrapping info as allocated/returned by {@link #bootstrap_create_info} |
| * @param cspace CSpace that will be used for bootstrapping purposes. The cspace only needs to exist |
| * for as long as bootstrapping is happening, it will not be used afterwards |
| * @param root_cnode Path to the root cnode of cspace. This is needed so that a cap to the old cspace |
| * can be provided in the new cspace |
| * |
| * @return returns 0 on success |
| */ |
| int bootstrap_set_boot_cspace(bootstrap_info_t *bs, cspace_interface_t cspace, cspacepath_t root_cnode); |
| |
| /** |
| * Adds knowledge of untypeds to the bootstrapping information. These untypeds will |
| * be moved to the new cspace and be given to the untyped manager once bootstrapping |
| * has completed. |
| * |
| * @param bs Internal bootstrapping info as allocated/returned by {@link #bootstrap_create_info} |
| * @param num Number of untypeds to be added |
| * @param uts Path to each of the untypeds |
| * @param size_bits Size of each of the untypeds |
| * @param paddr Optional physical address of each of the untypeds |
| * @param isDevice whether this untyped is for a device region or not |
| * |
| * @return returns 0 on success |
| */ |
| int bootstrap_add_untypeds(bootstrap_info_t *bs, size_t num, const cspacepath_t *uts, size_t *size_bits, uintptr_t *paddr, bool isDevice); |
| |
| /** |
| * Adds knowledge of all the untypeds of bootinfo to the bootstrapper. These will |
| * be moved to the new cspace and given to the untyped manager once bootstrapping has |
| * completed |
| * |
| * @param bs Internal bootstrapping info as allocated/returned by {@link #bootstrap_create_info} |
| * @param bi BootInfo as passed to the rootserver |
| * |
| * @return returns 0 on success |
| */ |
| int bootstrap_add_untypeds_from_bootinfo(bootstrap_info_t *bs, seL4_BootInfo *bi); |
| |
| /** |
| * Completes bootstrapping into a new single level cspace. |
| * |
| * @param info Internal bootstrapping info as allocated/returned by {@link #bootstrap_create_info} |
| * @param cnode_size Size in slot bits of new cspace |
| * @param tcb Path to the TCB of the current thread, need to perform an invocation of seL4_TCB_SetSpace |
| * @param pd Path to the PD of the current thread. This is needed to work around seL4 restriction that |
| * requires the address space be set at the same time as the cspace |
| * @param oldroot Optional location to store a path to a cnode that is root cnode given in {@link #bootstrap_set_boot_cspace} |
| * |
| * @return returns NULL on error |
| */ |
| allocman_t *bootstrap_new_1level(bootstrap_info_t *info, size_t cnode_size, cspacepath_t tcb, cspacepath_t pd, cspacepath_t *oldroot); |
| |
| /** |
| * Completes bootstrapping into a new two level cspace. |
| * |
| * @param info Internal bootstrapping info as allocated/returned by {@link #bootstrap_create_info} |
| * @param l1size Number of slot bits (l1_slots = 2^l1size) for the level 1 cnode |
| * @param l2size Number of slot bits (l2_slots = 2^l2size) for the level 2 cnode |
| * @param tcb Path to the TCB of the current thread, need to perform an invocation of seL4_TCB_SetSpace |
| * @param pd Path to the PD of the current thread. This is needed to work around seL4 restriction that |
| * requires the address space be set at the same time as the cspace |
| * @param oldroot Optional location to store a path to a cnode that is root cnode given in {@link #bootstrap_set_boot_cspace} |
| * |
| * @return returns NULL on error |
| */ |
| allocman_t *bootstrap_new_2level(bootstrap_info_t *info, size_t l1size, size_t l2size, cspacepath_t tcb, cspacepath_t pd, cspacepath_t *oldroot); |
| |
| /** |
| * This function starts bootstrapping the system, and then 'breaks out' and |
| * allows you to give a description of the boot cspace as well as provide any |
| * untypeds. A new 1 or 2 level cspace can then be created. |
| * |
| * @param pool_size Size of the initial pool. See file comments for details |
| * @param pool Initial pool. See file comments for details |
| * |
| * @return returns NULL on error |
| */ |
| bootstrap_info_t *bootstrap_create_info(size_t pool_size, void *pool); |
| |
| /** |
| * Creates an empty allocman from a starting pool. The returned allocman will not |
| * have an attached cspace or utspace. This function provides the ultimate flexibility |
| * in how you can boot strap the system (read: this does basically nothing for you). |
| |
| * @param pool_size Size of the initial pool. See file comments for details |
| * @param pool Initial pool. See file comments for details |
| * |
| * @return returns NULL on error |
| */ |
| allocman_t *bootstrap_create_allocman(size_t pool_size, void *pool); |
| |
