umem_vmm.h

Simple Operating Systems （简称SOS）是一个可以运行在X86平台上（包括QEMU

 * space. All the translations belonging to private mappings are
 * marked 'read-only' to activate the "copy-on-write" semantics.
 *
 * @param owner The process that will hold the new address space
 *
 * @note automatically calls
 * sos_thread_prepare_user_space_access()/sos_thread_end_user_space_access()
 */
struct sos_umem_vmm_as *
sos_umem_vmm_duplicate_current_thread_as(struct sos_process *owner);


/**
 * Called at process deletion time, to remove all mappings present in
 * the address space. This function not only delete all the VR data
 * structures, it also calls the unmap()/unref() callbacks of these
 * VRs. However, the physical pages mapped inside the address space
 * won't be unmapped at this stage: they will be unmapped all in one
 * go when the undelying mm_context will become unused.
 *
 * @note no need to call
 * sos_thread_prepare_user_space_access()/sos_thread_end_user_space_access()
 */
sos_ret_t
sos_umem_vmm_delete_as(struct sos_umem_vmm_as * as);


/*
 * Accessor functions for the address space
 */

/** Retrieve the pointer (NOT a new reference !) to the process owning
    the given address space. */
struct sos_process *
sos_umem_vmm_get_process(struct sos_umem_vmm_as * as);

/** Retrieve the pointer (NOT a new reference !) to the MMU
    configuration for the given address space */
struct sos_mm_context *
sos_umem_vmm_get_mm_context(struct sos_umem_vmm_as * as);

/** Retrieve a pointer to the VR that covers the given virtual address
    in the given address space */
struct sos_umem_vmm_vr *
sos_umem_vmm_get_vr_at_address(struct sos_umem_vmm_as * as,
			       sos_uaddr_t uaddr);


/*
 * Accessor functions for the virtual regions
 */

/** Retrieve the address space owning the given VR */
struct sos_umem_vmm_as *
sos_umem_vmm_get_as_of_vr(struct sos_umem_vmm_vr * vr);

/** Retrieve the set of callbacks of the given VR */
struct sos_umem_vmm_vr_ops *
sos_umem_vmm_get_ops_of_vr(struct sos_umem_vmm_vr * vr);

/** Retrieve the current protection of the given VR */
sos_ui32_t sos_umem_vmm_get_prot_of_vr(struct sos_umem_vmm_vr * vr);

/** Retrieve the flags of the given VR. One will especially be
    interested in the SOS_VR_MAP_SHARED bit */
sos_ui32_t sos_umem_vmm_get_flags_of_vr(struct sos_umem_vmm_vr * vr);

/** Retrieve the resource mapped by the VR */
struct sos_umem_vmm_mapped_resource *
sos_umem_vmm_get_mapped_resource_of_vr(struct sos_umem_vmm_vr * vr);

/** Retrieve the start user address for the given mapping */
sos_uaddr_t sos_umem_vmm_get_start_of_vr(struct sos_umem_vmm_vr * vr);

/** Retrieve the size (in user space) of the given mapping */
sos_size_t sos_umem_vmm_get_size_of_vr(struct sos_umem_vmm_vr * vr);

/** Retrieve the offset in the resource of the mapping */
sos_luoffset_t
sos_umem_vmm_get_offset_in_resource(struct sos_umem_vmm_vr * vr);


/*
 * Restricted accessor functions. May only be called from inside the
 * map() callback of a VR
 */

/**
 * Function that is not called directly by the umem_subsystem: It MUST
 * always be called by the mmap() callback of the resource being
 * mapped (@see sos_umem_vmm_mapped_resource::mmap()). The mmap()
 * method is called at VR creation time, automatically by
 * sos_umem_vmm_map().
 *
 * @note The VR MUST NOT already have a set of operations (fatal error)
 */
sos_ret_t sos_umem_vmm_set_ops_of_vr(struct sos_umem_vmm_vr * vr,
				     struct sos_umem_vmm_vr_ops * ops);


/*
 * mmap API
 */


/** sos_umem_vmm_map() flag: the address given as parameter to
    sos_umem_vmm_map() is not only a hint, it is where the VR is
    expected to be mapped */
#define SOS_VR_MAP_FIXED  (1 << 31)


/**
 * Add a new VR in the given address space, that maps the given
 * resource. Its semantics follows that of the UNIX mmap() call
 * (including SOS_VR_MAP_FIXED). Real mapping in physical memory will
 * be delayed as much as possible (demand paging) and the physical
 * pages will be shared among processes as much as possible (COW).
 *
 * @param *uaddr must be page-aligned, and can be NULL. It stores the
 * address of the mapping, when successful
 *
 * @param size The size of the mapping in user space
 *
 * @param access_rights The allowed accesses to the mapped resource
 * (@see SOS_VM_MAP_PROT_* flags in hwcore/paging.h)
 *
 * @param flags mainly: is it shared mapping (SOS_VR_MAP_SHARED) or not ?
 *
 * @param resource MUST be NON NULL, and its mmap() method must also
 * be NON NULL
 *
 * @param offset_in_resource where inside the resource does the
 * mapping start
 *
 * @return SOS_OK on success (address of the mapping stored in uaddr)
 *
 * @note no need to call
 * sos_thread_prepare_user_space_access()/sos_thread_end_user_space_access()
 */
sos_ret_t
sos_umem_vmm_map(struct sos_umem_vmm_as * as,
		 sos_uaddr_t *uaddr, sos_size_t size,
		 sos_ui32_t access_rights,
		 sos_ui32_t flags,
		 struct sos_umem_vmm_mapped_resource * resource,
		 sos_luoffset_t offset_in_resource);


/**
 * Unmap the given address interval. This might imply the partial or
 * complete unmapping of 0, 1 or more VRs. Same semantics as unix
 * munmap()
 *
 * @note automatically calls
 * sos_thread_prepare_user_space_access()/sos_thread_end_user_space_access()
 */
sos_ret_t
sos_umem_vmm_unmap(struct sos_umem_vmm_as * as,
		   sos_uaddr_t uaddr, sos_size_t size);


/**
 * Change the access rights of the given address interval. This might
 * concern 0, 1 or more VRs, and result in the splitting in 1 or 2 VRs
 * if they are partially concerned by the change in protection.. Same
 * semantics as unix mprotect()
 *
 * @param new_access_rights @see SOS_VM_MAP_PROT_* flags in hwcore/paging.h
 *
 * @note MAKE SURE YOU CALL
 * sos_thread_prepare_user_space_access()/sos_thread_end_user_space_access()
 */
sos_ret_t
sos_umem_vmm_chprot(struct sos_umem_vmm_as * as,
		    sos_uaddr_t uaddr, sos_size_t size,
		    sos_ui32_t new_access_rights);



/**
 * Flag for sos_umem_vmm_resize() to indicate that the VR being
 * resized can be moved elsewhere if there is not enough room to
 * resize it in-place
 */
#define SOS_VR_REMAP_MAYMOVE (1 << 30)

/**
 * Lookup the region covering the old_uaddr/old_size interval, and
 * resize it to match the *new_uaddr/new_size requirements. This is a
 * variant of Unix's mremap() that allow to resize the VR by its
 * low-addresses (mremap only allows to resize a VR by its
 * top-address).
 *
 * @param old_uaddr Low address of the interval covered by the VR to resize
 *
 * @param old_size Size of the interval covered by the VR to resize
 *
 * @param new_uaddr MUST BE page-aligned ! Initially: the new start
 * address of the VR, allowing to change the low-address. Once the
 * function returns: the actual start address of the VR (which might
 * be different, due to SOS_VR_REMAP_MAYMOVE flag, when set)
 *
 * @param new_size The size requested for the VR. Might be
 * smaller/larger than the original VR size
 *
 * @param flags Essentially: 0 or SOS_VR_REMAP_MAYMOVE
 *
 * @note MAKE SURE YOU CALL
 * sos_thread_prepare_user_space_access()/sos_thread_end_user_space_access()
 */
sos_ret_t
sos_umem_vmm_resize(struct sos_umem_vmm_as * as,
		    sos_uaddr_t old_uaddr, sos_size_t old_size,
		    sos_uaddr_t /* in/out */*new_uaddr, sos_size_t new_size,
		    sos_ui32_t flags);


/*
 * Heap management API (ie libc's malloc support)
 */

/**
 * Change the top address of the heap.
 *
 * @param new_top_uaddr When NULL don't change anything. Otherwise:
 * change the top address of the heap
 *
 * @return The top address of the heap after having been updated (if
 * ever)
 */
sos_uaddr_t
sos_umem_vmm_brk(struct sos_umem_vmm_as * as,
		 sos_uaddr_t new_top_uaddr);


/*
 * Reserved functions
 */

/**
 * Called by the main page fault handler when a physical page is not
 * mapped for the given address of the current address space. This
 * function is called only if:
 *  - The access (read / write) is allowed on this VR
 *  - no physical page is mapped yet
 * This function first calls the sos_paging_try_resolve_COW() to
 * resolve the COW if a COW access pattern is detected, and, if
 * unsuccessful, the sos_umem_vmm_vr_ops::page_in() method of the VR.
 *
 * @param uaddr The address that was accessed, causing the fault.
 *
 * @param write_access Was it write access ?
 *
 * @param user_access Was it a user access ? Or a kernel access (by
 * uaccess.h functions) ?
 *
 * @return SOS_OK when the fault could be solved, ie a page could be
 * mapped for the given address. -SOS_EFAULT otherwise, meaning the
 * faulting thread should be terminated or signalled (SIGSEGV)
 *
 * @note: The current mm_context MUST be that of the current thread
 * (which caused the exception) !
 */
sos_ret_t sos_umem_vmm_try_resolve_page_fault(sos_uaddr_t uaddr,
					      sos_bool_t write_access,
					      sos_bool_t user_access);



/**
 * Initialize the initial heap once the program code/data is mapped
 * Called by the ELF32 program loader.
 */
sos_ret_t
sos_umem_vmm_init_heap(struct sos_umem_vmm_as * as,
		       sos_uaddr_t heap_start);

#endif /* _SOS_UMEM_VMM_H_ */